Skip to content

Commit c270d26

Browse files
demirkayaenderdemirkayaender
authored
feat: Introduce a generator based samples (#124)
Signed-off-by: Ender Demirkaya <[email protected]>
1 parent 90f978c commit c270d26

File tree

13 files changed

+636
-0
lines changed

13 files changed

+636
-0
lines changed

‎new_samples/hello_world/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Hello World Sample
5+
6+
## Prerequisites
7+
8+
0. Install Cadence CLI. See instruction [here](https://cadenceworkflow.io/docs/cli/).
9+
1. Run the Cadence server:
10+
1. Clone the [Cadence](https://github.com/cadence-workflow/cadence) repository if you haven't done already: `git clone https://github.com/cadence-workflow/cadence.git`
11+
2. Run `docker compose -f docker/docker-compose.yml up` to start Cadence server
12+
3. See more details at https://github.com/uber/cadence/blob/master/README.md
13+
2. Once everything is up and running in Docker, open [localhost:8088](localhost:8088) to view Cadence UI.
14+
3. Register the `cadence-samples` domain:
15+
16+
```bash
17+
cadence --env development --domain cadence-samples domain register
18+
```
19+
20+
Refresh the [domains page](http://localhost:8088/domains) from step 2 to verify `cadence-samples` is registered.
21+
22+
## Steps to run sample
23+
24+
Inside the folder this sample is defined, run the following command:
25+
26+
```bash
27+
go run .
28+
```
29+
30+
This will call the main function in main.go which starts the worker, which will be execute the sample workflow code
31+
32+
### Start your workflow
33+
34+
This workflow takes an input message and greet you as response. Try the following CLI
35+
36+
```bash
37+
cadence --env development \
38+
--domain cadence-samples \
39+
workflow start \
40+
--workflow_type cadence_samples.HelloWorldWorkflow \
41+
--tl cadence-samples-worker \
42+
--et 60 \
43+
--input '{"message":"Cadence"}'
44+
```
45+
46+
Here are the details to this command:
47+
48+
* `--domain` option describes under which domain to run this workflow
49+
* `--env development` calls the "local" cadence server
50+
* `--workflow_type` option describes which workflow to execute
51+
* `-tl` (or `--tasklist`) tells cadence-server which tasklist to schedule tasks with. This is the same tasklist the worker polls tasks from. See worker.go
52+
* `--et` (or `--execution_timeout`) tells cadence server how long to wait until timing out the workflow
53+
* `--input` is the input to your workflow
54+
55+
To see more options run `cadence --help`
56+
57+
### View your workflow
58+
59+
#### Cadence UI (cadence-web)
60+
61+
Click on `cadence-samples` domain in cadence-web to view your workflow.
62+
63+
* In Summary tab, you will see the input and output to your workflow
64+
* Click on History tab to see individual steps.
65+
66+
#### CLI
67+
68+
List workflows using the following command:
69+
70+
```bash
71+
cadence --env development --domain cadence-samples --workflow list
72+
```
73+
74+
You can view an individual workflow by using the following command:
75+
76+
```bash
77+
cadence --env development \
78+
--domain cadence-samples \
79+
--workflow describe \
80+
--wid <workflow_id>
81+
```
82+
83+
* `workflow` is the noun to run commands within workflow scope
84+
* `describe` is the verb to return the summary of the workflow
85+
* `--wid` (or `--workflow_id`) is the option to pass the workflow id. If there are multiple "run"s, it will return the latest one.
86+
* (optional) `--rid` (or `--run_id`) is the option to pass the run id to describe a specific run, instead of the latest.
87+
88+
To view the entire history of the workflow, use the following command:
89+
90+
```bash
91+
cadence --env development \
92+
--domain cadence-samples \
93+
--workflow show \
94+
--wid <workflow_id>
95+
```
96+
97+
## References
98+
99+
* The website: https://cadenceworkflow.io
100+
* Cadence's server: https://github.com/uber/cadence
101+
* Cadence's Go client: https://github.com/uber-go/cadence-client
102+

‎new_samples/hello_world/generator/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Sample Generator
5+
6+
This folder is NOT part of the actual sample. It exists only for contributors who work on this sample. Please disregard it if you are trying to learn about Cadence.
7+
8+
To create a better learning experience for Cadence users, each sample folder is designed to be self contained. Users can view every part of writing and running workflows, including:
9+
10+
* Cadence client initialization
11+
* Worker with workflow and activity registrations
12+
* Workflow starter
13+
* and the workflow code itself
14+
15+
Some samples may have more or fewer parts depending on what they need to demonstrate.
16+
17+
In most cases, the workflow code (e.g. `workflow.go`) is the part that users care about. The rest is boilerplate needed to run that workflow. For each sample folder, the workflow code should be written by hand. The boilerplate can be generated. Keeping all parts inside one folder gives early learners more value because they can see everything together rather than jumping across directories.
18+
19+
## Contributing
20+
21+
* When creating a new sample, follow the steps mentioned in the README file in the main samples folder.
22+
* To update the sample workflow code, edit the workflow file directly.
23+
* To update the worker, client, or other boilerplate logic, edit the generator file. If your change applies to all samples, update the common generator file inside the `template` folder. Edit the generator file in this folder only when the change should affect this sample alone.

‎new_samples/hello_world/generator/README_specific.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
### Start your workflow
2+
3+
This workflow takes an input message and greet you as response. Try the following CLI
4+
5+
```bash
6+
cadence --env development \
7+
--domain cadence-samples \
8+
workflow start \
9+
--workflow_type cadence_samples.HelloWorldWorkflow \
10+
--tl cadence-samples-worker \
11+
--et 60 \
12+
--input '{"message":"Cadence"}'
13+
```
14+
15+
Here are the details to this command:
16+
17+
* `--domain` option describes under which domain to run this workflow
18+
* `--env development` calls the "local" cadence server
19+
* `--workflow_type` option describes which workflow to execute
20+
* `-tl` (or `--tasklist`) tells cadence-server which tasklist to schedule tasks with. This is the same tasklist the worker polls tasks from. See worker.go
21+
* `--et` (or `--execution_timeout`) tells cadence server how long to wait until timing out the workflow
22+
* `--input` is the input to your workflow
23+
24+
To see more options run `cadence --help`
25+
26+
### View your workflow
27+
28+
#### Cadence UI (cadence-web)
29+
30+
Click on `cadence-samples` domain in cadence-web to view your workflow.
31+
32+
* In Summary tab, you will see the input and output to your workflow
33+
* Click on History tab to see individual steps.
34+
35+
#### CLI
36+
37+
List workflows using the following command:
38+
39+
```bash
40+
cadence --env development --domain cadence-samples --workflow list
41+
```
42+
43+
You can view an individual workflow by using the following command:
44+
45+
```bash
46+
cadence --env development \
47+
--domain cadence-samples \
48+
--workflow describe \
49+
--wid <workflow_id>
50+
```
51+
52+
* `workflow` is the noun to run commands within workflow scope
53+
* `describe` is the verb to return the summary of the workflow
54+
* `--wid` (or `--workflow_id`) is the option to pass the workflow id. If there are multiple "run"s, it will return the latest one.
55+
* (optional) `--rid` (or `--run_id`) is the option to pass the run id to describe a specific run, instead of the latest.
56+
57+
To view the entire history of the workflow, use the following command:
58+
59+
```bash
60+
cadence --env development \
61+
--domain cadence-samples \
62+
--workflow show \
63+
--wid <workflow_id>
64+
```

‎new_samples/hello_world/generator/generate.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
package main
2+
3+
import "github.com/uber-common/cadence-samples/new_samples/template"
4+
5+
func main() {
6+
// Define the data for HelloWorld
7+
data := template.TemplateData{
8+
SampleName: "Hello World",
9+
Workflows: []string{"HelloWorldWorkflow"},
10+
Activities: []string{"HelloWorldActivity"},
11+
}
12+
13+
template.GenerateAll(data)
14+
}
15+
16+
// Implement custom generator below

‎new_samples/hello_world/main.go‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// THIS IS A GENERATED FILE
2+
// PLEASE DO NOT EDIT
3+
4+
package main
5+
6+
import (
7+
"fmt"
8+
"os"
9+
"os/signal"
10+
"syscall"
11+
)
12+
13+
func main() {
14+
StartWorker()
15+
16+
done := make(chan os.Signal, 1)
17+
signal.Notify(done, syscall.SIGINT)
18+
fmt.Println("Cadence worker started, press ctrl+c to terminate...")
19+
<-done
20+
}

‎new_samples/hello_world/worker.go‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
// THIS IS A GENERATED FILE
2+
// PLEASE DO NOT EDIT
3+
4+
// Package worker implements a Cadence worker with basic configurations.
5+
package main
6+
7+
import (
8+
"github.com/uber-go/tally"
9+
apiv1 "github.com/uber/cadence-idl/go/proto/api/v1"
10+
"go.uber.org/cadence/.gen/go/cadence/workflowserviceclient"
11+
"go.uber.org/cadence/activity"
12+
"go.uber.org/cadence/compatibility"
13+
"go.uber.org/cadence/worker"
14+
"go.uber.org/cadence/workflow"
15+
"go.uber.org/yarpc"
16+
"go.uber.org/yarpc/peer"
17+
yarpchostport "go.uber.org/yarpc/peer/hostport"
18+
"go.uber.org/yarpc/transport/grpc"
19+
"go.uber.org/zap"
20+
"go.uber.org/zap/zapcore"
21+
)
22+
23+
const (
24+
HostPort = "127.0.0.1:7833"
25+
Domain = "cadence-samples"
26+
// TaskListName identifies set of client workflows, activities, and workers.
27+
// It could be your group or client or application name.
28+
TaskListName = "cadence-samples-worker"
29+
ClientName = "cadence-samples-worker"
30+
CadenceService = "cadence-frontend"
31+
)
32+
33+
// StartWorker creates and starts a basic Cadence worker.
34+
func StartWorker() {
35+
logger, cadenceClient := BuildLogger(), BuildCadenceClient()
36+
workerOptions := worker.Options{
37+
Logger: logger,
38+
MetricsScope: tally.NewTestScope(TaskListName, nil),
39+
}
40+
41+
w := worker.New(
42+
cadenceClient,
43+
Domain,
44+
TaskListName,
45+
workerOptions)
46+
// HelloWorld workflow registration
47+
w.RegisterWorkflowWithOptions(HelloWorldWorkflow, workflow.RegisterOptions{Name: "cadence_samples.HelloWorldWorkflow"})
48+
w.RegisterActivityWithOptions(HelloWorldActivity, activity.RegisterOptions{Name: "cadence_samples.HelloWorldActivity"})
49+
50+
err := w.Start()
51+
if err != nil {
52+
panic("Failed to start worker: " + err.Error())
53+
}
54+
logger.Info("Started Worker.", zap.String("worker", TaskListName))
55+
56+
}
57+
58+
func BuildCadenceClient(dialOptions ...grpc.DialOption) workflowserviceclient.Interface {
59+
grpcTransport := grpc.NewTransport()
60+
// Create a single peer chooser that identifies the host/port and configures
61+
// a gRPC dialer with TLS credentials
62+
myChooser := peer.NewSingle(
63+
yarpchostport.Identify(HostPort),
64+
grpcTransport.NewDialer(dialOptions...),
65+
)
66+
outbound := grpcTransport.NewOutbound(myChooser)
67+
68+
dispatcher := yarpc.NewDispatcher(yarpc.Config{
69+
Name: ClientName,
70+
Outbounds: yarpc.Outbounds{
71+
CadenceService: {Unary: outbound},
72+
},
73+
})
74+
if err := dispatcher.Start(); err != nil {
75+
panic("Failed to start dispatcher: " + err.Error())
76+
}
77+
78+
clientConfig := dispatcher.ClientConfig(CadenceService)
79+
80+
// Create a compatibility adapter that wraps proto-based YARPC clients
81+
// to provide a unified interface for domain, workflow, worker, and visibility APIs
82+
return compatibility.NewThrift2ProtoAdapter(
83+
apiv1.NewDomainAPIYARPCClient(clientConfig),
84+
apiv1.NewWorkflowAPIYARPCClient(clientConfig),
85+
apiv1.NewWorkerAPIYARPCClient(clientConfig),
86+
apiv1.NewVisibilityAPIYARPCClient(clientConfig),
87+
)
88+
}
89+
90+
func BuildLogger() *zap.Logger {
91+
config := zap.NewDevelopmentConfig()
92+
config.Level.SetLevel(zapcore.InfoLevel)
93+
94+
var err error
95+
logger, err := config.Build()
96+
if err != nil {
97+
panic("Failed to setup logger: " + err.Error())
98+
}
99+
100+
return logger
101+
}

‎new_samples/hello_world/workflow.go‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"fmt"
6+
"go.uber.org/cadence/activity"
7+
"go.uber.org/cadence/workflow"
8+
"go.uber.org/zap"
9+
"time"
10+
)
11+
12+
type sampleInput struct {
13+
Message string `json:"message"`
14+
}
15+
16+
// This is the workflow function
17+
// Given an input, HelloWorldWorkflow returns "Hello <input>!"
18+
func HelloWorldWorkflow(ctx workflow.Context, input sampleInput) (string, error) {
19+
ao := workflow.ActivityOptions{
20+
ScheduleToStartTimeout: time.Minute,
21+
StartToCloseTimeout: time.Minute,
22+
}
23+
ctx = workflow.WithActivityOptions(ctx, ao)
24+
25+
logger := workflow.GetLogger(ctx)
26+
logger.Info("HelloWorldWorkflow started")
27+
28+
var greetingMsg string
29+
err := workflow.ExecuteActivity(ctx, HelloWorldActivity, input).Get(ctx, &greetingMsg)
30+
if err != nil {
31+
logger.Error("HelloWorldActivity failed", zap.Error(err))
32+
return "", err
33+
}
34+
35+
logger.Info("Workflow result", zap.String("greeting", greetingMsg))
36+
return greetingMsg, nil
37+
}
38+
39+
// This is the activity function
40+
// Given an input, HelloWorldActivity returns "Hello <input>!"
41+
func HelloWorldActivity(ctx context.Context, input sampleInput) (string, error) {
42+
logger := activity.GetLogger(ctx)
43+
logger.Info("HelloWorldActivity started")
44+
return fmt.Sprintf("Hello, %s!", input.Message), nil
45+
}

0 commit comments

Comments
 (0)