Skip to content

Commit 8a34ee6

Browse files
dianazawadzkidianazawadzki
committed
docs: add root README.md for migrated new_samples
1 parent ae6a7d6 commit 8a34ee6

File tree

6 files changed

+505
-0
lines changed

6 files changed

+505
-0
lines changed

‎new_samples/consistentquery/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Consistent Query 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+
## Consistent Query Sample
33+
34+
This sample demonstrates **consistent queries** with signal handling.
35+
36+
### Start the Workflow
37+
38+
```bash
39+
cadence --env development \
40+
--domain cadence-samples \
41+
workflow start \
42+
--tl cadence-samples-worker \
43+
--et 180 \
44+
--workflow_type cadence_samples.ConsistentQueryWorkflow
45+
```
46+
47+
### Query the Workflow
48+
49+
```bash
50+
cadence --env development \
51+
--domain cadence-samples \
52+
workflow query \
53+
--wid <workflow_id> \
54+
--qt state
55+
```
56+
57+
### Send Signals to Update State
58+
59+
```bash
60+
cadence --env development \
61+
--domain cadence-samples \
62+
workflow signal \
63+
--wid <workflow_id> \
64+
--name increase
65+
```
66+
67+
Each signal increments the counter. Query to see the updated value.
68+
69+
### Key Concept: Query + Signal
70+
71+
```go
72+
queryResult := 0
73+
74+
// Register query handler
75+
workflow.SetQueryHandler(ctx, "state", func() (int, error) {
76+
return queryResult, nil
77+
})
78+
79+
// Handle signals that modify state
80+
signalChan := workflow.GetSignalChannel(ctx, "increase")
81+
signalChan.Receive(ctx, nil)
82+
queryResult += 1 // State changes are visible to queries
83+
```
84+
85+
86+
## References
87+
88+
* The website: https://cadenceworkflow.io
89+
* Cadence's server: https://github.com/uber/cadence
90+
* Cadence's Go client: https://github.com/uber-go/cadence-client
91+

‎new_samples/crossdomain/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Cross Domain 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+
## Cross Domain Sample
33+
34+
This sample demonstrates executing **child workflows across different Cadence domains**.
35+
36+
### Prerequisites
37+
38+
Register a second domain for the child workflow:
39+
40+
```bash
41+
cadence --env development --domain child-domain domain register
42+
```
43+
44+
Start a worker in the child domain (separate terminal):
45+
46+
```bash
47+
# Worker for child-domain would need to be configured separately
48+
```
49+
50+
### Start the Parent Workflow
51+
52+
```bash
53+
cadence --env development \
54+
--domain cadence-samples \
55+
workflow start \
56+
--tl cadence-samples-worker \
57+
--et 120 \
58+
--workflow_type cadence_samples.CrossDomainWorkflow
59+
```
60+
61+
### Key Concept: Cross-Domain Child Options
62+
63+
```go
64+
childCtx := workflow.WithChildOptions(ctx, workflow.ChildWorkflowOptions{
65+
Domain: "other-domain", // Different domain!
66+
WorkflowID: "child-wf-123",
67+
TaskList: "other-task-list",
68+
ExecutionStartToCloseTimeout: time.Minute,
69+
})
70+
71+
workflow.ExecuteChildWorkflow(childCtx, ChildWorkflow, args...)
72+
```
73+
74+
### Use Cases
75+
76+
- Multi-tenant architectures
77+
- Isolation between teams/services
78+
- Cross-cluster workflow execution
79+
80+
81+
## References
82+
83+
* The website: https://cadenceworkflow.io
84+
* Cadence's server: https://github.com/uber/cadence
85+
* Cadence's Go client: https://github.com/uber-go/cadence-client
86+

‎new_samples/ctxpropagation/README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Context Propagation 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+
## Context Propagation Sample
33+
34+
This sample demonstrates **custom context propagation** across workflow and activity execution.
35+
36+
### Key Concept: Context Propagator
37+
38+
A context propagator allows you to pass custom values (like user IDs, trace IDs, tenant info) through:
39+
- Workflow execution
40+
- Activity execution
41+
- Child workflows
42+
43+
```go
44+
type propagator struct{}
45+
46+
func (s *propagator) Inject(ctx context.Context, writer workflow.HeaderWriter) error {
47+
// Serialize and inject values into headers
48+
}
49+
50+
func (s *propagator) Extract(ctx context.Context, reader workflow.HeaderReader) (context.Context, error) {
51+
// Extract values from headers into context
52+
}
53+
```
54+
55+
### Configuring the Worker
56+
57+
Register the propagator when creating the worker:
58+
59+
```go
60+
workerOptions := worker.Options{
61+
ContextPropagators: []workflow.ContextPropagator{
62+
NewContextPropagator(),
63+
},
64+
}
65+
```
66+
67+
### Start the Workflow
68+
69+
```bash
70+
cadence --env development \
71+
--domain cadence-samples \
72+
workflow start \
73+
--tl cadence-samples-worker \
74+
--et 60 \
75+
--workflow_type cadence_samples.CtxPropagationWorkflow
76+
```
77+
78+
### Use Cases
79+
80+
- Distributed tracing (trace IDs)
81+
- Multi-tenancy (tenant IDs)
82+
- User context (user IDs, auth tokens)
83+
- Request correlation
84+
85+
86+
## References
87+
88+
* The website: https://cadenceworkflow.io
89+
* Cadence's server: https://github.com/uber/cadence
90+
* Cadence's Go client: https://github.com/uber-go/cadence-client
91+

‎new_samples/sideeffect/README.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
<!-- THIS IS A GENERATED FILE -->
2+
<!-- PLEASE DO NOT EDIT -->
3+
4+
# Side Effect 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+
## Side Effect Sample
33+
34+
This sample demonstrates **workflow.SideEffect** for handling non-deterministic operations.
35+
36+
### The Problem
37+
38+
Workflows must be deterministic for replay. But sometimes you need non-deterministic values like:
39+
- UUIDs
40+
- Random numbers
41+
- Current time
42+
- External state
43+
44+
### The Solution: SideEffect
45+
46+
```go
47+
workflow.SideEffect(ctx, func(ctx workflow.Context) interface{} {
48+
return uuid.New().String() // Non-deterministic!
49+
}).Get(&value)
50+
```
51+
52+
On first execution, SideEffect runs the function and records the result.
53+
On replay, it returns the recorded value without re-executing.
54+
55+
### Start the Workflow
56+
57+
```bash
58+
cadence --env development \
59+
--domain cadence-samples \
60+
workflow start \
61+
--tl cadence-samples-worker \
62+
--et 60 \
63+
--workflow_type cadence_samples.SideEffectWorkflow
64+
```
65+
66+
### Query the Generated Value
67+
68+
```bash
69+
cadence --env development \
70+
--domain cadence-samples \
71+
workflow query \
72+
--wid <workflow_id> \
73+
--qt value
74+
```
75+
76+
The same UUID is returned every time you query, demonstrating deterministic replay.
77+
78+
79+
## References
80+
81+
* The website: https://cadenceworkflow.io
82+
* Cadence's server: https://github.com/uber/cadence
83+
* Cadence's Go client: https://github.com/uber-go/cadence-client
84+

0 commit comments

Comments
 (0)