CLI

CLI is a command-line interface for Yorkie. You can use CLI to manage your projects, documents or to start the server.

Getting started

Let's get started with the CLI. There are two ways to install the CLI: pre-built binaries and Homebrew.

Install pre-built binaries

The easiest way to install Yorkie is from pre-built binaries:

  1. Download the compressed archive file for your platform from Releases.
  2. Unpack the archive file. This results in a directory containing the binaries.
  3. Add the executable binaries to your PATH. For example, rename and/or move the binaries to a directory in your PATH (like /usr/local/bin), or add the directory created from the previous step to your PATH.
  4. Test if Yorkie is in your PATH in shell:
$ yorkie version
Yorkie: 0.2.20
Commit: ...
Go: ...
Build date: ...

Install via Homebrew

Homebrew is a free and open-source package management system for Mac OS X. Install the official Yorkie formula in Terminal.

To update Yorkie to the latest version, update Homebrew first.

$ brew update

Now, install Yorkie.

$ brew install yorkie

Verify that the installation worked by opening a new Terminal session and trying Yorkie's available subcommands.

$ yorkie version
Yorkie: 0.2.20
Commit: ...
Go: ...
Build date: ...

Commands

Yorkie is just a single command-line application yorkie, which takes a subcommand such as server.

The Yorkie CLI is a well-behaved command-line application. In erroneous cases, a non-zero exit status will be returned. It also responds to -h and ---help as you'd most likely expect.

To get help for any specific command, pass the -h flag to the relevant subcommand. For example, to see help about the server subcommand:

$ yorkie server --help
Start Yorkie server
Usage:
yorkie server [options] [flags]
Flags:
--auth-webhook-cache-auth-ttl duration TTL value to set when caching authorized webhook response. (default 10s)
--auth-webhook-cache-size int The cache size of the authorization webhook. (default 5000)
--auth-webhook-cache-unauth-ttl duration TTL value to set when caching unauthorized webhook response. (default 10s)
--auth-webhook-max-retries uint Maximum number of retries for an authorization webhook. (default 10)
--auth-webhook-max-wait-interval duration Maximum wait interval for authorization webhook. (default 3s)
--backend-snapshot-interval uint Interval of changes to create a snapshot. (default 1000)
--backend-snapshot-threshold uint Threshold that determines if changes should be sent with snapshot when the number of changes is greater than this value. (default 500)
--backend-use-default-project Whether to use the default project. Even if public key is not provided from the client, the default project will be used for the request. (default true)
-c, --config string Config path
--enable-pprof Enable runtime profiling data via HTTP server.
--etcd-dial-timeout duration ETCD's dial timeout (default 5s)
--etcd-endpoints strings Comma separated list of etcd endpoints
--etcd-lock-lease-time duration ETCD's lease time for lock (default 30s)
--etcd-password string ETCD's password
--etcd-username string ETCD's user name
-h, --help help for server
--housekeeping-candidates-limit int candidates limit for a single housekeeping run (default 500)
--housekeeping-deactivate-threshold duration time after which clients are considered deactivate (default 168h0m0s)
--housekeeping-interval duration housekeeping interval between housekeeping runs (default 1m0s)
-l, --log-level string Log level: debug, info, warn, error, panic, fatal (default "info")
--mongo-connection-timeout duration Mongo DB's connection timeout (default 5s)
--mongo-connection-uri string MongoDB's connection URI
--mongo-ping-timeout duration Mongo DB's ping timeout (default 5s)
--mongo-yorkie-database string Yorkie's database name in MongoDB (default "yorkie-meta")
--profiling-port int Profiling port (default 11102)
--rpc-cert-file string RPC certification file's path
--rpc-key-file string RPC key file's path
--rpc-max-requests-bytes uint Maximum client request size in bytes the server will accept. (default 4194304)
--rpc-port int RPC port (default 11101)

Project

Project represents your service or application in Yorkie. Separate Projects can exist within a single application. You can add more Projects as needed, for example, if you want to manage auth webhook and documents for specific purposes.

