restate（restate 命令行）

Restate Durable Execution Framework

Restate is a durable execution framework that makes applications resilient to failures. Use this skill when building:

• Durable workflows with automatic retries
• Services with persisted state (Virtual Objects)
• Microservice orchestration with transactional guarantees
• Event processing with exactly-once semantics
• Long-running tasks that survive crashes

When to Use Restate

Use Restate when:

• Building workflows that must complete despite failures
• Need automatic retry and recovery without manual retry logic
• Building stateful services (shopping carts, user sessions, payment processing)
• Orchestrating multiple services with saga/compensation patterns
• Processing events with exactly-once delivery guarantees
• Scheduling durable timers and cron jobs

Core Concepts

Service Types

Restate supports three service types:

1. Services - Stateless handlers with durable execution

- Use for: microservice orchestration, sagas, idempotent requests

1. Virtual Objects - Stateful handlers with K/V state isolated per key

- Use for: entities (shopping cart), state machines, actors, stateful event processing - Only one handler runs at a time per object key (consistency guarantee)

1. Workflows - Special Virtual Objects where run handler executes exactly once

- Use for: order processing, human-in-the-loop, long-running provisioning

See Services Concepts for detailed comparison.

Durable Building Blocks

Restate provides these building blocks through the SDK context:

• Journaled actions (ctx.run()) - Persist results of side effects
• State (ctx.get/set/clear) - K/V state for Virtual Objects
• Timers (ctx.sleep()) - Durable sleep that survives restarts
• Service calls (ctx.serviceClient()) - RPC with automatic retries
• Awakeables - Wait for external events/signals

See Durable Building Blocks.

TypeScript SDK Quick Reference

Installation

npm install @restatedev/restate-sdk

Basic Service

import * as restate from "@restatedev/restate-sdk";

const myService = restate.service({
  name: "MyService",
  handlers: {
    greet: async (ctx: restate.Context, name: string) => {
      return "Hello, " + name + "!";
    },
  },
});

restate.endpoint().bind(myService).listen(9080);

Virtual Object (Stateful)

const counter = restate.object({
  name: "Counter",
  handlers: {
    add: async (ctx: restate.ObjectContext, value: number) => {
      const current = (await ctx.get<number>("count")) ?? 0;
      ctx.set("count", current + value);
      return current + value;
    },
    get: restate.handlers.object.shared(
      async (ctx: restate.ObjectSharedContext) => {
        return (await ctx.get<number>("count")) ?? 0;
      }
    ),
  },
});

Workflow

const paymentWorkflow = restate.workflow({
  name: "PaymentWorkflow",
  handlers: {
    run: async (ctx: restate.WorkflowContext, payment: Payment) => {
      // Step 1: Reserve funds
      const reservation = await ctx.run("reserve", () =>
        reserveFunds(payment)
      );

      // Step 2: Wait for approval (awakeable)
      const approved = await ctx.promise<boolean>("approval");
      if (!approved) {
        await ctx.run("cancel", () => cancelReservation(reservation));
        return { status: "cancelled" };
      }

      // Step 3: Complete payment
      await ctx.run("complete", () => completePayment(reservation));
      return { status: "completed" };
    },

    approve: async (ctx: restate.WorkflowSharedContext) => {
      ctx.promise<boolean>("approval").resolve(true);
    },

    reject: async (ctx: restate.WorkflowSharedContext) => {
      ctx.promise<boolean>("approval").resolve(false);
    },
  },
});

Key SDK Patterns

// Journaled action - result persisted, replayed on retry
const result = await ctx.run("action-name", async () => {
  return await callExternalApi();
});

// Durable timer - survives restarts
await ctx.sleep(60_000); // 60 seconds

// Call another service
const client = ctx.serviceClient(OtherService);
const response = await client.handler(input);

// Async call (fire and forget)
ctx.serviceSendClient(OtherService).handler(input);

// Delayed call
ctx.serviceSendClient(OtherService, { delay: 60_000 }).handler(input);

// Awakeable - wait for external signal
const { id, promise } = ctx.awakeable<string>();
// Give `id` to external system, then:
const result = await promise;

// Random (deterministic)
const value = ctx.rand.random();
const uuid = ctx.rand.uuidv4();

Running Locally

1. Start Restate server:

npx @restatedev/restate-server

1. Run your service:

npx ts-node src/app.ts

1. Register service with Restate:

npx @restatedev/restate deployments register http://localhost:9080

1. Invoke handlers via HTTP:

# Service handler
curl localhost:8080/MyService/greet -H 'content-type: application/json' -d '"World"'

# Virtual Object handler (with key)
curl localhost:8080/Counter/user123/add -H 'content-type: application/json' -d '5'

# Start workflow
curl localhost:8080/PaymentWorkflow/order-456/run -H 'content-type: application/json' -d '{"amount": 100}'

Documentation References

Concepts

• Services - Service types and use cases
• Invocations - How invocations work
• Durable Execution - Execution guarantees
• Durable Building Blocks - SDK primitives

TypeScript SDK

• Overview - SDK setup and service definitions
• State - K/V state management
• Journaling Results - Side effects and ctx.run()
• Durable Timers - Sleep and scheduling
• Service Communication - Calling other services
• Awakeables - External events
• Workflows - Workflow implementation
• Error Handling - Error patterns
• Serving - Running services
• Testing - Testing strategies
• Clients - Client SDK

Guides

• Error Handling - Comprehensive error handling
• Sagas - Saga pattern with compensations
• Cron Jobs - Scheduled tasks
• Parallelizing Work - Fan-out patterns
• Databases - Database integration
• Lambda Deployment - AWS Lambda deployment

Use Cases

• Workflows
• Async Tasks
• Event Processing
• Microservice Orchestration

Operations

• HTTP Invocation
• Service Registration
• Versioning
• Architecture

Important Guidelines

1. Side effects must be wrapped in ctx.run() - External calls, random values, timestamps must go through the context to be journaled and replayed correctly.
2. State access only in Virtual Objects/Workflows - Plain Services don't have state access.
3. Handlers must be deterministic - Same inputs should produce same outputs. Use ctx.rand for randomness.
4. One handler per Virtual Object key at a time - Restate ensures consistency by queuing concurrent requests to the same key.
5. Workflows run handler executes exactly once - Use other handlers to query/signal the workflow.
6. Register services after code changes - Run restate deployments register to update handler definitions.

*Generated from Restate documentation. Run scripts/sync-docs.sh to update.*

License

The content in the references/ directory is derived from the Restate documentation and TypeScript SDK.