@ogygia/core 0.0.0 → 0.11.1

package/dist/server/seed-shape.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SEED SHAPING — the server half. The build says which top-level `page.data` keys the islands on a
+ * page read (link/page-keys.ts → island-deps handoff → Region records per island); the handle
+ * unions those asks per request and ships only that slice of `page.data` in the page seed.
+ *
+ * The ask is `'all'` whenever ANY region on the page could not be pinned (a promise `of` whose
+ * module SSR cannot see, an entry the handoff does not know, a closure that hands `page.data` to
+ * a function) — then the seed ships whole, exactly as before shaping existed.
+ */
+/** What a region asks of the page seed: nothing, everything, or these keys of `page.data`. */
+export type SeedAsk = false | "all" | readonly string[];
+/** The request's union of asks: `'all'`, or the key set. (No ask at all = no seed.) */
+export type SeedKeys = "all" | Set<string>;
+/** Fold one region's ask into the request's union. */
+export declare function merge_seed_ask(current: SeedKeys | null, ask: SeedAsk): SeedKeys | null;
+/**
+ * The slice of `page.data` to ship. A plain object is picked down to `keys` (present keys only — a
+ * key the load never returned stays absent, so `page.data.x` is `undefined` on both legs alike);
+ * `'all'`, or a non-object (a load returned nothing, or something exotic), ships as is. A key
+ * whose value is a promise stays a promise: the streaming/settling that follows sees the same shape.
+ */
+export declare function shape_page_data(data: unknown, keys: SeedKeys | null): unknown;

package/dist/server/seed-shape.js

@@ -0,0 +1,24 @@
+// src/server/seed-shape.ts
+/** Fold one region's ask into the request's union. */
+function merge_seed_ask(current, ask) {
+	if (ask === false) return current;
+	if (ask === "all" || current === "all") return "all";
+	const next = current ?? /* @__PURE__ */ new Set();
+	for (const k of ask) next.add(k);
+	return next;
+}
+/**
+* The slice of `page.data` to ship. A plain object is picked down to `keys` (present keys only — a
+* key the load never returned stays absent, so `page.data.x` is `undefined` on both legs alike);
+* `'all'`, or a non-object (a load returned nothing, or something exotic), ships as is. A key
+* whose value is a promise stays a promise: the streaming/settling that follows sees the same shape.
+*/
+function shape_page_data(data, keys) {
+	if (keys === null || keys === "all") return data;
+	if (data === null || typeof data !== "object" || Array.isArray(data)) return data;
+	const src = data;
+	const out = {};
+	for (const k of keys) if (Object.prototype.hasOwnProperty.call(src, k)) out[k] = src[k];
+	return out;
+}
+export { merge_seed_ask, shape_page_data };

package/dist/server/shared-cache.d.ts

@@ -0,0 +1,35 @@
+/** The default for how long after expiry a capability can still be renewed
+ *  (`maxPageAge`): the longest a stale document is expected to live in a shared cache (a
+ *  week of `s-maxage` plus a day of revalidation). */
+export declare const RENEW_WINDOW_SEC: number;
+/**
+ * How long shared caches may serve a document with this `cache-control`, in seconds: its freshness
+ * (`s-maxage`, else `max-age`) plus `stale-while-revalidate`. 0 when shared caches may not keep it
+ * (`private`, `no-store`) or must revalidate every use (`no-cache`). `max-age` counts without
+ * `public`: a shared cache may store any response not marked `private` (RFC 9111 §3).
+ * `stale-if-error` does not count: it serves a stale copy only while the origin is failing, when a
+ * hole could not render anyway.
+ */
+export declare function shared_cache_lifetime(cache_control: string): number;
+/**
+ * The capability lifetime to mint with: prerender-grade for a stored page (prerender / postrender);
+ * for an anonymous hole on a document shared caches keep for `shared` seconds, twice that (so the
+ * window-aligned expiry still covers the whole cache life), capped at prerender-grade; else
+ * `ttl`. A session-bound hole is never extended — its document is the visitor's own.
+ */
+export declare function mint_ttl_sec(o: {
+  stored: boolean;
+  session: string;
+  shared: number;
+  region_ttl: number;
+}): number;
+/** A renewable expiry: an integer that HAS passed, by at most `window` seconds (the app's
+ *  `maxPageAge`; `0` renews nothing). */
+export declare function renewable_expiry(exp_raw: string, now_sec: number, window?: number): boolean;
+/** Why a capability's `exp` refuses it, or null: past it (`expired`); for a renewal, not inside
+ *  the renew window (`renew-window`), so a URL that has not expired never renews. */
+export declare function expiry_refusal(exp_raw: string, now_sec: number, renewal: boolean, window: number): "expired" | "renew-window" | null;
+/** The handle: a load set `cache-control` on this page request. */
+export declare function note_cache_control(request: Request, cache_control: string): void;
+/** The mint: how long shared caches keep the document this request renders (0 = unknown / none). */
+export declare function document_shared_lifetime(request: Request | null | undefined): number;

