@spacefast/common 0.0.23 → 0.0.26

package/dist/contracts/space-config.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import { serviceOrigin } from "../config/domains.js";
-import { normalizedSiteClass } from "./enums.js";
 import { GRANT_RESOURCE_PATTERN_LIMIT, normalizeGrantResourcePattern } from "./grants.js";
 export const SPACE_CONFIG_CANONICAL_FILE = "sf.jsonc";
 export const SPACE_CONFIG_ALIAS_FILES = [
@@ -15,8 +14,15 @@ export const SPACE_CONFIG_ACCEPTED_FILES = [
     SPACE_CONFIG_CANONICAL_FILE,
     ...SPACE_CONFIG_ALIAS_FILES,
 ];
+/**
+ * Accepted config filenames in read precedence order, highest first. Kept in
+ * step with the finalizer's `CONFIG_ACCEPTED_FILES` (crates/stattic-runtime-core
+ * protocol.rs) — the runtime compile is the selection authority, and a local
+ * read choosing a different file than the publish serves is a split brain.
+ */
+export const SPACE_CONFIG_PRECEDENCE = SPACE_CONFIG_ACCEPTED_FILES;
 export const SPACE_CONFIG_PRIVATE_FILES = [...SPACE_CONFIG_ACCEPTED_FILES];
-// Config compiler parser-safety caps (internal-docs/platform.md "Config
+// Config compiler parser-safety caps (the platform spec "Config
 // compiler scale targets"): hard from launch, enforced by ONE shared validator
 // at every intake seam — finalize for the `sf.jsonc` file, request
 // validation for the API `config` overlay. Plan policy may LOWER these caps,
@@ -30,6 +36,7 @@ export const SPACE_CONFIG_CAPS = {
     templates: 100,
     metaTitleChars: 300,
     metaDescriptionChars: 1000,
+    /** Max OG image or favicon path/URL length; enough for signed URLs while staying request-safe. */
     metaImageChars: 2000,
     /** Max bytes per `inject` snippet. */
     injectSnippetBytes: 8 * 1024,
@@ -45,6 +52,10 @@ export const SPACE_CONFIG_CAPS = {
     themeNameChars: 120,
     /** Max top-level `name` (space display name) length. Matches the stored column. */
     nameChars: 255,
+    /** Max `crons` entries. One provider crontab slot each, so the cap is small and hard. */
+    crons: 8,
+    /** Max `crons[].path` length. */
+    cronPathChars: 512,
 };
 /** Published JSON Schema URL for `sf.jsonc` ($schema autocomplete). */
 export const SPACE_CONFIG_SCHEMA_URL = `${serviceOrigin("www", "prod")}/schemas/sf.json`;
@@ -126,16 +137,12 @@ export const spaceBuildSettingsSchema = z
 })
     .strict()
     .describe("Remote build settings used by repository builds.");
-// Reuses the same shared/dedicated vocabulary as `normalizedSiteClass`
-// (enums.ts) rather than declaring a second "shared"/"dedicated" enum —
-// space placement mode and normalized site class are the same axis.
-export const spacePlacementModeSchema = normalizedSiteClass;
-// No region knob: a space binds to the site it was placed on at creation and
-// the only placement change that relocates it is shared -> dedicated. Data
-// location is chosen once, at creation, and never changes.
+// Every space gets its own site, so there is nothing to place between: no mode,
+// no region knob. `burstable` is the one real provider knob left — whether the
+// space's site may burst provider PHP workers. Data location is chosen once, at
+// creation, and never changes.
 export const spacePlacementConfigSchema = z
     .object({
-    mode: spacePlacementModeSchema.optional(),
     burstable: z.boolean().optional(),
 })
     .strict()
@@ -347,7 +354,7 @@ function refineDefaultDataSource(config, ctx) {
         });
     }
 }
-// Shared SpaceConfig fields (internal-docs/platform.md "SpaceConfig"): the
+// Shared SpaceConfig fields (the platform spec "SpaceConfig"): the
 // declarative serving config also accepted by `sf.jsonc`. Cloud-only overlay
 // fields such as pre-build data sources are added to `spaceConfigSchema` below.
 // Meta caps are the spec parser-safety numbers (title 300, description 1000,
@@ -377,9 +384,10 @@ const spaceConfigBaseSchema = z.object({
         title: z.string().min(1).max(SPACE_CONFIG_CAPS.metaTitleChars).optional(),
         description: z.string().max(SPACE_CONFIG_CAPS.metaDescriptionChars).optional(),
         image: z.string().max(SPACE_CONFIG_CAPS.metaImageChars).optional(),
+        favicon: z.string().max(SPACE_CONFIG_CAPS.metaImageChars).optional(),
     })
         .optional()
