ankka 0.10.0 → 0.11.0

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),
     });
 }

package/dist/server/stateless.js

@@ -8,6 +8,7 @@ import { TimedAction as TimedActionService, TimedActionEffectSchema } from "../_
 import { codecFor } from "../codec.js";
 import { metadataFromProto, metadataToProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
+import { clientRows } from "../keyedView.js";
 import { ProtocolVersionError, requireSeveralMessages } from "../consumer.js";
 import { GRAPH_DELTA_SCHEMA, deltaRecords } from "../graph.js";
 import { JSON_CONTENT } from "../codec.js";
@@ -17,7 +18,44 @@ import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
 function messageOf(e) {
     return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
 }
+/**
+ * A keyed view's change: sent with the component it came from and no row, answered with the rows the
+ * source's handler names. The view reads its own rows through the client, on its own id.
+ */
+async function handleKeyedView(req, sourceId, ctx) {
+    const registered = ctx.registry.of("keyed-view", req.componentId);
+    if (!registered)
+        throw new ConnectError(`no keyed view ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);
+    const source = registered.sources.get(sourceId);
+    if (!source)
+        throw new ConnectError(`keyed view ${registered.id} reads no ${JSON.stringify(sourceId)}`, Code.NotFound);
+    const metadata = metadataFromProto(req.metadata);
+    const view = new registered.cls();
+    try {
+        const client = ctx.client.withMetadata(metadata);
+        view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec));
+        const effect = (req.deleted
+            ? source.deleted
+                ? await source.deleted(view)
+                : undefined
+            : await source.onChange(view, decodePayload(source.eventCodec, req.event)));
+        if (effect !== undefined && effect?.kind !== "rows")
+            throw new TypeError(`${registered.id}'s handler for ${sourceId} returned something that is not a keyed view effect`);
+        const changes = (effect?.changes ?? []).map((c) => "deleted" in c
+            ? { key: c.key, change: { case: "delete", value: {} } }
+            : { key: c.key, change: { case: "upsert", value: encodePayload(registered.rowCodec, c.row) } });
+        return create(ViewEffectSchema, { effect: { case: "rows", value: { changes } } });
+    }
+    catch (e) {
+        if (e instanceof ConnectError)
+            throw e;
+        ctx.log(`ankka: keyed view ${registered.id} on ${sourceId} ${metadata["ce-subject"] ?? "?"} threw: ${messageOf(e)}`);
+        throw new ConnectError(messageOf(e), Code.Internal);
+    }
+}
 export async function handleView(req, ctx) {
+    if (req.sourceId !== undefined)
+        return handleKeyedView(req, req.sourceId, ctx);
     const registered = ctx.registry.of("view", req.componentId);
     if (!registered)
         throw new ConnectError(`no view ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);

package/dist/server/workflow.js

@@ -114,7 +114,11 @@ class WorkflowStream {
             return failure(run.id, { message: `${registered.id}/${run.step}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest });
         }
         let effect;
-        fresh._bindCommand(this.state, commandContext(registered.id, this.entityId, 0n, {}), ctx.client);
+        // What the sidecar says about this step: its trace, and the step as the caller of whatever it calls.
+        // Carried on the step's calls as a command's is; a sidecar before 1.3 sends none.
+        const metadata = metadataFromProto(run.metadata);
+        fresh._bindCommand(this.state, commandContext(registered.id, this.entityId, 0n, metadata), ctx.client.withMetadata(metadata));
+        fresh._enterStep();
         try {
             effect = (await step.run(fresh, input));
         }

package/dist/service.d.ts

