next-evolve 0.0.0-stage → 0.3.1

package/dist/core/constants.js

@@ -0,0 +1,5 @@
+// src/core/constants.ts
+/** Request headers the proxy sets for dynamic-mode routes. */
+const HEADER_CODE = "x-evolve-a";
+const HEADER_PATH = "x-evolve-path";
+export { HEADER_CODE, HEADER_PATH };

package/dist/core/cookies.d.ts

@@ -0,0 +1,12 @@
+/** Cookie names (spec §6.2). */
+export declare const ANON_COOKIE = "evolve_id";
+export declare const ASSIGN_COOKIE = "evolve_a";
+export declare const PREVIEW_COOKIE = "evolve_pv";
+/** Max experiments remembered in `evolve_a`. */
+export declare const MAX_ASSIGNMENTS = 20;
+/** Assignment value meaning "outside the experiment's traffic share". */
+export declare const EXCLUDED = "x";
+/** Parses `evolve_a` (`exp:var` pairs joined by `.`). Malformed entries are dropped. */
+export declare function parseAssignments(raw: string | undefined): Map<string, string>;
+/** Serializes assignments sorted by experiment id, keeping at most {@link MAX_ASSIGNMENTS}. */
+export declare function serializeAssignments(assigned: ReadonlyMap<string, string>): string;

package/dist/core/cookies.js

@@ -0,0 +1,25 @@
+// src/core/cookies.ts
+/** Cookie names (spec §6.2). */
+const ANON_COOKIE = "evolve_id";
+const ASSIGN_COOKIE = "evolve_a";
+const PREVIEW_COOKIE = "evolve_pv";
+/** Max experiments remembered in `evolve_a`. */
+const MAX_ASSIGNMENTS = 20;
+/** Assignment value meaning "outside the experiment's traffic share". */
+const EXCLUDED = "x";
+const ENTRY_RE = /^([a-z0-9]{6}):([a-z0-9]{6}|x)$/;
+/** Parses `evolve_a` (`exp:var` pairs joined by `.`). Malformed entries are dropped. */
+function parseAssignments(raw) {
+	const out = /* @__PURE__ */ new Map();
+	if (!raw) return out;
+	for (const entry of raw.split(".")) {
+		const m = ENTRY_RE.exec(entry);
+		if (m && !out.has(m[1]) && out.size < 20) out.set(m[1], m[2]);
+	}
+	return out;
+}
+/** Serializes assignments sorted by experiment id, keeping at most {@link MAX_ASSIGNMENTS}. */
+function serializeAssignments(assigned) {
+	return [...assigned].sort(([a], [b]) => a < b ? -1 : 1).slice(0, 20).map(([e, v]) => `${e}:${v}`).join(".");
+}
+export { ANON_COOKIE, ASSIGN_COOKIE, EXCLUDED, MAX_ASSIGNMENTS, PREVIEW_COOKIE, parseAssignments, serializeAssignments };

package/dist/core/keys.d.ts

@@ -0,0 +1,14 @@
+import { KeyRing } from "@next-evolve/protocol";
+type Env = Record<string, string | undefined>;
+/**
+ * Public keys this app trusts for bundles and preview tokens: Evolve Cloud's
+ * production keys, plus an optional test key for local development and the
+ * fake cloud.
+ *
+ * `EVOLVE_UNSAFE_TEST_PUBLIC_KEY=<kid>:<x>` is ignored when
+ * NODE_ENV=production, unless `EVOLVE_UNSAFE_ALLOW_TEST_KEY=1` is also set
+ * (needed only to run SDK e2e tests against a production build).
+ */
+export declare function trustedKeySet(env?: Env): Record<string, string>;
+export declare function trustedKeys(env?: Env): KeyRing;
+export {};

package/dist/core/keys.js

@@ -0,0 +1,38 @@
+import { EVOLVE_PUBLIC_KEYS, createKeyRing } from "@next-evolve/protocol";
+// src/core/keys.ts
+let warned = false;
+/**
+* Public keys this app trusts for bundles and preview tokens: Evolve Cloud's
+* production keys, plus an optional test key for local development and the
+* fake cloud.
+*
+* `EVOLVE_UNSAFE_TEST_PUBLIC_KEY=<kid>:<x>` is ignored when
+* NODE_ENV=production, unless `EVOLVE_UNSAFE_ALLOW_TEST_KEY=1` is also set
+* (needed only to run SDK e2e tests against a production build).
+*/
+function trustedKeySet(env = process.env) {
+	const keys = { ...EVOLVE_PUBLIC_KEYS };
+	const test = env.EVOLVE_UNSAFE_TEST_PUBLIC_KEY;
+	if (!test) return keys;
+	const prod = env.NODE_ENV === "production";
+	if (prod && env.EVOLVE_UNSAFE_ALLOW_TEST_KEY !== "1") {
+		if (!warned) {
+			warned = true;
+			console.error("[evolve] EVOLVE_UNSAFE_TEST_PUBLIC_KEY is ignored in production.");
+		}
+		return keys;
+	}
+	const m = /^([A-Za-z0-9_.-]{1,64}):([A-Za-z0-9_-]{43})$/.exec(test);
+	if (!m) {
+		console.error("[evolve] EVOLVE_UNSAFE_TEST_PUBLIC_KEY must be <kid>:<base64url x>; ignored.");
+		return keys;
+	}
+	if (m[1] in keys) return keys;
+	if (prod) console.error("[evolve] UNSAFE: trusting a test signing key in a production build.");
+	keys[m[1]] = m[2];
+	return keys;
+}
+function trustedKeys(env = process.env) {
+	return createKeyRing(trustedKeySet(env));
+}
+export { trustedKeySet, trustedKeys };

package/dist/core/log.d.ts

@@ -0,0 +1,2 @@
+/** Logs at most once per `intervalMs` per key (default 60 s), so a hot path can't flood logs. */
+export declare function logRateLimited(key: string, message: string, err?: unknown, intervalMs?: number): void;

package/dist/core/log.js

@@ -0,0 +1,10 @@
+// src/core/log.ts
+const last = /* @__PURE__ */ new Map();
+/** Logs at most once per `intervalMs` per key (default 60 s), so a hot path can't flood logs. */
+function logRateLimited(key, message, err, intervalMs = 6e4) {
+	const now = Date.now();
+	if ((last.get(key) ?? 0) + intervalMs > now) return;
+	last.set(key, now);
+	console.error(`[evolve] ${message}`, ...err === void 0 ? [] : [err]);
+}
+export { logRateLimited };

package/dist/db/client.d.ts

@@ -0,0 +1,22 @@
+import postgres from "postgres";
+export type Sql = postgres.Sql;
+type Env = Record<string, string | undefined>;
+/** True on hosts where each request may run in a fresh, short-lived instance. */
+export declare function isServerless(env?: Env): boolean;
+/**
+ * Opens a connection pool. Prepared statements are off so pooled endpoints
+ * (Neon's `-pooler` host, PgBouncer in transaction mode) work.
+ */
+export declare function createSql(url: string, opts?: {
+  env?: Env;
+  max?: number;
+  debug?: postgres.Options<Record<string, never>>["debug"];
+}): Sql;
+/**
+ * The process-wide pool for the customer DB, created on first use. Null when
+ * the URL variable isn't set. The proxy never imports this module.
+ */
+export declare function getSql(urlEnv?: string, env?: Env): Sql | null;
+/** Closes every pool (tests, CLI). */
+export declare function closeAllSql(): Promise<void>;
+export {};

package/dist/db/client.js

