Skip to content

Add Python/Rust durable-workflows reference to the coding-agent skill#306

Closed
chrnorm wants to merge 1 commit into
restatedev:mainfrom
chrnorm:add-python-rust-durable-workflows-reference
Closed

Add Python/Rust durable-workflows reference to the coding-agent skill#306
chrnorm wants to merge 1 commit into
restatedev:mainfrom
chrnorm:add-python-rust-durable-workflows-reference

Conversation

@chrnorm

@chrnorm chrnorm commented Jun 10, 2026

Copy link
Copy Markdown

What

Adds references/durable-workflows-python-rust.md to the building-restate-services skill (both restate-plugin/src/ and the generated restate-plugin/skills/ copy — the new file has no CODE_LOAD tags, so the copies are identical), plus one routing row in SKILL.md.

Why

Stephan asked us to contribute the Restate skill we use internally with Claude Code so it can be merged into the public one. This is that content, with examples genericized to order/payment processing. We built it while writing long-running workflows (multi-minute activities, polling external systems, operator-approval signals) in Python, then porting toward Rust.

Content the existing references don't cover yet:

  • Rust SDK — there is no references/rust/ today. Covers the trait macro, the ctx.run builder, the ~50s default RunRetryPolicy.max_duration foot-gun (vs Python's retry-forever), ServiceOptions timeouts, select!/DurableFuturesUnordered, testcontainers, and a Python↔Rust cheat sheet for porting.
  • Polling-loop vs single retrying ctx.run — when each is appropriate, and why raising synthetic errors for successful-but-InProgress observations pollutes backing-off status and retry alerting.
  • Journal hygiene — entries per poll iteration, accumulate-then-set state, deterministic action names and error 570.
  • Inactivity/abort timeouts for activities longer than the default ~11 min budget.
  • Assorted pitfalls: ctx.get needs type_hint= with Pydantic, never except Exception in handlers, deadlock between exclusive VirtualObject handlers.

Written against server 1.6.2, Python SDK 0.15.0, Rust SDK 0.9.0.

Notes for maintainers

Opened as a draft on purpose: structure it however fits — e.g. split the Rust half into references/rust/api-and-pitfalls.md (plus Cargo.toml detection in SKILL.md) and fold the Python sections into references/python/api-and-pitfalls.md. Happy to do that restructuring in this PR if you'd prefer; otherwise feel free to take the content and edit freely.

🤖 Generated with Claude Code

A deep-dive reference built while writing long-running Restate workflows
in Python and Rust, contributed upstream so it can be merged into
building-restate-services. Notable content not yet covered by the
existing references: Rust SDK coverage (no rust/ reference exists yet),
the ~50s default RunRetryPolicy max_duration foot-gun, polling-loop vs
backing-off semantics, journal hygiene, and a Python<->Rust cheat sheet.

Co-Authored-By: Claude <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

@chrnorm chrnorm closed this Jun 10, 2026
@github-actions github-actions Bot locked and limited conversation to collaborators Jun 10, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant