@spacefast/common 0.0.12 → 0.0.17

package/dist/contracts/functions.js

@@ -0,0 +1,475 @@
+import { z } from "zod";
+import { appRoutePathSchema, executionCapabilitiesSchema, executionLogEntrySchema, executionLogListQuerySchema, executionLogListResponseSchema, executionSha256Schema, httpMethodSchema, runtimeKindSchema, } from "./execution.js";
+/**
+ * Spacefast Functions: tenant workers run as Cloudflare Dynamic Workers.
+ *
+ * The shape of this product follows from two constraints that are not
+ * negotiable and that together rule out the obvious architecture:
+ *
+ * 1. **Cloudflare is reached from wp.cloud, never from the control plane.**
+ *    The control plane records intent; the space's own origin performs every
+ *    Cloudflare call.
+ * 2. **Every asset is served by wp.cloud.** We deliberately decline
+ *    Cloudflare's static-asset support for user workers. A worker receives
+ *    only the requests that could not be answered from bytes on disk, and
+ *    `/_next/static/*` and friends never leave our origin.
+ *
+ * Dynamic Workers is what makes both hold at once. There is no upload: a
+ * version's bundle stays in its own content store on wp.cloud, and the host
+ * worker pulls it on demand through the Worker Loader binding. So there is no
+ * script lifecycle here — no namespace, no script name, no tag budget, no
+ * eviction, no garbage collection — because there is no artefact of ours living
+ * on Cloudflare to manage. What Cloudflare holds is a warm isolate, which is a
+ * cache, not a record.
+ *
+ * That also keeps the exit cheap. The contract below is "here is a module
+ * graph, here is its configuration, run it", which is workerd's own shape; the
+ * managed runtime is an implementation of it rather than the thing we built
+ * against.
+ *
+ * What the worker gets in exchange is the thing we could not build: a real V8
+ * isolate that runs npm packages and framework output — OpenNext Next.js among
+ * them — without us having to sandbox any of it.
+ *
+ * The cost is that the worker is a continent away from the space's MySQL.
+ * `ctx.db` therefore travels back over an HTTPS relay to the same PHP broker
+ * the local tier speaks to over a pipe, which is slower and batched rather
+ * than transactional. That is why capsules are a different product rather
+ * than a placement option — see `endpointIsPortable` in `./execution.js`.
+ */
+export const FUNCTIONS_RUNTIME_KIND = "functions";
+export const FUNCTIONS_SOURCE_METADATA_KEY = "spacefastFunctions";
+export const FUNCTIONS_PLATFORM_ROUTE_PREFIX = "/__spacefast/functions";
+export const FUNCTIONS_RUNTIME_ROUTE_PATHS = {
+    logs: `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/logs`,
+    /** Where a dispatched worker calls back for brokered capabilities. */
+    relay: `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/relay`,
+};
+/** Public, signed read path. Distinct from storage so the token is never a filename. */
+export const FUNCTIONS_BUNDLE_ROUTE_PREFIX = `${FUNCTIONS_PLATFORM_ROUTE_PREFIX}/b`;
+export const FUNCTIONS_RUNTIME_STORAGE_ROOT = "__spacefast/functions";
+/**
+ * Where a version's compiled bundle lives.
+ *
+ * Under the same `__spacefast/` prefix as every other platform-owned path, so
+ * there is one convention rather than one per product. Two consequences fall
+ * out of that placement, and both are wanted:
+ *
+ * - It is not servable as static content. The runtime treats the whole prefix
+ *   as control paths, so a tenant's compiled source is not readable at a
+ *   guessable URL — and the digest that would make it guessable appears in
+ *   build output.
+ * - It is written by the ordinary publish path anyway. The upload policy
+ *   carves out exactly this subtree (`publish-policy.ts`), so the bundle rides
+ *   the normal manifest and upload passes instead of needing a parallel one.
+ *
+ * The dispatch configuration — host, capabilities, relay credential — is not
+ * here and is not content at all. The engine writes it beside the version's
+ * file tree rather than inside it, exactly as it does for Zero, so a publish
+ * cannot reach it: no carve-out, no upload path, nothing to guard. A publish
+ * able to write that file would be a publish able to grant itself authority it
+ * was never given.
+ */
+export const FUNCTIONS_RUNTIME_BUNDLE_ROOT = `${FUNCTIONS_RUNTIME_STORAGE_ROOT}/bundles`;
+export const FUNCTIONS_BUNDLE_FORMAT = "spacefast.functions.bundle.v1";
+/**
+ * Ceiling on a bundle's decoded size.
+ *
+ * The whole module graph arrives in one response so a cold isolate costs a
+ * single round trip, which means this number is also how much the host holds in
+ * memory before instantiating anything. Set below the runtime's own script
+ * limit so an oversized build fails in our tooling, where we can say which
+ * modules are large, rather than at dispatch, where the tenant sees a 502.
+ */
+export const FUNCTIONS_BUNDLE_MAX_BYTES = 8 * 1024 * 1024;
+const functionsRoutePathSchema = appRoutePathSchema({
+    subject: "Function routes",
+});
+/**
+ * A worker's dynamic route table. Anything not matched here is answered from
+ * the version's static content by wp.cloud and never reaches Cloudflare, which
+ * is both the cheaper path and the one that keeps assets ours.
+ */
+export const functionsRouteSchema = z
+    .object({
+    method: httpMethodSchema.nullable().default(null),
+    path: functionsRoutePathSchema,
+    /** A terminal `:splat` route claims the whole subtree below `path`. */
+    subtree: z.boolean().default(false),
+})
+    .strict();
+/**
+ * One module in a bundle, in the shape the Worker Loader consumes.
+ *
+ * `commonjs` exists because bundlers still emit it and rejecting it would fail
+ * builds for a format the runtime accepts. Binary module types are deliberately
+ * absent: nothing we build today emits them, and adding one later is additive.
+ */
+export const functionsBundleModuleSchema = z.union([
+    z.object({ js: z.string() }).strict(),
+    z.object({ cjs: z.string() }).strict(),
+    z.object({ text: z.string() }).strict(),
+    z.object({ json: z.unknown() }).strict(),
+]);
+/**
+ * The document served at a bundle URL and parsed by the host.
+ *
+ * Both sides of that exchange validate against this schema, which is the point
+ * of it living here: the CLI's bundler and the host's loader are separate
+ * deployments that must agree, and the only thing keeping them honest is a
+ * shared definition of the bytes in between.
+ */
+export const functionsBundleManifestSchema = z
+    .object({
+    format: z.literal(FUNCTIONS_BUNDLE_FORMAT),
+    mainModule: z.string().min(1).max(1024),
+    modules: z.record(z.string().min(1).max(1024), functionsBundleModuleSchema),
+})
+    .strict()
+    .refine((manifest) => Object.hasOwn(manifest.modules, manifest.mainModule), {
+    message: "A bundle manifest must contain its own entry module.",
+    path: ["mainModule"],
+});
+/**
+ * Where the worker's compiled bytes live in the version's own content store.
+ * Unlike Zero's bundles these are not carried inline in the finalize payload:
+ * framework output routinely runs to megabytes, and inlining it would put the
+ * whole thing through the control plane, which the direct-from-wp.cloud rule
+ * forbids.
+ */
+export const functionsBundleRefSchema = z
+    .object({
+    path: z
+        .string()
+        .min(1)
+        .startsWith(`${FUNCTIONS_RUNTIME_BUNDLE_ROOT}/`)
+        .refine((path) => !path.split("/").includes(".."), {
+        message: "Function bundle paths cannot traverse outside the bundle root.",
+    }),
+    sha256: executionSha256Schema,
+    size: z.number().int().nonnegative().max(FUNCTIONS_BUNDLE_MAX_BYTES),
+})
+    .strict();
+/**
+ * The path a bundle is served from.
+ *
+ * Content-addressed, so the response is immutable and can be cached at our edge
+ * forever — a cold isolate anywhere in the world costs one CDN hit rather than
+ * a round trip to the space's origin.
+ *
+ * The token rides in the path rather than the query string for exactly that
+ * reason: a query parameter is subject to cache-key normalisation, and a token
+ * that gets stripped from the key would let one space's cached bundle answer
+ * another space's URL.
+ *
+ * Both halves are load-bearing. The digest alone is unguessable to anyone who
+ * lacks the bytes, but it is derivable by anyone who *has* them, and it shows up
+ * in build output and `sf runtime status`. The token adds the dimension the
+ * digest cannot: holding the code does not entitle you to fetch it from us, and
+ * rotating the site secret invalidates every URL at once.
+ */
+export function functionsBundlePath(input) {
+    return `${FUNCTIONS_BUNDLE_ROUTE_PREFIX}/${bundleDigest(input.sha256)}/${input.token}/bundle.json`;
+}
+/**
+ * Where the bundle actually sits in the published version — the same path minus
+ * the token segment. The token authorises the read; it does not name the file,
+ * so rotating the signing key changes every URL without moving a single byte.
+ */
+export function functionsBundleStoragePath(input) {
+    return `${FUNCTIONS_RUNTIME_BUNDLE_ROOT}/${bundleDigest(input.sha256)}/bundle.json`;
+}
+/**
+ * The digest is carried in contracts as `sha256:<hex>` but appears in paths as
+ * bare hex: a colon is legal in a path segment yet needlessly invites
+ * normalisation differences between the edge, the origin, and fetch.
+ */
+function bundleDigest(sha256) {
+    return sha256.startsWith("sha256:") ? sha256.slice(7) : sha256;
+}
+/**
+ * Cloudflare pins runtime behaviour to a date rather than a version number, so
+ * a worker built today keeps today's semantics forever. We record the author's
+ * choice on the version, which is what makes rollback honest: promoting an old
+ * version restores the compatibility date it was built against.
+ */
+const functionsCompatibilityDateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+export const functionsWorkerArtifactSchema = z
+    .object({
+    format: z.literal("spacefast.functions.worker.v1"),
+    appName: z.string().min(1).max(128),
+    /**
+     * What the author wrote, for display: `handler.ts`, `.open-next/worker.js`.
+     * It names a file in their project, which after bundling no longer exists.
+     */
+    entry: z.string().min(1).max(1024),
+    /**
+     * The entry module's name *inside the bundle manifest* — what the loader
+     * instantiates. Carried here rather than read from the manifest because the
+     * origin dispatches without ever opening the bundle: the bytes go from our
+     * CDN straight to the isolate, and the origin only routes.
+     */
+    mainModule: z.string().min(1).max(1024),
+    bundle: functionsBundleRefSchema,
+    compatibilityDate: functionsCompatibilityDateSchema,
+    compatibilityFlags: z.array(z.string().min(1).max(128)).max(32).default([]),
+    routes: z.array(functionsRouteSchema).max(256).default([]),
+    /**
+     * Aggregate of what the worker's handlers reach, used to decide which
+     * brokered capabilities the relay will honour for this version. A worker
+     * that never declares `db` gets a relay that refuses `db.read` outright,
+     * so an injected dependency cannot widen authority at runtime.
+     */
+    capabilities: executionCapabilitiesSchema,
+})
+    .strict();
+/**
+ * The authority a dispatched worker may exercise, in the vocabulary the host
+ * speaks on the wire.
+ *
+ * Deliberately a different, narrower list than `executionCapabilitiesSchema`.
+ * That one records what a build *declared* it uses; this one is what the origin
+ * *grants*, resolved by the control plane at finalize so the origin forwards a
+ * decision rather than making one. Anything absent fails closed at the relay.
+ */
+export const FUNCTIONS_DISPATCH_CAPABILITIES = ["db.read", "db.write", "fetch", "log"];
+export const functionsDispatchCapabilitySchema = z.enum(FUNCTIONS_DISPATCH_CAPABILITIES);
+/**
+ * Resolves a build's declared capabilities into the grant a dispatch carries.
+ *
+ * Three of the six declared capabilities have no dispatch counterpart, and each
+ * for its own reason:
+ *
+ * - `env` is not a runtime call at all. Values are resolved at finalize and
+ *   travel in the config, so a worker reading `env` reaches nothing.
+ * - `auth` and `realtime` bind a handler to the local tier — see
+ *   `endpointIsPortable` — so code declaring them deploys as a capsule and
+ *   never arrives here.
+ *
+ * `db` widens to both read and write because a declaration says a handler
+ * touches the database, not how. Narrowing it would take per-statement analysis
+ * we do not do, and guessing "read-only" from a declaration would be a grant
+ * the author never asked for and cannot see.
+ */
+export function functionsDispatchCapabilities(capabilities) {
+    const granted = new Set();
+    if (capabilities.db) {
+        granted.add("db.read");
+        granted.add("db.write");
+    }
+    if (capabilities.fetch) {
+        granted.add("fetch");
+    }
+    if (capabilities.logging) {
+        granted.add("log");
+    }
+    // Filtered from the canonical list so the order is stable: the grant is part
+    // of the host's isolate identity, and a reordering would retire warm isolates
+    // for no reason.
+    return FUNCTIONS_DISPATCH_CAPABILITIES.filter((capability) => granted.has(capability));
+}
+/** Everything except `log` needs the relay to mean anything. */
+export function functionsGrantNeedsRelay(granted) {
+    return granted.some((capability) => capability !== "log");
+}
+/**
+ * What the space origin needs in order to dispatch to the host on its own. The
+ * shared secret is a wp.cloud site secret; it is never part of a version's
+ * content and never reaches tenant code, so it is not modelled here.
+ *
+ * There is no account id and no namespace: the origin talks to one host worker
+ * over HTTPS and holds no Cloudflare API credential at all.
+ */
+export const functionsHostConfigSchema = z
+    .object({
+    /** The host worker's hostname, which wp.cloud dispatches to. */
+    hostname: z.string().min(1).max(255),
+    /**
+     * Where the host pulls this version's module graph, signed and minted at
+     * finalize.
+     *
+     * It is here rather than on the artifact because the artifact records what
+     * was built — a path and a digest, both stable — while this records how to
+     * reach it, which depends on a signing key and a hostname the build knew
+     * nothing about. Rotating the key changes every URL without changing a
+     * single artifact.
+     */
+    bundleUrl: z.string().url(),
+})
+    .strict();
+/**
+ * The callback a dispatched worker uses for `ctx.db`, `ctx.fetch` and logging.
+ *
+ * Each relay call re-enters the space's PHP-FPM pool, which is the deadlock
+ * hazard this product's admission control exists to bound: a proxied request
+ * occupies a worker for its whole life while its relay calls demand more. The
+ * batching allowance below is the other half of the answer — a handler that
+ * issues twenty statements must cost one relay round trip, not twenty. Measured
+ * against the PHP broker, batching twenty writes into one call is 8.3x faster
+ * than twenty separate ones.
+ */
+export const functionsRelayConfigSchema = z
+    .object({
+    url: z.string().url(),
+    /**
+     * Bearer credential minted per version. Rotating it also retires the warm
+     * isolate holding it: the host folds this token into the isolate's identity
+     * precisely so that a revoked credential cannot outlive its revocation.
+     */
+    token: z.string().min(1),
+    maxBatchStatements: z.number().int().min(1).max(256),
+    maxConcurrentCalls: z.number().int().min(1).max(64),
+})
+    .strict();
+/**
+ * What a build declares about its worker — everything the CLI can know from the
+ * author's project alone.
+ *
+ * Unlike Zero, this is *not* the same document the runtime receives. A build
+ * cannot name the host it will be dispatched to, cannot mint the credential its
+ * relay calls will carry, and cannot decide what authority it is granted; all
+ * three are the platform's to say. Keeping them out of this schema is what makes
+ * that structural rather than a convention — a version's own metadata has no
+ * field in which to assert authority it was not given.
+ */
+export const functionsSourceFinalizeSchema = z
+    .object({
+    runtimeKind: z.literal(FUNCTIONS_RUNTIME_KIND),
+    artifact: functionsWorkerArtifactSchema,
+    variables: z
+        .object({
+        source: z.literal("spacefast-variables"),
+        names: z.array(z.string().min(1)).default([]),
+    })
+        .strict()
+        .default({ source: "spacefast-variables", names: [] }),
+})
+    .strict();
+/**
+ * The document the control plane sends to the runtime, which the engine stores
+ * beside the version's files and the origin reads on every dispatch.
+ *
+ * It is the build's declaration plus the four things only the platform can
+ * supply: where to dispatch, what the worker is allowed to do, the credential
+ * that lets it do those things, and the resolved values of its variables.
+ */
+export const functionsRuntimeConfigSchema = functionsSourceFinalizeSchema
+    .extend({
+    host: functionsHostConfigSchema,
+    grantedCapabilities: z.array(functionsDispatchCapabilitySchema).max(8).default([]),
+    relay: functionsRelayConfigSchema.nullable().default(null),
+    /**
+     * Resolved at finalize, so a worker reading configuration never calls back
+     * to us for it — and so rotating a variable is a republish with an audit
+     * trail rather than a live mutation of what running code sees.
+     */
+    variableValues: z.record(z.string(), z.string()).default({}),
+})
+    .strict()
+    .refine((config) => !functionsGrantNeedsRelay(config.grantedCapabilities) || config.relay, {
+    message: "Capabilities were granted without a relay to serve them.",
+    path: ["relay"],
+});
+export const functionsDeployMetadataSchema = z
+    .object({
+    artifactId: z.string().min(1).optional(),
+    finalize: functionsSourceFinalizeSchema,
+})
+    .strict();
+/**
+ * Builds the declaration a publish attaches to its version.
+ *
+ * Exists so the CLI's publish step and every test that needs a Functions
+ * version agree on the shape by construction rather than by copying an object
+ * literal around — the same reason `createZeroRuntimeFinalizePayload` exists.
+ */
+export function createFunctionsSourceFinalize(input) {
+    return functionsSourceFinalizeSchema.parse({
+        runtimeKind: FUNCTIONS_RUNTIME_KIND,
+        artifact: {
+            format: "spacefast.functions.worker.v1",
+            appName: input.appName,
+            entry: input.entry,
+            mainModule: input.mainModule,
+            bundle: input.bundle,
+            compatibilityDate: input.compatibilityDate,
+            compatibilityFlags: input.compatibilityFlags ?? [],
+            routes: input.routes ?? [],
+            capabilities: input.capabilities ?? {},
+        },
+        variables: {
+            source: "spacefast-variables",
+            names: input.variableNames ?? [],
+        },
+    });
+}
+/**
+ * What a version's worker is currently doing, as an observer of the space can
+ * actually determine.
+ *
+ * There is no upload state to report. A bundle is either in the version's
+ * content store or it is not, and dispatch is decided by which version is
+ * serving — so these three cover the whole space of answers, and each one is
+ * checkable rather than inferred from a job we ran earlier.
+ */
+export const functionsExecutionStateSchema = z.enum([
+    /** No bundle at the version's bundle path. */
+    "absent",
+    /** Bundle present and dispatchable, but this version is not the live one. */
+    "ready",
+    /** This version is live: its routes dispatch to the host. */
+    "serving",
+]);
+/**
+ * What a live worker is, as the `app` member of a space's runtime status.
+ *
+ * Shaped like `zeroAppSchema` and discriminated by the same `runtimeKind`, so a
+ * reader switches on one field rather than probing for which product answered.
+ * No `versionId`: the status response it rides in already names the live
+ * version.
+ *
+ * Everything but `executionState` is a field of the version's own finalize
+ * metadata, so this answers whether or not the origin is reachable. There is no
+ * `database` field: `capabilities.db` is the fact the whole `/db` family
+ * branches on, and stating it twice invites the two to disagree.
+ */
+export const functionsAppSchema = z
+    .object({
+    runtimeKind: z.literal(FUNCTIONS_RUNTIME_KIND),
+    artifactId: z.string().min(1),
+    appName: z.string().min(1),
+    entry: z.string().min(1),
+    compatibilityDate: functionsCompatibilityDateSchema,
+    compatibilityFlags: z.array(z.string()).default([]),
+    routes: z.array(functionsRouteSchema).default([]),
+    capabilities: executionCapabilitiesSchema,
+    executionState: functionsExecutionStateSchema,
+    bundleSize: z.number().int().nonnegative(),
+    /** Digest of the bundle bytes; also this app's `artifactId` by default. */
+    bundleSha256: executionSha256Schema,
+    variables: z
+        .object({
+        source: z.literal("spacefast-variables"),
+        names: z.array(z.string()).default([]),
+    })
+        .strict(),
+})
+    .strict();
+/**
+ * The wire shape of the origin's log-read route, not a public API contract.
+ *
+ * Handler logs reach callers through `GET /v1/spaces/:spaceId/logs/runtime`,
+ * which serves the platform's own `runtimeLogListResponseSchema` for both
+ * execution tiers. These aliases describe the hop underneath it: a worker tails
+ * its output to the origin that dispatched it, and the control plane reads it
+ * back from there. Keeping them named after this product is the point — the
+ * origin is the only place a wp.cloud-hosted space keeps anything, and Zero's
+ * records never travel this path at all.
+ */
+export const functionsLogEntrySchema = executionLogEntrySchema;
+export const functionsLogListQuerySchema = executionLogListQuerySchema;
+export const functionsLogListResponseSchema = executionLogListResponseSchema;
+/** Narrows a space's live runtime kind to this product. */
+export function isFunctionsRuntime(kind) {
+    return kind === FUNCTIONS_RUNTIME_KIND;
+}