package/dist/server/shared-cache.js

@@ -0,0 +1,104 @@
+import { PRERENDER_REGION_TTL_SEC } from "./endpoint.js";
+// src/server/shared-cache.ts
+/**
+* HOLES ON A CACHED DOCUMENT — a deferred hole's capability must outlive the document it sits in.
+*
+* A page whose load says `cache-control: public, s-maxage=604800` is served from a CDN for a week,
+* but its holes were minted for `ttl` (an hour by default, capped at a day): once that passed,
+* every visitor served the cached copy got a 403 for every hole, and nothing logged it. Prerender
+* already solves the same problem by signing for the life of the deploy; this is the request-time
+* equivalent, bounded by what the app itself declared.
+*
+* 1. The handle notes the `cache-control` a load sets (`setHeaders`) on the page request; the mint
+*    reads it and signs an ANONYMOUS hole for twice that lifetime (`capability_expiry` guarantees
+*    only half of a ttl). Same safety argument as prerender: the props are already in the public
+*    HTML, and nothing session-bound is extended.
+* 2. A document already cached with short-lived holes (or one whose cache header a handle set after
+*    the render, where the mint cannot see it) is rescued by RENEWAL: the runtime retries an expired
+*    hole once with `&renew=1`, and the handle re-signs a capability it minted itself, anonymous,
+*    expired by at most {@link RENEW_WINDOW_SEC}.
+*
+* State rides ONE `globalThis` + `Symbol.for` slot (the PAGE-STATE-SINGLETON law): the handle
+* (hooks.js) records and the mint (server/region-endpoint.js) reads, and dist entries can each carry
+* their own evaluation of this module — a module-local map would split the seam.
+*/
+/** The default for how long after expiry a capability can still be renewed
+*  (`maxPageAge`): the longest a stale document is expected to live in a shared cache (a
+*  week of `s-maxage` plus a day of revalidation). */
+const RENEW_WINDOW_SEC = 691200;
+/**
+* How long shared caches may serve a document with this `cache-control`, in seconds: its freshness
+* (`s-maxage`, else `max-age`) plus `stale-while-revalidate`. 0 when shared caches may not keep it
+* (`private`, `no-store`) or must revalidate every use (`no-cache`). `max-age` counts without
+* `public`: a shared cache may store any response not marked `private` (RFC 9111 §3).
+* `stale-if-error` does not count: it serves a stale copy only while the origin is failing, when a
+* hole could not render anyway.
+*/
+function shared_cache_lifetime(cache_control) {
+	let s_maxage = -1;
+	let max_age = -1;
+	let swr = 0;
+	for (const part of cache_control.toLowerCase().split(",")) {
+		const eq = part.indexOf("=");
+		const name = (eq === -1 ? part : part.slice(0, eq)).trim();
+		if (name === "private" || name === "no-store" || name === "no-cache") return 0;
+		if (eq === -1) continue;
+		const n = seconds(part.slice(eq + 1));
+		if (n === null) continue;
+		if (name === "s-maxage") s_maxage = n;
+		else if (name === "max-age") max_age = n;
+		else if (name === "stale-while-revalidate") swr = n;
+	}
+	return (s_maxage >= 0 ? s_maxage : max_age >= 0 ? max_age : 0) + swr;
+}
+/** A delta-seconds value (optionally quoted), or null. */
+function seconds(raw) {
+	let v = raw.trim();
+	if (v.length >= 2 && v[0] === "\"" && v[v.length - 1] === "\"") v = v.slice(1, -1);
+	if (v === "" || v.length > 10) return null;
+	for (let i = 0; i < v.length; i++) {
+		const c = v.charCodeAt(i);
+		if (c < 48 || c > 57) return null;
+	}
+	return Number(v);
+}
+/**
+* The capability lifetime to mint with: prerender-grade for a stored page (prerender / postrender);
+* for an anonymous hole on a document shared caches keep for `shared` seconds, twice that (so the
+* window-aligned expiry still covers the whole cache life), capped at prerender-grade; else
+* `ttl`. A session-bound hole is never extended — its document is the visitor's own.
+*/
+function mint_ttl_sec(o) {
+	if (o.stored) return PRERENDER_REGION_TTL_SEC;
+	if (o.session !== "" || o.shared <= 0) return o.region_ttl;
+	return Math.min(PRERENDER_REGION_TTL_SEC, Math.max(o.region_ttl, 2 * o.shared));
+}
+/** A renewable expiry: an integer that HAS passed, by at most `window` seconds (the app's
+*  `maxPageAge`; `0` renews nothing). */
+function renewable_expiry(exp_raw, now_sec, window = RENEW_WINDOW_SEC) {
+	if (window <= 0 || exp_raw === "" || exp_raw.length > 12) return false;
+	for (let i = 0; i < exp_raw.length; i++) {
+		const c = exp_raw.charCodeAt(i);
+		if (c < 48 || c > 57) return false;
+	}
+	const exp = Number(exp_raw);
+	return exp < now_sec && now_sec - exp <= window;
+}
+/** Why a capability's `exp` refuses it, or null: past it (`expired`); for a renewal, not inside
+*  the renew window (`renew-window`), so a URL that has not expired never renews. */
+function expiry_refusal(exp_raw, now_sec, renewal, window) {
+	if (renewal) return renewable_expiry(exp_raw, now_sec, window) ? null : "renew-window";
+	const exp = Number(exp_raw);
+	return !Number.isFinite(exp) || exp < now_sec ? "expired" : null;
+}
+const SLOT_KEY = Symbol.for("ogygia.shared-cache");
+const slot = globalThis[SLOT_KEY] ??= { by_request: /* @__PURE__ */ new WeakMap() };
+/** The handle: a load set `cache-control` on this page request. */
+function note_cache_control(request, cache_control) {
+	slot.by_request.set(request, shared_cache_lifetime(cache_control));
+}
+/** The mint: how long shared caches keep the document this request renders (0 = unknown / none). */
+function document_shared_lifetime(request) {
+	return request ? slot.by_request.get(request) ?? 0 : 0;
+}
+export { RENEW_WINDOW_SEC, document_shared_lifetime, expiry_refusal, mint_ttl_sec, note_cache_control, renewable_expiry, shared_cache_lifetime };