@@ -0,0 +1,50 @@
+import postgres from "postgres";
+// src/db/client.ts
+/** True on hosts where each request may run in a fresh, short-lived instance. */
+function isServerless(env = process.env) {
+	return Boolean(env.VERCEL || env.AWS_LAMBDA_FUNCTION_NAME || env.NETLIFY);
+}
+/**
+* Opens a connection pool. Prepared statements are off so pooled endpoints
+* (Neon's `-pooler` host, PgBouncer in transaction mode) work.
+*/
+function createSql(url, opts = {}) {
+	return postgres(url, {
+		max: opts.max ?? (isServerless(opts.env) ? 1 : 10),
+		prepare: false,
+		idle_timeout: 20,
+		connect_timeout: 10,
+		onnotice: () => {},
+		connection: { application_name: "next-evolve" },
+		...opts.debug ? { debug: opts.debug } : {}
+	});
+}
+const POOLS = Symbol.for("next-evolve.sql");
+const pools = () => {
+	const g = globalThis;
+	g[POOLS] ??= /* @__PURE__ */ new Map();
+	return g[POOLS];
+};
+/**
+* The process-wide pool for the customer DB, created on first use. Null when
+* the URL variable isn't set. The proxy never imports this module.
+*/
+function getSql(urlEnv = "EVOLVE_DATABASE_URL", env = process.env) {
+	const url = env[urlEnv];
+	if (!url) return null;
+	const all = pools();
+	let sql = all.get(url);
+	if (!sql) {
+		sql = createSql(url, { env });
+		all.set(url, sql);
+	}
+	return sql;
+}
+/** Closes every pool (tests, CLI). */
+async function closeAllSql() {
+	const all = pools();
+	const list = [...all.values()];
+	all.clear();
+	await Promise.all(list.map((s) => s.end({ timeout: 5 })));
+}
+export { closeAllSql, createSql, getSql, isServerless };

package/dist/db/migrate.d.ts

@@ -0,0 +1,18 @@
+import { Sql } from "./client.js";
+/** Shipped with the package: `next-evolve/migrations/*.sql`. */
+export declare const MIGRATIONS_DIR: URL;
+export type Migration = {
+  id: string;
+  sql: string;
+};
+export type MigrateResult = {
+  applied: string[];
+  skipped: string[];
+};
+export declare function loadMigrations(dir?: URL): Promise<Migration[]>;
+/**
+ * Applies pending migrations in order, all in one transaction under an
+ * advisory lock, so concurrent runs (several instances booting) are safe and
+ * a failure leaves nothing half-applied. Idempotent.
+ */
+export declare function migrate(sql: Sql, migrations?: Migration[]): Promise<MigrateResult>;

package/dist/db/migrate.js

@@ -0,0 +1,43 @@
+import { readFile, readdir } from "node:fs/promises";
+// src/db/migrate.ts
+/** Shipped with the package: `next-evolve/migrations/*.sql`. */
+const MIGRATIONS_DIR = new URL("../../migrations/", import.meta.url);
+const LOCK_KEY = 1702260588;
+async function loadMigrations(dir = MIGRATIONS_DIR) {
+	const files = (await readdir(dir)).filter((f) => /^\d{4}_[a-z0-9_]+\.sql$/.test(f)).sort();
+	return Promise.all(files.map(async (f) => ({
+		id: f.replace(/\.sql$/, ""),
+		sql: await readFile(new URL(f, dir), "utf8")
+	})));
+}
+/**
+* Applies pending migrations in order, all in one transaction under an
+* advisory lock, so concurrent runs (several instances booting) are safe and
+* a failure leaves nothing half-applied. Idempotent.
+*/
+async function migrate(sql, migrations) {
+	const list = migrations ?? await loadMigrations();
+	return sql.begin(async (tx) => {
+		await tx`select pg_advisory_xact_lock(${LOCK_KEY})`;
+		await tx`create schema if not exists evolve`;
+		await tx`create table if not exists evolve.migrations (
+      id text primary key, applied_at timestamptz not null default now())`;
+		const done = new Set((await tx`select id from evolve.migrations`).map((r) => r.id));
+		const applied = [];
+		const skipped = [];
+		for (const m of list) {
+			if (done.has(m.id)) {
+				skipped.push(m.id);
+				continue;
+			}
+			await tx.unsafe(m.sql);
+			await tx`insert into evolve.migrations (id) values (${m.id})`;
+			applied.push(m.id);
+		}
+		return {
+			applied,
+			skipped
+		};
+	});
+}
+export { MIGRATIONS_DIR, loadMigrations, migrate };

package/dist/db/writer.d.ts

