next-evolve 0.1.0 → 0.3.1

package/dist/store/global-config.d.ts

@@ -0,0 +1,39 @@
+import { FetchBundleResult } from "./fetch.js";
+type Env = Record<string, string | undefined>;
+/** How often instances re-read Global Config. */
+export declare const GLOBAL_CONFIG_TTL_MS = 10000;
+/** Max wait for the first read on a cold start; then the build bundle serves. */
+export declare const COLD_READ_CAP_MS = 20;
+export declare const globalConfigItemKey: (site: string) => string;
+export type GlobalConfigSettings = {
+  connectionString: string;
+  /** Write access (sync route only). */
+  id?: string;
+  apiToken?: string;
+  teamId?: string;
+};
+/**
+ * Global Config settings when the app opted in: `store: "global-config"`, or
+ * `"auto"` with `EVOLVE_GLOBAL_CONFIG` (connection string) set.
+ */
+export declare function globalConfigSettings(store: "auto" | "memory" | "global-config" | undefined, env: Env): GlobalConfigSettings | null;
+export type GlobalConfigReader = (key: string) => Promise<unknown>;
+export declare function defaultReader(connectionString: string): GlobalConfigReader;
+/**
+ * Fetcher for the memory store: reads Global Config every call; also asks the
+ * cloud when Global Config is empty or every `cloudEveryMs` (so a missed
+ * webhook or a stale item can't freeze the app), and returns the newer token.
+ */
+export declare function createGlobalConfigFetcher(opts: {
+  site: string;
+  read: GlobalConfigReader;
+  cloud?: (etag: string | null) => Promise<FetchBundleResult>;
+  cloudEveryMs: number;
+  now?: () => number;
+}): (etag: string | null) => Promise<FetchBundleResult>;
+/**
+ * Writes the token to the site's item via the Vercel REST API (sync route).
+ * Never throws; returns whether the write succeeded.
+ */
+export declare function writeGlobalConfig(settings: GlobalConfigSettings, site: string, token: string, f?: typeof fetch): Promise<boolean>;
+export {};

package/dist/store/global-config.js

