ankka 0.10.0 → 0.11.0

package/dist/service.js

@@ -3,15 +3,19 @@
 // time, and reported together before anything listens — the same rule as the Scala builder.
 //
 //   await Ankka.service().register(ShoppingCartEntity).register(ShoppingCartEndpoint).listen()
+import { isStartFrom } from "./startFrom.js";
+import { Contract } from "./contract.js";
 import { codecFor, isCodec } from "./codec.js";
 import { EventSourcedEntity } from "./eventSourcedEntity.js";
 import { KeyValueEntity } from "./keyValueEntity.js";
 import { Workflow } from "./workflow.js";
 import { View } from "./view.js";
+import { KeyedView } from "./keyedView.js";
 import { Consumer } from "./consumer.js";
 import { GraphConsumer, graphDeltaCodec } from "./graph.js";
 import { TimedAction } from "./timedAction.js";
 import { Agent } from "./agent.js";
+import { serverProblems, TOOL_PREFIX } from "./mcp.js";
 import { AutonomousAgent, COMPLETE_TASK, FAIL_TASK } from "./autonomous.js";
 import { Endpoint } from "./endpoint.js";
 import { isAcl } from "./routes.js";
@@ -96,6 +100,8 @@ export class ServiceBuilder {
                 add(registerWorkflow(cls, problems), cls);
             else if (extendsBase(cls, View))
                 add(registerView(cls, problems), cls);
+            else if (extendsBase(cls, KeyedView))
+                add(registerKeyedView(cls, problems), cls);
             else if (extendsBase(cls, Consumer))
                 add(registerConsumer(cls, problems), cls);
             else if (extendsBase(cls, GraphConsumer))
@@ -123,7 +129,7 @@ export class ServiceBuilder {
                 }
             }
             else {
-                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, KeyedView, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
             }
         }
         if (problems.length > 0)
@@ -223,19 +229,59 @@ function registerWorkflow(cls, problems) {
         return undefined;
     return Object.freeze({ kind: "workflow", id: cls.componentId, cls, stateCodec: codecFor(cls.state), handlers, steps, settings });
 }