@@ -0,0 +1,53 @@
+import { Sql } from "./client.js";
+type Json = Record<string, unknown>;
+export type ExposureRow = {
+  experiment_id: string;
+  anon_id: string;
+  variant_id: string;
+  path: string;
+  /** When the beacon arrived (same clock as event `ts`), not when the batch is written. */
+  first_at: Date;
+};
+export type EventRow = {
+  ts: Date;
+  name: string;
+  anon_id: string | null;
+  user_id: string | null;
+  value: number | null;
+  goal_values: Json | null;
+  props: Json | null;
+  source: string;
+  path: string | null;
+  dedupe_key: string | null;
+};
+export type IdentityRow = {
+  anon_id: string;
+  user_id: string;
+};
+export type WriterOptions = {
+  sql: () => Sql | null;
+  /** node: flush on a timer / row count and keep rows while the DB is down. serverless: flush per request. */
+  mode?: "node" | "serverless";
+  flushMs?: number;
+  flushRows?: number;
+  maxBuffer?: number;
+};
+export type Writer = {
+  readonly mode: "node" | "serverless";
+  exposures(rows: ExposureRow[]): void;
+  events(rows: EventRow[]): void;
+  identities(rows: IdentityRow[]): void;
+  /** Adds tested page views to a UTC day (`YYYY-MM-DD`). */
+  usage(day: string, pageviews: number): void;
+  /** Rows waiting to be written. */
+  pending(): number;
+  /** Writes everything queued so far: one insert per table (chunked at 1,000 rows). */
+  flush(): Promise<void>;
+};
+export declare function createWriter(opts: WriterOptions): Writer;
+/**
+ * The process-wide writer for a DB URL variable. On long-running Node it also
+ * flushes on SIGTERM so a graceful shutdown doesn't lose buffered rows.
+ */
+export declare function getWriter(sql: () => Sql | null, key?: string): Writer;
+export {};

package/dist/db/writer.js