@@ -0,0 +1,122 @@
+// src/store/global-config.ts
+/** How often instances re-read Global Config. */
+const GLOBAL_CONFIG_TTL_MS = 1e4;
+/** Max wait for the first read on a cold start; then the build bundle serves. */
+const COLD_READ_CAP_MS = 20;
+const globalConfigItemKey = (site) => `evolve_bundle_${site}`;
+/**
+* Global Config settings when the app opted in: `store: "global-config"`, or
+* `"auto"` with `EVOLVE_GLOBAL_CONFIG` (connection string) set.
+*/
+function globalConfigSettings(store, env) {
+	if (store === "memory") return null;
+	const connectionString = env.EVOLVE_GLOBAL_CONFIG;
+	if (!connectionString) {
+		if (store === "global-config") console.error("[evolve] store: \"global-config\" needs EVOLVE_GLOBAL_CONFIG; using memory");
+		return null;
+	}
+	return {
+		connectionString,
+		id: env.EVOLVE_GLOBAL_CONFIG_ID,
+		apiToken: env.EVOLVE_VERCEL_API_TOKEN,
+		teamId: env.EVOLVE_VERCEL_TEAM_ID
+	};
+}
+function defaultReader(connectionString) {
+	let client = null;
+	return async (key) => {
+		client ??= import("@vercel/global-config").then((m) => m.createClient(connectionString));
+		return (await client).get(key);
+	};
+}
+/** `"<ver>.<iat>"` of a token, without verifying it (verification is the store's job). */
+function versionOf(token) {
+	try {
+		const p = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+		return typeof p.ver === "number" && typeof p.iat === "number" ? p : null;
+	} catch {
+		return null;
+	}
+}
+const newer = (a, b) => {
+	const x = versionOf(a);
+	const y = versionOf(b);
+	if (!x) return b;
+	if (!y) return a;
+	return x.ver > y.ver || x.ver === y.ver && x.iat >= y.iat ? a : b;
+};
+/**
+* Fetcher for the memory store: reads Global Config every call; also asks the
+* cloud when Global Config is empty or every `cloudEveryMs` (so a missed
+* webhook or a stale item can't freeze the app), and returns the newer token.
+*/
+function createGlobalConfigFetcher(opts) {
+	const now = opts.now ?? Date.now;
+	const key = globalConfigItemKey(opts.site);
+	let lastCloud = -Infinity;
+	return async (etag) => {
+		let fromConfig = null;
+		try {
+			const v = await opts.read(key);
+			fromConfig = typeof v === "string" && v ? v : null;
+		} catch (e) {
+			if (!opts.cloud) return {
+				status: "error",
+				code: "network",
+				message: String(e)
+			};
+		}
+		let fromCloud = null;
+		if (opts.cloud && (!fromConfig || now() - lastCloud >= opts.cloudEveryMs)) {
+			lastCloud = now();
+			const r = await opts.cloud(fromConfig ? null : etag);
+			if (r.status === "ok") fromCloud = r.token;
+			else if (!fromConfig) return r;
+		}
+		const best = fromConfig && fromCloud ? newer(fromConfig, fromCloud) : fromConfig ?? fromCloud;
+		if (!best) return { status: "not_modified" };
+		const v = versionOf(best);
+		if (v && etag === `"${v.ver}.${v.iat}"`) return { status: "not_modified" };
+		return {
+			status: "ok",
+			token: best,
+			etag: null
+		};
+	};
+}
+/**
+* Writes the token to the site's item via the Vercel REST API (sync route).
+* Never throws; returns whether the write succeeded.
+*/
+async function writeGlobalConfig(settings, site, token, f = fetch) {
+	if (!settings.id || !settings.apiToken) {
+		console.error("[evolve] Global Config is read-only here: set EVOLVE_GLOBAL_CONFIG_ID and EVOLVE_VERCEL_API_TOKEN");
+		return false;
+	}
+	const url = new URL(`https://api.vercel.com/v1/edge-config/${settings.id}/items`);
+	if (settings.teamId) url.searchParams.set("teamId", settings.teamId);
+	try {
+		const res = await f(url, {
+			method: "PATCH",
+			headers: {
+				authorization: `Bearer ${settings.apiToken}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({ items: [{
+				operation: "upsert",
+				key: globalConfigItemKey(site),
+				value: token
+			}] }),
+			signal: AbortSignal.timeout(1e4)
+		});
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			console.error(`[evolve] Global Config write failed (${res.status})`, body.slice(0, 200));
+		}
+		return res.ok;
+	} catch (e) {
+		console.error("[evolve] Global Config write failed", e);
+		return false;
+	}
+}
+export { COLD_READ_CAP_MS, GLOBAL_CONFIG_TTL_MS, createGlobalConfigFetcher, defaultReader, globalConfigItemKey, globalConfigSettings, writeGlobalConfig };

package/dist/store/memory.d.ts

@@ -8,8 +8,15 @@ export type BundleStore = {
   peek(waitUntil?: (p: Promise<unknown>) => void): BundlePayload | null;
   /** Verifies and installs a token (build bundle, disk, sync route). Returns whether it was accepted. */
   load(token: string): boolean;
-  /** Fetches now (one in flight). Resolves once done. */
-  refresh(): Promise<void>;
+  /**
+   * Fetches now (one in flight). Resolves once done. `force`: a fetch already
+   * in flight may predate a publish, so wait for it and fetch again.
+   */
+  refresh(opts?: {
+    force?: boolean;
+  }): Promise<void>;
+  /** The current bundle without side effects (no refresh; expiry not applied). */
+  current(): BundlePayload | null;
   /** Raw token of the current bundle (for persistence). */
   token(): string | null;
 };
@@ -22,6 +29,8 @@ export type MemoryStoreOptions = {
   initialToken?: string | null;
   now?: () => number;
   random?: () => number;
+  /** Called with each token accepted after creation (persistence). */
+  onAccept?: (token: string) => void;
 };
 /**
  * In-memory bundle store with stale-while-revalidate polling (spec §7.5):

package/dist/store/memory.js

@@ -16,6 +16,7 @@ function createMemoryStore(opts) {
 	const schedule = () => {
 		nextCheck = now() + opts.pollMs * (.9 + .2 * random());
 	};
+	let ready = false;
 	function load(token) {
 		const r = verifyBundle(token, {
 			keys: opts.keys,
@@ -33,11 +34,12 @@ function createMemoryStore(opts) {
 		current = r.payload;
 		currentToken = token;
 		etag = `"${r.payload.ver}.${r.payload.iat}"`;
+		if (ready) opts.onAccept?.(token);
 		return true;
 	}
-	function refresh() {
+	function refresh(o = {}) {
 		if (!opts.fetcher) return Promise.resolve();
-		if (inflight) return inflight;
+		if (inflight) return o.force ? inflight.then(() => refresh()) : inflight;
 		schedule();
 		inflight = opts.fetcher(etag).then((res) => {
 			if (res.status === "ok") load(res.token);
@@ -48,6 +50,7 @@ function createMemoryStore(opts) {
 		return inflight;
 	}
 	if (opts.initialToken) load(opts.initialToken);
+	ready = true;
 	return {
 		peek(waitUntil) {
 			if (current && now() >= current.exp * 1e3) {
@@ -62,6 +65,7 @@ function createMemoryStore(opts) {
 		},
 		load,
 		refresh,
+		current: () => current,
 		token: () => currentToken
 	};
 }

package/dist/store/runtime.d.ts

@@ -1,3 +1,4 @@
+import { GlobalConfigReader } from "./global-config.js";
 import { BundleStore } from "./memory.js";
 import { KeyRing } from "@next-evolve/protocol";
 type Env = Record<string, string | undefined>;
@@ -7,7 +8,13 @@ export type RuntimeOptions = {
   /** Inject a store (tests). */
   store?: BundleStore;
   env?: Env;
+  /** Global Config reader (tests). */
+  globalConfigReader?: GlobalConfigReader;
+  /** Disk cache directory on long-running Node (default: $EVOLVE_CACHE_DIR, else os.tmpdir()). */
+  diskDir?: string;
 };
+/** True off serverless hosts: a process that lives across requests (next start, Docker). */
+export declare function isLongRunningNode(env?: Env): boolean;
 /** Default cloud URL (decision D29). Override with EVOLVE_CLOUD_URL. */
 export declare const DEFAULT_CLOUD_URL: string | undefined;
 /**
@@ -17,7 +24,14 @@ export declare const DEFAULT_CLOUD_URL: string | undefined;
  */
 export declare function getBundleStore(config: {
   pollSeconds?: number;
+  store?: "auto" | "memory" | "global-config";
 }, opts?: RuntimeOptions): BundleStore | null;
+/**
+ * Global Config hosts, first request of an instance: a promise that resolves
+ * after one Global Config read or {@link COLD_READ_CAP_MS}, whichever comes
+ * first (spec §7.8). Null when there's nothing to wait for.
+ */
+export declare function coldStart(store: BundleStore): Promise<void> | null;
 /** This app's site id (from EVOLVE_SECRET_KEY) and trusted public keys. Cached; null without a valid key. */
 export declare function getSiteIdentity(opts?: {
   env?: Env;

package/dist/store/runtime.js

@@ -1,8 +1,14 @@
 import { trustedKeys } from "../core/keys.js";
+import { defaultDiskDir, diskPath, readDisk, writeDisk } from "./disk.js";
 import { fetchBundle } from "./fetch.js";
+import { GLOBAL_CONFIG_TTL_MS, createGlobalConfigFetcher, defaultReader, globalConfigSettings } from "./global-config.js";
 import { createMemoryStore } from "./memory.js";
 import { parseSecretKey } from "@next-evolve/protocol";
 // src/store/runtime.ts
+/** True off serverless hosts: a process that lives across requests (next start, Docker). */
+function isLongRunningNode(env = process.env) {
+	return !env.VERCEL && !env.AWS_LAMBDA_FUNCTION_NAME && !env.NETLIFY;
+}
 /** Default cloud URL (decision D29). Override with EVOLVE_CLOUD_URL. */
 const DEFAULT_CLOUD_URL = "https://api.evolveab.com";
 const REGISTRY = Symbol.for("next-evolve.stores");
@@ -29,20 +35,46 @@ function getBundleStore(config, opts = {}) {
 		return existing;
 	}
 	const cloudUrl = env.EVOLVE_CLOUD_URL ?? "https://api.evolveab.com";
+	const disk = isLongRunningNode(env) ? diskPath(opts.diskDir ?? env.EVOLVE_CACHE_DIR ?? defaultDiskDir(), site) : null;
+	const pollMs = (config.pollSeconds ?? (env.NODE_ENV === "production" ? 60 : 5)) * 1e3;
+	const cloud = cloudUrl ? (etag) => fetchBundle({
+		cloudUrl,
+		secretKey,
+		etag
+	}) : void 0;
+	const gc = globalConfigSettings(config.store, env);
 	const store = createMemoryStore({
 		site,
 		keys: trustedKeys(env),
-		pollMs: (config.pollSeconds ?? (env.NODE_ENV === "production" ? 60 : 5)) * 1e3,
+		pollMs: gc ? Math.min(pollMs, GLOBAL_CONFIG_TTL_MS) : pollMs,
 		initialToken: opts.buildBundle ?? null,
-		fetcher: cloudUrl ? (etag) => fetchBundle({
-			cloudUrl,
-			secretKey,
-			etag
-		}) : void 0
+		fetcher: gc ? createGlobalConfigFetcher({
+			site,
+			read: opts.globalConfigReader ?? defaultReader(gc.connectionString),
+			cloud,
+			cloudEveryMs: pollMs
+		}) : cloud,
+		...disk ? { onAccept: (token) => writeDisk(disk, token) } : {}
 	});
+	if (disk) {
+		const cached = readDisk(disk);
+		if (cached && cached !== store.token()) store.load(cached);
+	}
 	reg.set(site, store);
+	if (gc) coldReads.set(store, true);
 	return store;
 }
+const coldReads = /* @__PURE__ */ new WeakMap();
+/**
+* Global Config hosts, first request of an instance: a promise that resolves
+* after one Global Config read or {@link COLD_READ_CAP_MS}, whichever comes
+* first (spec §7.8). Null when there's nothing to wait for.
+*/
+function coldStart(store) {
+	if (!coldReads.get(store)) return null;
+	coldReads.delete(store);
+	return Promise.race([store.refresh(), new Promise((r) => setTimeout(r, 20))]);
+}
 const identities = /* @__PURE__ */ new Map();
 /** This app's site id (from EVOLVE_SECRET_KEY) and trusted public keys. Cached; null without a valid key. */
 function getSiteIdentity(opts = {}) {
@@ -66,4 +98,4 @@ function getSiteIdentity(opts = {}) {
 function resetBundleStores() {
 	registry().clear();
 }
-export { DEFAULT_CLOUD_URL, getBundleStore, getSiteIdentity, resetBundleStores };
+export { DEFAULT_CLOUD_URL, coldStart, getBundleStore, getSiteIdentity, isLongRunningNode, resetBundleStores };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-evolve",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "description": "Self-improving Next.js sites: server-side variants with no flicker, measured in your own Postgres.",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@vercel/global-config": "1.5.1",
     "isbot": "5.2.2",
     "postgres": "3.4.9",
     "server-only": "^0.0.1",