Service and Action

How Service, Action, the unified route space, and AIService relate inside @downcity/federation.

Service and Action are the main business organization units inside @downcity/federation.

Keep one sentence in mind:

a Service is a long-lived group of capabilities, and an Action is the concrete callable entry.

What this concept means

Every Action is simultaneously:

  • a business entry point
  • an HTTP route node
  • a hook target
  • an auth boundary

When you should write a custom service

  • you want city business actions, not raw model inference only
  • you want one business entry shared across frontend, app, and internal tools
  • you want that capability to participate in hooks, auth, usage, and service governance

Typical examples:

  • rewriting content
  • generating reports
  • running workflows
  • processing business data

When AIService is the better starting point

If you mainly want to expose text, stream, image, or video, then AIService is usually the cleaner first mental model.

Minimal custom service example

import { Federation, Service } from "@downcity/federation";

const base = new Federation({ database });

const translate = new Service({
  id: "translate",
  name: "Translate",
});

translate.action("zh2en", async (ctx) => {
  return {
    text: await runTranslate(String(ctx.input.text ?? ""), "en"),
  };
});

translate.action("list", async () => {
  return {
    items: ["zh2en"],
  };
}, {
  method: "GET",
});

base.use(translate);

How routes are exposed

Those Actions automatically enter the shared route space:

POST /v1/translate/zh2en
GET  /v1/translate/list

That is why the product side can stay unified:

const result = await client
  .service("translate")
  .action("zh2en")
  .invoke<{ text: string }>({
    text: "Hello Downcity",
  });

const list = await city.service("translate").get("list");

Common scenarios

Scenario 1: city business action

const writer = new Service({ id: "writer", name: "Writer" });

writer.action("draft", async (ctx) => {
  return {
    title: "Draft",
    topic: ctx.input.topic,
  };
});

Scenario 2: admin-only action

writer.action("remove", async (ctx) => {
  await removeDraft(String(ctx.input.id));
  return { ok: true };
}, {
  auth: ["admin"],
});

Scenario 3: guest entry

writer.action("webhook", async (ctx) => {
  await verify_webhook(ctx.raw_body ?? "");
  return { accepted: true };
}, {
  auth: [],
  body: "raw",
});

Document a Service and its entries

new Service({ id, name, description, requirements, availability }) declares public service metadata. Actions accept options.documentation for descriptions, request and response schemas, errors, examples, protocol details, requirements, and local readiness checks. Installable routes declare the same documentation alongside their handler.

Federation exposes these declarations through the public service directory and OpenAPI document. See Service discovery and API documentation for discovery requests, all fields, and complete authoring examples.

Action body modes

service.action(name, handler, options?) accepts optional body: "json" | "raw". POST Actions default to "json": empty or whitespace-only input becomes {}, and every non-empty body must be a JSON object. Invalid JSON returns 400 INVALID_JSON; arrays, null, and other JSON primitives return 400 INVALID_INPUT. A body read failure returns 400 INVALID_BODY. GET Actions read query parameters.

Use body: "raw" for webhook signatures or other text protocols. A regular Action reads the original text from ctx.raw_body; its ctx.input starts as {}. Installable Service ctx.route({ method, path, body?, handler }) supports the same optional body mode for Action handlers. Inside that route handler, ctx.text() returns the original text and ctx.json() still strictly parses a JSON object on demand, accepting empty or whitespace-only text as {}.

Installable native routes use handler: { request }. Their bodies also undergo one bounded read at the HTTP boundary before the Request is rebuilt from the original bytes without Action JSON parsing. body is only an Action option. Native OAuth form submissions, callbacks, and redirects use their own protocols. Body size, read deadlines, and encoding validation also apply to native routes; see HTTP API.

Request context and failures

For HTTP Actions, ctx.request_id and ctx.locals.request_id contain the server-generated req_<UUID>, assigned at the HTTP boundary before middleware runs. x-request-id, the Router, and AI relay share that ID; caller-supplied IDs are ignored. Ordinary HTTP middleware short circuits and 413, 408, 504 responses also carry it. HTTP 101 upgrades are neither rewrapped nor managed, and their x-request-id response header is not guaranteed.

