slopkit 0.2.0 → 0.4.0-rc.0

package/dist/contract.d.ts

@@ -12,13 +12,23 @@ export declare function endpoint<Req, Res>(method: "GET" | "POST", path: string,
 }): Endpoint<Req, Res>;
 /**
  * Why a call failed. `signed-out`: the login is gone (the only kind that reloads the page). `forbidden`: signed in but
- * not allowed. `invalid`: the request or the reply broke the contract. `conflict`: refused for the current state.
- * `upstream`: a service behind the server failed. `unavailable`: the server is up but can't now. `offline`: no answer.
+ * not allowed. `invalid`: the request broke the contract. `conflict`: refused for the current state. `upstream`: a
+ * service behind the server failed. `unavailable`: the server is up but can't now. `offline`: no answer. `unreadable`:
+ * a reply that broke the contract (not JSON, or failing its schema): it may have acted, and the server never sends it.
+ *
+ * `refused`: the server's own refusal, its kit error body naming a kind that matches the status; only then can it be
+ * final, since a proxy can answer any status. `path`: where a refused request broke its schema. `retryAfterMs`: the
+ * provider's `Retry-After`, a floor for the next try.
  */
 export type Failure = {
-    kind: "signed-out" | "forbidden" | "invalid" | "conflict" | "upstream" | "unavailable" | "offline";
+    kind: "signed-out" | "forbidden" | "invalid" | "conflict" | "upstream" | "unavailable" | "offline" | "unreadable";
     message: string;
+    refused?: true;
+    path?: string;
+    retryAfterMs?: number;
 };
