Skip to content

Commit 578758f

Browse files
zawadzkidianazawadzkidiana
committed
Add README for remaining 10 recipe samples
Signed-off-by: Diana Zawadzki <[email protected]>
1 parent 052aa66 commit 578758f

File tree

10 files changed

+584
-0
lines changed

10 files changed

+584
-0
lines changed

‎cmd/samples/recipes/cancelactivity/README.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Cancel Activity Sample
2+
3+
This sample demonstrates **graceful activity cancellation** with cleanup operations.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌──────────────────┐
11+
│ Start Workflow │
12+
└────────┬─────────┘
13+
▼
14+
┌──────────────────┐ ┌──────────────────┐
15+
│ activityToBe │────▶│ User cancels │
16+
│ Canceled() │ │ workflow │
17+
│ (heartbeating) │ └────────┬─────────┘
18+
└──────────────────┘ │
19+
│◀───────────────────────┘
20+
▼
21+
┌──────────────────┐
22+
│ cleanupActivity()│ (runs via NewDisconnectedContext)
23+
└──────────────────┘
24+
```
25+
26+
## Prerequisites
27+
28+
1. Cadence server running (see [main README](../../../../README.md))
29+
2. Build the samples: `make`
30+
31+
## Running the Sample
32+
33+
```bash
34+
# Terminal 1: Start worker
35+
./bin/cancelactivity -m worker
36+
37+
# Terminal 2: Trigger workflow
38+
./bin/cancelactivity -m trigger
39+
40+
# Terminal 3: Cancel the workflow (copy WorkflowID from trigger output)
41+
./bin/cancelactivity -m cancel -w <WorkflowID>
42+
```
43+
44+
## Key Code
45+
46+
```go
47+
defer func() {
48+
if cadence.IsCanceledError(retError) {
49+
newCtx, _ := workflow.NewDisconnectedContext(ctx)
50+
workflow.ExecuteActivity(newCtx, cleanupActivity).Get(ctx, nil)
51+
}
52+
}()
53+
```
54+
55+
## Testing
56+
57+
```bash
58+
go test -v ./cmd/samples/recipes/cancelactivity/
59+
```
60+

‎cmd/samples/recipes/crossdomain/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Cross Domain Sample
2+
3+
This sample demonstrates **cross-domain child workflows** - executing child workflows in different Cadence domains.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌─────────────────────────────────────────┐
11+
│ Parent Workflow (domain0) │
12+
│ │ │
13+
│ ┌───────────────┴───────────────┐ │
14+
│ ▼ ▼ │
15+
│ ┌─────────┐ ┌─────────┐ │
16+
│ │ Child │ │ Child │ │
17+
│ │ domain1 │ │ domain2 │ │
18+
│ │(cluster1)│ │(cluster0)│ │
19+
│ └─────────┘ └─────────┘ │
20+
└─────────────────────────────────────────┘
21+
```
22+
23+
**Use case:** Multi-tenant systems, cross-region workflows, domain isolation.
24+
25+
## Prerequisites
26+
27+
1. Cadence server with multiple domains configured
28+
2. Build the samples: `make`
29+
30+
## Running the Sample
31+
32+
```bash
33+
./bin/crossdomain
34+
```
35+
36+
**Note:** This sample requires specific multi-domain setup. See main.go for domain configuration.
37+
38+
## Key Code
39+
40+
```go
41+
ctx1 := workflow.WithChildOptions(ctx, workflow.ChildWorkflowOptions{
42+
Domain: domain1,
43+
TaskList: tasklist1,
44+
})
45+
workflow.ExecuteChildWorkflow(ctx1, wf1, data).Get(ctx1, nil)
46+
```
47+