-function sourceOf(cls, fail) {
+/**
+ * What a view or consumer says about the topic it reads, checked where its other declarations are:
+ * a consumer must say where it starts, and a start position means something only for a topic. A
+ * version means something for a view whatever it reads — raising it rebuilds the view, from a topic
+ * as far back as the broker retains and from an entity from its first event — and for a consumer only
+ * over a topic, whose group it renames.
+ */
+function topicProblems(cls, consumer, fail) {
+    const readsTopic = cls.source === undefined && cls.topic !== undefined;
+    if (cls.startFrom !== undefined && !isStartFrom(cls.startFrom))
+        fail("startFrom must be StartFrom.earliest, StartFrom.latest or StartFrom.at(...)");
+    if (cls.startFrom !== undefined && !readsTopic)
+        fail("declares a start position, which applies to a topic; it reads a component");
+    if (consumer && readsTopic && cls.startFrom === undefined) {
+        fail(`reads topic ${JSON.stringify(cls.topic)} and declares no start position; declare static startFrom = StartFrom.earliest, StartFrom.latest or StartFrom.at(...)`);
+    }
+    if (cls.version !== undefined) {
+        if (typeof cls.version !== "number" || !Number.isSafeInteger(cls.version) || cls.version < 1) {
+            fail(`declares version ${String(cls.version)}; a version is a whole number of 1 or more`);
+        }
+        else if (consumer && !readsTopic)
+            fail("declares a version, which applies to a topic; it reads a component");
+    }
+    if (cls.contract !== undefined && !(cls.contract instanceof Contract))
+        fail("contract must be a Contract: Contract.fromFile(path, name)");
+    if (cls.broker !== undefined && (typeof cls.broker !== "string" || cls.broker.trim() === ""))
+        fail("broker must be the name of a broker the project declares");
+    if (cls.parallel !== undefined && typeof cls.parallel !== "boolean")
+        fail("parallel must be true or false");
+    if ((cls.contract !== undefined || cls.broker !== undefined || cls.parallel !== undefined) && !readsTopic) {
+        fail("declares a contract, a broker or parallel, which apply to a topic; it reads a component");
+    }
+}
+function sourceOf(cls, fail, consumer) {
     const hasSource = cls.source !== undefined;
     const hasTopic = cls.topic !== undefined;
     if (hasSource === hasTopic) {
         fail("needs a static source (a component class) or a static topic, and not both");
         return undefined;
     }
+    topicProblems(cls, consumer, fail);
     if (hasTopic) {
         if (typeof cls.topic !== "string" || cls.topic.trim() === "") {
             fail("topic must be a non-empty string");
             return undefined;
         }
-        return { topic: cls.topic };
+        return {
+            topic: cls.topic,
+            ...(isStartFrom(cls.startFrom) ? { startFrom: cls.startFrom } : {}),
+            ...(cls.contract instanceof Contract ? { contract: cls.contract } : {}),
+            ...(typeof cls.broker === "string" ? { broker: cls.broker } : {}),
+            ...(cls.parallel === true ? { parallel: true } : {}),
+        };
     }
     const src = cls.source;
     const kind = src?.prototype?._kind;
@@ -248,25 +294,112 @@ function sourceOf(cls, fail) {
 function registerView(cls, problems) {
     const { fail, ok } = checker(cls, problems);
     requireId(cls, fail);
-    const source = sourceOf(cls, fail);
+    const source = sourceOf(cls, fail, false);
     requireShape(cls.events, "events: a schema or codec for the source's events", fail);
     requireShape(cls.row, "row: a schema or codec for its rows", fail);
     const queries = cls.queries ?? ["get", "all"];
     if (!Array.isArray(queries) || queries.some((q) => typeof q !== "string" || q.trim() === ""))
         fail("queries must be a list of names");
+    const declared = cls.declared ?? [];
+    if (!Array.isArray(declared) || declared.some((q) => typeof q?.name !== "string" || q.name.trim() === "" || typeof q?.statement !== "string" || q.statement.trim() === "")) {
+        fail("declared must be a list of declaredQuery(name, statement)");
+    }
+    else {
+        const names = declared.map((q) => q.name);
+        const twice = names.filter((n, i) => names.indexOf(n) !== i);
+        if (twice.length > 0)
+            fail(`declares the query '${twice[0]}' twice; each query has a name of its own`);
+    }
     if (!ok() || !source)
         return undefined;
-    return Object.freeze({ kind: "view", id: cls.componentId, cls, source, eventCodec: codecFor(cls.events), rowCodec: codecFor(cls.row), queries: Object.freeze([...queries]) });
+    return Object.freeze({
+        kind: "view",
+        id: cls.componentId,
+        cls,
+        source,
+        eventCodec: codecFor(cls.events),
+        rowCodec: codecFor(cls.row),
+        queries: Object.freeze([...queries]),
+        version: cls.version,
+        declared: Object.freeze([...declared]),
+    });
+}
+function checkVersion(version, fail) {
+    if (version !== undefined && (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1)) {
+        fail(`declares version ${String(version)}; a version is a whole number of 1 or more`);
+    }
+}
+function checkDeclared(declared, fail) {
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared) || declared.some((q) => typeof q?.name !== "string" || q.name.trim() === "" || typeof q?.statement !== "string" || q.statement.trim() === "")) {
+        fail("declared must be a list of declaredQuery(name, statement)");
+        return [];
+    }
+    const names = declared.map((q) => q.name);
+    const twice = names.filter((n, i) => names.indexOf(n) !== i);
+    if (twice.length > 0)
+        fail(`declares the query '${twice[0]}' twice; each query has a name of its own`);
+    return declared;
+}
+/**
+ * A keyed view: one or more entities, each through a handler of its own. A topic is not a keyed view's
+ * source, and one entity is read once.
+ */
+function registerKeyedView(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    requireShape(cls.row, "row: a schema or codec for its rows", fail);
+    checkVersion(cls.version, fail);
+    const declared = checkDeclared(cls.declared, fail);
+    const sources = new Map();
+    const declaredSources = cls.sources;
+    if (!Array.isArray(declaredSources) || declaredSources.length === 0) {
+        fail("declares no source; a keyed view reads one or more entities, each declared with on(...)");
+    }
+    else {
+        for (const [i, s] of declaredSources.entries()) {
+            const ref = s?.source;
+            const kind = ref?.prototype?._kind;
+            if (typeof s?.onChange !== "function" || typeof ref?.componentId !== "string" || typeof kind !== "string") {
+                fail(`sources[${i}] is not a source: declare it with on(EntityClass, events, handler)`);
+                continue;
+            }
+            if (kind !== "event-sourced" && kind !== "key-value") {
+                fail(`reads ${kind} ${JSON.stringify(ref.componentId)}; a keyed view reads event sourced and key value entities`);
+                continue;
+            }
+            if (!isShape(s.events)) {
+                fail(`sources[${i}] needs a schema or codec for ${ref.componentId}'s changes`);
+                continue;
+            }
+            if (sources.has(ref.componentId)) {
+                fail(`reads ${JSON.stringify(ref.componentId)} twice; each source is read once`);
+                continue;
+            }
+            sources.set(ref.componentId, Object.freeze({ id: ref.componentId, kind, eventCodec: codecFor(s.events), onChange: s.onChange, deleted: s.deleted }));
+        }
+    }
+    if (!ok())
+        return undefined;
+    return Object.freeze({
+        kind: "keyed-view",
+        id: cls.componentId,
+        cls,
+        sources,
+        rowCodec: codecFor(cls.row),
+        version: cls.version,
+        declared: Object.freeze([...declared]),
+    });
 }
 function registerConsumer(cls, problems) {
     const { fail, ok } = checker(cls, problems);
     requireId(cls, fail);
-    const source = sourceOf(cls, fail);
+    const source = sourceOf(cls, fail, true);
     requireShape(cls.message, "message: a schema or codec for the source's messages", fail);
-    if (cls.producesTo !== undefined && (typeof cls.producesTo !== "string" || cls.producesTo.trim() === ""))
-        fail("producesTo must be a topic name");
-    if (cls.producesTo !== undefined && !isShape(cls.out))
-        fail(`produces to ${JSON.stringify(cls.producesTo)} and needs a static out: the shape of what it produces`);
+    const produces = publicationOf(cls.producesTo, fail);
+    if (produces !== undefined && !isShape(cls.out))
+        fail(`produces to ${JSON.stringify(produces.topic)} and needs a static out: the shape of what it produces`);
     if (!ok() || !source)
         return undefined;
     return Object.freeze({
@@ -276,15 +409,44 @@ function registerConsumer(cls, problems) {
         source,
         messageCodec: codecFor(cls.message),
         outCodec: cls.out ? codecFor(cls.out) : undefined,
-        producesTo: cls.producesTo,
+        producesTo: produces?.topic,
+        produces,
         graph: false,
+        version: cls.version,
     });
 }
+/**
+ * `producesTo` as declared: a topic name, or a Publication naming the topic with the contract stated
+ * for it and its broker. Undefined when the consumer produces nothing.
+ */
+function publicationOf(declared, fail) {
+    if (declared === undefined)
+        return undefined;
+    if (typeof declared === "string") {
+        if (declared.trim() === "")
+            fail("producesTo must be a topic name");
+        return declared.trim() === "" ? undefined : { topic: declared };
+    }
+    const p = declared;
+    if (typeof p !== "object" || p === null || typeof p.topic !== "string" || p.topic.trim() === "") {
+        fail("producesTo must be a topic name, or { topic, contract?, broker? }");
+        return undefined;
+    }
+    if (p.contract !== undefined && !(p.contract instanceof Contract))
+        fail("producesTo.contract must be a Contract: Contract.fromFile(path, name)");
+    if (p.broker !== undefined && (typeof p.broker !== "string" || p.broker.trim() === ""))
+        fail("producesTo.broker must be the name of a broker the project declares");
+    return {
+        topic: p.topic,
+        ...(p.contract instanceof Contract ? { contract: p.contract } : {}),
+        ...(typeof p.broker === "string" ? { broker: p.broker } : {}),
+    };
+}
 /** A graph consumer is a consumer to discovery and to the runtime: one that produces deltas to its topic. */
 function registerGraphConsumer(cls, problems) {
     const { fail, ok } = checker(cls, problems);
     requireId(cls, fail);
-    const source = sourceOf(cls, fail);
+    const source = sourceOf(cls, fail, true);
     requireShape(cls.message, "message: a schema or codec for the source's messages", fail);
     if (typeof cls.producesTo !== "string" || cls.producesTo.trim() === "")
         fail("needs a static producesTo: the topic its deltas are published to");
@@ -300,7 +462,9 @@ function registerGraphConsumer(cls, problems) {
         messageCodec: codecFor(cls.message),
         outCodec: graphDeltaCodec,
         producesTo: cls.producesTo,
+        produces: undefined,
         graph: true,
+        version: cls.version,
     });
 }
 function registerTimedAction(cls, problems) {
@@ -340,9 +504,10 @@ function registerAgent(cls, problems) {
     const maxToolCallSteps = cls.maxToolCallSteps ?? 100;
     if (!Number.isInteger(maxToolCallSteps) || maxToolCallSteps <= 0)
         fail("maxToolCallSteps must be a positive integer");
+    const { mcpServers, resultGuardrails } = collectMcp(cls, tools, fail);
     if (!ok())
         return undefined;
-    return Object.freeze({ kind: "agent", id: cls.componentId, cls, handlers, tools, guardrails, role: cls.role ?? "", maxToolCallSteps });
+    return Object.freeze({ kind: "agent", id: cls.componentId, cls, handlers, tools, guardrails, mcpServers, resultGuardrails, role: cls.role ?? "", maxToolCallSteps });
 }
 function registerAutonomousAgent(cls, problems) {
     const { fail, ok } = checker(cls, problems);
@@ -378,9 +543,39 @@ function registerAutonomousAgent(cls, problems) {
             fail(`task type ${JSON.stringify(a.taskType.name)} needs a budget of at least one iteration`);
         taskTypes.set(a.taskType.name, a.taskType);
     }
+    const { mcpServers, resultGuardrails } = collectMcp(cls, tools, fail);
     if (!ok())
         return undefined;
-    return Object.freeze({ kind: "autonomous-agent", id: cls.componentId, cls, tools, guardrails, taskTypes });
+    return Object.freeze({ kind: "autonomous-agent", id: cls.componentId, cls, tools, guardrails, mcpServers, resultGuardrails, taskTypes });
+}
+/** An agent's MCP servers and result guardrails by name, with what is wrong with them in the sidecar's words. */
+function collectMcp(cls, tools, fail) {
+    const mcpServers = new Map();
+    for (const [property, server] of Object.entries(cls.mcpServers ?? {})) {
+        if (typeof server !== "object" || server === null || typeof server.name !== "string") {
+            fail(`mcpServers.${property} is not an MCP server: declare it with mcpServer(name, options)`);
+            continue;
+        }
+        serverProblems(server).forEach(fail);
+        if (mcpServers.has(server.name))
+            fail(`MCP server '${server.name}' is listed twice`);
+        mcpServers.set(server.name, server);
+    }
+    for (const t of tools.values()) {
+        if (t.name.startsWith(TOOL_PREFIX))
+            fail(`tool '${t.name}' takes the prefix '${TOOL_PREFIX}', which names an MCP server's tools`);
+    }
+    const resultGuardrails = new Map();
+    for (const [property, g] of Object.entries(cls.resultGuardrails ?? {})) {
+        if (typeof g !== "object" || g === null || typeof g.name !== "string" || typeof g.check !== "function") {
+            fail(`resultGuardrails.${property} is not a result guardrail: declare it with resultGuardrail(name, check)`);
+            continue;
+        }
+        if (resultGuardrails.has(g.name))
+            fail(`result guardrail '${g.name}' is declared twice`);
+        resultGuardrails.set(g.name, g);
+    }
+    return { mcpServers, resultGuardrails };
 }
 /** Collects a handler table by wire name, reporting a duplicate wire name or a kind the component cannot host. */
 export function collectHandlers(table, what, allowed, fail) {

package/dist/services.d.ts

@@ -0,0 +1,137 @@
+import { type ComponentClient } from "./client.ts";
+import { type Shape } from "./codec.ts";
+/** The protocol that added calls to other services. */
+export declare const SERVICES_SINCE = "1.8";
+/** The largest body, either way, a call through the sidecar carries: under gRPC's 4 MiB. */
+export declare const MAX_BODY_BYTES = 4000000;
+/** Headers, in order; a name may appear twice. The platform's own are removed before sending. */
+export type ServiceHeaders = ReadonlyArray<readonly [string, string]>;
+/** What the service answered: its status, content type, body and headers, as it sent them. */
+export interface ServiceResponse {
+    readonly status: number;
+    readonly contentType: string;
+    readonly body: Uint8Array;
+    readonly headers: ServiceHeaders;
+    readonly text: string;
+}
+/** A call to another service that did not end in an answer a typed helper accepts. */
+export declare class ServiceError extends Error {
+    readonly service: string;
+    constructor(service: string, message: string);
+}
+/** No such service was found; nothing was sent. `reason` says what was tried. */
+export declare class ServiceUnresolvable extends ServiceError {
+    readonly reason: string;
+    constructor(service: string, reason: string);
+}
+/** What answered for the name is not the service asked for; nothing was sent. */
+export declare class ServiceIdentityMismatch extends ServiceError {
+    readonly detail: string;
+    constructor(service: string, detail: string);
+}
+/**
+ * No answer came: the connection was refused or broke, or the service's timeout passed. The service
+ * may have received the request; one that may change something was sent at most once.
+ */
+export declare class ServiceUnanswered extends ServiceError {
+    readonly reason: string;
+    constructor(service: string, reason: string);
+}
+/** The service answered with a status outside 2xx, to a typed helper. `request` returns every answer. */
+export declare class ServiceCallFailed extends ServiceError {
+    readonly status: number;
+    readonly body: string;
+    constructor(service: string, status: number, body: string);
+}
+/** One request, as a client sends it. */
+export interface ServiceRequest {
+    readonly service: string;
+    readonly project: string | undefined;
+    readonly method: string;
+    readonly path: string;
+    readonly headers: ServiceHeaders;
+    readonly contentType: string | undefined;
+    readonly body: Uint8Array | undefined;
+}
+type Send = (request: ServiceRequest, target: string) => Promise<ServiceResponse>;
+/** Calls one service. `target` is the service as it was named: `name` or `project/name`. */
+export declare class ServiceClient {
+    #private;
+    readonly target: string;
+    /** @internal */
+    constructor(send: Send, service: string, project: string | undefined);
+    /** One request, answered whatever its status. Throws only when no answer came. */
+    request(method: string, path: string, options?: {
+        body?: Uint8Array;
+        contentType?: string;
+        headers?: ServiceHeaders;
+    }): Promise<ServiceResponse>;
+    /** A JSON answer, decoded as `returns`; a status outside 2xx is a `ServiceCallFailed`. */
+    get<R>(path: string, returns: Shape<R>, options?: {
+        headers?: ServiceHeaders;
+    }): Promise<R>;
+    /** A text answer: what an endpoint returning a string sends. */
+    getText(path: string, options?: {
+        headers?: ServiceHeaders;
+    }): Promise<string>;
+    post<B, R>(path: string, body: B, shapes: {
+        body: Shape<B>;
+        returns: Shape<R>;
+    }, options?: {
+        headers?: ServiceHeaders;
+    }): Promise<R>;
+    put<B, R>(path: string, body: B, shapes: {
+        body: Shape<B>;
+        returns: Shape<R>;
+    }, options?: {
+        headers?: ServiceHeaders;
+    }): Promise<R>;
+    /** For a route answering nothing: succeeds on any 2xx. */
+    delete(path: string, options?: {
+        headers?: ServiceHeaders;
+    }): Promise<void>;
+}
+/**
+ * How a component obtains clients for other services: `this.services.service("orders")`, or
+ * `this.services.service("billing", "invoices")` for a service in another project — whether it admits
+ * this one is its own ACL's decision. The call carries the metadata of the handler that is running, so
+ * the runtime makes it as that handler: counted from it, and in its trace.
+ */
+export declare class Services {
+    #private;
+    /** Calls through `client`'s sidecar, as the handler `client` is scoped to; with none, every call throws. */
+    constructor(client?: ComponentClient);
+    service(name: string): ServiceClient;
+    service(project: string, name: string): ServiceClient;
+    /** @internal */
+    _send(request: ServiceRequest, target: string): Promise<ServiceResponse>;
+}
+/**
+ * Other services, for a unit test: each answers as the test scripted it, and every request is
+ * recorded. A call to a service nothing is scripted for fails the test, naming the service: a test
+ * whose call quietly got a default answer is no longer testing what it says.
+ */
+export declare class ScriptedServices extends Services {
+    #private;
+    readonly requests: ServiceRequest[];
+    constructor();
+    /** `name` answers with what `handler` returns; in this service's own project unless one is given. */
+    answer(name: string, handler: (request: ServiceRequest) => ServiceResponse, project?: string): this;
+    unresolvable(name: string, project?: string): this;
+    unanswered(name: string, project?: string): this;
+    mismatch(name: string, project?: string): this;
+    /** An answer of `body` as `text/plain`, for a script. */
+    static text(body: string, status?: number): ServiceResponse;
+    /** An answer of `body` as `application/json`, for a script. */
+    static json(body: string, status?: number): ServiceResponse;
+    /** @internal */
+    _send(request: ServiceRequest, target: string): Promise<ServiceResponse>;
+}
+/** Services for a unit test whose every call throws: the unit kit's default, beside `noClient()`. */
+export declare function noServices(): Services;
+/**
+ * @internal Other services, reached through `client`'s sidecar as the handler it is scoped to. Not a
+ * member of the client, which an entity holds too: only the kinds that may call one call this.
+ */
+export declare function servicesFor(client: ComponentClient): Services;
+export {};