+/** The kinds a server answers with: a reply it can't read is the client's observation, never a server's. */
+export type RefusalKind = Exclude<Failure["kind"], "unreadable">;
 export type Result<T> = {
     ok: true;
     value: T;
@@ -26,12 +36,15 @@ export type Result<T> = {
     ok: false;
     failure: Failure;
 };
-export declare const STATUS: Record<Failure["kind"], number>;
+export declare const STATUS: Record<RefusalKind, number>;
+/** The longest a `Retry-After` defers the next try: a bad header can delay sync, never stop it. */
+export declare const RETRY_AFTER_MAX_MS = 3600000;
 /** GET requests carry their input as one `q` query parameter of JSON; POST as the body. */
 export declare function encodeUrl<Req>(route: Endpoint<Req, unknown>, request: Req): string;
 /**
- * Call an endpoint from a browser (or any fetch). Every outcome is a `Result`: thrown errors, non-JSON answers (a
- * proxy's login page means signed out), error statuses and replies that break the schema all become a `Failure`.
+ * Call an endpoint from a browser (or any fetch). Every outcome is a `Result`: thrown errors, redirects and successful
+ * HTML pages (a proxy's login page means signed out), error statuses, and successes that aren't JSON or break the
+ * schema (`unreadable`) all become a `Failure`. An error is `refused` only with the kit's own body.
  */
 export declare function call<Req, Res>(route: Endpoint<Req, Res>, request: Req, options?: {
     fetch?: typeof fetch;

package/dist/contract.js

@@ -3,7 +3,7 @@
  * server (which checks requests and its own replies) and the page (which checks replies, since a proxy in between can
  * answer anything, such as an HTML login page). Failures are a closed set of kinds; a caller handles each by kind.
  */
-import { check, object, string } from "./schema.js";
+import { check, object, optional, string } from "./schema.js";
 export function endpoint(method, path, request, response, options = {}) {
     return { method, path, request, response, person: options.person ?? false };
 }
@@ -16,8 +16,25 @@ export const STATUS = {
     unavailable: 503,
     offline: 503,
 };
+const KINDS = [
+    "signed-out",
+    "forbidden",
+    "invalid",
+    "conflict",
+    "upstream",
+    "unavailable",
+    "offline",
+];
+/** A body that was due as JSON and wasn't. */
+const UNREADABLE = Symbol("unreadable");
 /** A failure's body, as `serveWeb` answers it: its message is shown when there is one. */
 const ERROR_BODY = object({ message: string() });
+/** The kit's own error body: a kind it can send, its message, and the schema path of a refused request. */
+const KIT_BODY = object({ kind: string(), message: string(), path: optional(string()) });
+/**
+ * A status's kind when no kit body says otherwise. A wrong endpoint or method and a body past the server's limit are
+ * `invalid` (no command path: incompatible); a timeout or rate limit is `unavailable`, retried.
+ */
 function kindOf(status) {
     if (status === 401) {
         return "signed-out";
@@ -28,6 +45,9 @@ function kindOf(status) {
     if (status === 409) {
         return "conflict";
     }
+    if (status === 408 || status === 429) {
+        return "unavailable";
+    }
     if (status === 502 || status === 504) {
         return "upstream";
     }
@@ -36,6 +56,21 @@ function kindOf(status) {
     }
     return "invalid";
 }
+/** The longest a `Retry-After` defers the next try: a bad header can delay sync, never stop it. */
+export const RETRY_AFTER_MAX_MS = 3_600_000;
+/**
+ * `Retry-After` as milliseconds from now, capped at `RETRY_AFTER_MAX_MS`: delay seconds or an HTTP date; undefined
+ * when absent or unreadable.
+ */
+function retryAfter(value) {
+    if (value === null) {
+        return undefined;
+    }
+    const at = /^\d+$/.test(value.trim())
+        ? Number(value.trim()) * 1000
+        : Date.parse(value) - Date.now();
+    return Number.isNaN(at) ? undefined : Math.min(RETRY_AFTER_MAX_MS, Math.max(0, at));
+}
 /** GET requests carry their input as one `q` query parameter of JSON; POST as the body. */
 export function encodeUrl(route, request) {
     if (route.method === "POST") {
@@ -44,8 +79,9 @@ export function encodeUrl(route, request) {
     return `${route.path}?q=${encodeURIComponent(JSON.stringify(request))}`;
 }
 /**
- * Call an endpoint from a browser (or any fetch). Every outcome is a `Result`: thrown errors, non-JSON answers (a
- * proxy's login page means signed out), error statuses and replies that break the schema all become a `Failure`.
+ * Call an endpoint from a browser (or any fetch). Every outcome is a `Result`: thrown errors, redirects and successful
+ * HTML pages (a proxy's login page means signed out), error statuses, and successes that aren't JSON or break the
+ * schema (`unreadable`) all become a `Failure`. An error is `refused` only with the kit's own body.
  */
 export async function call(route, request, options = {}) {
     const send = options.fetch ?? fetch;
@@ -70,29 +106,60 @@ export async function call(route, request, options = {}) {
             failure: { kind: "offline", message: error instanceof Error ? error.message : String(error) },
         };
     }
-    // A redirect (an opaque one, in a browser) or an HTML page is a proxy sending the browser to sign in.
+    // A redirect (an opaque one, in a browser) or a successful HTML page is a proxy sending the browser to sign in. An
+    // HTML error page keeps its status's kind.
     const type = response.headers.get("content-type") ?? "";
     if (response.type === "opaqueredirect" ||
         (response.status >= 300 && response.status < 400) ||
-        type.includes("text/html")) {
+        (response.ok && type.includes("text/html"))) {
         return { ok: false, failure: { kind: "signed-out", message: "the login expired" } };
     }
     const body = type.includes("application/json")
-        ? await response.json().catch(() => undefined)
-        : undefined;
+        ? await response.json().catch(() => UNREADABLE)
+        : UNREADABLE;
     if (!response.ok) {
+        const kit = check(KIT_BODY, body);
+        const named = kit.ok ? KINDS.find((each) => each === kit.value.kind) : undefined;
+        // Only the kit's own body, naming a kind its status carries, is the server's refusal; anything else is a status.
+        const own = kit.ok && named !== undefined && STATUS[named] === response.status;
+        const kind = own ? named : kindOf(response.status);
+        const after = kind === "unavailable" ? retryAfter(response.headers.get("retry-after")) : undefined;
+        if (own) {
+            const path = kit.value.path;
+            return {
+                ok: false,
+                failure: {
+                    kind,
+                    message: kit.value.message,
+                    refused: true,
+                    ...(path === undefined ? {} : { path }),
+                    ...(after === undefined ? {} : { retryAfterMs: after }),
+                },
+            };
+        }
         const error = check(ERROR_BODY, body);
         return {
             ok: false,
             failure: {
-                kind: kindOf(response.status),
+                kind,
                 message: error.ok ? error.value.message : `HTTP ${response.status}`,
+                ...(after === undefined ? {} : { retryAfterMs: after }),
             },
         };
     }
+    // A success the page can't read may still have acted: unreadable, never a refusal.
+    if (body === UNREADABLE) {
+        return {
+            ok: false,
+            failure: { kind: "unreadable", message: `reply: not JSON (HTTP ${response.status})` },
+        };
+    }
     const parsed = check(route.response, body);
     if (!parsed.ok) {
-        return { ok: false, failure: { kind: "invalid", message: `reply: ${parsed.error.message}` } };
+        return {
+            ok: false,
+            failure: { kind: "unreadable", message: `reply: ${parsed.error.message}` },
+        };
     }
     return { ok: true, value: parsed.value };
 }

package/dist/server/auth.d.ts

@@ -12,15 +12,16 @@ export declare class WebAuth {
     private writing;
     private readonly pending;
     private readonly env;
+    private readonly keys;
     constructor(config: WebConfig, home: string, env: Readonly<Record<string, string | undefined>>);
     get oidc(): boolean;
     private allowed;
     /**
-     * The allowed identities of a request: from the proxy's JWT when it sends one (a bad one is refused, never ignored),
-     * else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
+     * The allowed identities of a request: from an agent's bearer key when it sends one, else the proxy's JWT when it
+     * sends one (a bad one of either is refused, never ignored), else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
      * not allowed.
      */
-    identify(proxyJwt: string | undefined, token: string | undefined): Promise<Identities | false | undefined>;
+    identify(proxyJwt: string | undefined, token: string | undefined, bearer?: string): Promise<Identities | false | undefined>;
     private discover;
     /** Where to send a browser to sign in, with PKCE; `redirect` is this server's own callback URL. */
     loginUrl(redirect: string): Promise<string>;

package/dist/server/auth.js

@@ -1,12 +1,13 @@
 /**
- * Who a web request is: Cloudflare Access's signed JWT (`Cf-Access-Jwt-Assertion`), or a session from this server's
- * own OpenID Connect login (authorization code with PKCE). The issuer, audience and claims come from `web.json`.
- * Either way the identity must be on `web.allow`.
+ * Who a web request is: an agent's key (`Authorization: Bearer`, see `keys.ts`), Cloudflare Access's signed JWT
+ * (`Cf-Access-Jwt-Assertion`), or a session from this server's own OpenID Connect login (authorization code with
+ * PKCE). The issuer, audience and claims come from `web.json`. Either way the identity must be on `web.allow`.
  */
 import { createHash, randomBytes } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createRemoteJWKSet, jwtVerify } from "jose";
+import { Keys } from "./keys.js";
 const SESSION_DAYS = 7;
 const PENDING_MS = 10 * 60_000;
 /** A claim by dotted path, as a string, or `undefined`. */
@@ -42,6 +43,7 @@ export class WebAuth {
     writing = Promise.resolve();
     pending = new Map();
     env;
+    keys;
     constructor(config, home, env) {
         if (config.access === undefined && config.oidc === undefined) {
             throw new Error("web needs a login: set web.access (an identity-aware proxy) or web.oidc in web.json");
@@ -52,6 +54,7 @@ export class WebAuth {
         this.config = config;
         this.env = env;
         this.sessionsPath = join(home, "web-sessions.json");
+        this.keys = new Keys(home);
         this.accessKeys =
             config.access === undefined
                 ? undefined
@@ -66,11 +69,16 @@ export class WebAuth {
             : undefined;
     }
     /**
-     * The allowed identities of a request: from the proxy's JWT when it sends one (a bad one is refused, never ignored),
-     * else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
+     * The allowed identities of a request: from an agent's bearer key when it sends one, else the proxy's JWT when it
+     * sends one (a bad one of either is refused, never ignored), else from the session token (the session cookie's value). `undefined` means not signed in; `false`, signed in but
      * not allowed.
      */
-    async identify(proxyJwt, token) {
+    async identify(proxyJwt, token, bearer) {
+        // A bearer decides alone: one that doesn't verify is refused, never passed over for a cookie or a proxy's header.
+        if (bearer !== undefined) {
+            const name = await this.keys.verify(bearer);
+            return name === undefined ? false : (this.allowed([`key:${name}`]) ?? false);
+        }
         if (proxyJwt !== undefined) {
             const access = this.config.access;
             if (access === undefined || this.accessKeys === undefined) {

package/dist/server/cli.d.ts

@@ -0,0 +1,117 @@
+import type { WebConfig } from "./config.ts";
+import { Jobs } from "./jobs.ts";
+import type { Job, JobEnd } from "./jobs.ts";
+import { Log } from "./log.ts";
+import type { Logger } from "./log.ts";
+/** What a release says of itself: its version and the store schema it writes (`<name> version --json`). */
+export type ReleaseInfo = {
+    version: string;
+    schema: number;
+};
+export type Installed = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    tail: string[];
+};
+/** The automatic rollback that put `version` in place, if it is the one running: what it replaced and when. */
+export declare function rolledBackTo(home: string, version: string): {
+    from: string;
+    at: string;
+} | null;
+/** Whether a server holds the home's lock, without creating the lock file. */
+export declare function running(home: string): boolean;
+/** What an update job leaves when done: the release it installed and the version it replaced. */
+export type UpdateResult = {
+    release?: string;
+    from?: string;
+};
+/** How one update job ended, as a server reports it. */
+export type UpdateRecord = {
+    job: number;
+    release: string;
+    from: string;
+    result: "installed" | "failed";
+    reason: string | null;
+    at: string;
+};
+/** An update job (`slopkit/server/jobs`, kind `update`): one open at a time; every tap while it is open joins it. */
+export declare const UPDATE_KIND = "update";
+/** An update job asked for, and whether it is still due to run. */
+export type AskedUpdate = {
+    id: number;
+    due: boolean;
+};
+/** Ask for an update to `release` from `version` (joins one already open): the job's id, and whether still due. */
+export declare function askUpdate(jobs: Jobs<UpdateResult>, release: string, version: string, by: {
+    client: string;
+    id: number;
+}, now?: number): AskedUpdate;
+/** Claim the asked update before the server stops: running, "installing <release> from <version>", committed. */
+export declare function beginUpdate(jobs: Jobs<UpdateResult>, version: string): {
+    id: number;
+    release: string;
+    from: string;
+} | undefined;
+/**
+ * At start, before serving: how an update job a stop left running is settled. The install began: installed when this
+ * is another version than the one it replaced (the reconciliation read), else failed as interrupted.
+ */
+export declare function recoverUpdate(job: Job<UpdateResult>, version: string): JobEnd<UpdateResult>;
+/** At start, after running jobs are settled: an update still due failed, nothing changed. Returns how many. */
+export declare function settleAskedUpdates(jobs: Jobs<UpdateResult>): number;
+/** The newest `kept` finished updates, newest first. */
+export declare function updateRecords(jobs: Jobs<UpdateResult>, kept: number): UpdateRecord[];
+/** The open update job's id, if one is asked or installing. */
+export declare function updating(jobs: Jobs<UpdateResult>): number | null;
+/** The newer `edge` commit when this is an edge build behind it; a hint only, nothing installs it. */
+export declare function newerEdge(root: URL | string, env?: Readonly<Record<string, string | undefined>>): Promise<string | undefined>;
+/** What an app's `serve` gets: its home, what it is, the log, the web settings, and a way to ask for an update. */
+export type ServeContext = {
+    home: string;
+    version: string;
+    log: Log;
+    /** The server's own log lines (`server`). */
+    say: Logger;
+    /** `web.json`, or why the web is off. */
+    web: WebConfig | {
+        off: string;
+    };
+    env: Readonly<Record<string, string | undefined>>;
+    /** Stop the server for the update the app's store has asked (`askUpdate`), then start the same command again. */
+    update: () => void;
+};
+/** What an app's `serve` hands back once it serves. */
+export type Served = {
+    /** Its web server's address, when it has one. */
+    url?: string;
+    close: () => Promise<void>;
+    /** The asked update job, claimed running before anything stops (`beginUpdate`). */
+    claim?: () => {
+        id: number;
+        release: string;
+    } | undefined;
+};
+export type CliOptions = {
+    /** The binary's name: `<NAME>_HOME`, `~/.<name>`, `<name>.sqlite`, `<name>.tgz`. */
+    name: string;
+    /** The installed package's directory (`new URL("../", import.meta.url)`). */
+    root: URL | string;
+    /** The store schema this release writes (`schemaVersion`). */
+    schema: number;
+    /** What `serve` does, for the help: "<name> serve: Run the server on the home: <serves>". */
+    serves: string;
+    serve: (context: ServeContext) => Promise<Served>;
+    /** The app's own commands, beside the kit's. */
+    commands?: Record<string, {
+        usage: string;
+        help: string;
+        run: (args: string[], home: string) => Promise<number>;
+    }>;
+    env?: Readonly<Record<string, string | undefined>>;
+    /** How long a server stays up before its release is proven here (default an hour). */
+    provenAfterMs?: number;
+};
+/** Run the command line: the exit code. */
+export declare function runCli(args: readonly string[], options: CliOptions): Promise<number>;