Action Context.abort_signal and Installable ServiceRouteContext.abort_signal are readable; native handlers can use request.signal. Adapters should combine request cancellation with their own deadlines; shorter upstream deadlines still apply. Client cancellation corresponds to 499 REQUEST_CANCELLED, but disconnected clients are not guaranteed to receive a response. Cancellation is cooperative: database operations may continue, transactions are not automatically rolled back, and no automatic retry is triggered. Queued image tasks do not inherit foreground request cancellation.

Framework-caught errors use error: { code, message, type, request_id }. Explicit 4xx httpError messages are preserved; all 5xx messages are generic. An explicit integer statusCode from 400 through 599 preserves a code matching ^[A-Za-z][A-Za-z0-9_]{0,63}$, including 503 async_dispatch_unavailable. A missing or invalid status becomes 500 INTERNAL_ERROR regardless of any supplied code. See HTTP API for defaults and messages.

Business and native handlers own the bodies of error Responses returned directly; the HTTP boundary still overwrites x-request-id. The framework does not buffer complete response bodies or SSE. After streaming starts, boundary timeout or cancellation aborts downstream work, cancels the reader, and ends the stream without changing the HTTP status, returning JSON, or synthesizing generic SSE error frames. An onError hook failure does not replace the original error.

The model layer uses server-side AIServiceOptions.model_stream?: Partial<AIModelStreamPolicy>, defaulting to 120 seconds for response-stream establishment (not TCP connection), 120 seconds for first useful output, 120 seconds for idle, and 15 minutes total. Native model streams, OpenAI SSE / JSON, and every Relay language model execution share the policy; clients cannot raise deadlines through a request. First output accumulates provider open and actual read waits; idle accumulates actual read waits between useful outputs. Backpressure consumes neither budget, while the total wall clock keeps running. The HTTP SSE total clock starts at the end of request body reading; the model total clock starts at provider execution. Both apply independently, together with shorter provider deadlines and the default 180-second synchronous HTTP deadline; whichever expires first applies.

Model timeouts use provider_timeout / 504 and timeout_phase: connect (waiting for a response stream, not TCP connection), first_output, idle, or total. Only connect and first-output expiry are transient (retryable: true); Agent also checks partial output and its default 900-second recovery budget. Budget expiry uses timeout_phase: "recovery_budget", retryable: false, and Model recovery budget exhausted; other model timeouts use the safe message Model provider timed out. retry_at_ms preserves the upstream retry deadline; warning next_retry_at_ms identifies a scheduled attempt. Before response start, timeout returns 504; an already-started native stream emits model_error without changing the HTTP status. A framework model_start may precede a failure terminal without fabricating usage. OpenAI SSE sends an error frame without a success [DONE]; JSON aggregation returns 504.

Completion or cancellation releases timers, listeners, and readers without waiting for an upstream cancel that could hang indefinitely. Trustworthy usage facts are retained; missing usage does not lead to estimated tokens or costs. Existing bill callbacks use actual facts, and business charging rules do not promise zero charges in every case without usage. completion.outcome explicitly distinguishes succeeded, failed, and cancelled. A cancel after the terminal event does not relabel the result as cancellation or timeout, or duplicate settlement or charges. Underlying SQL side effects are not guaranteed to roll back. See Calling models for useful output and the full policy.

Common API surface

  • new Service({ id, name })
  • service.action(name, handler, options?)
  • options.method?: "GET" | "POST"
  • options.body?: "json" | "raw" (POST defaults to "json")
  • options.auth: ["user"] | ["admin"] | []
  • options.documentation?: ApiDocumentation
  • base.use(service)
  • city.service(id).action(name).invoke(input)
  • city.service(id).get(path, query?)

Common misunderstandings

An Action is not just a function

It eventually becomes a route, an auth boundary, a hook target, and a usage recording point.

Official services and custom services do not need separate call patterns

From the product side, both still go through city.service("service_id").action("action_id").invoke(...).

GET and POST are not cosmetic

Read-oriented operations fit GET better. Execution and mutation fit POST better.