@alpamayo-solutions/colca-client 0.0.0 → 0.2.0

package/README.md

@@ -1,5 +1,145 @@
 # @alpamayo-solutions/colca-client
 
-The TypeScript client for [Colca](https://github.com/alpamayo-solutions/colca).
-This version only holds the name. The first real release is published from the
-repository's CI, with provenance.
+A Colca node's door, in TypeScript: records over HTTP — `fetch`, `ack`,
+`publish`, `kv`, `self` — and live values over MQTT. No runtime dependencies
+for the door, no framework, no opinion about how your service is built.
+
+```sh
+npm install @alpamayo-solutions/colca-client
+```
+
+## A consumer
+
+```ts
+import { Door, Stream } from "@alpamayo-solutions/colca-client";
+
+const door = new Door({ baseUrl: "http://colca", service: "my-app" });
+const panels = new Stream(door, "annotations", door.cursorName("panels"), {
+  prefix: "wisewoods/line1",
+});
+
+for await (const record of panels.follow()) {
+  // Acked page by page: a handler that throws sees its page again.
+  console.log(record.topic, record.payload);
+}
+```
+
+## A producer
+
+```ts
+await door.publishTo(
+  { root: "steine", contract: "_Metric", node: "n-technikum", path: "wisewoods/line1/mas2/grit" },
+  { signal_id: "01M2AB…", timestamp: Date.now() / 1000, value: 60 },
+);
+```
+
+## Live values
+
+`@alpamayo-solutions/colca-client/live` keeps one MQTT connection to the node's
+WebSocket door for people and applications, and hands out values as they change.
+
+```sh
+npm install mqtt
+```
+
+```ts
+import { Live } from "@alpamayo-solutions/colca-client/live";
+
+const live = new Live({
+  url: "wss://node:8885",
+  // Asked before every connection, so hand back a token that is valid now.
+  token: () => auth.freshToken(),
+});
+
+const stop = live.subscribe("steine/v1/_Metric/n-technikum/wisewoods/#", (value) => {
+  show(value.topic, value.payload);
+});
+live.onState((state) => showOffline(state !== "online"));
+```
+
+Data and entity paths are retained at the node, so a subscription starts with
+the current values and continues with the changes; nothing has to be fetched
+first. Around that the client does what a page left open all day needs:
+
+- **One connection for the whole page.** `subscribe` returns the function that
+  ends that subscription and no other; the node's subscription goes when the
+  last listener on a filter does.
+- **A second subscriber gets the value at once.** The client keeps the last value
+  of every topic, and `latest()` and `values()` read it.
+- **A fresh token before the old one runs out.** The node ends a session when its
+  token expires. The client reconnects shortly before, with a new token and every
+  subscription sent again, and stays `online` while doing so.
+- **Waits that grow after a drop**, jittered, each attempt with a fresh token.
+
+These are values, not a log. A change during a reconnect is superseded by the
+retained value that follows it. Whatever must see every record reads a stream
+through the door.
+
+### Commands
+
+A person's session sends commands, not values. `command()` sends one and waits
+for the executor's `_Ack`:
+
+```ts
+const ack = await live.command("steine/v1/_CmdParam/n-technikum/wisewoods/line1/mas2/sta1/aggos/setGrit", {
+  params: { signal: "grit", value: 120 },
+});
+if (ack.result_code !== 200) showRefusal(ack.message);
+```
+
+It adds the correlation id and the expiry, subscribes to the acknowledgements
+before it sends, so an executor that answers at once is not missed, and matches
+the answer by its id wherever in the tree it arrives. The promise settles with
+the `_Ack` whatever its result code, and rejects with `CommandTimeout` when
+nobody answers in time (30 s by default, which is also the command's expiry).
+Offline, nothing is queued: a setpoint sent minutes late is a different
+setpoint.
+
+`publish()` sends a single record without waiting, and `newUlid()` makes ids
+that sort by the time they were made, as the node's own do.
+
+## Which door, which credential
+
+| Door      | URL                                                     | Credential                                                        |
+| --------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| local     | `http://colca` (port 80, inside the deployment network) | none — reachability is the credential; `service` names the caller |
+| published | `https://node:443`                                      | a person's bearer token, or a machine's pinned client certificate |
+
+A client certificate is a TLS matter, so it belongs to the runtime rather than
+to this package: hand in a `fetch` that carries it (`options.fetch`).
+
+## Things the node insists on
+
+- **Cursors belong to their caller.** They are named `c/{service}/…`, which is
+  what `door.cursorName()` builds; the node refuses any other name.
+- **Fetching never moves a cursor.** Only `ack` does, and only forward. `tail`
+  reads the end of a stream without touching it, which is what a view wants.
+- **A gap is not an error.** When records were pruned below the cursor, the page
+  says so. `Stream` passes it to `onGap` and acks past it, so it is reported
+  once rather than forever.
+- **The node decides what you see.** `/fetch` and `/kv` filter by the caller's
+  read grants; a publish is judged against its zone and grants. A 403 carries
+  the node's reason.
+
+## Ids
+
+`deriveAnnotationId()` computes an annotation's id the way the node's own
+contracts package does. It is derived rather than drawn so that create, update
+and delete of one annotation are appends under the same id — a producer that
+runs twice overwrites its own record instead of doubling it.
+
+The agreement is checked against `clients/spec/vectors.json`, generated from
+`colca-data-contracts`. If a rule changes there, the tests here fail.
+
+## Development
+
+```sh
+npm install
+npm run lint
+npm run typecheck
+npm test
+npm run build
+```
+
+The wire format itself is documented in
+[HTTP API](https://alpamayo-solutions.github.io/colca/http-api/).

package/dist/door.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The door's HTTP client: `GET /fetch`, `POST /ack`, `GET /kv`, `GET /self`
+ * and `POST /publish`. One class, no runtime dependencies — the platform's
+ * `fetch` does the work.
+ *
+ * Which door a client talks to is decided by the URL and the credential:
+ *
+ * - the local door (`http://colca`, port 80 inside the deployment network) has
+ *   no credential. The caller names itself with `X-Colca-Service` and the door
+ *   registers it on first sight;
+ * - the published door (`https://node:443`) wants a credential: a person's
+ *   bearer token, or a machine's pinned client certificate — the latter is a
+ *   TLS matter and therefore the runtime's, not this client's (see `agent`).
+ *
+ * Wire fields arrive in snake_case and are handed on in camelCase; the payload
+ * itself is passed through untouched, because decoding it into a contract type
+ * is the caller's business.
+ */
+import { type TopicOptions } from "./topics.js";
+export interface DoorRecord {
+    offset: number;
+    originOffset: number;
+    topic: string;
+    payload: unknown;
+    /** Colca's record timestamp, in unix **milliseconds** (payload times are seconds). */
+    ts: number;
+    writtenBy: string;
+    actorId: string;
+    actorLabel: string;
+    actorKind: string;
+}
+/**
+ * A pruned range. Present only when the cursor sits below the stream's
+ * low-water mark, and reported again until the consumer acks `toOffset`.
+ */
+export interface Gap {
+    stream: string;
+    fromOffset: number;
+    toOffset: number;
+    firstTs?: number;
+    lastTs?: number;
+    approx: boolean;
+}
+export interface Page {
+    records: DoorRecord[];
+    /** Where a following read starts. Fetching never moves the cursor; acking does. */
+    next: number;
+    gap?: Gap;
+}
+export interface KvEntry {
+    path: string;
+    nodeId: string;
+    topic: string;
+    payload: unknown;
+    ts: number;
+    offset: number;
+}
+export interface SelfInfo {
+    ulid: string;
+    name: string;
+    node: string;
+    element: string;
+    mount: string;
+    limits: {
+        maxRecordBytes: number;
+        maxBlobBytes: number;
+    };
+}
+export interface PublishResult {
+    stream: string;
+    offset: number;
+    topic: string;
+    command?: unknown;
+}
+export interface FetchOptions {
+    /** Records per page, 1…1000. */
+    max?: number;
+    /** Narrows to a subtree of the UNS path — the part after the node, not the raw topic. */
+    prefix?: string;
+    /** Only for the `metrics` stream, at most 1000 ids. */
+    signalIds?: readonly string[];
+    /**
+     * Read the *end* of the stream instead of the cursor's position, without
+     * moving it. What a view wants when it opens: the last `max` records.
+     */
+    tail?: boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Who a record is attributed to, when the publisher acts for someone else.
+ * A service that cannot forward a person's token names their groups instead
+ * and must say why — the node logs every such use.
+ */
+export interface Attribution {
+    actorId?: string;
+    actorLabel?: string;
+    actorKind?: string;
+    actorGroups?: readonly string[];
+    fallbackReason?: string;
+    writtenBy?: string;
+}
+export interface DoorOptions {
+    /** The door's origin, e.g. `http://colca` or `https://node:443`. */
+    baseUrl: string;
+    /** This caller's name on the local door. Also owns the `c/{service}/…` cursors. */
+    service?: string;
+    /** A person's token for the published door. */
+    token?: string;
+    /** The node's admin token (`X-Colca-Token`), for administrative callers. */
+    adminToken?: string;
+    timeoutMs?: number;
+    /** For tests, proxies, or a Node `Agent` that carries a client certificate. */
+    fetch?: typeof globalThis.fetch;
+}
+/** A non-2xx answer from the door, with the node's own words kept. */
+export declare class DoorError extends Error {
+    readonly status: number;
+    readonly route: string;
+    /** The node's denial reason, on a 403. */
+    readonly reason?: string | undefined;
+    constructor(status: number, route: string, message: string, 
+    /** The node's denial reason, on a 403. */
+    reason?: string | undefined);
+}
+export declare class Door {
+    #private;
+    readonly service?: string;
+    constructor(options: DoorOptions);
+    /** The cursor namespace this caller owns. The door refuses any other. */
+    cursorName(suffix: string): string;
+    /** `GET /fetch` — read forward from the cursor's stored position. */
+    fetchPage(stream: string, cursor: string, options?: FetchOptions): Promise<Page>;
+    /**
+     * `POST /ack` — ack the last **processed** offset. Monotonic: the door never
+     * moves a cursor backwards, and answers whether this one moved.
+     */
+    ack(stream: string, cursor: string, offset: number): Promise<boolean>;
+    /** `POST /ack` with `delete` — retire a cursor. Fine when it never existed. */
+    deleteCursor(stream: string, cursor: string): Promise<void>;
+    /** `POST /publish` — one record under this caller's identity. */
+    publish(topic: string, payload: unknown, attribution?: Attribution): Promise<PublishResult>;
+    /** The same, with the topic built from its parts. */
+    publishTo(parts: TopicOptions, payload: unknown, attribution?: Attribution): Promise<PublishResult>;
+    /**
+     * `GET /kv` — the retained entries under `prefix`, every page followed.
+     * `contract` narrows the scan at the node, before payloads are decoded.
+     */
+    kv(prefix?: string, options?: {
+        contract?: string | readonly string[];
+        signal?: AbortSignal;
+    }): Promise<KvEntry[]>;
+    /** `GET /self` — this caller's minted identity and the limits it must respect. */
+    self(): Promise<SelfInfo>;
+}
+//# sourceMappingURL=door.d.ts.map

package/dist/door.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"door.d.ts","sourceRoot":"","sources":["../src/door.ts"],"names":[],"mappings":"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"}

package/dist/door.js

@@ -0,0 +1,212 @@
+/**
+ * The door's HTTP client: `GET /fetch`, `POST /ack`, `GET /kv`, `GET /self`
+ * and `POST /publish`. One class, no runtime dependencies — the platform's
+ * `fetch` does the work.
+ *
+ * Which door a client talks to is decided by the URL and the credential:
+ *
+ * - the local door (`http://colca`, port 80 inside the deployment network) has
+ *   no credential. The caller names itself with `X-Colca-Service` and the door
+ *   registers it on first sight;
+ * - the published door (`https://node:443`) wants a credential: a person's
+ *   bearer token, or a machine's pinned client certificate — the latter is a
+ *   TLS matter and therefore the runtime's, not this client's (see `agent`).
+ *
+ * Wire fields arrive in snake_case and are handed on in camelCase; the payload
+ * itself is passed through untouched, because decoding it into a contract type
+ * is the caller's business.
+ */
+import { topic as buildTopic } from "./topics.js";
+/** A non-2xx answer from the door, with the node's own words kept. */
+export class DoorError extends Error {
+    status;
+    route;
+    reason;
+    constructor(status, route, message, 
+    /** The node's denial reason, on a 403. */
+    reason) {
+        super(`${route}: ${String(status)} ${message}`);
+        this.status = status;
+        this.route = route;
+        this.reason = reason;
+        this.name = "DoorError";
+    }
+}
+export class Door {
+    #base;
+    #headers;
+    #timeout;
+    #fetch;
+    service;
+    constructor(options) {
+        this.#base = options.baseUrl.replace(/\/+$/, "");
+        this.service = options.service;
+        this.#timeout = options.timeoutMs ?? 10_000;
+        this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.#headers = { "content-type": "application/json" };
+        if (options.service)
+            this.#headers["x-colca-service"] = options.service;
+        if (options.token)
+            this.#headers.authorization = `Bearer ${options.token}`;
+        if (options.adminToken)
+            this.#headers["x-colca-token"] = options.adminToken;
+    }
+    /** The cursor namespace this caller owns. The door refuses any other. */
+    cursorName(suffix) {
+        if (!this.service) {
+            throw new Error("cursorName() needs the service name the cursors are namespaced by");
+        }
+        return `c/${this.service}/${suffix}`;
+    }
+    /** `GET /fetch` — read forward from the cursor's stored position. */
+    async fetchPage(stream, cursor, options = {}) {
+        const query = new URLSearchParams({ stream, cursor });
+        if (options.max !== undefined)
+            query.set("max", String(options.max));
+        if (options.prefix)
+            query.set("prefix", options.prefix);
+        if (options.tail)
+            query.set("tail", "1");
+        for (const id of options.signalIds ?? [])
+            query.append("signal_id", id);
+        const body = await this.#call("GET", `/fetch?${query.toString()}`, undefined, options.signal);
+        return {
+            records: (body.records ?? []).map(toRecord),
+            next: body.next,
+            gap: body.gap ? toGap(body.gap) : undefined,
+        };
+    }
+    /**
+     * `POST /ack` — ack the last **processed** offset. Monotonic: the door never
+     * moves a cursor backwards, and answers whether this one moved.
+     */
+    async ack(stream, cursor, offset) {
+        const body = await this.#call("POST", "/ack", { cursor, stream, offset });
+        return body.moved;
+    }
+    /** `POST /ack` with `delete` — retire a cursor. Fine when it never existed. */
+    async deleteCursor(stream, cursor) {
+        await this.#call("POST", "/ack", { cursor, stream, delete: true });
+    }
+    /** `POST /publish` — one record under this caller's identity. */
+    async publish(topic, payload, attribution = {}) {
+        return this.#call("POST", "/publish", {
+            topic,
+            payload,
+            written_by: attribution.writtenBy,
+            actor_id: attribution.actorId,
+            actor_label: attribution.actorLabel,
+            actor_kind: attribution.actorKind,
+            actor_groups: attribution.actorGroups,
+            fallback_reason: attribution.fallbackReason,
+        });
+    }
+    /** The same, with the topic built from its parts. */
+    async publishTo(parts, payload, attribution = {}) {
+        return this.publish(buildTopic(parts), payload, attribution);
+    }
+    /**
+     * `GET /kv` — the retained entries under `prefix`, every page followed.
+     * `contract` narrows the scan at the node, before payloads are decoded.
+     */
+    async kv(prefix = "", options = {}) {
+        const contracts = typeof options.contract === "string" ? [options.contract] : (options.contract ?? []);
+        const entries = [];
+        let after = "";
+        for (;;) {
+            const query = new URLSearchParams({ prefix, max: "10000" });
+            for (const name of contracts)
+                query.append("contract", name);
+            if (after)
+                query.set("after", after);
+            const body = await this.#call("GET", `/kv?${query.toString()}`, undefined, options.signal);
+            for (const entry of body.entries ?? []) {
+                entries.push({
+                    path: entry.path,
+                    nodeId: entry.node_id,
+                    topic: entry.topic,
+                    payload: entry.payload,
+                    ts: entry.ts,
+                    offset: entry.offset,
+                });
+            }
+            const next = body.next ?? "";
+            if (!next)
+                return entries;
+            if (next === after)
+                throw new Error("GET /kv: the node repeated a page token");
+            after = next;
+        }
+    }
+    /** `GET /self` — this caller's minted identity and the limits it must respect. */
+    async self() {
+        const body = await this.#call("GET", "/self");
+        return {
+            ulid: body.ulid,
+            name: body.name,
+            node: body.node,
+            element: body.element,
+            mount: body.mount,
+            limits: {
+                maxRecordBytes: body.limits.max_record_bytes,
+                maxBlobBytes: body.limits.max_blob_bytes,
+            },
+        };
+    }
+    async #call(method, route, body, signal) {
+        // One timeout per call, dropped again as soon as the answer is in, so a
+        // long-lived client does not collect timers.
+        const timer = AbortSignal.timeout(this.#timeout);
+        const response = await this.#fetch(`${this.#base}${route}`, {
+            method,
+            headers: this.#headers,
+            body: body === undefined ? undefined : JSON.stringify(stripUndefined(body)),
+            signal: signal ? AbortSignal.any([signal, timer]) : timer,
+        });
+        const text = await response.text();
+        const parsed = text ? safeJson(text) : undefined;
+        if (!response.ok) {
+            const error = parsed;
+            throw new DoorError(response.status, route.split("?")[0], error?.error ?? text, error?.reason);
+        }
+        return parsed;
+    }
+}
+function toRecord(r) {
+    return {
+        offset: r.offset,
+        originOffset: r.origin_offset,
+        topic: r.topic,
+        payload: r.payload,
+        ts: r.ts,
+        writtenBy: r.written_by ?? "",
+        actorId: r.actor_id ?? "",
+        actorLabel: r.actor_label ?? "",
+        actorKind: r.actor_kind ?? "",
+    };
+}
+function toGap(g) {
+    return {
+        stream: g.stream,
+        fromOffset: g.from_offset,
+        toOffset: g.to_offset,
+        firstTs: g.first_ts,
+        lastTs: g.last_ts,
+        approx: g.approx ?? false,
+    };
+}
+/** Attribution fields left unset must not reach the node as nulls. */
+function stripUndefined(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=door.js.map

package/dist/door.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"door.js","sourceRoot":"","sources":["../src/door.ts"],"names":[],"mappings":"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"}