Cadence CLI (uber#577)

.travis.yml

@@ -5,7 +5,7 @@ language: go
 directories:
     - $HOME/.glide/cache
 go:
-  - 1.8
+  - 1.9
 
 addons:
   apt:

Makefile

@@ -81,10 +81,13 @@ copyright: cmd/tools/copyright/licensegen.go
 cadence-cassandra-tool: vendor/glide.updated $(TOOLS_SRC)
 	go build -i -o cadence-cassandra-tool cmd/tools/cassandra/main.go
 
-cadence: vendor/glide.updated $(ALL_SRC)
-	go build -i -o cadence cmd/server/cadence.go cmd/server/server.go
+cadence: vendor/glide.updated $(TOOLS_SRC)
+	go build -i -o cadence cmd/tools/cli/main.go
 
-bins_nothrift: lint copyright cadence-cassandra-tool cadence
+cadence-server: vendor/glide.updated $(ALL_SRC)
+	go build -i -o cadence-server cmd/server/cadence.go cmd/server/server.go
+
+bins_nothrift: lint copyright cadence-cassandra-tool cadence cadence-server
 
 bins: thriftc bins_nothrift
 
@@ -137,6 +140,7 @@ fmt:
 clean:
 	rm -f cadence
 	rm -f cadence-cassandra-tool
+	rm -f cadence-server
 	rm -Rf $(BUILD)
 
 install-schema: bins
@@ -148,7 +152,7 @@ install-schema: bins
 	./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility update-schema -d ./schema/visibility/versioned
 
 start: bins
-	./cadence start
+	./cadence-server start
 
 install-schema-cdc: bins
 	@echo Setting up cadence_active key space
@@ -167,7 +171,7 @@ install-schema-cdc: bins
 	./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility_standby update-schema -d ./schema/visibility/versioned
 
 start-cdc-active: bins
-	./cadence --zone active start
+	./cadence-server --zone active start
 
 start-cdc-standby: bins
-	./cadence --zone standby start
+	./cadence-server --zone standby start

README.md

@@ -32,7 +32,7 @@ make install-schema
 
 * Start the service:
 ```bash
-./cadence start
+./cadence-server start
 ```
 
 ### Using Docker

cmd/tools/cli/main.go

@@ -0,0 +1,34 @@
+// Copyright (c) 2017 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+package main
+
+import (
+	"os"
+
+	"github.com/uber/cadence/tools/cli"
+)
+
+// Start using this CLI tool with command
+// See cadence/tools/cli/README.md for usage
+func main() {
+	app := cli.NewCliApp()
+	app.Run(os.Args)
+}

docker/start.sh

@@ -112,4 +112,4 @@ fi
 
 # fix up config
 envsubst < config/docker_template.yaml > config/docker.yaml
-./cadence --root $CADENCE_HOME --env docker start --services=$SERVICES
+./cadence-server --root $CADENCE_HOME --env docker start --services=$SERVICES

glide.yaml

@@ -23,6 +23,9 @@ import:
 - package: github.com/emirpasic/gods
 - package: github.com/davecgh/go-spew
 - package: github.com/urfave/cli
+- package: github.com/fatih/color
+- package: github.com/olekukonko/tablewriter
+- package: github.com/mattn/go-runewidth
 - package: gopkg.in/yaml.v2
 - package: gopkg.in/validator.v2
 - package: golang.org/x/time
@@ -31,6 +34,7 @@ import:
 - package: github.com/cactus/go-statsd-client
   subpackages:
   - statsd
+- package: go.uber.org/cadence
 - package: go.uber.org/thriftrw
   version: ^1.6
 - package: go.uber.org/yarpc

service/frontend/handler.go

@@ -1108,7 +1108,7 @@ func (wh *WorkflowHandler) StartWorkflowExecution(
 	return resp, nil
 }
 
-// GetWorkflowExecutionHistory - retrieves the hisotry of workflow execution
+// GetWorkflowExecutionHistory - retrieves the history of workflow execution
 func (wh *WorkflowHandler) GetWorkflowExecutionHistory(
 	ctx context.Context,
 	getRequest *gen.GetWorkflowExecutionHistoryRequest) (*gen.GetWorkflowExecutionHistoryResponse, error) {

service/worker/README.md

@@ -32,7 +32,7 @@ bin/kafka-topics.sh --create --zookeeper localhost:2181 --replication-factor 1 -
 ```
 4. Start Cadence development server for active zone:
 ```
-./cadence --zone active start
+./cadence-server --zone active start
 ```
 
 

tools/cassandra/README.md

@@ -1,20 +1,16 @@
-What
-----
+## What
 This package contains the tooling for cadence cassandra operations.
 
-How
----
-- Run make bins
+## How
+- Run `make bins`
 - You should see an executable `cadence-cassandra-tool`
 
-Setting up cassandra schema on a new cluster shortcut
-----------------------------------------------------
+## Setting up cassandra schema on a new cluster shortcut
 ``` 
 make install-schema
 ```
 
-Setting up schema on a new cluster manually
-----------------------------------------------------
+## Setting up schema on a new cluster manually
 ```
 ./cadence-cassandra-tool -ep 127.0.0.1 -k cadence setup-schema -v 0.0 -- this sets up just the schema version tables with initial version of 0.0
 ./cadence-cassandra-tool -ep 127.0.0.1 -k cadence update-schema -d ./schema/cadence/versioned -- upgrades your schema to the latest version
@@ -23,8 +19,7 @@ Setting up schema on a new cluster manually
 ./cadence-cassandra-tool -ep 127.0.0.1 -k cadence_visibility update-schema -d ./schema/visibility/versioned -- upgrades your schema to the latest version for visibility
 ```
 
-Updating schema on an existing cluster
---------------------------------------
+## Updating schema on an existing cluster
 You can only upgrade to a new version after the initial setup done above.
 
 ```

tools/cli/README.md

@@ -0,0 +1,114 @@
+## What
+Cadence CLI provide an command-line tool for users to perform various tasks on Cadence.  
+Users can perform operations like register, update and describe on domain;  
+also start workflow, show workflow history, signal workflow ... and many other tasks.    
+
+## How
+- Run `make bins`
+- You should see an executable `cadence`
+
+## Quick Start
+Run `./cadence` to view help message. There are some top level commands and global options.   
+Run `./cadence domain` to view help message about operations on domain  
+Run `./cadence workflow` to view help message about operations on workflow  
+(`./cadence help`, `./cadence help [domain|workflow]` will also print help messages)
+
+**Note:** make sure you have cadence server running before using CLI 
+
+### Domain operation examples 
+- Register a new domain named "samples-domain":  
+```
+./cadence --domain samples-domain domain register 
+# OR using short alias  
+./cadence --do samples-domain domain re
+```   
+- View "samples-domain" details:   
+```
+./cadence --domain samples-domain domain describe  
+```
+
+**Tips:**  
+to avoid repeated input global option **domain**, user can export domain-name in environment variable CADENCE_CLI_DOMAIN.
+```
+export CADENCE_CLI_DOMAIN=samples-domain
+
+# then just run commands without --domain flag, like
+./cadence domain desc
+```
+
+### Workflow operation examples
+(The following examples assume you already export CADENCE_CLI_DOMAIN environment variable as Tips above)
+
+- Run workflow: Start a workflow and see it's progress, this command doesn't finish until workflow completes
+```
+./cadence workflow run --tl helloWorldGroup --wt main.Workflow --et 60 -i '"cadence"'
+
+# view help messages for workflow run
+./cadence workflow run -h
+``` 
+Brief explanation:  
+To run a workflow, user must specify 
+1. Tasklist name (--tl), 
+2. Workflow type (--wt), 
+3. Execution start to close timeout in seconds (--et), 
+
+Example uses [this cadence-samples workflow](https://github.com/samarabbas/cadence-samples/blob/master/cmd/samples/recipes/helloworld/helloworld_workflow.go) 
+and it takes a string as input, so there is the `-i '"cadence"'`. Single quote `''` is used to wrap input as json. 
+
+**Note:** you need to start worker so that workflow can make progress.  
+(Run `make && ./bin/helloworld -m worker` in cadence-samples to start the worker)
+
+- Start workflow: 
+```
+./cadence workflow start --tl helloWorldGroup --wt main.Workflow --et 60 -i '"cadence"'
+
+# view help messages for workflow start
+./cadence workflow start -h
+
+# for workflow with multiple input, seperate each json with space/newline like
+./cadence workflow start --tl helloWorldGroup --wt main.WorkflowWith3Args --et 60 -i '"your_input_string" 123 {"Name":"my-string", "Age":12345}'
+```
+Workflow `start` command is similar to `run` command and takes same flag options. But it just start the workflow and immediately return workflow_id and run_id.  
+User need to run `show` to view workflow history/progress.  
+
+- Show workflow history
+```
+./cadence workflow show -w 3ea6b242-b23c-4279-bb13-f215661b4717 -r 866ae14c-88cf-4f1e-980f-571e031d71b0
+# a shortcut of this is (without -w -r flag)
+./cadence workflow showid 3ea6b242-b23c-4279-bb13-f215661b4717 866ae14c-88cf-4f1e-980f-571e031d71b0
+
+# if run_id is not provided, it will show the latest run history for that workflow_id
+./cadence workflow show -w 3ea6b242-b23c-4279-bb13-f215661b4717
+# a shortcut of this is
+./cadence workflow showid 3ea6b242-b23c-4279-bb13-f215661b4717
+```
+
+- List open or closed workflow executions
+```
+./cadence workflow list
+```
+
+- Query workflow execution
+```
+# use custom query type
+./cadence workflow query -w <wid> -r <rid> --qt <query-type>
+
+# use build-in query type "__stack_trace" which is supported by cadence client library
+./cadence workflow query -w <wid> -r <rid> --qt __stack_trace
+# a shortcut to query using __stack_trace is (without --qt flag)
+./cadence workflow stack -w <wid> -r <rid> 
+```
+
+- Signal, cancel, terminate workflow
+```
+# signal
+./cadence workflow signal -w <wid> -r <rid> -n <signal-name> -i '"signal-value"'
+
+# cancel
+./cadence workflow cancel -w <wid> -r <rid>
+
+# terminate
+./cadence workflow terminate -w <wid> -r <rid> --reason 
+```
+Terminate a running workflow execution will record WorkflowExecutionTerminated event as closing event in the history. No more decision task will be scheduled for terminated workflow execution.  
+Cancel a running workflow execution will record WorkflowExecutionCancelRequested event in the history, and a new decision task will be scheduled. Workflow has a chance to do some clean up work after cancellation.