@@ -0,0 +1,182 @@
+import { logRateLimited } from "../core/log.js";
+import { isServerless } from "./client.js";
+// src/db/writer.ts
+const CHUNK = 1e3;
+const MAX_BACKOFF_MS = 3e4;
+function createWriter(opts) {
+	const mode = opts.mode ?? (isServerless() ? "serverless" : "node");
+	const flushMs = opts.flushMs ?? 1e3;
+	const flushRows = opts.flushRows ?? 100;
+	const maxBuffer = opts.maxBuffer ?? 1e4;
+	let exposures = [];
+	let events = [];
+	let identities = [];
+	let usage = /* @__PURE__ */ new Map();
+	let timer;
+	let backoffMs = 0;
+	let running = Promise.resolve();
+	const pending = () => exposures.length + events.length + identities.length + usage.size;
+	function schedule(delay) {
+		if (mode !== "node" || timer) return;
+		timer = setTimeout(() => {
+			timer = void 0;
+			flush();
+		}, delay);
+		timer.unref?.();
+	}
+	function added() {
+		if (mode !== "node") return;
+		trim();
+		if (pending() >= flushRows && backoffMs === 0) flush();
+		else schedule(backoffMs || flushMs);
+	}
+	/** Keeps the buffer bounded while the DB is down: the oldest rows go first. */
+	function trim() {
+		let over = pending() - maxBuffer;
+		if (over <= 0) return;
+		logRateLimited("writer:drop", `customer DB unavailable; dropping ${over} buffered rows`);
+		for (const list of [
+			events,
+			exposures,
+			identities
+		]) {
+			const n = Math.min(over, list.length);
+			list.splice(0, n);
+			over -= n;
+		}
+	}
+	async function write(sql, batch) {
+		for (const rows of chunks(batch.exposures)) await sql`insert into evolve.exposures ${sql(rows, "experiment_id", "anon_id", "variant_id", "path", "first_at")}
+        on conflict do nothing`;
+		for (const rows of chunks(batch.events)) await sql`insert into evolve.events ${sql(rows.map((r) => ({
+			...r,
+			goal_values: r.goal_values && sql.json(r.goal_values),
+			props: r.props && sql.json(r.props)
+		})), EVENT_COLS)}
+        on conflict (dedupe_key) where dedupe_key is not null do nothing`;
+		for (const rows of chunks(batch.identities)) await sql`insert into evolve.identities ${sql(rows, "anon_id", "user_id")} on conflict do nothing`;
+		const days = [...batch.usage].map(([day, n]) => ({
+			day,
+			tested_pageviews: n
+		}));
+		if (days.length) await sql`insert into evolve.usage_daily ${sql(days, "day", "tested_pageviews")}
+        on conflict (day) do update
+        set tested_pageviews = evolve.usage_daily.tested_pageviews + excluded.tested_pageviews`;
+	}
+	function take() {
+		const b = {
+			exposures,
+			events,
+			identities,
+			usage
+		};
+		exposures = [];
+		events = [];
+		identities = [];
+		usage = /* @__PURE__ */ new Map();
+		return b;
+	}
+	function restore(b) {
+		exposures = [...b.exposures, ...exposures];
+		events = [...b.events, ...events];
+		identities = [...b.identities, ...identities];
+		for (const [d, n] of b.usage) usage.set(d, (usage.get(d) ?? 0) + n);
+	}
+	async function flushOnce() {
+		if (pending() === 0) return;
+		const sql = opts.sql();
+		if (!sql) {
+			logRateLimited("writer:nodb", "EVOLVE_DATABASE_URL is not set; events are not stored");
+			take();
+			return;
+		}
+		const batch = take();
+		try {
+			await write(sql, batch);
+			backoffMs = 0;
+		} catch (e) {
+			if (mode === "serverless") try {
+				await write(sql, batch);
+				return;
+			} catch (e2) {
+				logRateLimited("writer:dropped", "customer DB write failed; batch dropped", e2);
+				return;
+			}
+			logRateLimited("writer:retry", "customer DB write failed; will retry", e);
+			restore(batch);
+			trim();
+			backoffMs = Math.min(MAX_BACKOFF_MS, backoffMs ? backoffMs * 2 : flushMs);
+			schedule(backoffMs);
+		}
+	}
+	function flush() {
+		if (timer) {
+			clearTimeout(timer);
+			timer = void 0;
+		}
+		running = running.then(flushOnce, flushOnce);
+		return running;
+	}
+	return {
+		mode,
+		exposures(rows) {
+			if (!rows.length) return;
+			exposures.push(...rows);
+			added();
+		},
+		events(rows) {
+			if (!rows.length) return;
+			events.push(...rows);
+			added();
+		},
+		identities(rows) {
+			if (!rows.length) return;
+			identities.push(...rows);
+			added();
+		},
+		usage(day, n) {
+			if (n <= 0) return;
+			usage.set(day, (usage.get(day) ?? 0) + n);
+			added();
+		},
+		pending,
+		flush
+	};
+}
+const EVENT_COLS = [
+	"ts",
+	"name",
+	"anon_id",
+	"user_id",
+	"value",
+	"goal_values",
+	"props",
+	"source",
+	"path",
+	"dedupe_key"
+];
+function* chunks(rows) {
+	for (let i = 0; i < rows.length; i += CHUNK) yield rows.slice(i, i + CHUNK);
+}
+const WRITERS = Symbol.for("next-evolve.writers");
+/**
+* The process-wide writer for a DB URL variable. On long-running Node it also
+* flushes on SIGTERM so a graceful shutdown doesn't lose buffered rows.
+*/
+function getWriter(sql, key = "EVOLVE_DATABASE_URL") {
+	const g = globalThis;
+	g[WRITERS] ??= /* @__PURE__ */ new Map();
+	let w = g[WRITERS].get(key);
+	if (!w) {
+		const writer = createWriter({ sql });
+		w = writer;
+		g[WRITERS].set(key, writer);
+		if (!isServerless() && typeof process !== "undefined" && process.once) process.once("SIGTERM", () => {
+			writer.flush().finally(() => {
+				if (process.listenerCount("SIGTERM") === 0) process.exit(0);
+			});
+		});
+	}
+	return w;
+}
+export { createWriter, getWriter };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { OptimizableComponent, OptimizableMeta, getOptimizableMeta, optimizable } from "./react/optimizable.js";
+import { Optimizable, OptimizableProps } from "./react/region.js";
+import { EvolvePageProps, evolveMetadata, evolveStaticParams, withEvolve } from "./react/with-evolve.js";
+import "server-only";
+export { type EvolvePageProps, Optimizable, type OptimizableComponent, type OptimizableMeta, type OptimizableProps, evolveMetadata, evolveStaticParams, getOptimizableMeta, optimizable, withEvolve };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { getOptimizableMeta, optimizable } from "./react/optimizable.js";
+import { Optimizable } from "./react/region.js";
+import { evolveMetadata, evolveStaticParams, withEvolve } from "./react/with-evolve.js";
+import "server-only";
+export { Optimizable, evolveMetadata, evolveStaticParams, getOptimizableMeta, optimizable, withEvolve };

