@mostra/protocol 0.0.0-placeholder → 0.1.0

package/src/actions.ts

@@ -0,0 +1,418 @@
+/**
+ * Actions, live data and secrets (INTERFACES §2.4, §4, §6; D24, D44, D54, D56): the shapes the
+ * browser protocol, the host protocol and the worker channel share. Server-function arguments and
+ * results travel as the serializer's batches (`Batches`).
+ *
+ * ```ts
+ * const run: RunState = await post("runs", { viewId, fnId: "actions.ts#sendReply", args, clientKey });
+ * if (run.status === "succeeded") show(await deserializeAll(run.batches));
+ * ```
+ */
+import * as z from "zod";
+import { ViewId } from "./ids.ts";
+import type { Frame, WireError } from "./serializer.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** A value written by the serializer: its batches, in order (`serializeAll`). */
+export type Batches = readonly (readonly Frame[])[];
+
+/**
+ * The Zod schema of the `Batches` type: a list of batches, each a list of frames. The frames
+ * themselves are checked by the reader (`ValueReader`), which refuses anything malformed.
+ */
+export const Batches: z.ZodType<Batches> = z
+  .array(z.array(z.record(z.string(), z.unknown())).readonly())
+  .readonly()
+  .register(wireRegistry, {
+    id: "Batches",
+    description: "A serialized server-function value: its batches of frames, in order.",
+  }) as unknown as z.ZodType<Batches>;
+
+/** An error as runs, calls and live sources report it. */
+export interface ActionError extends WireError {
+  /** The stack of the thrown error, kept in the run log and never sent to a page. */
+  readonly stack?: string;
+}
+
+/** The Zod schema of the `ActionError` type. */
+export const ActionError: z.ZodType<ActionError> = z
+  .object({
+    message: z.string(),
+    code: z.string().exactOptional(),
+    stack: z.string().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "ActionError",
+    description: "An error from server code: its message and diagnostic code.",
+  });
+
+/** The largest serialized arguments a call or run takes, in characters of JSON. */
+export const ACTION_ARGS_MAX: number = 16 * 1024 * 1024;
+
+/** The largest serialized result a run keeps, in characters of JSON (larger fails the run). */
+export const ACTION_RESULT_MAX: number = 16 * 1024 * 1024;
+
+/** The cap of a run's log, in UTF-16 code units of its lines (D47's 1 MB). */
+export const RUN_LOG_MAX: number = 1024 * 1024;
+
+/** The line a capped log ends with. */
+export const RUN_LOG_TRUNCATED = "[log truncated at 1 MB]";
+
+/** The longest run key, in characters. */
+export const RUN_KEY_MAX = 256;
+
+/**
+ * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.
+ * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's
+ * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are
+ * final.
+ */
+export type RunStatus = "queued" | "running" | "waiting" | "succeeded" | "failed" | "cancelled";
+
+/** Every run status. */
+export const RUN_STATUSES: readonly RunStatus[] = [
+  "queued",
+  "running",
+  "waiting",
+  "succeeded",
+  "failed",
+  "cancelled",
+];
+
+/** Whether a run in `status` has ended. */
+export function isFinalRunStatus(status: RunStatus): boolean {
+  return status === "succeeded" || status === "failed" || status === "cancelled";
+}
+
+/**
+ * Why a run ended the way it did, beside its status: `interrupted` (its worker or the instance
+ * stopped while it ran, D24), `threw` (the action threw), `unserializable` (its result is outside
+ * the type set), `too-large`, `parked` (its artifact's worker keeps crashing), `cancelled` (by a
+ * viewer), `unknown-function`. Later releases add reasons.
+ */
+export type RunReason = string;
+
+/** A run's progress, as the action last reported it. */
+export interface RunProgress {
+  /** From 0 to 1. */
+  readonly fraction?: number;
+  /** One short line for people. */
+  readonly message?: string;
+}
+
+/** The Zod schema of the `RunProgress` type. */
+export const RunProgress: z.ZodType<RunProgress> = z
+  .object({
+    fraction: z.number().min(0).max(1).exactOptional(),
+    message: z.string().max(1000).exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "RunProgress",
+    description: "A run's progress: fraction and message.",
+  });
+
+/**
+ * One action run as a page reads it (D54): its state, progress, log and the result written so far.
+ * A result that is an async iterable grows item by item while the run is `running`.
+ */
+export interface RunState {
+  /** The run's `run_` ID. */
+  readonly runId: string;
+  /** The server function it runs: `<module path>#<export>`. */
+  readonly fnId: string;
+  /** The idempotency key it was started with, if any. */
+  readonly key?: string;
+  /** The run's state. */
+  readonly status: RunStatus;
+  /** Why it ended, for `failed` and `cancelled`. */
+  readonly reason?: RunReason;
+  /** Its latest progress. */
+  readonly progress?: RunProgress;
+  /** The log lines, capped at 1 MB with a marker line. */
+  readonly log: readonly string[];
+  /** The result's batches so far. */
+  readonly batches: Batches;
+  /** For `failed`: what went wrong, without the stack. */
+  readonly error?: WireError;
+  /** When it was recorded. */
+  readonly startedAt: string;
+  /** When it ended. */
+  readonly finishedAt?: string;
+  /** Whether this request joined a run that already existed (a key or a retried `clientKey`). */
+  readonly joined?: boolean;
+  /**
+   * The index of the first line in `log`, when the request said which lines the page holds
+   * (`RunAttachRequest.held`); absent: 0, the whole log.
+   */
+  readonly logFrom?: number;
+  /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */
+  readonly batchFrom?: number;
+}
+
+/** The Zod schema of the `RunState` type. */
+export const RunState: z.ZodType<RunState> = z
+  .object({
+    runId: z.string(),
+    fnId: z.string(),
+    key: z.string().exactOptional(),
+    status: z.enum(RUN_STATUSES as [RunStatus, ...RunStatus[]]),
+    reason: z.string().exactOptional(),
+    progress: RunProgress.exactOptional(),
+    log: z.array(z.string()).readonly(),
+    batches: Batches,
+    error: z.object({ message: z.string(), code: z.string().exactOptional() }).exactOptional(),
+    startedAt: z.string(),
+    finishedAt: z.string().exactOptional(),
+    joined: z.boolean().exactOptional(),
+    logFrom: z.number().int().nonnegative().exactOptional(),
+    batchFrom: z.number().int().nonnegative().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "RunState",
+    description: "An action run: status, progress, log and the result written so far.",
+  });
+
+/**
+ * What changed in a run since a page last heard: a lossy notification on the event stream. Lines
+ * start at `logFrom` and batches at `batchFrom`; a page that holds fewer reads the run again
+ * (`runs/attach`).
+ */
+export interface RunDelta {
+  /** The run's `run_` ID. */
+  readonly runId: string;
+  /** The run's state. */
+  readonly status: RunStatus;
+  /** Why it ended so, for `failed` and `cancelled`. */
+  readonly reason?: RunReason;
+  /** Its latest progress. */
+  readonly progress?: RunProgress;
+  /** The index of the first line in `log`. */
+  readonly logFrom: number;
+  /** Log lines, starting at `logFrom`. */
+  readonly log: readonly string[];
+  /** The index of the first batch in `batches`. */
+  readonly batchFrom: number;
+  /** Result batches, starting at `batchFrom`. */
+  readonly batches: Batches;
+  /** What went wrong. */
+  readonly error?: WireError;
+  /** When it ended. */
+  readonly finishedAt?: string;
+}
+
+/** A live source's value as a page reads it (D56). */
+export interface LiveState {
+  /** The idempotency key it was started with, if any. */
+  readonly key: string;
+  /** The value's revision, a decimal string that only grows; absent before any value. */
+  readonly revision?: string;
+  /** When the value was produced. */
+  readonly at?: string;
+  /** The latest value, serialized. */
+  readonly value?: Batches;
+  /**
+   * Append mode (`useLive(key, { mode: "append" })`): the values kept in the source's ring, oldest
+   * first, at most the window the page asked for.
+   */
+  readonly ring?: readonly {
+    readonly revision: string;
+    readonly at: string;
+    readonly value: Batches;
+  }[];
+  /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */
+  readonly error?: WireError;
+}
+
+/** One live update on the event stream: never stored as an event (D63, LL-04). */
+export interface LiveUpdate {
+  /** The live source's key. */
+  readonly key: string;
+  /** The value's revision. */
+  readonly revision?: string;
+  /** When the value was produced. */
+  readonly at?: string;
+  /** The value, serialized. */
+  readonly value?: Batches;
+  /** What went wrong. */
+  readonly error?: WireError;
+}
+
+/**
+ * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an
+ * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and
+ * never stored as an event.
+ */
+export type EphemeralMessage =
+  | { readonly kind: "run"; readonly run: RunDelta }
+  | { readonly kind: "live"; readonly live: LiveUpdate };
+
+/** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */
+export interface CallRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** The arguments, serialized as one array value. */
+  readonly args: Batches;
+}
+
+/** The Zod schema of the `CallRequest` type. */
+export const CallRequest: z.ZodType<CallRequest> = z
+  .object({ viewId: ViewId.schema, args: Batches })
+  .register(wireRegistry, {
+    id: "CallRequest",
+    description: "A plain server-function call: the view and the serialized arguments.",
+  });
+
+/**
+ * One line of a plain call's answer (`application/x-ndjson`): a batch of the result, then the end.
+ */
+export type CallLine =
+  | { readonly batch: readonly Frame[] }
+  | { readonly end: { readonly status: "succeeded" } }
+  | { readonly end: { readonly status: "failed"; readonly error: WireError } };
+
+/** `POST …/runs`: start a durable action run, or join one (D54, AC-02, AC-03). */
+export interface RunRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** `<module path>#<export>`. */
+  readonly fnId: string;
+  /** The arguments, serialized as one array value. */
+  readonly args: Batches;
+  /** The author's idempotency key: one run per artifact, function and key, ever. */
+  readonly key?: string;
+  /** A fresh ID per invocation, so a retried request joins the run it already started. */
+  readonly clientKey: string;
+}
+
+/** The Zod schema of the `RunRequest` type. */
+export const RunRequest: z.ZodType<RunRequest> = z
+  .object({
+    viewId: ViewId.schema,
+    fnId: z.string().min(3).max(1024),
+    args: Batches,
+    key: z.string().min(1).max(RUN_KEY_MAX).exactOptional(),
+    clientKey: z.string().min(8).max(64),
+  })
+  .register(wireRegistry, {
+    id: "RunRequest",
+    description: "Start or join an action run: the function, its arguments and keys.",
+  });
+
+/**
+ * `POST …/runs/attach`: read runs and hear their changes on the event stream for the next minute
+ * (re-attach after a reload, AC-02). By ID, or by function and key.
+ */
+export interface RunAttachRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /** Runs by ID. */
+  readonly runIds?: readonly string[];
+  /** Runs by function and key. */
+  readonly keyed?: readonly { readonly fnId: string; readonly key: string }[];
+  /**
+   * What the page already holds of runs it names by ID: so many log lines and batches. Each such
+   * run's answer starts there (`RunState.logFrom`, `batchFrom`), so a page renewing its interest
+   * doesn't read the whole run again (Opus review 14).
+   */
+  readonly held?: readonly {
+    readonly runId: string;
+    readonly log: number;
+    readonly batches: number;
+  }[];
+}
+
+/** The Zod schema of the `RunAttachRequest` type. */
+export const RunAttachRequest: z.ZodType<RunAttachRequest> = z
+  .object({
+    viewId: ViewId.schema,
+    runIds: z.array(z.string().max(64)).max(100).readonly().exactOptional(),
+    keyed: z
+      .array(
+        z.object({ fnId: z.string().min(3).max(1024), key: z.string().min(1).max(RUN_KEY_MAX) }),
+      )
+      .max(100)
+      .readonly()
+      .exactOptional(),
+    held: z
+      .array(
+        z.object({
+          runId: z.string().max(64),
+          log: z.number().int().nonnegative(),
+          batches: z.number().int().nonnegative(),
+        }),
+      )
+      .max(100)
+      .readonly()
+      .exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "RunAttachRequest",
+    description: "Runs a page reads and follows: by ID, or by function and key.",
+  });
+
+/** `POST …/runs/{id}/cancel`. */
+export interface RunCancelRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+}
+
+/** The Zod schema of the `RunCancelRequest` type. */
+export const RunCancelRequest: z.ZodType<RunCancelRequest> = z
+  .object({ viewId: ViewId.schema })
+  .register(wireRegistry, { id: "RunCancelRequest", description: "Cancel a run, from a view." });
+
+/** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */
+export const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;
+
+/** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */
+export const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;
+
+/** The ring size of a pushed source in append mode that no `defineLive` sized. */
+export const LIVE_RING_DEFAULT = 1024;
+
+/** The largest ring a source may keep. */
+export const LIVE_RING_MAX = 100_000;
+
+/**
+ * `POST …/live`: read live sources and keep their producers running for this view for the next
+ * minute (D56, LL-04); a page asks again while it shows them.
+ */
+export interface LiveRequest {
+  /** The view the page was opened as (D104). */
+  readonly viewId: string;
+  /**
+   * The sources, each with its append window; `refresh` asks the source's producer to load again
+   * now (`useLive`'s `refresh()`).
+   */
+  readonly keys: readonly {
+    readonly key: string;
+    readonly window?: number;
+    readonly refresh?: boolean;
+  }[];
+}
+
+/** The Zod schema of the `LiveRequest` type. */
+export const LiveRequest: z.ZodType<LiveRequest> = z
+  .object({
+    viewId: ViewId.schema,
+    keys: z
+      .array(
+        z.object({
+          key: z.string().regex(LIVE_KEY_PATTERN),
+          window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),
+          refresh: z.boolean().exactOptional(),
+        }),
+      )
+      .max(256)
+      .readonly(),
+  })
+  .register(wireRegistry, {
+    id: "LiveRequest",
+    description: "Live sources a page reads and keeps running: keys and append windows.",
+  });
+
+/** Secret names: letters, digits, `_`, `.` and `-`, starting with a letter or `_` (D44). */
+export const SECRET_NAME_PATTERN: RegExp = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;
+
+/** The largest secret value, in UTF-8 bytes. */
+export const SECRET_VALUE_MAX: number = 64 * 1024;