package/dist/server/signing-key.d.ts

@@ -0,0 +1,11 @@
+export interface SigningKey {
+  secret: string;
+  /** env-provided: survives redeploys and is shared by every deployment that sets the same value */
+  stable: boolean;
+  /** 8-char key fingerprint (`&k=` on capabilities, `x-ogygia-key` on refusals) */
+  fp: string;
+}
+export declare function signing_key(): SigningKey;
+export declare function key_fingerprint(secret: string): string;
+/** Tests: forget the decided key. */
+export declare function reset_signing_key(): void;

package/dist/server/signing-key.js

@@ -0,0 +1,47 @@
+import { buildHadSecret, buildKey } from "virtual:ogygia/secret";
+import { sign } from "virtual:ogygia/sign";
+import { building } from "$app/env";
+// src/server/signing-key.ts
+/**
+* THE region signing key, decided once at first use (the first mint or verify), not at module eval:
+* a host that fills `process.env` after the server's modules load (an adapter loading a `.env` late)
+* still counts. The runtime's `OGYGIA_SECRET` wins; else this build's random key.
+*
+* A capability carries its minter's key FINGERPRINT (`&k=`): an HMAC of a constant under the key —
+* the same on every instance sharing the key, and it reveals nothing of the key. A deployment that
+* verifies a capability minted under another key can then say so (`x-ogygia-deny: foreign-key`)
+* instead of an opaque 403: the page and its islands endpoint came from different deployments (a CDN
+* routing them to two backends, HTML cached across a key change).
+*/
+let key;
+function signing_key() {
+	if (key) return key;
+	const from_env = typeof process !== "undefined" && process.env?.OGYGIA_SECRET || "";
+	const secret = from_env || buildKey;
+	key = {
+		secret,
+		stable: from_env !== "",
+		fp: key_fingerprint(secret)
+	};
+	if (!key.stable && !import.meta.env.DEV) warn_build_key();
+	return key;
+}
+function key_fingerprint(secret) {
+	return sign(secret, "ogygia:key-fp").slice(0, 8);
+}
+/** One message per process (a shared Symbol: one across every copy of this module): a server
+*  signing with this build's random key. */
+function warn_build_key() {
+	const g = globalThis;
+	const K = Symbol.for("ogygia.build-key-warned");
+	if (g[K]) return;
+	g[K] = true;
+	if (building) console.warn("[ogygia] prerendered page mints region capabilities signed with a per-build random key — they stop verifying after your next deploy while the static HTML lives on. Set a stable OGYGIA_SECRET env var so prerendered holes survive redeploys.");
+	else if (buildHadSecret) console.error("[ogygia] OGYGIA_SECRET was set when this app was built but is not set where it runs: region capabilities are signed with this build's random key, so every hole minted by another deployment (another backend behind the same CDN, the previous deploy) is refused (403, x-ogygia-deny: foreign-key). Set OGYGIA_SECRET in the server's runtime environment.");
+	else console.warn("[ogygia] OGYGIA_SECRET is not set: region capabilities are signed with this build's random key, so a page cached across a deploy, or served by another deployment than its islands endpoint, gets its holes refused (403, x-ogygia-deny: foreign-key). Set a stable OGYGIA_SECRET.");
+}
+/** Tests: forget the decided key. */
+function reset_signing_key() {
+	key = void 0;
+}
+export { key_fingerprint, reset_signing_key, signing_key };

