DOCSEARCHbyAlgolia
Submit Docs

Restate Documentation

repository·main·Indexed 26 days ago

https://github.com/restatedev/restate

A platform for building resilient applications with distributed, durable building blocks for workflows, microservice orchestration, and event processing. Includes documentation for the Restate runtime, Helm chart installation, local cluster runner, and developer utilities such as restate-cli-util, codederror, and the restate-platform crate.

Tokens
43.3K
Snippets
55
Records
295
Agent score
87%

What's inside Restate

  1. Overview of PP-Bench

    main
    PP-Bench is a benchmark tool designed to measure the performance of the partition processor state machine replay path. It drives StateMachine::apply() directly against a real RocksDB-backed PartitionStore, bypassing Bifrost to isolate the state-machine and storage performance from networking, invoker, and scheduler overhead. It measures throughput, latency, CPU, and memory usage in isolation.

  2. Overview of the DataFusion Query Engine in Restate

    main

    Restate integrates Apache DataFusion to provide SQL querying capabilities over internal state. The query engine is exposed via the /query endpoint on the admin service and is used by:

    • CLI: The restate sql command for interactive queries.
    • Web UI: For introspecting invocations, state, and other system data.

    Users can use standard SQL to inspect invocation status, state, journals, and other internal data.

  3. Overview of the restate-platform crate

    main
    The restate-platform crate serves as the foundation for the Restate project. It is designed to be a lightweight dependency at the bottom of the dependency graph, providing key type aliases, traits, and essential types. It is intended to be used by other crates in the workspace to ensure safe and reliable dependencies without introducing heavy transitive dependencies like serialization frameworks, async runtimes, or storage engines.

  4. Overview of Restate build outputs and distribution channels

    main

    Restate's build system generates several types of artifacts for different environments:

    Build Outputs

    • Docker images: Multi-arch (linux/amd64, linux/arm64) images for restate-server and restate-cli.
    • Static binaries: MUSL-linked Linux binaries and macOS binaries (supporting both x86_64 and aarch64).
    • Helm chart: Kubernetes deployment chart published to GHCR.

    Distribution Channels

    • GitHub Releases: Binary archives with checksums.
    • Docker registries:
      • GHCR: ghcr.io/restatedev/restate, ghcr.io/restatedev/restate-cli
      • Docker Hub: docker.io/restatedev/restate
    • Homebrew: Via the restatedev/homebrew-tap repository.
    • npm: @restatedev/restate, @restatedev/restate-server, @restatedev/restatectl.
    • Helm OCI registry: ghcr.io/restatedev/restate-helm.

  5. Use the Local Cluster Runner to run Restate nodes

    main

    The Local Cluster Runner is a tool for running clusters of Restate nodes on a local machine. It automates port allocation (ingress, admin, pgsql), uses Unix sockets for node services, and wires up metadata clients automatically.

    When a cluster is running, the runner creates the following files in the base directory:

    • $BASE_DIR/$NODE_NAME/config.toml: The node configuration (passed via RESTATE_CONFIG).
    • $BASE_DIR/$NODE_NAME/fabric.sock: The gRPC node service (advertised as an absolute Unix path).
    • $BASE_DIR/$NODE_NAME/restate.log: The stdout and stderr of the server process.

  6. Understand npm Distribution Architecture

    main

    The @restatedev/restate npm package is a TypeScript wrapper that provides a platform-agnostic interface. It uses a platform-specific binary architecture to ensure compatibility without requiring postinstall network requests.

    Package Structure:

    • @restatedev/restate: The base package containing the TypeScript wrapper.
    • Optional Dependencies: The wrapper detects the current OS and architecture (os.platform(), os.arch()) and automatically resolves the correct binary from these packages:
      • @restatedev/restate-linux-x64
      • @restatedev/restate-linux-arm64
      • @restatedev/restate-darwin-x64
      • @restatedev/restate-darwin-arm64

    This approach allows for hosting binaries directly on npm and supports --tag next for pre-releases.

  7. Understand the HTTP/2 Connection Pool architecture

    main

    The Restate service-client uses a hierarchical, multiplexed HTTP/2 connection pool designed for high-throughput service-to-service communication. The architecture is organized into three layers:

    1. Pool: The top-level entry point. It routes requests to an AuthorityPool based on the (scheme, authority) key using a concurrent DashMap.
    2. AuthorityPool: Manages multiple Connection instances for a specific HTTP authority. It handles scaling (up to max_connections), load balancing across existing connections, and back-pressure.
    3. Connection: A single HTTP/2 session. It uses lazy initialization, performing the H2 handshake only on the first request. It manages concurrency via a semaphore that respects the remote peer's MAX_CONCURRENT_STREAMS limit.

  8. Use restate-util-random for non-cryptographic randomness

    main

    The restate-util-random crate provides lightweight, dependency-free pseudo-random utilities designed for use inside Restate crates. It uses a thread-local xorshift* generator seeded from a process-wide counter.

    Warning: This is NOT a cryptographically secure PRNG. Do not use this for security-sensitive operations like generating tokens, nonces, or keys. Each thread has its own seed, so randomness is not reproducible across threads.

  9. Understand the Restate CI Pipeline and Integration Tests

    main

    The Restate CI pipeline consists of several key jobs triggered by PRs, pushes to main, or releases.

    Core Jobs:

    • workspace-hack-check: Verifies cargo-hakari workspace-hack is up to date.
    • build-and-test: Runs just verify (includes linting, testing, and doctests).
    • docker: Builds the Docker image and uploads it as a restate.tar artifact.

    Integration Testing: After the Docker build, integration tests are run against the built image for various SDKs:

    • sdk-java, sdk-python, sdk-go, sdk-typescript, sdk-rust
    • e2e: End-to-end tests from restatedev/e2e.
    • jepsen: Distributed systems tests (runs on main branch only).

    Artifact Flow: Integration tests use a restate.tar OCI tarball artifact. The docker job builds it, and SDK/e2e jobs download and docker load it to run tests against the specific commit being tested.

  10. Use CodedError to add metadata to errors

    main
    CodedError is an extension of thiserror that allows you to attach machine-readable error codes and human-readable hints to your error types. This is useful for providing structured error metadata that can be used for programmatic handling or improved debugging.

  11. Understand Restate observability and symbol management

    main

    Restate uses several tools for analytics and debugging support:

    Analytics

    • Scarf Gateway: Homebrew formulae and GitHub release notes use restate.gateway.scarf.sh for anonymous download statistics. npm packages use @scarf/scarf.

    Debugging and Profiling

    Restate Docker images are optimized for size by stripping debug symbols, but support rich profiling via Polar Signals / Parca:

    1. Automatic Profiling: Symbols are uploaded to grpc.polarsignals.com during build. Symbols are resolved automatically via debuginfod when using Parca.
    2. Manual Symbol Download: If you need to debug with other tools, you can use the script provided inside the Docker image to fetch symbols by build ID: /usr/local/bin/download-restate-debug-symbols.sh

  12. Run synthetic workloads with PP-Bench

    main

    You can run benchmarks using synthetic workloads (patch-state or invoke) which are generated in-memory.

    Workload Types:

    • patch-state: Exercises state table reads/writes and virtual object status lookups. Simplest workload.
    • invoke: Exercises invocation status table, journal table, virtual object locking, inbox, and outbox.

    Example: Quick one-shot benchmark

    RUST_LOG=warn cargo run --release -p pp-bench -- \
    run --workload patch-state --num-commands 1000000 --batch-size 10

    Example: Separated workflow (Generate -> Inspect -> Run)

    # 1. Generate commands
cargo run --release -p pp-bench -- \
    generate -o commands.bin --workload invoke --num-commands 1000000

# 2. Inspect the file
cargo run --release -p pp-bench -- inspect commands.bin

# 3. Run from the file
RUST_LOG=warn cargo run --release -p pp-bench -- \
    run --command-file commands.bin --batch-size 10