ankka 0.9.1 → 0.11.0

package/dist/keyedView.js

@@ -0,0 +1,67 @@
+// A keyed view: several entities' changes, each through a handler of its own, written to whichever rows
+// a change is about, by key. The sidecar runs one projection per source and handles one change at a
+// time across all of them; this process only says which rows each change writes.
+//
+//   export class Shipments extends KeyedView<ShipmentRow> {
+//     static readonly componentId = "shipments"
+//     static readonly row = ShipmentRowShape
+//     static readonly sources = [
+//       on(ShipmentEntity, ShipmentEvents, (v: Shipments, e) => v.onShipment(e)),
+//       on(CustomerEntity, CustomerEvents, (v: Shipments, e) => v.onCustomer(e)),
+//     ]
+//     static readonly declared = [declaredQuery("of-customer", `SELECT payload FROM ${tableOf("shipments")} WHERE ...`)]
+//     async onCustomer(event: CustomerEvent) {
+//       const theirs = await this.rows.ask("of-customer", { customer: this.subject })
+//       return this.effects.updateRows(theirs.map((r) => [r.shipmentId, { ...r, name: event.name }]))
+//     }
+//   }
+import { KeyedViewEffects } from "./effects/keyed.js";
+/**
+ * Declares a source of a keyed view: the entity whose changes it reads, the shape of those changes, and
+ * the handler for each. When the entity is deleted the view does nothing unless `deleted` names rows.
+ */
+export function on(source, events, onChange, options = {}) {
+    return Object.freeze({ source, events, onChange, ...(options.deleted ? { deleted: options.deleted } : {}) });
+}
+export class KeyedView {
+    effects = new KeyedViewEffects();
+    #metadata = {};
+    #client;
+    #rows;
+    /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
+    get metadata() {
+        return this.#metadata;
+    }
+    /** The id of the entity the change came from. */
+    get subject() {
+        return this.#metadata["ce-subject"] ?? "";
+    }
+    /** This view's own rows, by key or by one of its declared queries. */
+    get rows() {
+        if (!this.#rows)
+            throw new Error("rows are only available inside a keyed view's handler");
+        return this.#rows;
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a keyed view's handler");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "view";
+    }
+    /** @internal */
+    _bind(metadata, client, rows) {
+        this.#metadata = metadata;
+        this.#client = client;
+        this.#rows = rows;
+    }
+}
+/** The rows a keyed view reads through the component client, on its own id. */
+export function clientRows(client, viewId, row) {
+    return {
+        get: (key) => client.views.get(viewId, key, row),
+        ask: (name, values = {}) => client.views.ask(viewId, name, values, row),
+    };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,57 @@
+import { type Approval } from "./approvals.ts";
+export declare const VARIABLE_PREFIX = "ANKKA_MCP_";
+export declare const TOOL_PREFIX = "mcp__";
+type MaybePromise<T> = T | Promise<T>;
+export interface McpServerOptions {
+    /** Where the server is; `ANKKA_MCP_<NAME>_URL` replaces it, and is required when neither this nor `service` is given. */
+    readonly url?: string;
+    /** An ankka service, called as one, at `path` (by default `/mcp`), in `project` (by default this one). */
+    readonly service?: string;
+    readonly project?: string;
+    readonly path?: string;
+    /** A header's name and the `ANKKA_MCP_` variable its value is read from. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Every tool of the server waits for a person. */
+    readonly approval?: Approval;
+}
+export interface McpServerRef extends McpServerOptions {
+    readonly name: string;
+}
+/** An MCP server the agent lists under `name`, lower-case letters, digits and hyphens. */
+export declare function mcpServer(name: string, options?: McpServerOptions): McpServerRef;
+/** Checks what an MCP server's tool answered before the model is told it: a reason to withhold it, or `null`. */
+export interface ResultGuardrailRef {
+    readonly name: string;
+    readonly check: (tool: string, text: string) => MaybePromise<string | null>;
+}
+export declare function resultGuardrail(name: string, check: (tool: string, text: string) => MaybePromise<string | null>): ResultGuardrailRef;
+/** The name a server's tool is offered to the model under. */
+export declare function toolName(server: string, tool: string): string;
+/** What is wrong with one server, in the sidecar's words. */
+export declare function serverProblems(server: McpServerRef): string[];
+/** The discovery form of a server. */
+export declare function serverToProto(server: McpServerRef): {
+    name: string;
+    address: {
+        case: "url";
+        value: string;
+    } | {
+        case: "service";
+        value: {
+            name: string;
+            path: string;
+            project?: string | undefined;
+        };
+    } | {
+        value?: undefined;
+        case: undefined;
+    };
+    headers: {
+        name: string;
+        variable: string;
+    }[];
+    approval?: {
+        withinMillis?: bigint;
+    } | undefined;
+};
+export {};

package/dist/mcp.js

@@ -0,0 +1,64 @@
+// MCP servers an agent offers the model, and the guardrails that check what they answer.
+//
+// The sidecar connects to each server when it starts, reads its tools and offers them to the model as
+// `mcp__<server>__<tool>`. This process is never asked to run one, and never sees a credential: a
+// header's value is read from a variable on the sidecar, and only `ANKKA_MCP_` variables reach it. What a
+// server's tool answers is put through the agent's result guardrails, which this process answers,
+// before the model is told it.
+//
+//   static readonly mcpServers = { tickets: mcpServer("tickets", { headers: { Authorization: "ANKKA_MCP_TICKETS_TOKEN" } }) }
+//   static readonly resultGuardrails = { noInstructions: resultGuardrail("no-instructions", (tool, text) => null) }
+import { approvalProblem, approvalToProto } from "./approvals.js";
+export const VARIABLE_PREFIX = "ANKKA_MCP_";
+export const TOOL_PREFIX = "mcp__";
+const NAME = /^[a-z0-9-]+$/;
+/** An MCP server the agent lists under `name`, lower-case letters, digits and hyphens. */
+export function mcpServer(name, options = {}) {
+    return Object.freeze({ ...options, name });
+}
+export function resultGuardrail(name, check) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a result guardrail needs a name");
+    return Object.freeze({ name, check });
+}
+/** The name a server's tool is offered to the model under. */
+export function toolName(server, tool) {
+    return `${TOOL_PREFIX}${server}__${tool}`;
+}
+/** What is wrong with one server, in the sidecar's words. */
+export function serverProblems(server) {
+    const found = [];
+    const name = server.name;
+    if (!NAME.test(name))
+        found.push(`an MCP server's name is lower-case letters, digits and hyphens ([a-z0-9-]), not '${name}'`);
+    if (server.url !== undefined && server.service !== undefined)
+        found.push(`MCP server '${name}' has both a URL and a service; give one`);
+    if (server.url !== undefined && server.url.trim() === "")
+        found.push(`MCP server '${name}' needs a URL`);
+    for (const [header, variable] of Object.entries(server.headers ?? {})) {
+        if (header.trim() === "")
+            found.push(`MCP server '${name}' has a header with no name`);
+        else if (!variable.startsWith(VARIABLE_PREFIX)) {
+            found.push(`MCP server '${name}': the header '${header}' takes its value from '${variable}', which must start ${VARIABLE_PREFIX} — only those variables reach the platform's program, which is what connects to the server`);
+        }
+    }
+    const approval = approvalProblem(server.approval);
+    if (approval)
+        found.push(`MCP server '${name}': ${approval}`);
+    return found;
+}
+/** The discovery form of a server. */
+export function serverToProto(server) {
+    const approval = approvalToProto(server.approval);
+    const address = server.url !== undefined
+        ? { case: "url", value: server.url }
+        : server.service !== undefined
+            ? { case: "service", value: { name: server.service, path: server.path ?? "/mcp", ...(server.project !== undefined ? { project: server.project } : {}) } }
+            : { case: undefined };
+    return {
+        name: server.name,
+        address,
+        headers: Object.entries(server.headers ?? {}).map(([name, variable]) => ({ name, variable })),
+        ...(approval !== undefined ? { approval } : {}),
+    };
+}

package/dist/routes.d.ts

@@ -1,3 +1,4 @@
+import type { Socket } from "./socket.ts";
 import type { Shape } from "./codec.ts";
 import type { RequestContext } from "./context.ts";
 import type { Infer, Schema } from "./schema.ts";
@@ -74,8 +75,10 @@ export interface RouteRef<Ep = unknown, P = unknown, B = unknown, R = unknown> {
     readonly body: Shape<B> | undefined;
     readonly reply: Shape<R> | undefined;
     readonly streaming: boolean;
+    /** Answered by opening a socket (protocol 1.9); `run`'s third argument is then the `Socket`. */
+    readonly socket: boolean;
     readonly acl: Acl | undefined;
-    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string>;
+    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string | SseEvent>;
 }
 export declare function parseTemplate(template: string): string[];
 type NoBodyRun<Ep, T extends string, PS, R> = (self: Ep, request: RequestContext<Params<T, PS>>) => MaybePromise<R>;
@@ -100,8 +103,25 @@ export declare const del: {
     <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
     <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
 };
-/** A server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
-export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string> | Promise<AsyncIterable<string>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/**
+ * A server-sent event under a name of its own, which an `sse` handler may yield beside text: an agent
+ * turn that stops for approval ends its stream with `sseEvent("approval", requests)`. `value` is sent as
+ * JSON. Needs protocol 1.11 of the runtime.
+ */
+export interface SseEvent {
+    readonly kind: "sse-event";
+    readonly name: string;
+    readonly value: unknown;
+}
+export declare function sseEvent(name: string, value: unknown): SseEvent;
+/** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
+export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string | SseEvent> | Promise<AsyncIterable<string | SseEvent>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/**
+ * A socket route: `socket("/{room}", async (ep: Rooms, req, socket) => { for await (const t of socket) await socket.send(t) })`.
+ * The handler runs for as long as the socket is open, with the opening request as `req` throughout.
+ * Needs protocol 1.9 of the runtime.
+ */
+export declare function socket<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>, socket: Socket) => Promise<void>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, Socket, void>;
 /** The routes table type an endpoint declares. */
 export type RouteTable<Ep> = Readonly<Record<string, RouteRef<Ep, any, any, any>>>;
 export {};

