You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+116-2Lines changed: 116 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -118,15 +118,15 @@ Orchestrations can start child orchestrations using the `call_sub_orchestrator`
118
118
119
119
Orchestrations can wait for external events using the `wait_for_external_event` API. External events are useful for implementing human interaction patterns, such as waiting for a user to approve an order before continuing.
120
120
121
-
### Continue-as-new (TODO)
121
+
### Continue-as-new
122
122
123
123
Orchestrations can be continued as new using the `continue_as_new` API. This API allows an orchestration to restart itself from scratch, optionally with a new input.
124
124
125
125
### Suspend, resume, and terminate
126
126
127
127
Orchestrations can be suspended using the `suspend_orchestration` client API and will remain suspended until resumed using the `resume_orchestration` client API. A suspended orchestration will stop processing new events, but will continue to buffer any that happen to arrive until resumed, ensuring that no data is lost. An orchestration can also be terminated using the `terminate_orchestration` client API. Terminated orchestrations will stop processing new events and will discard any buffered events.
128
128
129
-
### Retry policies (TODO)
129
+
### Retry policies
130
130
131
131
Orchestrations can specify retry policies for activities and sub-orchestrations. These policies control how many times and how frequently an activity or sub-orchestration will be retried in the event of a transient error.
132
132
@@ -191,6 +191,120 @@ To run the E2E tests, run the following command from the project root:
191
191
make test-e2e
192
192
```
193
193
194
+
### Configuration
195
+
196
+
The SDK connects to a Durable Task sidecar. By default it uses `localhost:4001`. You can override via environment variables (checked in order):
-`DURABLETASK_GRPC_HOST` and `DURABLETASK_GRPC_PORT`
200
+
-`TASKHUB_GRPC_ENDPOINT` (legacy)
201
+
202
+
Example (common ports: 4001 for DurableTask-Go emulator, 50001 for Dapr sidecar):
203
+
204
+
```sh
205
+
export DURABLETASK_GRPC_ENDPOINT=localhost:4001
206
+
# or
207
+
export DURABLETASK_GRPC_ENDPOINT=localhost:50001
208
+
```
209
+
210
+
### Async authoring compatibility
211
+
212
+
You can author orchestrators with `async def` using `add_async_orchestrator`, which provides awaitables for activities, timers, external events, and when_all/any:
Optional sandbox mode (`best_effort` or `strict`) patches `asyncio.sleep`, `random`, `uuid.uuid4`, and `time.time` within the workflow step to deterministic equivalents. This is best-effort and not a correctness guarantee.
228
+
229
+
In `strict` mode, `asyncio.create_task` is blocked inside workflows to preserve determinism and will raise a `RuntimeError` if used.
230
+
231
+
#### Async patterns
232
+
233
+
- Activities:
234
+
```python
235
+
result =await ctx.activity("process", input={"x": 1})
236
+
```
237
+
238
+
- Timers:
239
+
```python
240
+
await ctx.sleep(1.5) # seconds or timedelta
241
+
```
242
+
243
+
- External events:
244
+
```python
245
+
val =await ctx.wait_for_external_event("approval")
-`ctx.is_suspended` reflects suspension state during replay/processing.
281
+
- Suspend pauses progress without raising inside async orchestrators.
282
+
- Terminate completes with `TERMINATED` status; use client APIs to terminate/resume.
283
+
- Only new events are buffered while suspended; replay events continue to apply to rebuild local state deterministically.
284
+
285
+
### Tracing and context propagation
286
+
287
+
The SDK surfaces W3C tracing context provided by the sidecar:
288
+
289
+
- Orchestrations: `ctx.trace_parent`, `ctx.trace_state`, and `ctx.orchestration_span_id` are available on `OrchestrationContext` (and on `AsyncWorkflowContext`).
290
+
- Activities: `ctx.trace_parent` and `ctx.trace_state` are available on `ActivityContext`.
291
+
292
+
Propagate tracing to external systems (e.g., HTTP):
- The sidecar controls inbound `traceparent`/`tracestate`. App code can append vendor entries to `tracestate` for outbound calls but cannot currently alter the sidecar’s propagation for downstream Durable operations.
306
+
- Configure the sidecar endpoint with `DURABLETASK_GRPC_ENDPOINT` (e.g., `127.0.0.1:56178`).
307
+
194
308
## Contributing
195
309
196
310
This project welcomes contributions and suggestions. Most contributions require you to agree to a
0 commit comments