package/dist/instrumentation/index.d.ts

@@ -0,0 +1,24 @@
+import { EvolveConfig } from "../config/config.js";
+import { Goals } from "../config/goals.js";
+export type RegisterEvolveOptions = {
+  config: EvolveConfig;
+  goals?: Goals;
+};
+/**
+ * Call from `instrumentation.ts` `register()`:
+ *
+ *   export async function register() {
+ *     if (process.env.NEXT_RUNTIME === "nodejs") {
+ *       const { registerEvolve } = await import("next-evolve/instrumentation");
+ *       await registerEvolve({ config, goals });
+ *     }
+ *   }
+ *
+ * Registers the goals for this process and pushes the manifest to the cloud
+ * (goals, routes, versions, app URL; spec §8.4), once per process. On
+ * long-running Node it also polls the bundle in the background (spec §7.5),
+ * so the disk cache stays fresh between requests. Never throws.
+ */
+export declare function registerEvolve(opts: RegisterEvolveOptions): Promise<void>;
+/** Test helper. */
+export declare function resetRegisterEvolve(): void;

package/dist/instrumentation/index.js

@@ -0,0 +1,54 @@
+import { buildManifest, detectAppUrl } from "../cloud/manifest.js";
+import { pushToCloud } from "../cloud/push.js";
+import { resolveConfig } from "../config/config.js";
+import { setRuntime } from "../server/runtime.js";
+import { getBundleStore, isLongRunningNode } from "../store/runtime.js";
+// src/instrumentation/index.ts
+let registered = false;
+let poll = null;
+/**
+* Call from `instrumentation.ts` `register()`:
+*
+*   export async function register() {
+*     if (process.env.NEXT_RUNTIME === "nodejs") {
+*       const { registerEvolve } = await import("next-evolve/instrumentation");
+*       await registerEvolve({ config, goals });
+*     }
+*   }
+*
+* Registers the goals for this process and pushes the manifest to the cloud
+* (goals, routes, versions, app URL; spec §8.4), once per process. On
+* long-running Node it also polls the bundle in the background (spec §7.5),
+* so the disk cache stays fresh between requests. Never throws.
+*/
+async function registerEvolve(opts) {
+	if (registered) return;
+	registered = true;
+	try {
+		setRuntime({
+			config: opts.config,
+			goals: opts.goals
+		});
+		if (isLongRunningNode()) {
+			const cfg = resolveConfig(opts.config);
+			const store = getBundleStore(cfg);
+			if (store) {
+				store.refresh();
+				poll = setInterval(() => void store.refresh(), cfg.pollSeconds * 1e3);
+				poll.unref();
+			}
+		}
+		const manifest = buildManifest(opts.config, opts.goals, { appUrl: detectAppUrl() });
+		const res = await pushToCloud("/v1/manifest", manifest);
+		if (!res.ok && res.status !== "no_key") console.error(`[evolve] manifest push failed (${res.status})`);
+	} catch (e) {
+		console.error("[evolve] registerEvolve failed", e);
+	}
+}
+/** Test helper. */
+function resetRegisterEvolve() {
+	registered = false;
+	if (poll) clearInterval(poll);
+	poll = null;
+}
+export { registerEvolve, resetRegisterEvolve };