slopkit 0.2.0 → 0.4.0-rc.0

package/dist/server/sync.js

@@ -0,0 +1,293 @@
+import { digest } from "../digest.js";
+import { check } from "../schema.js";
+import { createPull } from "./pull.js";
+import { route, serveWeb } from "./web.js";
+/** The kit's own refusal messages, said the same in every app. */
+export const KIT_ANSWERS = {
+    replaced: "the server's data was replaced since this was tapped; tap again",
+    history: "this page's copy is from another history of the server's data; it starts over",
+    forbidden: (name) => `only a person's login can ${name}`,
+    reused: (id) => `command ${id} was already used for another command`,
+};
+/**
+ * The kit's own answers must come through the app's outcome schema, which checks every reply, or they'd never reach a
+ * page: refused when the routes are made. The type check (`Admits`) can't see a schema's bounds; this can.
+ */
+function admitted(api) {
+    const answers = [
+        { kind: "failed", reason: "conflict", message: KIT_ANSWERS.replaced },
+        { kind: "failed", reason: "conflict", message: KIT_ANSWERS.history },
+        { kind: "failed", reason: "conflict", message: KIT_ANSWERS.reused(Number.MAX_SAFE_INTEGER) },
+        { kind: "failed", reason: "forbidden", message: KIT_ANSWERS.forbidden("command") },
+        { kind: "retired" },
+    ];
+    const outcome = api.push.response;
+    for (const answer of answers) {
+        const parsed = check(outcome, {
+            results: [{ id: 1, outcome: answer, revision: 0 }],
+            revision: 0,
+        });
+        if (!parsed.ok) {
+            throw new Error(`the outcome schema refuses the kit's own answer: ${parsed.error.message}`);
+        }
+    }
+}
+/**
+ * Whose commands these are: every person is the one owner (single user by design), so a person is one principal
+ * whichever login they came through; each service or key is its own.
+ */
+export function principalOf(caller) {
+    if (caller.person) {
+        return "person";
+    }
+    return caller.identities.toSorted().join(" ") || "service";
+}
+export function syncHandlers(options) {
+    const { api, store, ledger, log } = options;
+    const listeners = new Set();
+    const principal = options.principal ?? principalOf;
+    const { outcome } = options;
+    const changed = () => {
+        for (const listener of listeners) {
+            listener();
+        }
+    };
+    async function pull(request, caller) {
+        if (caller.person && request.dataset === store.dataset() && store.wentBack(request.since)) {
+            log("warn", "a page holds more than the store: it was restored or went back; a new dataset", {
+                seen: request.since,
+                revision: store.revision(),
+            });
+        }
+        const server = options.server(caller);
+        const who = principal(caller);
+        const { row, ...paged } = options.history;
+        const pulls = createPull({
+            db: store.db,
+            dataset: () => store.dataset(),
+            revision: () => store.revision(),
+            known: (since) => store.known(since),
+            paged,
+            unpaged: options.unpaged,
+            receipts: {
+                read: (ask) => ask.commands === undefined
+                    ? ledger
+                        .receipts(who, request.client, ask.since)
+                        .map((each) => ({ ...each, client: request.client }))
+                    : ledger.receiptsOf(who, ask.commands),
+                names: (each) => options.names(each.receipt),
+            },
+            limits: options.limits,
+            respond: (pulled) => {
+                const receipts = pulled.receipts.map((each) => ({
+                    id: each.id,
+                    outcome: outcome(each.receipt),
+                    revision: each.revision,
+                    ...(each.client === request.client ? {} : { client: each.client }),
+                }));
+                const rows = { ...pulled.unpaged, [row]: pulled.rows };
+                // SAFETY: the history's rows under its key and the other keys' from `unpaged` are every row key of R, each
+                // its rows; the reply's own fields follow.
+                // oxlint-disable-next-line typescript/consistent-type-assertions, typescript/no-unsafe-type-assertion
+                return {
+                    ...rows,
+                    dataset: pulled.dataset,
+                    revision: pulled.revision,
+                    reset: pulled.reset,
+                    commands: receipts,
+                    server,
+                    ...(pulled.page === undefined ? {} : { page: pulled.page }),
+                };
+            },
+        });
+        const { reply } = pulls.pull(request, caller);
+        const partial = reply.page !== undefined && reply.page.next !== null;
+        const all = request.verify === true && !partial ? options.everything() : undefined;
+        store.served(reply.revision);
+        if (all === undefined) {
+            return reply;
+        }
+        return { ...reply, checksum: await digest(api.rows.map((key) => all[key])) };
+    }
+    async function command(key, each, caller) {
+        if (!caller.person && options.personOnly?.(each) === true) {
+            return {
+                outcome: {
+                    kind: "failed",
+                    reason: "forbidden",
+                    message: KIT_ANSWERS.forbidden(each.name),
+                },
+            };
+        }
+        const act = options.act(each, caller, key);
+        const ran = await ledger.run(key, { name: each.name, args: JSON.stringify(each) }, {
+            local: act.local,
+            remote: "remote" in act
+                ? act.remote
+                : () => Promise.reject(new Error(`${each.name} acts only in the store`)),
+        });
+        if (ran.kind === "elsewhere") {
+            return undefined;
+        }
+        if (ran.kind === "retired") {
+            return { outcome: { kind: "retired" } };
+        }
+        if (ran.kind === "conflict") {
+            return {
+                outcome: {
+                    kind: "failed",
+                    reason: "conflict",
+                    message: KIT_ANSWERS.reused(key.id),
+                },
+            };
+        }
+        if (ran.fresh) {
+            const { kind } = ran.receipt;
+            const attributes = { client: key.client, id: key.id };
+            log(kind === "failed" ? "warn" : "info", `command ${each.name} ${kind}`, attributes);
+        }
+        return {
+            outcome: outcome(ran.receipt),
+            ran: { key, command: each, kept: ran.receipt, fresh: ran.fresh },
+        };
+    }
+    async function push(request, caller) {
+        const refuse = (message) => {
+            const revision = store.revision();
+            store.served(revision);
+            return {
+                results: request.commands.map(({ id }) => ({
+                    id,
+                    outcome: { kind: "failed", reason: "conflict", message },
+                    revision,
+                })),
+                revision,
+            };
+        };
+        // Tapped against another store (this one was replaced or restored since): nothing runs.
+        if (request.dataset !== null && request.dataset !== store.dataset()) {
+            return refuse(KIT_ANSWERS.replaced);
+        }
+        // A page holding a revision this history never had, or no longer remembers: its taps may have run in a history
+        // that is gone, so none runs here, and its next pull starts it over.
+        if (!store.known(request.since)) {
+            return refuse(KIT_ANSWERS.history);
+        }
+        const results = [];
+        const ran = [];
+        for (const { id, command: each } of request.commands) {
+            const key = { principal: principal(caller), client: request.client, id };
+            // oxlint-disable-next-line no-await-in-loop -- a push's commands act in the order they were tapped
+            const done = await command(key, each, caller);
+            if (done === undefined) {
+                continue;
+            }
+            if (done.ran !== undefined) {
+                ran.push(done.ran);
+            }
+            // Where its effects are visible: the receipt's own revision (a replay too), else the store's now.
+            results.push({
+                id,
+                outcome: done.outcome,
+                revision: ledger.revisionOf(key) ?? store.revision(),
+            });
+        }
+        // The revision the reply carries is served before anything else can move it (`pushed` may write).
+        const revision = store.revision();
+        store.served(revision);
+        changed();
+        options.pushed?.(ran, caller);
+        return { results, revision };
+    }
+    return {
+        pull,
+        push,
+        revision: () => store.revision(),
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        changed,
+    };
+}
+/**
+ * The sync contract's routes: pull, push and telemetry. Each telemetry event is one `page` log line at `info`, its
+ * attributes the event's own with the kit's (`client`, `at`, `person`) set last, so a page can't claim another sender.
+ */
+export function syncRoutes(api, handlers) {
+    admitted(api);
+    return [
+        route(api.pull, (request, caller) => handlers.pull(request, caller)),
+        route(api.push, (request, caller) => handlers.push(request, caller)),
+        route(api.telemetry, (request, caller) => {
+            for (const event of request.events) {
+                handlers.page("info", event.name, {
+                    ...event.attributes,
+                    client: request.client,
+                    at: event.at,
+                    person: caller.person,
+                });
+            }
+            return { ok: true };
+        }),
+    ];
+}
+/**
+ * The poke socket: one poke with the revision on open, one for the changes within `gatherMs` (carrying the revision
+ * when it is sent), and a beat every `beatMs`, so a lost poke is made up for and a quiet socket is a dead one.
+ */
+export function pokes(api, options) {
+    return {
+        path: api.socket.path,
+        open: (send) => {
+            const poke = () => {
+                send({ type: "poke", revision: options.revision() });
+            };
+            let pending;
+            const unsubscribe = options.subscribe(() => {
+                pending ??= setTimeout(() => {
+                    pending = undefined;
+                    poke();
+                }, options.gatherMs ?? 50);
+            });
+            poke();
+            const alive = setInterval(poke, options.beatMs ?? 20_000);
+            return () => {
+                unsubscribe();
+                clearTimeout(pending);
+                clearInterval(alive);
+            };
+        },
+    };
+}
+const NAME = /^[a-z][a-z0-9-]{0,31}$/;
+export async function serveSync(options) {
+    const given = options;
+    const { name, api, sync, page, routes = [], manifest = {}, ...web } = given;
+    if (!NAME.test(name)) {
+        throw new Error(`serveSync: not an app name: ${name}`);
+    }
+    return await serveWeb({
+        ...web,
+        cookie: `${name}_session`,
+        manifest: {
+            id: "/",
+            name,
+            short_name: name,
+            start_url: "/",
+            scope: "/",
+            display: "standalone",
+            background_color: "#000000",
+            theme_color: "#000000",
+            icons: [{ src: "/icon.svg", sizes: "any", type: "image/svg+xml", purpose: "any maskable" }],
+            ...manifest,
+        },
+        routes: [
+            ...syncRoutes(api, { pull: sync.pull, push: sync.push, page }),
+            ...routes,
+        ],
+        socket: pokes(api, { revision: sync.revision, subscribe: sync.subscribe }),
+    });
+}

