OpenParable
Skip to content
← Back to skills

Reviewing Restate Handlers

Testing & Quality
reviewing-restate-handlers

Reviewing Restate Handlers is an Agent Skill for testing & quality published in the unkeyed/unkey repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Reviews restate handler code in svc/ctrl/worker to find restate client calls (service calls, state access, sleep, etc.) incorrectly placed inside restate.Run, restate.RunVoid, or restate.RunAsync closures. Use when reviewing restate handlers, checking restate.Run usage, or auditing worker service code.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/unkeyed/unkey/blob/HEAD/.agents/skills/reviewing-restate-handlers/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/reviewing-restate-handlers, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Reviewing Restate Handlers

Audit restate handler code to ensure the outer restate context is never used inside restate.Run, restate.RunVoid, or restate.RunAsync closures.

Background

Restate journals every interaction with its context for deterministic replay. The restate.Run / restate.RunVoid / restate.RunAsync functions wrap non-deterministic side effects (DB queries, HTTP calls, etc.) into a single journaled step. Inside these closures, the only context available is restate.RunContext, which is a plain context.Context — it has no restate capabilities.

If the outer restate context (the handler's ctx parameter, typed as restate.Context, restate.ObjectContext, restate.WorkflowContext, restate.WorkflowSharedContext, etc.) is used inside a Run closure, it can break replay determinism and cause subtle bugs that are very hard to diagnose.

What to check

Scan all .go files under svc/ctrl/worker/ for closures passed to:

  • restate.Run(ctx, func(rc restate.RunContext) ...)
  • restate.RunVoid(ctx, func(rc restate.RunContext) ...)
  • restate.RunAsync(ctx, func(rc restate.RunContext) ...)

Inside each closure body, flag any reference to the outer restate context variable. The outer context is typically the handler function's first parameter (often named ctx) whose type is one of:

  • restate.Context
  • restate.ObjectContext
  • restate.ObjectSharedContext
  • restate.WorkflowContext
  • restate.WorkflowSharedContext

Violations — using the outer ctx inside the closure

These are forbidden inside restate.Run / restate.RunVoid / restate.RunAsync:

  1. Service calls via the restate context: e.g., hydrav1.NewVersioningServiceClient(ctx, ...) — the first argument to generated service client constructors is the restate context
  2. State access: restate.Get(ctx, ...), restate.Set(ctx, ...)
  3. Sleep: restate.Sleep(ctx, ...)
  4. Nested Run: restate.Run(ctx, ...) inside another restate.Run
  5. Key access: restate.Key(ctx)
  6. Async operations: restate.RunAsync(ctx, ...), sending messages via .Send()
  7. Any other method or function that takes the outer ctx where ctx is a restate context type

Allowed — using the closure's RunContext

Inside the closure, code should use the restate.RunContext parameter (often named rc, runCtx, or stepCtx) for:

  • Database queries: db.Query.Something(runCtx, ...)
  • Transactions: db.TxRetry(runCtx, ...)
  • External API calls: s.vault.Encrypt(runCtx, ...)
  • Any operation that needs a context.Context

Not a violation

  • Using the outer ctx outside of restate.Run closures is correct and expected
  • Passing plain values (not the context) captured from outer scope into the closure is fine
  • Using restate.TerminalError(...) inside a closure is fine (it doesn't take a context)

Procedure

  1. Use Grep to find all files containing restate.Run, restate.RunVoid, or restate.RunAsync under svc/ctrl/worker/
  2. Read each file
  3. For each closure passed to Run/RunVoid/RunAsync, identify:
    • The outer restate context variable name and type (from the enclosing handler function signature)
    • The closure's RunContext parameter name
  4. Check if the outer context variable appears anywhere in the closure body
  5. Report each violation with file, line, and what the fix should be (either move the call outside the closure, or replace ctx with the closure's RunContext if the call only needs a context.Context)

Output format

For each violation found, report:

FILE:LINE — `ctx` used inside restate.Run/RunVoid/RunAsync
  Outer context: `ctx restate.ObjectContext` (from handler function signature)
  Violation: `someFunction(ctx, ...)` should use `runCtx` or be moved outside the closure

If no violations are found, report: "No restate context violations found."