‎cmd/samples/recipes/delaystart/README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Delay Start Sample
2+
3+
This sample demonstrates **delayed workflow execution** - starting a workflow that waits before executing its logic.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌──────────────────┐
11+
│ Workflow Start │
12+
│ (with delay) │
13+
└────────┬─────────┘
14+
│
15+
⏳ Wait 10s
16+
│
17+
▼
18+
┌──────────────────┐
19+
│ delayStartActivity│
20+
│ executes │
21+
└──────────────────┘
22+
```
23+
24+
**Use case:** Scheduled tasks, delayed notifications, batch processing at specific times.
25+
26+
## Prerequisites
27+
28+
1. Cadence server running (see [main README](../../../../README.md))
29+
2. Build the samples: `make`
30+
31+
## Running the Sample
32+
33+
```bash
34+
# Terminal 1: Start worker
35+
./bin/delaystart -m worker
36+
37+
# Terminal 2: Trigger workflow (will execute after delay)
38+
./bin/delaystart -m trigger
39+
```
40+
41+
## Key Code
42+
43+
```go
44+
func delayStartWorkflow(ctx workflow.Context, delayStart time.Duration) error {
45+
logger.Info("workflow started after waiting for " + delayStart.String())
46+
workflow.ExecuteActivity(ctx, delayStartActivity, delayStart).Get(ctx, &result)
47+
}
48+
```
49+
50+
## Testing
51+
52+
```bash
53+
go test -v ./cmd/samples/recipes/delaystart/
54+
```
55+

‎cmd/samples/recipes/dynamic/README.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Dynamic Sample
2+
3+
This sample demonstrates **dynamic activity invocation** - calling activities by string name instead of function reference.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌──────────────────────────────────────────────┐
11+
│ Workflow │
12+
│ │
13+
│ ExecuteActivity(ctx, "main.getGreeting") │
14+
│ ExecuteActivity(ctx, "main.getName") │
15+
│ ExecuteActivity(ctx, "main.sayGreeting") │
16+
│ │
17+
│ (activities called by STRING name) │
18+
└──────────────────────────────────────────────┘
19+
```
20+
21+
**Use case:** Plugin systems, configuration-driven workflows, runtime activity selection.
22+
23+
## Prerequisites
24+
25+
1. Cadence server running (see [main README](../../../../README.md))
26+
2. Build the samples: `make`
27+
28+
## Running the Sample
29+
30+
```bash
31+
# Terminal 1: Start worker
32+
./bin/dynamic -m worker
33+
34+
# Terminal 2: Trigger workflow
35+
./bin/dynamic -m trigger
36+
```
37+
38+
## Key Code
39+
40+
```go
41+
const getGreetingActivityName = "main.getGreetingActivity"
42+
43+
// Call activity by name string instead of function
44+
workflow.ExecuteActivity(ctx, getGreetingActivityName).Get(ctx, &result)
45+
```
46+
47+
## Testing
48+
49+
```bash
50+
go test -v ./cmd/samples/recipes/dynamic/
51+
```
52+

