@spacefast/common 0.0.12 → 0.0.13

package/dist/contracts/execution.d.ts

@@ -0,0 +1,212 @@
+import { z } from "zod";
+/**
+ * The platform execution layer: everything true of running tenant code on
+ * Spacefast regardless of which product is running it.
+ *
+ * Two products sit on top of this file, and they are genuinely different
+ * things rather than two configurations of one thing:
+ *
+ * - **Zero** (`./zero.js`) runs capsules — schema, queries, mutations and
+ *   endpoints that share one parent-owned transaction — in the native runner
+ *   on a dedicated wp.cloud site, next to that site's MySQL.
+ * - **Functions** (`./functions.js`) runs workers on Cloudflare Workers for
+ *   Platforms, carrying npm and framework output that we could never sandbox
+ *   as well ourselves.
+ *
+ * The only surface both can host is an endpoint that touches neither the
+ * database nor the caller's identity — see `endpointIsPortable`. That is the
+ * portable seam, and it is deliberately narrow: a capsule handler's semantics
+ * depend on the transaction wrapped around it, which does not exist on an
+ * isolate a continent away from the database.
+ */
+/**
+ * What a live version runs. `static` is bytes on disk with no execution at
+ * all, and remains the overwhelming majority of traffic; the other two each
+ * name a product.
+ */
+export declare const runtimeKindSchema: z.ZodEnum<{
+    zero: "zero";
+    functions: "functions";
+    static: "static";
+}>;
+export type RuntimeKind = z.infer<typeof runtimeKindSchema>;
+export declare const EXECUTION_ENV_MAX_KEYS = 64;
+export declare const EXECUTION_ENV_NAME_MAX_BYTES = 128;
+export declare const EXECUTION_ENV_VALUE_MAX_BYTES: number;
+export declare const EXECUTION_ENV_TOTAL_VALUE_MAX_BYTES: number;
+/**
+ * Names the platform reserves for itself in the tenant environment. Tenant
+ * code cannot set these, so it cannot spoof the values the broker trusts.
+ */
+export declare const EXECUTION_ENV_RESERVED_PREFIXES: readonly ["SPACEFAST_", "ZERO_"];
+/** Paths the platform owns on every space, whatever the product. */
+export declare const PLATFORM_ROUTE_PREFIX = "/__spacefast";
+/**
+ * First path segments the platform claims. Matched as segment prefixes rather
+ * than whole segments because the runtime already reserves the whole family —
+ * `/__stattic_probe` is a live serving path, and `upload-policy.php` refuses
+ * any first segment starting with either of these. Encoding it the same way
+ * here keeps a capsule or worker from declaring a route the origin would
+ * intercept before it ever reached them.
+ */
+export declare const PLATFORM_RESERVED_ROUTE_SEGMENT_PREFIXES: readonly ["__spacefast", "__stattic", "__span"];
+export declare const executionSha256Schema: z.ZodString;
+export declare const executionBase64Schema: z.ZodString;
+export declare const executionIdentifierSchema: z.ZodString;
+export declare const executionEnvNameSchema: z.ZodString;
+/**
+ * Builds the route-path schema for a product. Structural rules — normalization,
+ * traversal, wildcards, the platform's own prefixes — are identical everywhere
+ * and live here. Each product passes the extra paths and prefixes its own app
+ * shell claims, because those differ: Zero's client router owns `/auth/*`,
+ * a Functions worker owns nothing beyond what the platform reserves.
+ */
+export declare function appRoutePathSchema(options: {
+    subject: string;
+    reservedPaths?: readonly string[];
+    reservedPrefixes?: readonly string[];
+}): z.ZodString;
+export declare const httpMethodSchema: z.ZodEnum<{
+    POST: "POST";
+    PUT: "PUT";
+    GET: "GET";
+    HEAD: "HEAD";
+    PATCH: "PATCH";
+    DELETE: "DELETE";
+    OPTIONS: "OPTIONS";
+}>;
+export type HttpMethod = z.infer<typeof httpMethodSchema>;
+/**
+ * What a handler is allowed to reach. Declared at build time from what the
+ * source actually imports, not from what the author claims, and printed in the
+ * publish receipt so placement is never a surprise.
+ */
+export declare const executionCapabilitiesSchema: z.ZodDefault<z.ZodObject<{
+    db: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    fetch: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    auth: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    env: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    realtime: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    logging: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+}, z.core.$strip>>;
+export type ExecutionCapabilities = z.infer<typeof executionCapabilitiesSchema>;
+/**
+ * The portable seam, stated as one predicate.
+ *
+ * `db` and `auth` are the two capabilities that bind a handler to the local
+ * tier. `db` because Zero's store guarantees every handler runs inside one
+ * parent-owned transaction, which an isolate reaching the database over a
+ * relay cannot offer. `auth` because capsule identity is resolved against that
+ * same transaction's view. Everything else — fetch, env, realtime, logging —
+ * is brokered identically on both tiers and does not constrain placement.
+ *
+ * Nothing here decides placement automatically: the product a version deploys
+ * to is a property of what its author wrote, and this predicate only reports
+ * whether the code could also have run on the other tier.
+ */
+export declare function endpointIsPortable(capabilities: ExecutionCapabilities): boolean;
+/**
+ * A source-carrying handler, before it is compiled to whichever tier will run
+ * it. Both products publish these; only the capability set decides which of
+ * them could accept a given one.
+ */
+export declare function executionEndpointSourceSchema(routePathSchema: z.ZodType<string>): z.ZodObject<{
+    method: z.ZodEnum<{
+        POST: "POST";
+        PUT: "PUT";
+        GET: "GET";
+        HEAD: "HEAD";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+        OPTIONS: "OPTIONS";
+    }>;
+    path: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    endpointId: z.ZodString;
+    source: z.ZodString;
+    capabilities: z.ZodDefault<z.ZodObject<{
+        db: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        fetch: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        auth: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        env: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        realtime: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+        logging: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+/**
+ * Byte-carrying artifacts travel inline in the finalize payload rather than as
+ * a separate upload, so a version's code lands in the same atomic write as the
+ * rest of it. The storage root and ceiling differ per product, hence a factory.
+ */
+export declare function executionBundleSchema(options: {
+    bundleRoot: string;
+    maxBytes: number;
+}): z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+    contentBase64: z.ZodString;
+}, z.core.$strict>;
+export declare function executionStaticFileSchema(options: {
+    storageRoot: string;
+    maxBytes: number;
+}): z.ZodObject<{
+    path: z.ZodString;
+    contentType: z.ZodString;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+    contentBase64: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Whether a version's execution surface may be read by anyone or only by the
+ * space's own members. Both products expose an inspect route; the policy is
+ * the same question on each.
+ */
+export declare const executionInspectPolicySchema: z.ZodEnum<{
+    public: "public";
+    private: "private";
+}>;
+export type ExecutionInspectPolicy = z.infer<typeof executionInspectPolicySchema>;
+export declare const executionLogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodString;
+    level: z.ZodEnum<{
+        info: "info";
+        error: "error";
+        debug: "debug";
+        warn: "warn";
+    }>;
+    requestId: z.ZodNullable<z.ZodString>;
+    versionId: z.ZodNullable<z.ZodString>;
+    handlerName: z.ZodNullable<z.ZodString>;
+    message: z.ZodString;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ExecutionLogEntry = z.infer<typeof executionLogEntrySchema>;
+export declare const executionLogListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+    handlerName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ExecutionLogListQuery = z.infer<typeof executionLogListQuerySchema>;
+export declare const executionLogListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        timestamp: z.ZodString;
+        level: z.ZodEnum<{
+            info: "info";
+            error: "error";
+            debug: "debug";
+            warn: "warn";
+        }>;
+        requestId: z.ZodNullable<z.ZodString>;
+        versionId: z.ZodNullable<z.ZodString>;
+        handlerName: z.ZodNullable<z.ZodString>;
+        message: z.ZodString;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ExecutionLogListResponse = z.infer<typeof executionLogListResponseSchema>;

package/dist/contracts/execution.js

@@ -0,0 +1,288 @@
+import { z } from "zod";
+/**
+ * The platform execution layer: everything true of running tenant code on
+ * Spacefast regardless of which product is running it.
+ *
+ * Two products sit on top of this file, and they are genuinely different
+ * things rather than two configurations of one thing:
+ *
+ * - **Zero** (`./zero.js`) runs capsules — schema, queries, mutations and
+ *   endpoints that share one parent-owned transaction — in the native runner
+ *   on a dedicated wp.cloud site, next to that site's MySQL.
+ * - **Functions** (`./functions.js`) runs workers on Cloudflare Workers for
+ *   Platforms, carrying npm and framework output that we could never sandbox
+ *   as well ourselves.
+ *
+ * The only surface both can host is an endpoint that touches neither the
+ * database nor the caller's identity — see `endpointIsPortable`. That is the
+ * portable seam, and it is deliberately narrow: a capsule handler's semantics
+ * depend on the transaction wrapped around it, which does not exist on an
+ * isolate a continent away from the database.
+ */
+/**
+ * What a live version runs. `static` is bytes on disk with no execution at
+ * all, and remains the overwhelming majority of traffic; the other two each
+ * name a product.
+ */
+export const runtimeKindSchema = z.enum(["static", "zero", "functions"]);
+export const EXECUTION_ENV_MAX_KEYS = 64;
+export const EXECUTION_ENV_NAME_MAX_BYTES = 128;
+export const EXECUTION_ENV_VALUE_MAX_BYTES = 16 * 1024;
+export const EXECUTION_ENV_TOTAL_VALUE_MAX_BYTES = 64 * 1024;
+/**
+ * Names the platform reserves for itself in the tenant environment. Tenant
+ * code cannot set these, so it cannot spoof the values the broker trusts.
+ */
+export const EXECUTION_ENV_RESERVED_PREFIXES = ["SPACEFAST_", "ZERO_"];
+/** Paths the platform owns on every space, whatever the product. */
+export const PLATFORM_ROUTE_PREFIX = "/__spacefast";
+/**
+ * First path segments the platform claims. Matched as segment prefixes rather
+ * than whole segments because the runtime already reserves the whole family —
+ * `/__stattic_probe` is a live serving path, and `upload-policy.php` refuses
+ * any first segment starting with either of these. Encoding it the same way
+ * here keeps a capsule or worker from declaring a route the origin would
+ * intercept before it ever reached them.
+ */
+export const PLATFORM_RESERVED_ROUTE_SEGMENT_PREFIXES = [
+    "__spacefast",
+    "__stattic",
+    "__span",
+];
+export const executionSha256Schema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+export const executionBase64Schema = z
+    .string()
+    .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/);
+export const executionIdentifierSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+export const executionEnvNameSchema = z
+    .string()
+    .min(1)
+    .max(EXECUTION_ENV_NAME_MAX_BYTES)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
+    .refine((name) => !EXECUTION_ENV_RESERVED_PREFIXES.some((prefix) => name.toUpperCase().startsWith(prefix)), { message: "Environment variable name uses a reserved prefix." });
+/**
+ * Rejects lone surrogates. A path that survives JSON but not UTF-8 encoding
+ * round-trips differently through PHP, Rust and Cloudflare's router, so it is
+ * refused at the contract rather than resolved differently on each tier.
+ */
+function hasWellFormedUnicode(value) {
+    for (let index = 0; index < value.length; index++) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            if (index + 1 >= value.length)
+                return false;
+            const next = value.charCodeAt(index + 1);
+            if (next < 0xdc00 || next > 0xdfff)
+                return false;
+            index++;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            return false;
+        }
+    }
+    return true;
+}
+function hasNoAsciiControlCharacters(value) {
+    for (let index = 0; index < value.length; index++) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit <= 0x1f || codeUnit === 0x7f)
+            return false;
+    }
+    return true;
+}
+/**
+ * Builds the route-path schema for a product. Structural rules — normalization,
+ * traversal, wildcards, the platform's own prefixes — are identical everywhere
+ * and live here. Each product passes the extra paths and prefixes its own app
+ * shell claims, because those differ: Zero's client router owns `/auth/*`,
+ * a Functions worker owns nothing beyond what the platform reserves.
+ */
+export function appRoutePathSchema(options) {
+    const reservedPaths = options.reservedPaths ?? [];
+    const reservedPrefixes = options.reservedPrefixes ?? [];
+    return z
+        .string()
+        .min(1)
+        .max(2048)
+        .startsWith("/")
+        .refine(hasWellFormedUnicode, {
+        message: `${options.subject} must contain well-formed Unicode.`,
+    })
+        .refine((path) => path.normalize("NFC") === path, {
+        message: `${options.subject} must use NFC-normalized Unicode.`,
+    })
+        .refine(hasNoAsciiControlCharacters, {
+        message: `${options.subject} must not contain ASCII control characters.`,
+    })
+        .refine((path) => !path.includes("//") &&
+        !path.includes("\\") &&
+        !path.includes("*") &&
+        !path.includes("?") &&
+        !path.includes("#") &&
+        !path.includes("%") &&
+        // The root is the one path allowed to end in a slash. Zero reserves it
+        // for its app shell anyway, but a Functions worker serving a framework
+        // app needs to claim "/" as its index route.
+        (path === "/" || !path.endsWith("/")) &&
+        path
+            .split("/")
+            .every((segment, index, segments) => segment !== "." &&
+            segment !== ".." &&
+            segment !== ":" &&
+            (segment !== ":splat" || index === segments.length - 1)), {
+        message: `${options.subject} must be absolute app paths without encoded, empty, traversal, unnamed parameter, * wildcard, non-terminal splat, \\, ?, or # segments.`,
+    })
+        .refine((path) => !PLATFORM_RESERVED_ROUTE_SEGMENT_PREFIXES.some((segmentPrefix) => (path.split("/")[1] ?? "").startsWith(segmentPrefix)), { message: `${options.subject} cannot use a path the platform reserves.` })
+        .refine((path) => !reservedPaths.some((reservedPath) => path === reservedPath), {
+        message: `${options.subject} cannot use a reserved path.`,
+    })
+        .refine((path) => !reservedPrefixes.some((prefix) => path.startsWith(prefix)), {
+        message: `${options.subject} cannot use a reserved path prefix.`,
+    });
+}
+export const httpMethodSchema = z.enum([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+]);
+/**
+ * What a handler is allowed to reach. Declared at build time from what the
+ * source actually imports, not from what the author claims, and printed in the
+ * publish receipt so placement is never a surprise.
+ */
+export const executionCapabilitiesSchema = z
+    .object({
+    db: z.boolean().default(false),
+    fetch: z.boolean().default(false),
+    auth: z.boolean().default(false),
+    env: z.boolean().default(false),
+    realtime: z.boolean().default(false),
+    logging: z.boolean().default(false),
+})
+    .partial()
+    .default({});
+/**
+ * The portable seam, stated as one predicate.
+ *
+ * `db` and `auth` are the two capabilities that bind a handler to the local
+ * tier. `db` because Zero's store guarantees every handler runs inside one
+ * parent-owned transaction, which an isolate reaching the database over a
+ * relay cannot offer. `auth` because capsule identity is resolved against that
+ * same transaction's view. Everything else — fetch, env, realtime, logging —
+ * is brokered identically on both tiers and does not constrain placement.
+ *
+ * Nothing here decides placement automatically: the product a version deploys
+ * to is a property of what its author wrote, and this predicate only reports
+ * whether the code could also have run on the other tier.
+ */
+export function endpointIsPortable(capabilities) {
+    return capabilities.db !== true && capabilities.auth !== true;
+}
+/**
+ * A source-carrying handler, before it is compiled to whichever tier will run
+ * it. Both products publish these; only the capability set decides which of
+ * them could accept a given one.
+ */
+export function executionEndpointSourceSchema(routePathSchema) {
+    return z
+        .object({
+        method: httpMethodSchema,
+        path: routePathSchema,
+        endpointId: z.string().min(1).max(256),
+        source: z
+            .string()
+            .min(1)
+            .max(2 * 1024 * 1024),
+        capabilities: executionCapabilitiesSchema,
+    })
+        .strict();
+}
+/**
+ * Byte-carrying artifacts travel inline in the finalize payload rather than as
+ * a separate upload, so a version's code lands in the same atomic write as the
+ * rest of it. The storage root and ceiling differ per product, hence a factory.
+ */
+export function executionBundleSchema(options) {
+    return z
+        .object({
+        path: z
+            .string()
+            .min(1)
+            .startsWith(`${options.bundleRoot}/`)
+            .refine((bundlePath) => !bundlePath.split("/").includes(".."), {
+            message: "Bundle paths cannot traverse outside the runtime bundle root.",
+        }),
+        sha256: executionSha256Schema,
+        size: z.number().int().nonnegative().max(options.maxBytes),
+        contentBase64: executionBase64Schema,
+    })
+        .strict();
+}
+export function executionStaticFileSchema(options) {
+    return z
+        .object({
+        path: z
+            .string()
+            .min(1)
+            .max(2048)
+            .refine((path) => !path.startsWith("/") && !path.split("/").includes(".."), {
+            message: "Static file paths must be relative and cannot traverse.",
+        })
+            .refine((path) => !path.startsWith(`${options.storageRoot}/`), {
+            message: `Static files cannot use ${options.storageRoot}.`,
+        })
+            .refine((path) => !path.startsWith("_") && !path.startsWith("."), {
+            message: "Static file paths cannot use private root prefixes.",
+        }),
+        contentType: z.string().min(1).max(255),
+        sha256: executionSha256Schema,
+        size: z.number().int().nonnegative().max(options.maxBytes),
+        contentBase64: executionBase64Schema,
+    })
+        .strict();
+}
+/**
+ * Whether a version's execution surface may be read by anyone or only by the
+ * space's own members. Both products expose an inspect route; the policy is
+ * the same question on each.
+ */
+export const executionInspectPolicySchema = z.enum(["private", "public"]);
+export const executionLogEntrySchema = z
+    .object({
+    id: z.string().min(1),
+    timestamp: z.string().datetime(),
+    level: z.enum(["debug", "info", "warn", "error"]),
+    requestId: z.string().min(1).nullable(),
+    versionId: z.string().min(1).nullable(),
+    /** Zero names the mutation; Functions names the handler. */
+    handlerName: z.string().min(1).nullable(),
+    message: z.string(),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const executionLogListQuerySchema = z
+    .object({
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z.string().min(1).optional(),
+    requestId: z.string().min(1).optional(),
+    handlerName: z.string().min(1).optional(),
+})
+    .strict();
+export const executionLogListResponseSchema = z
+    .object({
+    data: z.array(executionLogEntrySchema),
+    pagination: z
+        .object({
+        nextCursor: z.string().nullable(),
+    })
+        .strict(),
+})
+    .strict();