package/dist/server/web.d.ts

@@ -1,26 +1,75 @@
-import type { Endpoint, Failure } from "../contract.ts";
+import type { IncomingMessage } from "node:http";
+import type { Endpoint, RefusalKind } from "../contract.ts";
 import type { WebConfig } from "./config.ts";
 import type { Logger } from "./log.ts";
-/** Who asked: their identities, whether a person (not a service token), and how they signed in. */
+/** Who asked: their identities, whether a person (not a service token or a key), and how they signed in. */
 export type Caller = {
     identities: string[];
     person: boolean;
-    login: "access" | "oidc";
+    login: "access" | "oidc" | "key";
     request: string;
 };
-/** A handler's refusal, answered as a typed failure. */
+/**
+ * A handler's refusal, answered as a typed failure: the kit's error body, so the page can tell it from a proxy's.
+ * `path` names where a request broke its schema (`request.commands[1].command.value`).
+ */
 export declare class Refusal extends Error {
-    readonly kind: Failure["kind"];
-    constructor(kind: Failure["kind"], message: string);
+    readonly kind: RefusalKind;
+    readonly path: string | undefined;
+    constructor(kind: RefusalKind, message: string, path?: string);
 }
 /** A route: an endpoint and its handler, typed together and run untyped by the server. */
 export type Route = {
     method: "GET" | "POST";
     path: string;
     person: boolean;
+    /** Its own request body limit; `serveWeb`'s `bodyLimit` when absent. */
+    bodyLimit?: number;
     run: (input: unknown, caller: Caller) => Promise<unknown>;
 };
