Federation
Federation is the server-side runtime container that manages Service lifecycle, auth, and HTTP routing.
Federation is the server-side core instance. It encapsulates HTTP routing, auth, env vars, and database infrastructure. The client-side entry is City.
Minimal Usage
import { Federation } from "@downcity/federation";
const base = new Federation({ database });Service Registration
import {
AIService,
AIChannel,
stream_openai_compatible_model,
type AIChannelStreamInput,
type AIChannelStreamResult,
} from "@downcity/federation";
class DeepSeekChannel extends AIChannel {
constructor() {
super({
id: "deepseek",
base_url: "https://api.deepseek.com",
env: { DEEPSEEK_API_KEY: "DeepSeek API Key" },
});
}
protected async stream(
input: AIChannelStreamInput,
): Promise<AIChannelStreamResult> {
const api_key = input.env("DEEPSEEK_API_KEY");
if (!api_key) throw new Error("DEEPSEEK_API_KEY is required");
return stream_openai_compatible_model(input, {
api_key,
base_url: this.base_url ?? "https://api.deepseek.com/v1",
});
}
}
const deepseek = new DeepSeekChannel();
const ai = new AIService();
ai.use(deepseek.model({ id: "deepseek-v4-flash", upstream_model: "deepseek-chat", name: "DeepSeek V4 Flash" }));
base.use(ai);See AIChannel & Model Registration.
Official Service Registration
import { AccountsService, googleAccountsProvider } from "@downcity/services";
base.use(new AccountsService({
providers: [
googleAccountsProvider(),
],
}));Routing
import { serve } from "@hono/node-server";
serve({ fetch: (request) => base.fetch(request), port: 43127, hostname: "127.0.0.1" });HTTP Middleware
Use base.middle() to register Federation-level HTTP middleware before the internal router and Action JSON parsing. The HTTP boundary generates the request ID and completes bounded body reading before dispatching middleware. Oversized bodies and body timeouts never reach middleware or business handlers. Ordinary HTTP middleware short-circuit responses also receive the boundary's x-request-id, shared by the Router and AI relay. HTTP 101 upgrades are neither rewrapped nor managed, and their x-request-id response header is not guaranteed.
FederationOptions.http enables category-based body and execution limits by default. ordinary, webhook, media, and model_stream accept partial max_body_bytes, body_timeout_ms, and execution_timeout_ms values. routes overrides exact path values and those limits. For non-SSE responses, the execution timer stays active until the response body finishes reading or is cancelled; bodyless OPTIONS requests also use the ordinary deadline. Expiry before headers returns 504; after headers have been sent, it only ends the stream. On receiving an SSE Response, the timer switches to stream_lifetime_ms, defaulting to 900_000, limiting the total time to 15 minutes measured from the end of request body reading, without buffering SSE. Model execution is also governed by 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. First output accumulates provider open and actual read waits; idle accumulates actual read waits between useful outputs. Consumer backpressure consumes neither budget, while the total wall clock keeps running. Clients cannot raise these limits through a request. The model total clock starts at provider execution, independently of the HTTP SSE clock measured from the end of body reading. Shorter provider deadlines and the default 180-second synchronous HTTP deadline still apply; whichever expires first applies. See Federation runtime for defaults and configuration.
Native /v1/ai/stream, OpenAI-compatible SSE / JSON, and every Relay language model execution share that model policy. Timeouts abort the same foreground execution without transparent retries. Timeout during provider open throws a 504 domain error with a safe Router message. Once streaming starts, native transport emits model_error (provider_timeout, status_code: 504, retryable: false); OpenAI SSE sends an error frame without a success [DONE], and JSON aggregation returns 504 on timeout. Streaming keeps the HTTP status already sent. See Calling models for useful output, terminal outcomes, and settlement rules.
Completion or cancellation releases timers, listeners, and readers without waiting for an upstream cancel that could hang indefinitely. Applications can add host policies such as CORS, security headers, and coarse rate limits through middleware. The execution deadline covers middleware. Handlers can read cancellation through ServiceRouteContext.abort_signal, Action Context.abort_signal, and the native request.signal. Adapters should combine the request signal with their own deadlines; shorter upstream deadlines still apply. Cancellation does not guarantee reversal of database operations or external side effects and does not trigger automatic retries.
base.middle(async (ctx, next) => {
const started_at = Date.now();
const response = await next();
const headers = new Headers(response.headers);
headers.set("X-Downcity-Time", String(Date.now() - started_at));
return new Response(response.body, {
status: response.status,
statusText: response.statusText,
headers,
});
}));Middleware enters in registration order and exits in reverse order. It can return a Response directly to short-circuit a request, or call await next() and then modify response headers.
Public service discovery
| Endpoint | Response |
|---|---|
GET /v1/services | Registered services with action summaries, local availability, and documentation links. |
GET /v1/services/{service_id} | One service's instruction and complete registered API documentation. |
GET /openapi.json | OpenAPI 3.1 projection of the same registration metadata. |
All three endpoints are public. Individual business routes retain their own authentication requirements. Availability describes local conditions and does not establish upstream uptime, caller permissions, or balance. See Service discovery and API documentation for response fields, curl requests, and authoring examples.
instruction aggregation
Federation can return a plain-text instruction document for the current instance:
const text = await base.instruction();The text aggregates:
- how to use the Federation itself
- which services are currently mounted
- env requirements declared by each module
- extra usage notes contributed by services
To read the same document remotely from a trusted admin side, call:
GET /v1/base/instructionThis route is admin-only and returns text/plain.
Auth
Federation automatically validates user_token and administrator session tokens. Access current user via ctx.user.
Database
ctx.db["table_name"] provides CityTableApi. Supports SQLite and PostgreSQL.