package/dist/server/sized-lru.d.ts

@@ -0,0 +1,20 @@
+export declare class SizedLru<V> {
+  #private;
+  readonly max_bytes: number;
+  readonly max_entries: number;
+  constructor(max_bytes: number, max_entries: number);
+  /** The live value for `key` (an LRU touch), or `null` on a miss or past `expires`. */
+  get(key: string, now: number): V | null;
+  has(key: string): boolean;
+  /** Store `value` (`bytes` big, live until `expires`), evicting the least recently used entries
+   *  to make room. A value larger than the whole budget is not stored. */
+  set(key: string, value: V, bytes: number, expires: number): void;
+  delete(key: string): boolean;
+  /** Every live key (insertion order — least recently used first). */
+  keys(): IterableIterator<string>;
+  /** Drop everything past `expires` (harness counts want live entries only). */
+  sweep(now: number): void;
+  clear(): void;
+  get size(): number;
+  get bytes(): number;
+}

package/dist/server/sized-lru.js

@@ -0,0 +1,68 @@
+// src/server/sized-lru.ts
+var SizedLru = class {
+	#entries = /* @__PURE__ */ new Map();
+	#bytes = 0;
+	max_bytes;
+	max_entries;
+	constructor(max_bytes, max_entries) {
+		this.max_bytes = max_bytes;
+		this.max_entries = max_entries;
+	}
+	/** The live value for `key` (an LRU touch), or `null` on a miss or past `expires`. */
+	get(key, now) {
+		const e = this.#entries.get(key);
+		if (e === void 0) return null;
+		if (now >= e.expires) {
+			this.delete(key);
+			return null;
+		}
+		this.#entries.delete(key);
+		this.#entries.set(key, e);
+		return e.value;
+	}
+	has(key) {
+		return this.#entries.has(key);
+	}
+	/** Store `value` (`bytes` big, live until `expires`), evicting the least recently used entries
+	*  to make room. A value larger than the whole budget is not stored. */
+	set(key, value, bytes, expires) {
+		this.delete(key);
+		if (bytes > this.max_bytes) return;
+		while (this.#entries.size > 0 && (this.#bytes + bytes > this.max_bytes || this.#entries.size >= this.max_entries)) {
+			const oldest = this.#entries.keys().next().value;
+			this.delete(oldest);
+		}
+		this.#entries.set(key, {
+			value,
+			bytes,
+			expires
+		});
+		this.#bytes += bytes;
+	}
+	delete(key) {
+		const e = this.#entries.get(key);
+		if (e === void 0) return false;
+		this.#entries.delete(key);
+		this.#bytes -= e.bytes;
+		return true;
+	}
+	/** Every live key (insertion order — least recently used first). */
+	keys() {
+		return this.#entries.keys();
+	}
+	/** Drop everything past `expires` (harness counts want live entries only). */
+	sweep(now) {
+		for (const [key, e] of this.#entries) if (now >= e.expires) this.delete(key);
+	}
+	clear() {
+		this.#entries.clear();
+		this.#bytes = 0;
+	}
+	get size() {
+		return this.#entries.size;
+	}
+	get bytes() {
+		return this.#bytes;
+	}
+};
+export { SizedLru };

package/dist/server/split-regions.d.ts