package/src/artifact.ts

@@ -0,0 +1,187 @@
+/**
+ * Artifacts and versions as clients see them (INTERFACES §6): how a client names an artifact or its
+ * source, and the summaries `artifact/list`, `artifact/get` and `artifact/publish` return.
+ */
+import * as z from "zod";
+import { ArtifactId, Cursor, TokenId, VersionId } from "./ids.ts";
+import { ArtifactLink, ArtifactManifest, SubmissionPolicy } from "./manifest.ts";
+import { wireRegistry } from "./wire-registry.ts";
+
+/** An absolute file system path: the client resolves relative paths against its own directory. */
+const AbsolutePath = z.string().regex(/^\//);
+
+/**
+ * Where to build an artifact from: a source path (a `.tsx`, `.jsx` or `.mdx` file, or a directory
+ * with an `index` entry), or an artifact ID, meaning the path it was last published from.
+ */
+export type SourceRef = { readonly path: string } | { readonly artifactId: string };
+
+/** Names an artifact: by its ID, or by a source path bound to it. */
+export type ArtifactRef = { readonly artifactId: string } | { readonly path: string };
+
+/** The Zod schema of the `SourceRef` type. */
+export const SourceRef: z.ZodType<SourceRef> = z
+  .union([z.object({ path: AbsolutePath }), z.object({ artifactId: ArtifactId.schema })])
+  .register(wireRegistry, {
+    id: "SourceRef",
+    description:
+      "Where to build an artifact from: an absolute source path, or an artifact ID (its last published source path).",
+  });
+
+/** The Zod schema of the `ArtifactRef` type. */
+export const ArtifactRef: z.ZodType<ArtifactRef> = z
+  .union([z.object({ artifactId: ArtifactId.schema }), z.object({ path: AbsolutePath })])
+  .register(wireRegistry, {
+    id: "ArtifactRef",
+    description: "Names an artifact by its ID or by an absolute source path bound to it.",
+  });
+
+/** One published version. */
+export interface VersionSummary {
+  /** The content-addressed version ID (D89). */
+  readonly id: string;
+  /** The per-artifact version number, for people: 1, 2, 3 … */
+  readonly number: number;
+  /** When it was published (RFC 3339, UTC). */
+  readonly publishedAt: string;
+  /** SHA-256 of the source tree's canonical listing, lowercase hex (DATA_MODEL §2). */
+  readonly sourceDigest: string;
+  /** SHA-256 of the build environment's canonical JSON, lowercase hex (DATA_MODEL §2). */
+  readonly envDigest: string;
+  /** SHA-256 of the build output's canonical listing: recorded, never identity (VR-01). */
+  readonly outputDigest: string;
+  /** Diagnostic codes a forced publish recorded (D41); absent when none. */
+  readonly forcedDiagnostics?: readonly string[];
+  /**
+   * When `mostra gc` removed the version's files (D140): its ID and number stay, but it can't be
+   * opened until its exact source is published again. Absent for a version whose files exist.
+   */
+  readonly collected?: string;
+}
+
+/** One artifact, as `artifact/list` returns it. Metadata comes from the latest version's manifest. */
+export interface ArtifactSummary {
+  /** The artifact ID. */
+  readonly id: string;
+  /** The title people see. */
+  readonly title: string;
+  /** What the artifact is for. */
+  readonly description?: string;
+  /** What kind of artifact it is. */
+  readonly family?: string;
+  /** Related artifacts. */
+  readonly links: readonly ArtifactLink[];
+  /** The render mode of the latest version. */
+  readonly mode: "spa";
+  /** The submission policy requested at publish or in the manifest; the host decides (D39). */
+  readonly policy?: SubmissionPolicy;
+  /** The source path the artifact was last published from. */
+  readonly source?: string;
+  /** When the artifact was first published (RFC 3339, UTC). */
+  readonly createdAt: string;
+  /** The version viewers are offered. */
+  readonly latestVersion?: VersionSummary;
+}
+
+/** One artifact in full, as `artifact/get` returns it. */
+export interface ArtifactDetail extends ArtifactSummary {
+  /** The latest version's manifest. */
+  readonly manifest: ArtifactManifest;
+  /** Every version, newest number first. */
+  readonly versions: readonly VersionSummary[];
+}
+
+/**
+ * The receipt of `artifact/publish` (INTERFACES §6, H-07). Everything it names is durable before the
+ * response is sent.
+ */
+export interface PublishReceipt {
+  /** The artifact the version belongs to. */
+  readonly artifactId: string;
+  /** The content-addressed version ID (D89). */
+  readonly versionId: string;
+  /** The version number. */
+  readonly version: number;
+  /**
+   * The capability URL: the artifact's default link (D97), the same for every publish until it is
+   * rotated or revoked. Instances with the gateway (WP-05 on) always set it; optional on
+   * the wire so instances without it can publish (D90).
+   */
+  readonly url?: string;
+  /**
+   * The ID of the token behind `url`, the artifact's default link (D97), for `view/rotate` and
+   * `view/revoke`. Present whenever `url` is.
+   */
+  readonly tokenId?: string;
+  /** The event cursor of the version's `version.published` event; `wait` and events read after it. */
+  readonly cursor: string;
+  /** `true` when this artifact already had this exact source and environment as a version. */
+  readonly reused: boolean;
+  /** The error codes a forced publish recorded (D41). */
+  readonly forcedDiagnostics?: readonly string[];
+}
+
+/** The Zod schema of the `VersionSummary` type. */
+export const VersionSummary: z.ZodType<VersionSummary> = z
+  .object({
+    id: VersionId.schema,
+    number: z.int().min(1),
+    publishedAt: z.iso.datetime(),
+    sourceDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    envDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    outputDigest: z.string().regex(/^[0-9a-f]{64}$/),
+    forcedDiagnostics: z.array(z.string()).readonly().exactOptional(),
+    collected: z.iso.datetime().exactOptional(),
+  })
+  .register(wireRegistry, { id: "VersionSummary", description: "One published version." });
+
+const summaryShape = {
+  id: ArtifactId.schema,
+  title: z.string(),
+  description: z.string().exactOptional(),
+  family: z.string().exactOptional(),
+  links: z.array(ArtifactLink).readonly(),
+  mode: z.literal("spa"),
+  policy: SubmissionPolicy.exactOptional(),
+  source: z.string().exactOptional(),
+  createdAt: z.iso.datetime(),
+  latestVersion: VersionSummary.exactOptional(),
+};
+
+/** The Zod schema of the `ArtifactSummary` type. */
+export const ArtifactSummary: z.ZodType<ArtifactSummary> = z
+  .object(summaryShape)
+  .register(wireRegistry, {
+    id: "ArtifactSummary",
+    description: "One artifact: metadata from its latest version, its source and latest version.",
+  });
+
+/** The Zod schema of the `ArtifactDetail` type. */
+export const ArtifactDetail: z.ZodType<ArtifactDetail> = z
+  .object({
+    ...summaryShape,
+    manifest: ArtifactManifest,
+    versions: z.array(VersionSummary).readonly(),
+  })
+  .register(wireRegistry, {
+    id: "ArtifactDetail",
+    description: "One artifact in full: its summary, the latest manifest and every version.",
+  });
+
+/** The Zod schema of the `PublishReceipt` type. */
+export const PublishReceipt: z.ZodType<PublishReceipt> = z
+  .object({
+    artifactId: ArtifactId.schema,
+    versionId: VersionId.schema,
+    version: z.int().min(1),
+    url: z.string().exactOptional(),
+    tokenId: TokenId.schema.exactOptional(),
+    cursor: Cursor.schema,
+    reused: z.boolean(),
+    forcedDiagnostics: z.array(z.string()).readonly().exactOptional(),
+  })
+  .register(wireRegistry, {
+    id: "PublishReceipt",
+    description:
+      "The receipt of artifact/publish: artifact, version, number, capability URL when served, event cursor, reuse.",
+  });