‎cmd/samples/recipes/pickfirst/README.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Pick First Sample
2+
3+
This sample demonstrates **racing activities** - running multiple activities in parallel and using the first result.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌─────────────────┐
11+
│ Start │
12+
└────────┬────────┘
13+
┌─────┴─────┐
14+
▼ ▼
15+
┌─────────┐ ┌─────────┐
16+
│ Task 1 │ │ Task 2 │ (parallel)
17+
│ 2 sec │ │ 10 sec │
18+
└────┬────┘ └────┬────┘
19+
│ │
20+
First ✓ Cancel ✗
21+
│
22+
▼
23+
┌─────────┐
24+
│ Result │
25+
└─────────┘
26+
```
27+
28+
**Use case:** Failover, load balancing, fastest-response-wins patterns.
29+
30+
## Prerequisites
31+
32+
1. Cadence server running (see [main README](../../../../README.md))
33+
2. Build the samples: `make`
34+
35+
## Running the Sample
36+
37+
```bash
38+
# Terminal 1: Start worker
39+
./bin/pickfirst -m worker
40+
41+
# Terminal 2: Trigger workflow
42+
./bin/pickfirst -m trigger
43+
```
44+
45+
## Key Code
46+
47+
```go
48+
f1 := workflow.ExecuteActivity(childCtx, sampleActivity, 0, time.Second*2)
49+
f2 := workflow.ExecuteActivity(childCtx, sampleActivity, 1, time.Second*10)
50+
51+
selector.AddFuture(f1, handler).AddFuture(f2, handler)
52+
selector.Select(ctx) // Wait for first
53+
cancelHandler() // Cancel others
54+
```
55+
56+
## Testing
57+
58+
```bash
59+
go test -v ./cmd/samples/recipes/pickfirst/
60+
```
61+

‎cmd/samples/recipes/retryactivity/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Retry Activity Sample
2+
3+
This sample demonstrates **activity retry with heartbeat progress** - automatic retries with resume from last checkpoint.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌────────────────────────────────────────────────┐
11+
│ Batch Processing (20 items) │
12+
│ │
13+
│ Attempt 1: Process 1-6 → FAIL (simulated) │
14+
│ Heartbeat: item 6 ✓ │
15+
│ │
16+
│ Attempt 2: Resume from 7 → Process 7-12 → FAIL│
17+
│ Heartbeat: item 12 ✓ │
18+
│ │
19+
│ Attempt 3: Resume from 13 → Process 13-20 ✓ │
20+
└────────────────────────────────────────────────┘
21+
```
22+
23+
**Use case:** Batch processing, unreliable external APIs, resumable long-running tasks.
24+
25+
## Prerequisites
26+
27+
1. Cadence server running (see [main README](../../../../README.md))
28+
2. Build the samples: `make`
29+
30+
## Running the Sample
31+
32+
```bash
33+
# Terminal 1: Start worker
34+
./bin/retryactivity -m worker
35+
36+
# Terminal 2: Trigger workflow
37+
./bin/retryactivity -m trigger
38+
```
39+
40+
## Key Code
41+
42+
```go
43+
RetryPolicy: &cadence.RetryPolicy{
44+
InitialInterval: time.Second,
45+
BackoffCoefficient: 2.0,
46+
MaximumAttempts: 5,
47+
}
48+
49+
// Resume from heartbeat progress
50+
if activity.HasHeartbeatDetails(ctx) {
51+
activity.GetHeartbeatDetails(ctx, &completedIdx)
52+
i = completedIdx + 1 // Resume from last checkpoint
53+
}
54+
55+
activity.RecordHeartbeat(ctx, i) // Save progress
56+
```
57+
58+
## Testing
59+
60+
```bash
61+
go test -v ./cmd/samples/recipes/retryactivity/
62+
```
63+

‎cmd/samples/recipes/sideeffect/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Side Effect Sample
2+
3+
This sample demonstrates **workflow.SideEffect** - handling non-deterministic operations safely.
4+
5+
> **Looking for a visual guide?** See [new_samples/hello_world](../../../../new_samples/hello_world/) for screenshots.
6+
7+
## How It Works
8+
9+
```
10+
┌─────────────────────────────────────────────────┐
11+
│ Workflow │
12+
│ │
13+
│ SideEffect(func() { │
14+
│ return uuid.New() // Non-deterministic! │
15+
│ }) │
16+
│ │
17+
│ First execution: Generates UUID, stores it │
18+
│ Replay: Returns stored UUID (no regeneration) │
19+
└─────────────────────────────────────────────────┘
20+
```
21+
22+
**Use case:** UUID generation, random numbers, timestamps, external state queries.
23+
24+
## Why SideEffect?
25+
26+
Workflow code must be deterministic for replay. `SideEffect` captures non-deterministic values once and returns the same value on replay.
27+
28+
## Prerequisites
29+
30+
1. Cadence server running (see [main README](../../../../README.md))
31+
2. Build the samples: `make`
32+
33+
## Running the Sample
34+
35+
```bash
36+
./bin/sideeffect
37+
```
38+
39+
**Note:** This sample starts worker, triggers workflow, and queries result in one command.
40+
41+
## Key Code
42+
43+
```go
44+
var value string
45+
workflow.SideEffect(ctx, func(ctx workflow.Context) interface{} {
46+
return uuid.New().String() // Only executed once, stored for replay
47+
}).Get(&value)
48+
```
49+
50+
## References
51+
52+
- [Side Effects](https://cadenceworkflow.io/docs/go-client/side-effect/)
53+

0 commit comments

Comments
 (0)