@@ -0,0 +1,81 @@
+export type RegionKind = "island" | "lake" | "hole";
+export interface RegionSpan {
+  /** `island` = a hydrated region (its bytes are off-limits to any post-SSR reshaping); `lake` = a
+   *  frozen (`wake="none"`) subtree, server HTML the browser never re-creates; `hole` = a deferred
+   *  region whose current markup is the page's fallback, not a hydration tree. */
+  kind: RegionKind;
+  /** Index of the `<` that opens `<ogygia-region …>`. */
+  start: number;
+  /** Index one past the `>` that closes `</ogygia-region>`. `[start, end)` is the whole element. */
+  end: number;
+  /** Index one past the `>` of the OPENING tag — the first byte of the region's inner HTML. */
+  innerStart: number;
+  /** Index of the `<` of the CLOSING tag — one past the last byte of the inner HTML.
+   *  `[innerStart, innerEnd)` is the inner HTML a reshaping pass may edit for a lake / hole. */
+  innerEnd: number;
+  /** The opening tag's attributes (unquoted values). Read `wake` / `endpoint` / `entry` here. */
+  attrs: Readonly<Record<string, string>>;
+  /** Nesting depth — `0` for a top-level region, `1` for one directly inside a lake / hole, and so
+   *  on. Island subtrees are never entered, so a region deeper than `0` is always inside a lake or
+   *  hole (never inside another island). */
+  depth: number;
+}
+/**
+ * Parse a tag's attribute run (everything between the tag name and its `>`) into a lower-cased map
+ * with quotes stripped. Shared by the region opener and the `<og-lift>` placeholder on restore.
+ *
+ * Hand-written (measured faster, no match arrays) with the rules the pattern
+ * `([^\s/>=]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s/>]+))?` had, quirks included: a value is a closed
+ * `"…"`, else a closed `'…'`, else an unquoted run (which may start with an unclosed quote — then
+ * the first and last characters are stripped, as before); `=` with no value leaves the name valueless.
+ * @internal Exported for test/regex-replacements.test.ts.
+ */
+export declare function parse_attr_string(inner: string): Record<string, string>;
+/**
+ * Yield every `<ogygia-region>` in `html`, in document order, an island's subtree treated as atomic
+ * (its nested regions are not yielded). One linear pass, O(html length); allocates no copy of the
+ * document. See the module doc for why this exists and how to use it.
+ */
+export declare function scanRegions(html: string): Generator<RegionSpan, void, undefined>;
+export interface LiftedRegion {
+  /** `island` bytes must be restored VERBATIM (reshaping them breaks hydration); a `lake` / `hole`
+   *  MAY be reshaped first via {@link LiftedRegion.withInner}. */
+  readonly kind: RegionKind;
+  /** The opening tag's attributes (`wake` / `endpoint` / `entry` …), lower-cased. */
+  readonly attrs: Readonly<Record<string, string>>;
+  /** `<ogygia-region …>` — the opening tag, verbatim. */
+  readonly openTag: string;
+  /** The region's inner HTML (`''` for a self-closed or unterminated region). */
+  readonly innerHtml: string;
+  /** `</ogygia-region>` — the closing tag (`''` for a self-closed or unterminated region). */
+  readonly closeTag: string;
+  /** `openTag + innerHtml + closeTag`. */
+  readonly outerHtml: string;
+  /** Ties this region to its `<og-lift data-i="…">` placeholder in the shell. */
+  readonly index: number;
+  /** A copy with the inner HTML replaced — for a lake / hole whose inner a caller has rendered. The
+   *  opening / closing tags and the index are preserved. Do NOT call this for an island. */
+  withInner(innerHtml: string): LiftedRegion;
+}
+export interface LiftResult {
+  /** The document with every TOP-LEVEL region replaced by an `<og-lift data-i="…"></og-lift>`
+   *  placeholder — the only part a foreign renderer should be handed. */
+  shell: string;
+  /** The lifted regions, in document order, index-aligned to their placeholders. */
+  regions: LiftedRegion[];
+}
+/**
+ * Lift every TOP-LEVEL `<ogygia-region>` out of `html`, leaving an `<og-lift>` placeholder where each
+ * was. Hand `shell` to the foreign renderer (and, to render a lake / hole, its `innerHtml` — recurse
+ * with `liftRegions` there so islands nested inside it stay protected), then {@link restoreRegions}.
+ * Islands come back verbatim. A region deeper than top level rides inside its parent's `outerHtml`.
+ */
+export declare function liftRegions(html: string): LiftResult;
+/**
+ * Splice lifted regions back over their `<og-lift>` placeholders, transplanting any attributes the
+ * foreign renderer stamped on a placeholder (scoped slot marks — a `sc-*` class, `c-id`, `s-sn`)
+ * onto the region's opening tag. The placeholder is matched loosely because the renderer annotates
+ * it; only opening-tag attributes are merged, never the region's light DOM. An unknown placeholder
+ * is left in place rather than dropped.
+ */
+export declare function restoreRegions(shell: string, regions: readonly LiftedRegion[]): string;