ankka 0.10.0 → 0.12.0

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) {
@@ -38,6 +47,8 @@ function callerOf(req) {
             return Object.freeze({ kind: "gateway" });
         case "service":
             return Object.freeze({ kind: "service", project: kind.value.project, name: kind.value.name });
+        case "machine":
+            return Object.freeze({ kind: "machine", organization: kind.value.organization, name: kind.value.name });
         default:
             return Object.freeze({ kind: "local" });
     }
@@ -69,6 +80,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 +130,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 +149,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 +177,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 +237,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,16 +8,55 @@ 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";
 import { errorCodeToProto } from "../kinds.js";
 import { decodePayload, encodePayload } from "./payloads.js";
 import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
+import { standingFromProto } from "../standing.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), standingFromProto(req.standing));
+        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);
@@ -25,7 +64,7 @@ export async function handleView(req, ctx) {
     const view = new registered.cls();
     try {
         const row = req.row ? decodePayload(registered.rowCodec, req.row) : null;
-        view._bind(row, metadata, ctx.client.withMetadata(metadata));
+        view._bind(row, metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
         const effect = req.deleted ? await view.onDelete() : await view.onChange(decodePayload(registered.eventCodec, req.event));
         switch (effect.kind) {
             case "update-row":
@@ -64,7 +103,7 @@ function produceAll(request, messages) {
 }
 async function graphEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
-    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
     switch (effect.kind) {
         case "publish":
@@ -83,7 +122,7 @@ async function graphEffect(registered, req, metadata, ctx) {
 }
 async function consumerEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
-    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
     const outCodec = () => {
         if (!registered.outCodec)

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";
@@ -24,6 +28,8 @@ export interface RegisteredEventSourced {
     readonly eventCodec: Codec<any>;
     readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
     readonly snapshotEvery: number;
+    /** Declared replicated (1.19). */
+    readonly replicated: boolean;
 }
 export interface RegisteredKeyValue {
     readonly kind: "key-value";
@@ -49,6 +55,15 @@ 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;
+    /** Another project's topic: the project whose topic it is (1.15). */
+    readonly project?: string;
+    /** Partitions handled at once, each in order. */
+    readonly parallel?: boolean;
 };
 export interface RegisteredView {
     readonly kind: "view";
@@ -58,6 +73,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 +101,13 @@ 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;
+    /** Given a replicated entity's mirrored changes too (1.19). */
+    readonly mirroredChanges: boolean;
 }
 export interface RegisteredTimedAction {
     readonly kind: "timed-action";
@@ -83,6 +122,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 +133,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 +179,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;