resonate-http-service-design-typescript

Resonate HTTP Service Design

SDK version: This skill reflects @resonatehq/sdk v0.11.4 (current on npm).

Overview

Use this skill to design HTTP services where route handlers start or await durable workflows. The HTTP server is the entrypoint; durable functions do the work and coordinate via Resonate. Downstream services (like a database service) expose their own durable functions and are invoked via RPC.

Architecture Model

• HTTP service: Express/Fastify server handling routes and mapping requests to durable workflows.
• Worker service: Resonate worker group that runs durable functions for business logic.
• DB service: Separate worker group exposing durable DB functions via Resonate RPC.
• Resonate Server: Durable promise store and coordination hub.

client -> HTTP routes -> Resonate Client (beginRpc/run)
         -> worker group (durable workflow)
             -> ctx.rpc -> db worker group (durable db functions)

Rules

• Route handlers are ephemeral: use Resonate Client APIs, not Context APIs.
• Durable functions are generator functions: function* with yield*.
• All external effects occur in durable steps and are awaited or explicitly detached.
• Use stable promise IDs for idempotency and replay safety.

Route Design Patterns

1) Submit and poll (async HTTP)

• POST /jobs starts a workflow and returns jobId.
• GET /jobs/:id returns status or result.

2) Submit and callback

• POST /jobs starts a workflow and returns jobId.
• External system resolves a promise when done.

3) Webhook gate

• POST /webhooks/service resolves a durable promise tied to a workflow.

Code Examples

HTTP server entrypoints (Express)

import express from "express";
import { Resonate } from "@resonatehq/sdk";
import crypto from "node:crypto";

const app = express();
app.use(express.json());

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "api",
});

// Start workflow
app.post("/jobs", async (req, res) => {
  const jobId = `job/${crypto.randomUUID()}`;

  await resonate.beginRpc(
    jobId,
    "process-job",
    req.body,
    resonate.options({ target: "poll://any@workers" })
  );

  res.status(202).json({ id: jobId });
});

// Poll status
app.get("/jobs/:id", async (req, res) => {
  const handle = await resonate.get(req.params.id);
  const result = await handle.result();
  res.json({ id: req.params.id, result });
});

// Look up a pending approval promise for a job.
// The worker records the generated promise id against the job (see below);
// this route reads it back through the db service. There is no promise-search
// method on the SDK client, so the mapping has to live in your own storage.
app.get("/jobs/:id/approval", async (req, res) => {
  const promiseId = await resonate.rpc(
    `approval-lookup/${req.params.id}`,
    "db.getApprovalPromiseId",
    req.params.id,
    resonate.options({ target: "poll://any@db" })
  );

  if (!promiseId) {
    res.status(404).json({ error: "no pending approval" });
    return;
  }

  res.json({ promiseId });
});

// Webhook: external system resolves promise
app.post("/webhooks/approval", async (req, res) => {
  const { promiseId, approved } = req.body;
  const data = Buffer.from(JSON.stringify({ approved })).toString("base64");
  await resonate.promises.resolve(promiseId, { data });
  res.status(204).end();
});