-        .describe("Listing/viewer/OG metadata."),
+        .describe("Listing, viewer, sharing, and browser icon metadata."),
     superpowers: z
         .object({
         enabled: z.boolean().optional().describe("Master switch for platform-managed injections."),
@@ -449,7 +457,7 @@ const spaceConfigBaseSchema = z.object({
         .optional()
         .describe("Accepted serving flag; runtime enforcement ships separately."),
     // Intentionally undescribed (hidden, experimental): enables the finalize-time
-    // build pipeline (internal-docs/build-pipeline-plan.md). Accepted without
+    // build pipeline (the build-pipeline plan). Accepted without
     // diagnostics; absent/false keeps today's behavior byte-for-byte.
     experimental_gutenberg: z.boolean().optional(),
     // Intentionally minimally described (hidden, experimental): static HTML
@@ -489,7 +497,7 @@ export function spaceSuperpowersEnabled(config) {
     const superpowers = config?.superpowers;
     return superpowers?.enabled !== false && superpowers?.disable_all_injection !== true;
 }
-// The `sf.jsonc` FILE shape (internal-docs/platform.md "Space
+// The `sf.jsonc` FILE shape (the platform spec "Space
 // Configuration Files"): SpaceConfig plus the editor `$schema` pointer and the
 // optional `space` link (slug or `spc_` id) resolved by CLI/publish flows.
 // Routing rules (`redirects`/`rewrites`/`headers`) are sf.jsonc keys too, but they belong
@@ -592,12 +600,17 @@ export const spaceRuntimeFunctionsSchema = z
         .string()
         .optional()
         .describe("Path to the worker entry module, relative to the published directory. " +
-        "When absent, the server detects it automatically. Naming an entry that does not exist is an error, not a silent static publish."),
+        "When absent, the server detects it automatically. Naming an entry that does not exist is an error, not a silent file-only publish."),
     database: z
         .boolean()
         .default(false)
         .describe("Give the worker `env.DB`, a D1-shaped binding to this space's database. " +
         "This capability is declared, not detected. A capability an author did not request is authority they cannot see. Reading it from minified build output is a guess. Defaults to off, so a worker reaches nothing until it says so."),
+    fetch: z
+        .boolean()
+        .optional()
+        .describe("Give the worker `ctx.fetch`, brokered outbound HTTP through the relay. " +
+        "Declared, not detected, for the same reason as `database`. No schema default, because the right one depends on what was published: a Next build gets egress unless this says false — SSR fetches while rendering, so denying it breaks the build rather than narrowing it — while a hand-written worker reaches nothing until it says so."),
     compatibilityDate: z
         .string()
         .regex(/^\d{4}-\d{2}-\d{2}$/)
@@ -615,7 +628,154 @@ export const spaceRuntimeFunctionsSchema = z
  */
 export const spaceRuntimeSchema = z
     .discriminatedUnion("kind", [spaceRuntimeZeroSchema, spaceRuntimeFunctionsSchema])
-    .describe("Runtime this version's code runs on. Omit it for a static space. Functions is also detected from the published directory when it is not stated.");
+    .describe("Runtime this version's code runs on. Omit it when the space does not run code. Functions is also detected from the published directory when it is not stated.");
+/**
+ * Scheduled requests: the provider crontab asks this space for these paths on
+ * these schedules.
+ *
+ * File-only for the same reason `runtime` is: what runs on a schedule is a fact
+ * about the content of a version, so it rolls forward and back with the version
+ * instead of being set through the API config overlay.
+ *
+ * The Rust config compiler is the selection authority for both fields; this
+ * schema exists so an editor and an agent get the same answer before publish.
+ */
+export const SPACE_CRON_NAMED_SCHEDULES = ["hourly", "daily", "twicedaily", "weekly"];
+/** Field bounds, in crontab order: minute, hour, day of month, month, weekday. */
+const CRON_FIELD_BOUNDS = [
+    [0, 59],
+    [0, 23],
+    [1, 31],
+    [1, 12],
+    [0, 7],
+];
+/** How many times per hour, day or week the `Nh`/`Nd`/`Nw` shorthand may ask. */
+const CRON_SHORTHAND_LIMITS = new Map([
+    ["h", 12],
+    ["d", 23],
+    ["w", 6],
+]);
+const CRON_STEP_MAX = 0xffff_ffff;
+function cronNumberInBounds(value, min, max) {
+    if (!/^\d+$/.test(value))
+        return false;
+    const parsed = Number(value);
+    return parsed >= min && parsed <= max;
+}
+function cronFieldIsValid(field, [min, max]) {
+    if (field.length === 0)
+        return false;
+    return field.split(",").every((item) => {
+        const slash = item.indexOf("/");
+        const range = slash === -1 ? item : item.slice(0, slash);
+        const step = slash === -1 ? undefined : item.slice(slash + 1);
+        // A step only makes sense over a span, which is what `*` and `a-b` are;
+        // `5/2` names one value and then asks to skip within it.
+        let span;
+        if (range === "*") {
+            span = true;
+        }
+        else if (range.includes("-")) {
+            const [start, end, ...rest] = range.split("-");
+            if (rest.length > 0 ||
+                start === undefined ||
+                end === undefined ||
+                !cronNumberInBounds(start, min, max) ||
+                !cronNumberInBounds(end, min, max) ||
+                Number(start) > Number(end)) {
+                return false;
+            }
+            span = true;
+        }
+        else {
+            if (!cronNumberInBounds(range, min, max))
+                return false;
+            span = false;
+        }
+        if (step === undefined)
+            return true;
+        const parsedStep = Number(step);
+        return (span &&
+            /^\d+$/.test(step) &&
+            Number.isInteger(parsedStep) &&
+            parsedStep >= 1 &&
+            parsedStep <= CRON_STEP_MAX);
+    });
+}
+/**
+ * The wp.cloud schedule grammar: a named interval, an `Nh`/`Nd`/`Nw` count, or
+ * a five-field crontab expression. No `@daily` macros and no month/day names —
+ * the provider does not accept them either.
+ */
+export function isSpaceCronSchedule(schedule) {
+    if (SPACE_CRON_NAMED_SCHEDULES.some((named) => named === schedule))
+        return true;
+    const shorthand = /^(\d+)([hdw])$/.exec(schedule);
+    const limit = CRON_SHORTHAND_LIMITS.get(shorthand?.[2] ?? "");
+    if (shorthand?.[1] !== undefined && limit !== undefined) {
+        const count = Number(shorthand[1]);
+        return count >= 1 && count <= limit;
+    }
+    const fields = schedule.split(" ");
+    return (fields.length === CRON_FIELD_BOUNDS.length &&
+        fields.every((field, index) => {
+            const bounds = CRON_FIELD_BOUNDS[index];
+            return bounds !== undefined && cronFieldIsValid(field, bounds);
+        }));
+}
+/**
+ * The artifact key for a cron path: lowercase, leading `/` stripped, every run
+ * of non-alphanumerics collapsed to one `-`, trimmed. Two paths that produce
+ * one key are rejected, so a key names exactly one schedule.
+ */
+export function spaceCronKey(path) {
+    return path
+        .replace(/^\/+/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/** Generated runtime file the serving engine reads, written only when a version declares a cron. */
+export const SPACE_CRONS_ARTIFACT_PATH = "__spacefast/crons.json";
+export const SPACE_CRONS_ARTIFACT_VERSION = 1;
+export const spaceCronSchema = z.object({
+    path: z
+        .string()
+        .max(SPACE_CONFIG_CAPS.cronPathChars)
+        .regex(/^\/[^*:?#\s\\]*$/, "must be a literal path starting with / (no * splats, :placeholders, query or fragment)")
+        .refine((path) => spaceCronKey(path).length > 0, "must contain at least one letter or digit")
+        .describe("Path this space is asked for on the schedule."),
+    schedule: z
+        .string()
+        .refine(isSpaceCronSchedule, "must be hourly, daily, twicedaily, weekly, an Nh/Nd/Nw interval, or a five-field crontab expression")
+        .describe("hourly, daily, twicedaily, weekly, an Nh/Nd/Nw interval, or a five-field crontab expression."),
+});
+export const spaceCronsSchema = z
+    .array(spaceCronSchema)
+    .max(SPACE_CONFIG_CAPS.crons)
+    .superRefine((entries, context) => {
+    // Identical paths always slug to one key, so keying on the key alone
+    // catches both defects: a path written twice, and two paths that slug to
+    // one key — which would give two schedules one identity downstream.
+    const seenByKey = new Map();
+    entries.forEach((entry, index) => {
+        const key = spaceCronKey(entry.path);
+        const at = seenByKey.get(key);
+        if (at !== undefined) {
+            // Name the exact duplicate the author wrote: the path when it repeats
+            // verbatim, the shared key when two distinct paths collide on it.
+            const collided = entries[at];
+            context.addIssue({
+                code: "custom",
+                path: [index, "path"],
+                message: `crons entry ${at} already declares ${collided?.path === entry.path ? entry.path : key}.`,
+            });
+            return;
+        }
+        seenByKey.set(key, index);
+    });
+})
+    .describe(`Scheduled requests Spacefast issues against this space's own paths; at most ${SPACE_CONFIG_CAPS.crons} entries.`);
 export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
     $schema: z
         .string()
@@ -637,6 +797,7 @@ export const spaceConfigFileSchema = spaceConfigBaseSchema.extend({
         .describe("Display name for this space. While set, the API refuses to rename the space."),
     access: spaceConfigFileAccessSchema.optional(),
     runtime: spaceRuntimeSchema.optional(),
+    crons: spaceCronsSchema.optional(),
 });
 /**
  * The published JSON Schema artifact for `sf.jsonc`, generated from the
@@ -662,6 +823,19 @@ export function spaceConfigJsonSchema() {
         },
     };
 }
+// The `!` and `name=:capture` of a `_redirects` line, shared by both rule
+// sections — the same shapes `config::strict::public_json_schema` publishes.
+const SPACE_CONFIG_ROUTING_FORCE_SCHEMA = {
+    type: "boolean",
+    default: false,
+    description: "Answer even when the request path resolves to a committed file — the ! of a _redirects rule.",
+};
+const SPACE_CONFIG_ROUTING_QUERY_SCHEMA = {
+    type: "object",
+    description: 'Query parameters the request must carry, as parameter name to capture name: { "id": "id" } is the name=:capture token id=:id.',
+    propertyNames: { pattern: "^[A-Za-z][A-Za-z0-9_-]*$" },
+    additionalProperties: { type: "string", pattern: "^[A-Za-z][A-Za-z0-9_]*$" },
+};
 const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     redirects: {
         type: "array",
@@ -684,6 +858,8 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
                     default: 302,
                     description: "Redirect status. To serve other content under this URL, use rewrites.",
                 },
+                force: SPACE_CONFIG_ROUTING_FORCE_SCHEMA,
+                query: SPACE_CONFIG_ROUTING_QUERY_SCHEMA,
             },
             required: ["source", "destination"],
             additionalProperties: false,
@@ -709,6 +885,13 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
                     const: "shared",
                     description: "Let shared caches store the proxy response. Absolute-URL destinations only.",
                 },
+                force: SPACE_CONFIG_ROUTING_FORCE_SCHEMA,
+                query: SPACE_CONFIG_ROUTING_QUERY_SCHEMA,
+                notFound: {
+                    type: "boolean",
+                    default: false,
+                    description: "Serve the destination with status 404 — the 404 of a _redirects rule. The destination must be a path.",
+                },
             },
             required: ["source", "destination"],
             additionalProperties: false,
@@ -716,7 +899,7 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     },
     headers: {
         type: "array",
-        description: "Response headers to set on matching requests. A _headers rule wins on the same header name.",
+        description: "Response headers to set or remove on matching requests. A _headers rule wins on the same header name.",
         items: {
             type: "object",
             properties: {
@@ -725,13 +908,29 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
                     type: "array",
                     minItems: 1,
                     items: {
-                        type: "object",
-                        properties: {
-                            key: { type: "string", minLength: 1 },
-                            value: { type: "string" },
-                        },
-                        required: ["key", "value"],
-                        additionalProperties: false,
+                        oneOf: [
+                            {
+                                type: "object",
+                                properties: {
+                                    key: { type: "string", minLength: 1 },
+                                    value: { type: "string" },
+                                },
+                                required: ["key", "value"],
+                                additionalProperties: false,
+                            },
+                            {
+                                type: "object",
+                                properties: {
+                                    key: { type: "string", minLength: 1 },
+                                    remove: {
+                                        const: true,
+                                        description: "Remove this header instead of setting it — the !Name line of a _headers block.",
+                                    },
+                                },
+                                required: ["key", "remove"],
+                                additionalProperties: false,
+                            },
+                        ],
                     },
                 },
             },
@@ -741,7 +940,7 @@ const SPACE_CONFIG_ROUTING_SCHEMA_PROPERTIES = {
     },
 };
 /*
- * Hidden-feature discipline (internal-docs/build-pipeline-plan.md): the
+ * Hidden-feature discipline (the build-pipeline plan): the
  * `experimental_gutenberg` flag and its `inject` companion are ACCEPTED by the
  * parser but never published — the bare key names alone would document the
  * feature to every editor/agent reading a schema artifact. Every generator
@@ -765,14 +964,14 @@ export function stripHiddenSpaceConfigKeys(schema) {
                 if (name === "experimental_gutenberg") {
                     return false;
                 }
-                return !(name === "inject" && isHiddenInjectShape(value));
+                return !(name === "inject" && isHiddenInjectSchema(value));
             }));
             return [key, stripHiddenSpaceConfigKeys(kept)];
         }
         return [key, stripHiddenSpaceConfigKeys(entry)];
     }));
 }
-function isHiddenInjectShape(value) {
+function isHiddenInjectSchema(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return false;
     }