@@ -1,12 +1,16 @@
+import { type StartFrom } from "./startFrom.ts";
+import { Contract, type Publication } from "./contract.ts";
 import { type Codec } from "./codec.ts";
 import { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
 import { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
 import { Workflow, type WorkflowClass } from "./workflow.ts";
-import { View, type ViewClass } from "./view.ts";
+import { View, type DeclaredQuery, type ViewClass } from "./view.ts";
+import { KeyedView, type KeyedViewClass } from "./keyedView.ts";
 import { Consumer, type ConsumerClass } from "./consumer.ts";
 import { GraphConsumer, type GraphConsumerClass } from "./graph.ts";
 import { TimedAction, type TimedActionClass } from "./timedAction.ts";
 import { Agent, type AgentClass } from "./agent.ts";
+import { type McpServerRef, type ResultGuardrailRef } from "./mcp.ts";
 import { AutonomousAgent, type AutonomousAgentClass, type TaskType } from "./autonomous.ts";
 import { Endpoint, type EndpointClass } from "./endpoint.ts";
 import type { GuardrailRef, HandlerRef, ToolRef } from "./handlers.ts";
@@ -49,6 +53,13 @@ export type Source = {
     };
 } | {
     readonly topic: string;
+    readonly startFrom?: StartFrom;
+    /** The contract the topic is expected to carry. */
+    readonly contract?: Contract;
+    /** The declared broker the topic is on; absent is the installation's. */
+    readonly broker?: string;
+    /** Partitions handled at once, each in order. */
+    readonly parallel?: boolean;
 };
 export interface RegisteredView {
     readonly kind: "view";
@@ -58,6 +69,25 @@ export interface RegisteredView {
     readonly eventCodec: Codec<any>;
     readonly rowCodec: Codec<any>;
     readonly queries: readonly string[];
+    readonly version: number | undefined;
+    readonly declared: readonly DeclaredQuery[];
+}
+/** One source of a keyed view: the entity it reads, how its changes decode, and its handlers. */
+export interface RegisteredKeyedSource {
+    readonly id: string;
+    readonly kind: ComponentKind;
+    readonly eventCodec: Codec<any>;
+    readonly onChange: (view: any, event: any) => unknown;
+    readonly deleted: ((view: any) => unknown) | undefined;
+}
+export interface RegisteredKeyedView {
+    readonly kind: "keyed-view";
+    readonly id: string;
+    readonly cls: KeyedViewClass<any, any>;
+    readonly sources: ReadonlyMap<string, RegisteredKeyedSource>;
+    readonly rowCodec: Codec<any>;
+    readonly version: number | undefined;
+    readonly declared: readonly DeclaredQuery[];
 }
 export interface RegisteredConsumer {
     readonly kind: "consumer";
@@ -67,8 +97,11 @@ export interface RegisteredConsumer {
     readonly messageCodec: Codec<any>;
     readonly outCodec: Codec<any> | undefined;
     readonly producesTo: string | undefined;
+    /** The publication as declared: the topic with the contract stated for it and its broker. */
+    readonly produces: Publication | undefined;
     /** A graph consumer: its handlers return elements, each published as a delta under its element key. */
     readonly graph: boolean;
+    readonly version: number | undefined;
 }
 export interface RegisteredTimedAction {
     readonly kind: "timed-action";
@@ -83,6 +116,8 @@ export interface RegisteredAgent {
     readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
     readonly tools: ReadonlyMap<string, ToolRef<any, any>>;
     readonly guardrails: ReadonlyMap<string, GuardrailRef>;
+    readonly mcpServers: ReadonlyMap<string, McpServerRef>;
+    readonly resultGuardrails: ReadonlyMap<string, ResultGuardrailRef>;
     readonly role: string;
     readonly maxToolCallSteps: number;
 }
@@ -92,9 +127,11 @@ export interface RegisteredAutonomousAgent {
     readonly cls: AutonomousAgentClass<any>;
     readonly tools: ReadonlyMap<string, ToolRef<any, any>>;
     readonly guardrails: ReadonlyMap<string, GuardrailRef>;
+    readonly mcpServers: ReadonlyMap<string, McpServerRef>;
+    readonly resultGuardrails: ReadonlyMap<string, ResultGuardrailRef>;
     readonly taskTypes: ReadonlyMap<string, TaskType<any>>;
 }
-export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent | RegisteredAutonomousAgent;
+export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredKeyedView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent | RegisteredAutonomousAgent;
 export interface RegisteredEndpoint {
     readonly id: string;
     readonly cls: EndpointClass<any>;
@@ -136,6 +173,7 @@ export declare class ServiceBuilder {
     register<S, C extends KeyValueEntity<S>>(cls: KeyValueEntityClass<S, C>): this;
     register<S, C extends Workflow<S>>(cls: WorkflowClass<S, C>): this;
     register<E, Row, C extends View<E, Row>>(cls: ViewClass<E, Row, C>): this;
+    register<Row, C extends KeyedView<Row>>(cls: KeyedViewClass<Row, C>): this;
     register<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>): this;
     register<M, C extends GraphConsumer<M>>(cls: GraphConsumerClass<M, C>): this;
     register<C extends TimedAction>(cls: TimedActionClass<C>): this;