package/dist/routes.js

@@ -57,7 +57,7 @@ export function parseTemplate(template) {
         throw new TypeError(`route template ${template} repeats a parameter`);
     return names;
 }
-function route(method, template, body, reply, run, options, streaming) {
+function route(method, template, body, reply, run, options, streaming, socket = false) {
     const paramNames = parseTemplate(template);
     if (typeof run !== "function")
         throw new TypeError(`route ${method} ${template}: the handler is not a function`);
@@ -68,7 +68,7 @@ function route(method, template, body, reply, run, options, streaming) {
         if (!paramNames.includes(name))
             throw new TypeError(`route ${method} ${template}: params names ${name}, which is not in the template`);
     }
-    return Object.freeze({ method, template, paramNames, paramShapes, body, reply, streaming, acl: options?.acl, run });
+    return Object.freeze({ method, template, paramNames, paramShapes, body, reply, streaming, socket, acl: options?.acl, run });
 }
 function isShape(x) {
     return typeof x === "object" && x !== null && (typeof x.kind === "string" || isCodec(x));
@@ -96,7 +96,20 @@ export const put = withBody("PUT");
 export const patch = withBody("PATCH");
 /** A DELETE route; `delete` is a reserved word, so `del`. */
 export const del = withBody("DELETE");
-/** A server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
+export function sseEvent(name, value) {
+    if (typeof name !== "string" || name === "" || /[\r\n]/.test(name))
+        throw new TypeError(`an event name must be one non-empty line, not ${JSON.stringify(name)}`);
+    return Object.freeze({ kind: "sse-event", name, value });
+}
+/** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
 export function sse(template, run, options) {
     return route("GET", template, undefined, undefined, run, options, true);
 }
+/**
+ * A socket route: `socket("/{room}", async (ep: Rooms, req, socket) => { for await (const t of socket) await socket.send(t) })`.
+ * The handler runs for as long as the socket is open, with the opening request as `req` throughout.
+ * Needs protocol 1.9 of the runtime.
+ */
+export function socket(template, run, options) {
+    return route("GET", template, undefined, undefined, run, options, false, true);
+}

package/dist/server/agent.js

@@ -84,7 +84,10 @@ export async function handleTool(req, ctx) {
     if (!registered)
         return create(ToolResultSchema, { result: { case: "error", value: `no agent ${JSON.stringify(req.componentId)} is registered` } });
     const agent = new registered.cls();
-    agent._bind(req.sessionId, {}, ctx.client);
+    // What the sidecar says about the tool's run: its trace, and the agent's handler as the caller of
+    // whatever the tool calls. A sidecar before 1.3 sends none.
+    const metadata = metadataFromProto(req.metadata);
+    agent._bind(req.sessionId, metadata, ctx.client.withMetadata(metadata));
     try {
         return create(ToolResultSchema, { result: { case: "ok", value: await runTool(registered, agent, req.tool, req.argumentsJson) } });
     }
@@ -95,11 +98,16 @@ export async function handleTool(req, ctx) {
 }
 export async function handleGuardrail(req, ctx) {
     const registered = ctx.registry.of("agent", req.componentId) ?? ctx.registry.of("autonomous-agent", req.componentId);
-    const guardrail = registered?.guardrails.get(req.guardrail);
+    // RESULT (1.11): what an MCP server's tool answered, checked by one of the agent's result guardrails,
+    // which are declared apart from its other guardrails.
+    const result = req.stage === GuardrailRequest_Stage.RESULT;
+    const guardrail = result ? registered?.resultGuardrails.get(req.guardrail) : registered?.guardrails.get(req.guardrail);
     if (!registered || !guardrail)
         return create(GuardrailResultSchema, { result: { case: "block", value: `no guardrail ${JSON.stringify(req.guardrail)} on ${req.componentId}` } });
     try {
-        const reason = await guardrail.check(req.stage === GuardrailRequest_Stage.OUTPUT ? "output" : "input", req.text);
+        const reason = result
+            ? await guardrail.check(req.tool ?? "", req.text)
+            : await guardrail.check(req.stage === GuardrailRequest_Stage.OUTPUT ? "output" : "input", req.text);
         return reason === null || reason === undefined
             ? create(GuardrailResultSchema, { result: { case: "pass", value: {} } })
             : create(GuardrailResultSchema, { result: { case: "block", value: reason } });
@@ -114,7 +122,7 @@ async function handleAutonomousTool(registered, req, ctx) {
     if (!tool)
         return create(ToolResultSchema, { result: { case: "error", value: `no tool ${JSON.stringify(req.tool)} on ${registered.id}` } });
     const agent = new registered.cls();
-    agent._bind(req.sessionId, ctx.client);
+    agent._bind(req.sessionId, ctx.client.withMetadata(metadataFromProto(req.metadata)));
     try {
         let input;
         if (isCodec(tool.input))

package/dist/server/discovery.d.ts

@@ -1,5 +1,16 @@
-import type { ConnectRouter } from "@connectrpc/connect";
+import { type ConnectRouter } from "@connectrpc/connect";
 import { type Spec } from "../_proto/ankka/protocol/v1/discovery_pb.ts";
+/**
+ * A sidecar older than 1.7 would ignore where a topic source starts and its version: a consumer
+ * declared `latest` would read everything, and a raised version would rebuild nothing. Refused,
+ * naming what declares them, rather than served wrong.
+ */
+export declare function refusal(spec: Spec, sidecarProtocol: string): string | undefined;
 /** Every problem the sidecar has reported to this process, in order. */
 export declare const problems: string[];
 export declare function discoveryRoutes(router: ConnectRouter, spec: () => Spec, log?: (message: string) => void): void;
+/** The protocol version whose runtimes serve socket routes. */
+export declare const SOCKETS_SINCE: readonly [number, number];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.9
+ * does not know a socket route, and would serve it as a plain GET. */
+export declare function socketRefusal(spec: Spec, runtime: string): string | undefined;

package/dist/server/discovery.js

@@ -1,16 +1,96 @@
 // Discovery: the first conversation. The sidecar asks what we host; we answer with the Spec the
 // registry renders. `ReportError` is how the sidecar tells us why it refused to start — logged, and kept
 // so a service can expose it (the conformance reference does, at GET /conformance/problems).
+import { Code, ConnectError } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 import { Discovery } from "../_proto/ankka/protocol/v1/discovery_pb.js";
 import { EmptySchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
+import { PROTOCOL_VERSION } from "../spec.js";
+import { olderThanContracts, olderThanDeclaredQueries, olderThanStartPositions } from "../startFrom.js";
+/**
+ * A sidecar older than 1.7 would ignore where a topic source starts and its version: a consumer
+ * declared `latest` would read everything, and a raised version would rebuild nothing. Refused,
+ * naming what declares them, rather than served wrong.
+ */
+export function refusal(spec, sidecarProtocol) {
+    return startPositionRefusal(spec, sidecarProtocol) ?? declaredQueryRefusal(spec, sidecarProtocol) ?? contractRefusal(spec, sidecarProtocol);
+}
+/**
+ * A sidecar older than 1.14 would ignore a topic's contract, broker and parallel reading and a
+ * publication's contract and broker: a contract would go unchecked, a topic on another broker would be
+ * read from the installation's. Refused at discovery, naming the components, rather than served wrong.
+ */
+function contractRefusal(spec, sidecarProtocol) {
+    if (!olderThanContracts(sidecarProtocol))
+        return undefined;
+    const declaring = spec.components
+        .filter((c) => {
+        const d = c.detail;
+        if (d.case !== "view" && d.case !== "consumer")
+            return false;
+        const src = d.value.source;
+        const onSource = src !== undefined && (src.contract !== undefined || src.broker !== undefined || src.parallel === true);
+        const onPublication = d.case === "consumer" && d.value.produces !== undefined && (d.value.produces.contract !== undefined || d.value.produces.broker !== undefined);
+        return onSource || onPublication;
+    })
+        .map((c) => c.id);
+    if (declaring.length === 0)
+        return undefined;
+    return (`${declaring.join(", ")} declare a topic's contract, broker or parallel reading, which the sidecar ignores: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.14 or later.`);
+}
+/**
+ * A sidecar older than 1.13 would ignore a view's declared queries, would read a keyed view as having
+ * no source, and would refuse a version on a view that reads an entity as applying only to a topic.
+ * Refused at discovery, naming the views, rather than found later or misreported.
+ */
+function declaredQueryRefusal(spec, sidecarProtocol) {
+    if (!olderThanDeclaredQueries(sidecarProtocol))
+        return undefined;
+    const declaring = spec.components
+        .filter((c) => {
+        if (c.detail.case !== "view")
+            return false;
+        const v = c.detail.value;
+        // A declared query, a keyed view, or a version on a view that reads an entity.
+        return v.declaredQueries.length > 0 || v.sources.length > 0 || (v.version !== undefined && v.source?.source.case === "component");
+    })
+        .map((c) => c.id);
+    if (declaring.length === 0)
+        return undefined;
+    return (`${declaring.join(", ")} declare queries, several sources, or a version on a view that reads an entity, which the sidecar ignores: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.13 or later.`);
+}
+function startPositionRefusal(spec, sidecarProtocol) {
+    if (!olderThanStartPositions(sidecarProtocol))
+        return undefined;
+    const declaring = spec.components
+        .filter((c) => {
+        const d = c.detail;
+        if (d.case !== "view" && d.case !== "consumer")
+            return false;
+        return d.value.source?.startFrom !== undefined || d.value.version !== undefined;
+    })
+        .map((c) => c.id);
+    if (declaring.length === 0)
+        return undefined;
+    return (`${declaring.join(", ")} declare where a topic source starts or its version, which the sidecar ignores: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.7 or later.`);
+}
 /** Every problem the sidecar has reported to this process, in order. */
 export const problems = [];
 export function discoveryRoutes(router, spec, log = console.error) {
     router.service(Discovery, {
         async discover(info) {
             log(`ankka: discovery from sidecar (protocol ${info.protocolVersion}, runtime ${info.runtimeVersion})`);
-            return spec();
+            const answer = spec();
+            const why = refusal(answer, info.protocolVersion) ?? socketRefusal(answer, info.protocolVersion);
+            if (why !== undefined) {
+                log(`ankka: ${why}`);
+                problems.push(why);
+                throw new ConnectError(why, Code.FailedPrecondition);
+            }
+            return answer;
         },
         async reportError(problem) {
             log(`ankka: the sidecar refused to start: ${problem.message}`);
@@ -19,3 +99,17 @@ export function discoveryRoutes(router, spec, log = console.error) {
         },
     });
 }
+/** The protocol version whose runtimes serve socket routes. */
+export const SOCKETS_SINCE = [1, 9];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.9
+ * does not know a socket route, and would serve it as a plain GET. */
+export function socketRefusal(spec, runtime) {
+    const routes = spec.endpoints.flatMap((e) => e.routes.filter((r) => r.socket).map((r) => `${e.id}.${r.id}`));
+    if (routes.length === 0)
+        return undefined;
+    const [major, minor] = runtime.split(".").map((part) => Number.parseInt(part, 10));
+    const speaks = Number.isFinite(major) && Number.isFinite(minor) ? [major, minor] : [0, 0];
+    if (speaks[0] > SOCKETS_SINCE[0] || (speaks[0] === SOCKETS_SINCE[0] && speaks[1] >= SOCKETS_SINCE[1]))
+        return undefined;
+    return `this runtime speaks protocol ${runtime || "unknown"}; a socket route needs 1.9 (${routes.join(", ")})`;
+}

package/dist/server/http.d.ts

@@ -1,9 +1,10 @@
 import type { ConnectRouter } from "@connectrpc/connect";
-import { type HttpRequest, type HttpReply, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
+import { type HttpRequest, type HttpReply, type SocketIn, type SocketOut, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
 import type { ServerContext } from "./server.ts";
 export interface HttpDispatcher {
     handle(req: HttpRequest): Promise<HttpReply>;
     handleStream(req: HttpRequest): AsyncIterable<StreamFrame>;
+    handleSocket(requests: AsyncIterable<SocketIn>): AsyncIterable<SocketOut>;
 }
 /** The behaviour behind `Http.Handle` and `Http.HandleStream`, over the registry's endpoints. */
 export declare function createHttpDispatcher(ctx: ServerContext): HttpDispatcher;

package/dist/server/http.js

@@ -5,7 +5,7 @@
 // `createHttpDispatcher` is the whole behaviour; the Connect servicer and the endpoint unit testkit both
 // call it, so a test cannot pass on a path the sidecar would not take.
 import { create } from "@bufbuild/protobuf";
-import { Http, HttpReplySchema, StreamFrameSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
+import { Http, HttpReplySchema, SocketOutSchema, StreamFrameSchema, } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
 import { codecFor } from "../codec.js";
 import { Headers, Query, metadataFromProto, withRequest } from "../context.js";
 import { CommandError, ErrorCode, httpStatusOf } from "../effects/common.js";
@@ -13,6 +13,7 @@ import { DecodingError } from "../json.js";
 import { errorCodeToProto } from "../kinds.js";
 import { HttpProblem } from "../routes.js";
 import { done, resolve } from "../schema.js";
+import { SocketClosed, socketOf } from "../socket.js";
 import { AsyncQueue } from "./queue.js";
 const utf8 = new TextEncoder();
 function textResponse(status, text) {
@@ -28,7 +29,15 @@ function principalOf(req) {
     const p = req.principal;
     if (!p)
         return null;
-    return Object.freeze({ subject: p.subject, name: p.name ?? null, email: p.email ?? null, emailVerified: p.emailVerified, roles: Object.freeze([...p.roles]) });
+    return Object.freeze({
+        subject: p.subject,
+        name: p.name ?? null,
+        email: p.email ?? null,
+        emailVerified: p.emailVerified,
+        roles: Object.freeze([...p.roles]),
+        claims: Object.freeze({ ...p.claims }),
+        issuer: p.issuer ?? null,
+    });
 }
 /** The caller the sidecar established; a sidecar that predates protocol 1.1 sends none, which reads as local. */
 function callerOf(req) {
@@ -69,6 +78,7 @@ function encodeResult(route, result) {
     const contentType = codec.contentType === "text/plain" ? "text/plain; charset=utf-8" : codec.contentType;
     return create(HttpReplySchema, { message: { case: "response", value: { status: 200, contentType, body: codec.encode(result), headers: [] } } });
 }
+const NEEDS_SOCKETS = "a socket route needs protocol 1.9; this runtime asked for a request";
 /** The behaviour behind `Http.Handle` and `Http.HandleStream`, over the registry's endpoints. */
 export function createHttpDispatcher(ctx) {
     const instances = new Map();
@@ -118,6 +128,8 @@ export function createHttpDispatcher(ctx) {
             const prep = prepare(req);
             if (!prep.ok)
                 return prep.reply;
+            if (prep.prepared.route.socket)
+                return failureReply(NEEDS_SOCKETS);
             const { route, instance, request, body } = prep.prepared;
             try {
                 const result = await withRequest(request, () => route.run(instance, request, body));
@@ -135,13 +147,21 @@ export function createHttpDispatcher(ctx) {
                 return;
             }
             const { route, instance, request } = prep.prepared;
+            if (route.socket) {
+                yield create(StreamFrameSchema, { frame: { case: "failed", value: { message: NEEDS_SOCKETS, code: errorCodeToProto(ErrorCode.Internal) } } });
+                return;
+            }
             // Produce inside the request's async context, consume here: the handler's `this.request` stays visible.
             const queue = new AsyncQueue();
             void withRequest(request, async () => {
                 try {
                     const frames = (await route.run(instance, request, undefined));
-                    for await (const text of frames)
-                        queue.push(create(StreamFrameSchema, { frame: { case: "text", value: text } }));
+                    for await (const part of frames) {
+                        if (typeof part === "string")
+                            queue.push(create(StreamFrameSchema, { frame: { case: "text", value: part } }));
+                        else
+                            queue.push(create(StreamFrameSchema, { frame: { case: "event", value: { name: part.name, data: JSON.stringify(part.value, (_k, v) => (typeof v === "bigint" ? v.toString() : v)) } } }));
+                    }
                     queue.push(create(StreamFrameSchema, { frame: { case: "completed", value: {} } }));
                 }
                 catch (e) {
@@ -155,6 +175,59 @@ export function createHttpDispatcher(ctx) {
             });
             yield* queue;
         },
+        // An open socket: `open` first, then frames until `closed`. The requests are read only when the
+        // handler asks for a frame, so a handler that does not read is not read for, and the sidecar's flow
+        // control holds the client back.
+        async *handleSocket(requests) {
+            const incoming = requests[Symbol.asyncIterator]();
+            const failed = (message, code = ErrorCode.Internal) => create(SocketOutSchema, { message: { case: "failed", value: { message, code: errorCodeToProto(code) } } });
+            const first = await incoming.next();
+            if (first.done || first.value.message.case !== "open") {
+                yield failed("a socket opens with open");
+                return;
+            }
+            const prep = prepare(first.value.message.value);
+            if (!prep.ok || !prep.prepared.route.socket) {
+                yield failed("unknown socket route", ErrorCode.NotFound);
+                return;
+            }
+            const { route, instance, request } = prep.prepared;
+            const outgoing = new AsyncQueue();
+            let closed = false;
+            const receive = async () => {
+                if (closed)
+                    return undefined;
+                const next = await incoming.next();
+                const message = next.done ? undefined : next.value.message;
+                if (message?.case === "frame" && message.value.kind.case === "text")
+                    return message.value.kind.value;
+                closed = true; // closed, the stream's end, or a kind this SDK does not know
+                return undefined;
+            };
+            const send = async (text) => {
+                if (closed)
+                    throw new SocketClosed();
+                outgoing.push(create(SocketOutSchema, { message: { case: "frame", value: { kind: { case: "text", value: text } } } }));
+            };
+            void withRequest(request, async () => {
+                try {
+                    await route.run(instance, request, socketOf(receive, send));
+                    outgoing.push(create(SocketOutSchema, { message: { case: "completed", value: {} } }));
+                }
+                catch (e) {
+                    if (e instanceof SocketClosed)
+                        outgoing.push(create(SocketOutSchema, { message: { case: "completed", value: {} } }));
+                    else {
+                        ctx.log(`ankka: SOCKET ${route.template} threw: ${messageOf(e)}`);
+                        outgoing.push(failed(messageOf(e)));
+                    }
+                }
+                finally {
+                    outgoing.close();
+                }
+            });
+            yield* outgoing;
+        },
     };
 }
 export function httpRoutes(router, ctx) {
@@ -162,5 +235,6 @@ export function httpRoutes(router, ctx) {
     router.service(Http, {
         handle: (req) => dispatcher.handle(req),
         handleStream: (req) => dispatcher.handleStream(req),
+        handleSocket: (requests) => dispatcher.handleSocket(requests),
     });
 }