-export declare function route<Req, Res>(endpoint: Endpoint<Req, Res>, handle: (request: Req, caller: Caller) => Res | Promise<Res>): Route;
+export declare function route<Req, Res>(endpoint: Endpoint<Req, Res>, handle: (request: Req, caller: Caller) => Res | Promise<Res>, options?: {
+    bodyLimit?: number;
+}): Route;
+/**
+ * What a raw route's handler gets: the URL, what a `/*` path matched past its prefix (`{ "*": rest }`, decoded once;
+ * `{}` for an exact path), the bounded body, the headers.
+ */
+export type RawRequest = {
+    url: URL;
+    params: Record<string, string>;
+    body: Buffer | undefined;
+    headers: IncomingMessage["headers"];
+};
+/**
+ * What a raw route answers. `cache`: `immutable` for content named by its hash (kept for a year, by this browser only),
+ * else `no-store`. The security headers are always the server's: `headers` can add others (`etag`,
+ * `content-disposition`), never replace those; a `content-security-policy` only adds directives that tighten the
+ * server's (`content-security-policy: sandbox` for bytes someone else made).
+ */
+export type RawReply = {
+    status: number;
+    type: string;
+    body: Buffer | string;
+    cache?: "immutable" | "no-store";
+    headers?: Record<string, string>;
+};
+/** A route that takes and answers bytes, behind every guard a contract route has. */
+export type RawRoute = {
+    raw: true;
+    method: "GET" | "POST";
+    /** Exact, or a prefix ending in `/*`. */
+    path: string;
+    person: boolean;
+    bodyLimit: number;
+    handle: (request: RawRequest, caller: Caller) => RawReply | Promise<RawReply>;
+};
+export declare function rawRoute(definition: {
+    method: "GET" | "POST";
+    path: string;
+    person?: boolean;
+    bodyLimit?: number;
+    handle: RawRoute["handle"];
+}): RawRoute;
 export type Socket = {
     path: string;
     /** A socket opened: return what to do when it closes. `send` takes JSON-ready values. */
@@ -35,11 +84,15 @@ export type WebOptions = {
     assets: string;
     /** The install manifest. */
     manifest: Record<string, unknown>;
-    routes: Route[];
+    /** Contract routes (`route`) and routes that take and answer bytes (`rawRoute`). */
+    routes: (Route | RawRoute)[];
     socket?: Socket;
     /** The session cookie's name. */
     cookie: string;
-    /** Request bodies past this are refused; default 64 KB. */
+    /**
+     * Request bodies past this many bytes are refused, unless a route sets its own; default 64 KiB. Give a push endpoint
+     * `PUSH_BYTES` or more.
+     */
     bodyLimit?: number;
 };
 export declare function serveWeb(options: WebOptions): Promise<{