To manage Projects, you can use the project subcommand:

$ yorkie project
Manage projects
Usage:
yorkie project [command]
Available Commands:
create Create a new project
ls List all projects
update Update a project
Flags:
-h, --help help for project
Use "yorkie project [command] --help" for more information about a command.

Listing Projects

You can list Projects on the server using ls.

$ yorkie project ls
NAME PUBLIC KEY SECRET KEY AUTH WEBHOOK URL AUTH WEBHOOK METHODS CREATED AT
default caes5i3hkdftdruae2tg caes5i3hkdftdruae2u0 [] 2 minutes

Server creates a default project automatically. If you create a Client without apiKey, the Client is created in the default Project.

Creating a Project

You can create a new Project with a name using create.

$ yorkie project create test-project
{"id":"627c9125d02654d3f0f769d8","name":"test-project","public_key":"c9u9298qp9as73b8i190","secret_key":"c9u9298qp9as73b8i19g","auth_webhook_url":"","auth_webhook_methods":null,"created_at":"2022-05-12T04:46:29.781052056Z"}

If you create a Client with public_key of the Project as apiKey, you can manage the Client in the Project.

1const client = new yorkie.Client('https://api.yorkie.dev', {
2 apiKey: 'c9u9298qp9as73b8i190', // public_key of the project
3});

Then Documents attached to the Client are isolated and stored in the Project.

Updating the Project

You can update the Project on the server using update.

Usage:
yorkie project update [name] [flags]
Examples:
yorkie project update name [options]
Flags:
--auth-webhook-url string authorization-webhook update url
-h, --help help for update
--name string new project name

You can update the name of the Project with --name flag.

$ yorkie project update test-project --name new-test-project
{"id":"627c9125d02654d3f0f769d8","name":"new-test-project","auth_webhook_url":"http://localhost:3000/webhook","auth_webhook_methods":["AttachDocument","WatchDocuments"],"public_key":"cblt65lcefodjh0aeakg","secret_key":"cblt65lcefodjh0aeal0","created_at":"2022-05-12T04:46:29.781052056Z","updated_at":"2022-08-11T14:58:22.11Z"}

Auth Webhook

A webhook is an HTTP POST that is called when something happens. If the Auth Webhook has been configured, when a Server receives a request from a Client, the Server checks if the Client has been authorized for a certain Document by asking an outside service with a REST request.

This page shows how to set up an Auth Webhook. The overall flow is as follows:

(5) response the request (4) handle the request
┌─────────────────┐ ┌──┐
│ │ │ │ (3) response
▼ │ ▼ │ - allowed
┌──────┐ ┌┴─────┤ - reason ┌──────────────┐
│Client├────────────►│Server│◄──────────────┤Outside Server│
└──────┘ (1)request └────┬─┘ └──────────────┘
- token │ ▲
- dockey └──────────────────────┘
(2) call webhook
- token
- dockey
- verb: r or rw

First, We need to pass some tokens (that identify users in the service) when creating a Client:

1const client = new yorkie.Client('https://api.yorkie.dev', {
2 token: SOME_TOKEN,
3});

This token will be sent to the Server upon every request from the Client.

We can specify an Auth Webhook for the project by update command with the --auth-webhook-url flag:

$ yorkie project update [name] --auth-webhook-url http://localhost:3000/auth-hook

The Server who receives the token calls the given webhook URL before processing the requests.

Here is an example of the webhook requests:

1{
2 "token": "SOME_TOKEN", // token passed by the client
3 "method": "PushPull", // method: ActivateClient, DeactivateClient, AttachDocument, DetachDocument, WatchDocuments
4 documentAttributes: [{
5 key: "DOCUMENT_KEY", // document key
6 verb: "r" // 'r' or 'rw'
7 }]
8}

The outside server should respond like this:

1{
2 "allowed": true, // or false if the given token is not authorized for this document.
3 "reason": "ok" // [optional] reason for this response.
4}

If the server receives a response with allowed: true from the outside server, it handles the request normally, otherwise it sends the codes.Unauthenticated error to the client.