@spacefast/common 0.0.2

package/dist/contracts/runtime-api.js

@@ -0,0 +1,513 @@
+import { z } from "zod";
+import { policyDocSchema } from "./access.js";
+import { conventionFilesSchema, manifestFileSchema } from "./internal.js";
+const runtimeConventionFilesSchema = conventionFilesSchema.omit({ routes: true }).strict();
+const hostCanonicalRedirectSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    status: z.literal(308).default(308),
+});
+// Immutable version hosts carry their own target version: the intent is the
+// COMPLETE declarative hostname map for the space (every retained ready
+// version), so a route update can never orphan an older version URL.
+const versionHostnameEntrySchema = z.object({
+    hostname: z.string().min(1),
+    version_id: z.string().min(1),
+});
+const proxyHostRouteEntrySchema = z.object({
+    hostname: z.string().min(1),
+    path_prefix: z.string().min(1).default("/"),
+    upstream: z.string().url(),
+    noindex: z.boolean().default(false),
+});
+const runtimeRouteIntentSchema = z.object({
+    production_hostnames: z.array(z.string().min(1)).default([]),
+    noindex_production_hostnames: z.array(z.string().min(1)).default([]),
+    version_hostnames: z.array(versionHostnameEntrySchema).default([]),
+    host_canonical_redirects: z.array(hostCanonicalRedirectSchema).default([]),
+    proxy_host_routes: z.array(proxyHostRouteEntrySchema).default([]),
+});
+// Changed-path purge contract (internal-docs/platform.md "Cache Management"):
+// finalize computes the changed-path set against the previous pointer target
+// — expanded to canonical request paths (leading slash, directory-index
+// variants included) — and carries it through the runtime callback journal;
+// the callback receiver translates journal events into edge purges scoped to
+// changed paths, never a blanket purge when a diff exists. Past this cap (or
+// when no previous pointer target exists) the control plane omits the set and
+// purge handling falls back to one host-wide purge.
+export const RUNTIME_CHANGED_PATHS_MAX = 500;
+const changedPathsSchema = z
+    .array(z
+    .string()
+    .min(1)
+    .max(2048)
+    .describe("Canonical request path (decoded, leading slash) whose served bytes changed."))
+    .max(RUNTIME_CHANGED_PATHS_MAX)
+    .optional()
+    .describe("Request paths changed vs the previous pointer target; absent = no diff available (host-wide purge fallback). Echoed verbatim into the route_updated journal event.");
+const previousVersionIdSchema = z
+    .string()
+    .min(1)
+    .optional()
+    .describe("The pointer target this activation replaces (diff baseline).");
+export const runtimeVersionCreateRequestSchema = z.object({
+    version_id: z.string().min(1).optional(),
+    files: z.array(manifestFileSchema),
+    retained_files: z.array(manifestFileSchema).default([]),
+    reusable_version_id: z.string().min(1).optional(),
+    // "declared" sessions validate every PUT against the declared manifest.
+    // "open" sessions (internal-docs/platform.md "Upload Contract" shape 2) have
+    // no manifest: the runtime enforces path policy and the session caps per
+    // PUT, computes streaming hashes, and finalize derives the manifest.
+    // Plan-policy caps ride in session state, never in the upload JWT, and are
+    // valid only on open sessions.
+    session_mode: z.enum(["declared", "open"]).default("declared"),
+    max_total_bytes: z.number().int().positive().optional(),
+    max_file_count: z.number().int().positive().optional(),
+    // Session state stores the upload truth (spec "Upload Contract"): the version's
+    // manifest hash and the draft expiry so resume answers come from runtime state.
+    manifest_hash: z.string().optional(),
+    expires_at: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+    convention_files: runtimeConventionFilesSchema.default({}),
+});
+export const runtimeVersionCreateResponseSchema = z.object({
+    space_id: z.string(),
+    version_id: z.string(),
+    upload_id: z.string(),
+    created_at: z.string(),
+});
+// Runtime-truth upload session state (spec "Upload Contract"): the resume flow asks
+// the runtime which declared files/chunks are actually present instead of guessing
+// from control-plane pending-upload state.
+export const runtimeUploadSessionResponseSchema = z.object({
+    space_id: z.string(),
+    version_id: z.string(),
+    upload_id: z.string(),
+    session_mode: z.enum(["declared", "open"]),
+    created_at: z.string().nullable(),
+    expires_at: z.string().nullable(),
+    manifest_hash: z.string().nullable(),
+    files: z.array(z.object({
+        path: z.string(),
+        size: z.number().int().nonnegative(),
+        sha256: z.string().optional(),
+        uploaded: z.boolean(),
+    })),
+    // Declared paths the runtime has not committed yet (empty for open sessions).
+    pending_paths: z.array(z.string()),
+    // Staged chunked-upload parts by canonical path (contiguity is checked at complete).
+    chunks: z.record(z.string(), z.array(z.number().int().positive())),
+});
+// Route-pointer config is pure serving policy: THE resolved access policy plus
+// the anonymous claim countdown. Space passwords are NOT a separate config
+// channel — they ride inside `policy.rules` as a password challenge rule (one
+// access model, spec "Runtime"). Per-version serving behavior
+// (index/fallback/listing) is a version artifact concern, never route config.
+const runtimeRouteConfigSchema = z.object({
+    // THE unified policy lane ({ rules: RuntimeRule[] }) the runtime enforcer
+    // (access-rules.php) evaluates first-match-wins for every host entry this
+    // space serves — route hosts, custom domains, and immutable version hosts
+    // alike. Carries platform + file + cloud rules (platform prepended, always
+    // wins). Explicit null clears the stored policy; absence leaves it untouched.
+    policy: policyDocSchema.nullable().optional(),
+    // Serving-secret map (name -> value) the policy's password rules reference by
+    // `auth.password.ref` = "secret:<name>". Carries the space-password bcrypt
+    // verifier hash the runtime resolves and `password_verify`s. Explicit null
+    // clears stored secrets; absence leaves them untouched.
+    secrets: z.record(z.string().min(1), z.string().min(1)).nullable().optional(),
+    // Anonymous claim-window countdown (ISO timestamp), compiled into serving
+    // state so the runtime can render the expiry-rescue banner for visitors
+    // holding the claim-link viewer session. Null/absent once claimed.
+    anonymous_expires_at: z.string().nullable().optional(),
+});
+// Compiled SpaceConfig serving primitives (spec "Serving resolution"): the finalize
+// compiler resolves content defaults -> sf.jsonc -> space overlay into this shape;
+// the runtime stores it on the version's serving artifact and never re-infers. When
+// absent, the runtime infers content defaults (root index.html => website-style,
+// otherwise artifact-style listing + viewer).
+const runtimeServingConfigSchema = z.object({
+    index: z
+        .union([z.string().min(1), z.literal(false)])
+        .optional()
+        .describe("Directory index file name, or false to disable directory index resolution."),
+    fallback: z
+        .object({
+        path: z.string().min(1).describe("Committed file served when no exact route matches."),
+        status: z
+            .union([z.literal(200), z.literal(404)])
+            .describe("Response status for the fallback; 200 with /index.html is the SPA shape."),
+    })
+        .nullable()
+        .optional(),
+    listing: z
+        .boolean()
+        .optional()
+        .describe("Generate directory-listing pages for directories without an index file."),
+    viewer: z
+        .boolean()
+        .optional()
+        .describe("Generate the single-file viewer page when a version has exactly one public file."),
+    meta: z
+        .object({
+        title: z.string().max(300).optional().describe("Listing/viewer/OG title."),
+        description: z.string().max(1000).optional().describe("Listing/viewer/OG description."),
+        image: z.string().max(2000).optional().describe("OG image path."),
+    })
+        .nullable()
+        .optional()
+        .describe("Finalize-resolved listing/viewer/OG metadata (effective SpaceConfig meta); wins over session metadata."),
+    // Hidden experimental build-pipeline flag: absent on every version finalized
+    // without it (byte-identical payload to today). Only ever sent as true.
+    experimental_gutenberg: z.boolean().optional(),
+    // Platform-owned head metadata injection for normal HTML finalization. This is
+    // distinct from the hidden user build-pipeline flag: it only enables missing
+    // title/description/OG/Twitter tags derived from finalized SpaceConfig meta.
+    platform_meta: z.boolean().optional(),
+    // Platform-owned same-host SDK bootstrap metadata. The public Cast base is
+    // finalized with the version so locally-created remote runtimes do not guess
+    // between local/prod; resource identity is also per-version because one
+    // runtime/Atomic can serve many spaces.
+    spacefast_sdk: z
+        .object({
+        cast_api_base: z.string().url().max(2000).nullable().optional(),
+        cast_ws_url: z.string().url().max(2000).nullable().optional(),
+        cast_resource_key: z.string().min(1).max(256).nullable().optional(),
+    })
+        .optional(),
+    // CP-validated inject snippets (<= 8 KB each, <= 16 per array); sent only
+    // when experimental_gutenberg is true. Char caps here are a sanity bound —
+    // the byte caps are enforced by the shared SpaceConfig validator.
+    inject: z
+        .object({
+        head: z.array(z.string().max(8192)).max(16).optional(),
+        bodyStart: z.array(z.string().max(8192)).max(16).optional(),
+        bodyEnd: z.array(z.string().max(8192)).max(16).optional(),
+        noscript: z.array(z.string().max(8192)).max(16).optional(),
+    })
+        .optional(),
+});
+const runtimeZeroEndpointCapabilitiesSchema = z
+    .object({
+    db: z.boolean().optional(),
+    fetch: z.boolean().optional(),
+    auth: z.boolean().optional(),
+    env: z.boolean().optional(),
+    realtime: z.boolean().optional(),
+})
+    .default({});
+const runtimeZeroEndpointSchema = z.object({
+    method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]),
+    path: z.string().min(1).max(2048),
+    source: z
+        .string()
+        .min(1)
+        .max(2 * 1024 * 1024),
+    endpoint_id: z.string().min(1).max(256).optional(),
+    schema_hash: z.string().min(1).max(256).optional(),
+    capabilities: runtimeZeroEndpointCapabilitiesSchema.optional(),
+    db: z.record(z.string(), z.unknown()).optional(),
+});
+const runtimeZeroRunSchema = z.object({
+    run_id: z.string().min(1).max(256),
+    source: z
+        .string()
+        .min(1)
+        .max(2 * 1024 * 1024),
+    schema_hash: z.string().min(1).max(256).optional(),
+    capabilities: runtimeZeroEndpointCapabilitiesSchema.optional(),
+    db: z.record(z.string(), z.unknown()).optional(),
+});
+export const runtimeVersionFinalizeRequestSchema = z.object({
+    upload_id: z.string().min(1),
+    // The version's authoritative ready timestamp (epoch seconds), passed by the
+    // control plane when the version already reached ready (re-finalize, import
+    // re-materialization, provider migration). The engine stamps it ONCE into the
+    // version metadata; access-window rules (windowDays) compare against this
+    // stored value — never a filesystem mtime that resets on rebuilds.
+    ready_at: z.number().int().positive().optional(),
+    convention_files: runtimeConventionFilesSchema.optional(),
+    // Finalize-time `{{ vars.NAME }}` substitution output (spec "Variable
+    // rules"): substituted bytes replace the served files; the engine keeps the
+    // pre-substitution bytes in `files-original/` so declared-sha dedup still
+    // verifies upload identity. Keyed by canonical version-relative path.
+    template_files: z
+        .record(z.string().min(1).describe("Canonical committed path declared in `templates`."), z
+        .string()
+        .max(2 * 1024 * 1024)
+        .describe("Substituted file contents (secret values never reach this payload)."))
+        .refine((files) => Object.keys(files).length <= 100, {
+        message: "template_files supports up to 100 entries.",
+    })
+        .optional()
+        .describe("Substituted template contents applied over the committed tree at finalize."),
+    // Per-channel template variants (spec "Per-channel values"): channelValues
+    // overrides compile channel-specific contents of declared template files as
+    // channel-scoped serving artifacts. Keyed by RUNTIME ROUTE NAME (route names
+    // are runtime-only vocabulary; the live channel serves via `production`).
+    // Variants serve only on the route's hosts — permanent Version URLs always
+    // serve the version's own finalize-resolved values.
+    template_variants: z
+        .record(z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[A-Za-z0-9._-]+$/)
+        .describe("Runtime route name this variant set serves."), z
+        .record(z.string().min(1).describe("Canonical committed path declared in `templates`."), z
+        .string()
+        .max(2 * 1024 * 1024)
+        .describe("Variant file contents (secret values never reach this payload)."))
+        .refine((files) => Object.keys(files).length <= 100, {
+        message: "template_variants supports up to 100 entries per route.",
+    }))
+        .refine((routes) => Object.keys(routes).length <= 8, {
+        message: "template_variants supports up to 8 routes.",
+    })
+        .optional()
+        .describe("Channel-variant template contents, keyed by runtime route name."),
+    serving: z
+        .object({
+        headers_exact: z.record(z.string(), z.array(z.record(z.string(), z.unknown()))).default({}),
+        headers_pattern: z.array(z.record(z.string(), z.unknown())).default([]),
+        redirects_exact: z.record(z.string(), z.array(z.record(z.string(), z.unknown()))).default({}),
+        redirects_pattern: z.array(z.record(z.string(), z.unknown())).default([]),
+        config: runtimeServingConfigSchema.optional(),
+        // Compiled SpaceTheme custom-property declarations consumed by themeable pages
+        // (directory listings, single-file viewers, platform pages). The finalize
+        // compiler validates the token grammar; the runtime re-rejects anything that
+        // could escape a <style> element or reach the network.
+        theme_css: z.string().max(16384).optional(),
+        // Trusted Zero endpoint source compiled by the runtime into private
+        // endpoint-specific JS, QuickJS bytecode, and PHP manifest invoke actions.
+        zero_endpoints: z.array(runtimeZeroEndpointSchema).max(128).optional(),
+        // Trusted Zero run-handler source compiled into private artifacts for
+        // non-HTTP Zero execution surfaces. These are not PHP route actions.
+        zero_runs: z.array(runtimeZeroRunSchema).max(128).optional(),
+    })
+        .optional(),
+    activate: z
+        .object({
+        route_name: z
+            .string()
+            .min(1)
+            .default("production")
+            .describe("Runtime route-pointer to activate; route names are runtime-only vocabulary."),
+        config: runtimeRouteConfigSchema.optional(),
+        changed_paths: changedPathsSchema,
+        previous_version_id: previousVersionIdSchema,
+        production_hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
+        noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
+        version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
+        host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
+        proxy_host_routes: runtimeRouteIntentSchema.shape.proxy_host_routes,
+    })
+        .optional(),
+});
+export const runtimeVersionFinalizeResponseSchema = z.object({
+    space_id: z.string(),
+    version_id: z.string(),
+    status: z.literal("ready"),
+    // Open sessions: the manifest derived from what was actually uploaded
+    // (path, size, streaming sha256). Absent for declared sessions.
+    manifest: z.array(manifestFileSchema).optional(),
+});
+export const runtimeRouteUpdateRequestSchema = z.object({
+    version_id: z.string().min(1),
+    config: runtimeRouteConfigSchema.optional(),
+    changed_paths: changedPathsSchema,
+    previous_version_id: previousVersionIdSchema,
+    production_hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
+    noindex_production_hostnames: runtimeRouteIntentSchema.shape.noindex_production_hostnames,
+    version_hostnames: runtimeRouteIntentSchema.shape.version_hostnames,
+    host_canonical_redirects: runtimeRouteIntentSchema.shape.host_canonical_redirects,
+    proxy_host_routes: runtimeRouteIntentSchema.shape.proxy_host_routes,
+});
+export const runtimeRouteUpdateResponseSchema = z.object({
+    space_id: z.string(),
+    route_name: z.string(),
+    version_id: z.string(),
+});
+export const runtimeTombstonesUpdateRequestSchema = z.object({
+    hostnames: runtimeRouteIntentSchema.shape.production_hostnames,
+    mode: z.enum(["replace", "add", "remove"]).default("replace"),
+    // Optional reason/category drive a differentiated tombstone variant on the
+    // runtime (e.g. csam -> bare 404, copyright -> 451, suspension -> 402). The
+    // runtime falls back to a generic 404 when both are absent, so these are
+    // additive and back-compatible.
+    reason: z.string().optional(),
+    category: z.string().optional(),
+});
+export const runtimeTombstonesUpdateResponseSchema = z.object({
+    space_id: z.string(),
+    tombstone_count: z.number().int().nonnegative(),
+});
+export const runtimeSpaceDeleteResponseSchema = z.object({
+    space_id: z.string(),
+    status: z.literal("deleted"),
+});
+export const runtimeVersionDeleteResponseSchema = z.object({
+    space_id: z.string(),
+    version_id: z.string(),
+    status: z.literal("deleted"),
+});
+export const runtimeSpaceRepairResponseSchema = z.object({
+    space_id: z.string(),
+    status: z.literal("repaired"),
+});
+const runtimeExportImportStatusSchema = z.enum([
+    "waiting_for_archive",
+    "pending",
+    "running",
+    "complete",
+]);
+export const runtimeSpaceExportStartRequestSchema = z
+    .object({
+    version_ids: z.array(z.string().min(1)).min(1).optional(),
+    // Honest export options (spec SpaceExportRequest): include_files=false
+    // produces a config-only archive; include_explicit_config=false skips the
+    // space access policy entry. Recorded in stattic.json `includes`.
+    include_files: z.boolean().optional(),
+    include_explicit_config: z.boolean().optional(),
+})
+    .strict();
+export const runtimeSpaceExportResponseSchema = z.object({
+    type: z.literal("space_export"),
+    export_id: z.string(),
+    space_id: z.string(),
+    status: runtimeExportImportStatusSchema,
+    cursor: z.number().int().nonnegative(),
+    processed_files: z.number().int().nonnegative(),
+    total_files: z.number().int().nonnegative(),
+    version_ids: z.array(z.string()),
+    archive_size: z.number().int().nonnegative().optional(),
+    // SHA-256 of the finished archive (64 lowercase hex), computed once at
+    // completion so the control plane can expose SpaceExport.archive.sha256.
+    archive_sha256: z.string().optional(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    completed_at: z.string().optional(),
+});
+export const runtimeSpaceImportStartRequestSchema = z
+    .object({
+    version_id_map: z.record(z.string(), z.string()).optional(),
+})
+    .strict();
+// Deferred version-id mapping: control-plane-driven uploads land on the
+// runtime before the control plane has read the archive, so the freshly
+// minted target ids are supplied here before the first step.
+export const runtimeSpaceImportMapRequestSchema = z
+    .object({
+    version_id_map: z.record(z.string(), z.string()),
+})
+    .strict();
+export const runtimeSpaceImportResponseSchema = z.object({
+    type: z.literal("space_import"),
+    import_id: z.string(),
+    space_id: z.string(),
+    status: runtimeExportImportStatusSchema,
+    cursor: z.number().int().nonnegative(),
+    processed_files: z.number().int().nonnegative(),
+    total_files: z.number().int().nonnegative(),
+    version_ids: z.array(z.string()),
+    created_at: z.string(),
+    updated_at: z.string(),
+    completed_at: z.string().optional(),
+});
+// Per-space generation state reported by the authed state endpoint. The
+// reconciliation sweep compares this against control-plane expectations
+// (space liveVersionId vs the runtime's route pointers) and repairs targeted
+// mismatches — never a blanket re-sync (internal-docs/platform.md "Cache
+// Management": missed callbacks degrade to bounded staleness).
+export const runtimeSpaceStateSchema = z.object({
+    space_id: z.string().min(1).describe("Space whose runtime route pointers follow."),
+    routes: z
+        .record(z.string(), z.string())
+        .describe("Route pointer map: route name -> version id currently compiled for serving."),
+    tombstone_count: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Hostnames the runtime serves a tombstone page for on this space."),
+});
+export const runtimeHealthResponseSchema = z.object({
+    ok: z.literal(true),
+    runtime: z.literal("stattic-php"),
+    schema: z.string().min(1).optional(),
+    engine_version: z.string().min(1).optional(),
+    engine_revision: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Runtime engine bundle revision. Missing means the engine predates revision health."),
+    site_state: z.string().min(1).optional(),
+    request_hostname: z.string().optional(),
+});
+export const runtimeStateResponseSchema = z.object({
+    ok: z.literal(true),
+    runtime: z.literal("stattic-php"),
+    engine_revision: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Runtime engine bundle revision. Missing means the engine predates revision state."),
+    // Optional generation-state fields (absent on engines predating the reconcile
+    // handshake; the sweep treats absence as "cannot compare").
+    routes_generation: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Active route-index generation id (routes/current.php pointer)."),
+    spaces: z
+        .array(runtimeSpaceStateSchema)
+        .optional()
+        .describe("Per-space route-pointer state for reconcile comparison."),
+});
+// Runtime callback journal event (internal-docs/platform.md "Cache
+// Management"): the engine journals every management mutation and delivers it
+// at-least-once to the control-plane callback receiver, which translates
+// serving-affecting events into provider edge purges. `event_id` is the stable
+// journal id — purge enqueues are idempotent on (event_id, hostname) so
+// replays are no-ops. The object is intentionally loose: engines may journal
+// extra diagnostic fields without breaking older control planes.
+export const runtimeCallbackEventSchema = z.looseObject({
+    event: z.string().min(1).describe("Journal event name (e.g. route_updated, space_deleted)."),
+    event_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Stable journal/callback id; purge handling replays as no-ops on this id."),
+    operation_id: z
+        .string()
+        .optional()
+        .describe("Control-plane operation the management call ran under."),
+    space_id: z.string().optional().describe("Space the event applies to, when space-scoped."),
+    version_id: z.string().optional().describe("Version the event applies to, when version-scoped."),
+    route_name: z.string().optional().describe("Route pointer the event updated, when route-scoped."),
+    hostnames: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Hostnames whose serving output this event changed; purge targets."),
+    changed_paths: changedPathsSchema,
+    previous_version_id: previousVersionIdSchema,
+});
+export const runtimeEventsDrainResponseSchema = z.object({
+    delivered_count: z.number().int().nonnegative(),
+    failed_count: z.number().int().nonnegative(),
+    expired_count: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Undeliverable callbacks dropped after exceeding the attempt cap."),
+    returned_count: z.number().int().nonnegative().optional(),
+    // Pull fallback: events whose push origin was unreachable are handed back to
+    // the drain caller (the control plane) instead of rotting in the journal.
+    // Processing replays are no-ops on (event_id, hostname).
+    events: z
+        .array(z.object({
+        operation_id: z.string().optional(),
+        event: runtimeCallbackEventSchema,
+    }))
+        .optional(),
+});