@ogygia/flags 0.11.0 → 0.13.0

package/README.md

@@ -31,4 +31,4 @@ hero(c); // 'control' | 'bold', sticky per visitor
 
 A native `flag()` works without the plugin. The plugin primes a `decide({ source })` (OpenFeature, OFREP, or your own function) one time per request, and drains the `exposure` sink at the end of each request. OpenFeature lives at `@ogygia/flags/openfeature`.
 
-Docs: [Flags & experiments](https://ogygiajs.dev/docs/app/experiments).
+Docs: [@ogygia/flags](https://ogygiajs.dev/docs/flags/overview), with the full [Flags & experiments](https://ogygiajs.dev/docs/flags/guide) guide.

package/dist/index.d.ts

@@ -58,14 +58,19 @@ export interface DecideOptions {
  *   decide({ source: openfeature(client), overrides: (c) => !!c.visitor?.qa, exposure: send });
  */
 export declare function decide(opts: DecideOptions): void;
-/** Drain queued exposures to the sink. Called at each request's end (serverless-safe tail) and on
- *  the size/age caps. A sink failure is contained — a lost batch is never a request's problem. */
-export declare function flush_exposures(): void;
+/**
+ * Send the queued exposures to the sink now. Called at each request's end (the flags plugin's `done`)
+ * and by the size and age caps. Resolves when they have reached the sink (behind the batches before
+ * them); `undefined` when nothing is queued or being sent. A sink failure is contained: a lost batch
+ * is never a request's problem.
+ */
+export declare function flush_exposures(): Promise<void> | undefined;
 /**
  * Resolve the source ONCE per request over every registered flag, caching decisions on the
  * Request so reads stay sync. Awaited by the flags plugin's `request` stage (flags/server.ts), above
  * the page / hole split. Idempotent; a no-op without a source. Never throws — a source failure
- * degrades every flag to its native rule, it does not take the request down.
+ * degrades every flag to its native rule, it does not take the request down, and is said
+ * (`flags_source_failed`, once per failing streak).
  */
 export declare function prime_flags(c: CtxLike): Promise<void>;
 /** A per-request component chooser for `page()` — `page(hero.pick({ control: A, bold: B }))`.

package/dist/index.js

@@ -1,6 +1,9 @@
 import { flags_app } from "./app.js";
+import { warn } from "./messages.js";
+import { source_answered, source_failed, source_mark, source_reset } from "./source-health.js";
 import { BROWSER, DEV } from "esm-env";
 import { fnv1a32 } from "@ogygia/core/plugin/utils";
+import { machine, outbox, policy } from "@ogygia/machine";
 // src/index.ts
 /**
 * `flag()` — the ONE assignment primitive. A kill switch, a rollout, a targeting rule, and an
@@ -20,8 +23,10 @@ import { fnv1a32 } from "@ogygia/core/plugin/utils";
 */
 /** Written by an upstream shell's identity hop (the fragment feature); absent = the tier is skipped. */
 const CLAIMS = Symbol.for("ogygia.claims.v1");
-/** Per-request source resolution, cached on the Request (GC'd with it). */
-const RESOLVED = Symbol.for("ogygia.flags.resolved.v1");
+/** Per-request source resolution, cached on the Request (GC'd with it): its {@link Prime}. */
+const RESOLVED = Symbol.for("ogygia.flags.resolved.v2");
+const prime_of = (c) => c.request[RESOLVED];
+const set_prime = (c, p) => c.request[RESOLVED] = p;
 /** 0..9999 — sticky hash bucket for (salt, visitor). Uniform + deterministic, not cryptographic;
 *  the shared pure hash keeps this module safe in ANY bundle (runtime + every island entry). */
 const pct = (s) => fnv1a32(s) % 1e4;
@@ -52,8 +57,6 @@ let _batch = {
 	max: 25,
 	ms: 2e3
 };
-let _queue = [];
-let _timer = null;
 /**
 * Configure flags for this server, once (hooks.server.ts / any server module). Everything is
 * optional — with no `decide()` at all, flags are native, sticky, and zero-JS.
@@ -61,7 +64,10 @@ let _timer = null;
 *   decide({ source: openfeature(client), overrides: (c) => !!c.visitor?.qa, exposure: send });
 */
 function decide(opts) {
-	if ("source" in opts) _source = opts.source ?? null;
+	if ("source" in opts) {
+		_source = opts.source ?? null;
+		source_reset();
+	}
 	if (opts.overrides) _override_gate = opts.overrides;
 	if ("exposure" in opts) _exposure = opts.exposure ?? null;
 	if (opts.batch) _batch = {
@@ -69,23 +75,75 @@ function decide(opts) {
 		ms: opts.batch.ms ?? 2e3
 	};
 }
+const _exposures = /* @__PURE__ */ (/* @__PURE__ */ machine()({
+	name: "flags exposures",
+	initial: "idle",
+	steps: {
+		idle: ["buffering"],
+		buffering: ["idle"]
+	}
+})).create();
+/** What the next batch takes. */
+let _queue = [];
+/** The last batch was given up: the next one given up is not said again until one is taken. */
+let _sink_failing = false;
+/** The last batch put, until it settles: the request's end waits for it (the outbox sends in
+*  order, so every batch before it has settled by then). */
+let _last_sent = null;
+/** The batches on their way to the sink: kept alive past the response, one at a time, in order. */
+const _batches = /* @__PURE__ */ outbox({
+	name: "flags exposures",
+	send: async (batch) => {
+		await _exposure?.(batch);
+		_sink_failing = false;
+	},
+	retry: /* @__PURE__ */ policy({
+		attempts: 3,
+		backoff: [250, 1e3],
+		jitter: .2,
+		deadline: 1e4
+	}),
+	inOrder: true,
+	giveUp: (_batch, error) => {
+		if (_sink_failing) return;
+		_sink_failing = true;
+		warn("flags_exposure_failed", error);
+	},
+	waitUntil: (work) => flags_app()?.keepAlive(work)
+});
 function emit_exposure(e) {
-	if (!_exposure) return;
+	if (BROWSER || !_exposure) return;
 	_queue.push(e);
-	if (_queue.length >= _batch.max) flush_exposures();
-	else if (!_timer) _timer = setTimeout(flush_exposures, _batch.ms);
+	if (_queue.length >= _batch.max) {
+		send();
+		return;
+	}
+	if (_exposures.now.kind === "buffering") return;
+	_exposures.go("buffering");
+	const timer = setTimeout(() => void send(), _batch.ms);
+	_exposures.scope.defer(() => clearTimeout(timer));
 }
-/** Drain queued exposures to the sink. Called at each request's end (serverless-safe tail) and on
-*  the size/age caps. A sink failure is contained — a lost batch is never a request's problem. */
-function flush_exposures() {
-	if (_timer) clearTimeout(_timer);
-	_timer = null;
-	if (_queue.length === 0) return;
+/** Everything queued, as one batch into the outbox now (buffering → idle). Settles once the sink
+*  took it or it was given up; never rejects. */
+function send() {
 	const batch = _queue;
 	_queue = [];
-	try {
-		_exposure?.(batch);
-	} catch {}
+	_exposures.move("buffering", "idle");
+	const sent = _batches.put(batch).then(() => {
+		if (_last_sent === sent) _last_sent = null;
+	});
+	_last_sent = sent;
+	return sent;
+}
+/**
+* Send the queued exposures to the sink now. Called at each request's end (the flags plugin's `done`)
+* and by the size and age caps. Resolves when they have reached the sink (behind the batches before
+* them); `undefined` when nothing is queued or being sent. A sink failure is contained: a lost batch
+* is never a request's problem.
+*/
+function flush_exposures() {
+	if (_queue.length > 0) return send();
+	return _last_sent ?? void 0;
 }
 /** Every constructed flag self-registers here — the complete name list a source is asked for, and
 *  the set federation auto-carries. Import your flags (route modules do this at startup; on plain
@@ -95,15 +153,32 @@ const _registry = /* @__PURE__ */ new Map();
 * Resolve the source ONCE per request over every registered flag, caching decisions on the
 * Request so reads stay sync. Awaited by the flags plugin's `request` stage (flags/server.ts), above
 * the page / hole split. Idempotent; a no-op without a source. Never throws — a source failure
-* degrades every flag to its native rule, it does not take the request down.
+* degrades every flag to its native rule, it does not take the request down, and is said
+* (`flags_source_failed`, once per failing streak).
 */
-async function prime_flags(c) {
-	const req = c.request;
-	if (!_source || req[RESOLVED] !== void 0) return;
-	req[RESOLVED] = {};
-	if (_registry.size === 0) return;
+function prime_flags(c) {
+	if (!_source) return Promise.resolve();
+	const now = prime_of(c);
+	if (now !== void 0) return now.kind === "priming" ? now.done : Promise.resolve();
+	if (_registry.size === 0) {
+		set_prime(c, {
+			kind: "resolved",
+			map: {}
+		});
+		return Promise.resolve();
+	}
+	const claim = {
+		kind: "priming",
+		done: Promise.resolve()
+	};
+	set_prime(c, claim);
+	claim.done = ask_source(c, _source);
+	return claim.done;
+}
+async function ask_source(c, source) {
+	const mark = source_mark();
 	try {
-		const out = await _source([..._registry.values()], {
+		const out = await source([..._registry.values()], {
 			...c,
 			visitor: visitor_of(c)
 		});
@@ -114,18 +189,26 @@ async function prime_flags(c) {
 			const norm = typeof raw === "boolean" ? { variant: raw ? "on" : "off" } : typeof raw === "string" ? { variant: raw } : raw;
 			if (norm && q.variants.includes(norm.variant)) map[q.name] = norm;
 		}
-		req[RESOLVED] = map;
-	} catch {
-		req[RESOLVED] = {};
+		set_prime(c, {
+			kind: "resolved",
+			map
+		});
+		source_answered(mark);
+	} catch (error) {
+		set_prime(c, {
+			kind: "resolved",
+			map: {}
+		});
+		source_failed(error);
 	}
 }
 function resolved_for(c, name) {
-	const map = c.request[RESOLVED];
-	if (map === void 0 && _source && !_unprimed_warned) {
+	const p = prime_of(c);
+	if (p === void 0 && _source && !_unprimed_warned) {
 		_unprimed_warned = true;
-		console.warn("[ogygia] flags: `decide({ source })` is set but no request was primed — list `flags()` beside `ogygia()` in vite.config `plugins`.");
+		warn("flags_source_unprimed");
 	}
-	return map?.[name];
+	return p?.kind === "resolved" ? p.map[name] : void 0;
 }
 let _unprimed_warned = false;
 let _unstarted_warned = false;
@@ -204,7 +287,7 @@ function flag(name, shape, opts = {}) {
 			if (facts.perVisitor === null) facts.perVisitor = `flag:${name}`;
 		} else if (!BROWSER && !_unstarted_warned) {
 			_unstarted_warned = true;
-			console.warn("[ogygia] flags: a flag was read on the server but the flags plugin is not running — list `flags()` (from `@ogygia/flags/vite`) beside `ogygia()` in vite.config `plugins`. Until then flag reads are not reported to the request, and a stored page could keep one variant.");
+			warn("flags_plugin_not_running");
 		}
 		const cached = memo.get(c.request);
 		if (cached !== void 0) return cached;

package/dist/messages.d.ts

@@ -0,0 +1,29 @@
+import { MessagesOf } from "@ogygia/core/internal/messages";
+/** The errors: `throw new OgygiaError(code, args)`. */
+export declare const FLAGS_ERRORS: {};
+/** The warnings: `warn(code, args, ...rest)`. */
+export declare const FLAGS_WARNINGS: {
+  flags_source_unprimed: {
+    text: () => string;
+    details: () => string;
+  };
+  flags_exposure_failed: {
+    text: () => string;
+    details: () => string;
+  };
+  flags_source_failed: {
+    text: () => string;
+    details: () => string;
+  };
+  flags_plugin_not_running: {
+    text: () => string;
+    details: () => string;
+  };
+};
+type Own = MessagesOf<typeof FLAGS_ERRORS, typeof FLAGS_WARNINGS>;
+/** `throw new OgygiaError(code, args)`; `warn(code, args, ...rest)` logs; `line(code, args)` is the
+ *  line as a string. Wording and link in dev and while prerendering, the link alone otherwise. */
+export declare const OgygiaError: Own["OgygiaError"];
+export declare const warn: Own["warn"];
+export declare const line: Own["line"];
+export {};

package/dist/messages.js

@@ -0,0 +1,84 @@
+import { BROWSER, DEV } from "esm-env";
+import { define_messages, dev_or_prerender, prose } from "@ogygia/core/internal/messages";
+// src/messages.ts
+/**
+* EVERY MESSAGE THE FLAGS PACKAGE PRINTS, in one place: its code, its wording, what to do about it
+* (core's `@ogygia/core/internal/messages` says how the system works).
+*
+*   warn('flags_plugin_not_running');
+*
+* Flag reads run in the app's server and its pages, so the wording is only passed in dev: a
+* production build prints the code's page alone.
+*/
+/** The errors: `throw new OgygiaError(code, args)`. */
+const FLAGS_ERRORS = {};
+/** The warnings: `warn(code, args, ...rest)`. */
+const FLAGS_WARNINGS = {
+	flags_source_unprimed: {
+		text: () => prose`
+			flags: \`decide({ source })\` is set but no request was primed — list \`flags()\` beside
+			\`ogygia()\` in vite.config \`plugins\`.
+		`,
+		details: () => prose`
+			A flag has a \`source\`, but the request it was read in was never primed by the flags
+			plugin, so every read ignores the source and falls back to the flag's own decision. Said
+			once per server.
+
+			List \`flags()\` (from \`@ogygia/flags/vite\`) beside \`ogygia()\` in the \`plugins\` of
+			vite.config.
+		`
+	},
+	flags_exposure_failed: {
+		text: () => prose`
+			flags: the exposure sink (\`decide({ exposure })\`) failed, and the batch it was sent is lost.
+			The error follows.
+		`,
+		details: () => prose`
+			The function given to \`decide({ exposure })\` threw, or the promise it returned rejected (a
+			send that failed), so the exposures in that batch did not reach your analytics. The request
+			that read the flags is not affected. Said once, then again only after a send has worked:
+			a sink that stays down does not fill the log.
+
+			Check the sink's endpoint and credentials. To keep a batch through an outage, retry or
+			queue inside the sink.
+		`
+	},
+	flags_source_failed: {
+		text: () => prose`
+			flags: the flag source (\`decide({ source })\`) failed, so its flags fell back to their own
+			rule. The error follows.
+		`,
+		details: () => prose`
+			The source given to \`decide({ source })\` threw, rejected, or (with \`ofrep()\`) its
+			endpoint answered an error or could not be reached in time; with \`openfeature()\`, one
+			flag's evaluation threw. The request is not affected: each flag the source did not answer
+			is decided by its own rollout, as if there were no source. Said once, then again only
+			after a request the source served worked: a source that stays down does not fill the log.
+
+			Check the vendor's status, the endpoint and its credentials, and \`ofrep({ timeout })\`.
+		`
+	},
+	flags_plugin_not_running: {
+		text: () => prose`
+			flags: a flag was read on the server but the flags plugin is not running — list
+			\`flags()\` (from \`@ogygia/flags/vite\`) beside \`ogygia()\` in vite.config \`plugins\`.
+			Until then flag reads are not reported to the request, and a stored page could keep one
+			variant.
+		`,
+		details: () => prose`
+			A flag was read on the server, but the flags plugin never started. Nothing tells the
+			request that its page depends on a flag, so a store (a postrender cache) could keep one
+			variant of an A/B-tested page and serve it to everyone. Said once per server.
+
+			List \`flags()\` (from \`@ogygia/flags/vite\`) beside \`ogygia()\` in the \`plugins\` of
+			vite.config.
+		`
+	}
+};
+const own = /* @__PURE__ */ define_messages(DEV || !BROWSER ? FLAGS_ERRORS : null, DEV || !BROWSER ? FLAGS_WARNINGS : null, dev_or_prerender);
+/** `throw new OgygiaError(code, args)`; `warn(code, args, ...rest)` logs; `line(code, args)` is the
+*  line as a string. Wording and link in dev and while prerendering, the link alone otherwise. */
+const OgygiaError = own.OgygiaError;
+const warn = own.warn;
+const line = own.line;
+export { FLAGS_ERRORS, FLAGS_WARNINGS, OgygiaError, line, warn };

package/dist/ofrep.js

@@ -1,4 +1,15 @@
+import { request_scope } from "@ogygia/core/internal/server";
 // src/ofrep.ts
+/**
+* `@ogygia/flags/openfeature` (OFREP) — speak the OpenFeature Remote Evaluation Protocol directly, with
+* ZERO vendor SDK. Any OFREP endpoint works (flagd, the OpenFeature operator, a gateway). One
+* bulk POST per request over the app's declared flags; decisions come back as variant names +
+* optional payloads, indistinguishable from native flags after the await.
+*
+*   import { decide } from '@ogygia/flags';
+*   import { ofrep } from '@ogygia/flags/openfeature';
+*   decide({ source: ofrep({ url: 'http://flagd:8016' }) });
+*/
 const TRAILING_SLASH_RE = /\/$/;
 function default_context(c) {
 	const sub = c.visitor?.sub;
@@ -14,6 +25,7 @@ function ofrep(opts) {
 	const timeout = opts.timeout ?? 800;
 	return async (queries, c) => {
 		const out = {};
+		const ended = request_scope(c.request).signal;
 		try {
 			const res = await f(endpoint, {
 				method: "POST",
@@ -22,9 +34,9 @@ function ofrep(opts) {
 					...opts.headers
 				},
 				body: JSON.stringify({ context: ctx_of(c) }),
-				signal: AbortSignal.timeout(timeout)
+				signal: AbortSignal.any([AbortSignal.timeout(timeout), ended])
 			});
-			if (!res.ok) return out;
+			if (!res.ok) throw new Error(`OFREP ${endpoint} answered ${res.status}`);
 			const body = await res.json();
 			const want = new Map(queries.map((q) => [q.name, q]));
 			for (const f of body.flags ?? []) {
@@ -37,7 +49,10 @@ function ofrep(opts) {
 					value: f.value
 				} : variant;
 			}
-		} catch {}
+		} catch (error) {
+			if (ended.aborted) return out;
+			throw error;
+		}
 		return out;
 	};
 }

package/dist/openfeature.js

@@ -1,3 +1,4 @@
+import { source_failed } from "./source-health.js";
 import { ofrep } from "./ofrep.js";
 // src/openfeature.ts
 function default_context(c) {
@@ -31,7 +32,9 @@ function openfeature(client, opts = {}) {
 						};
 					}
 				}
-			} catch {}
+			} catch (error) {
+				source_failed(error);
+			}
 		}));
 		return out;
 	};

package/dist/server.js

@@ -5,7 +5,9 @@ import { defineServer } from "@ogygia/core/plugin";
 /**
 * The flags plugin's server realm (named by `flags()`).
 * `request`: prime the decision source once, above the page / hole split, so every read stays sync.
-* `done`: drain queued exposures at the request's end, always (the serverless-safe tail).
+* `done`: drain queued exposures at the request's end, always (the serverless-safe tail): the send
+* is returned, so the request's end hands it to the platform's `waitUntil` when there is one (#243);
+* the response never waits for it.
 */
 const server = defineServer({
 	setup(app) {
@@ -19,7 +21,7 @@ const server = defineServer({
 		});
 	},
 	done() {
-		flush_exposures();
+		return flush_exposures();
 	}
 });
 export { server as default };

package/dist/source-health.d.ts

@@ -0,0 +1,8 @@
+/** A failure of the source (all of it, or one flag): said unless its streak was already said. */
+export declare function source_failed(error: unknown): void;
+/** Before a call of the source: what `source_answered` compares against. */
+export declare function source_mark(): number;
+/** The source answered: with no failure since `mark`, its streak ends. */
+export declare function source_answered(mark: number): void;
+/** A new source: no streak. */
+export declare function source_reset(): void;

package/dist/source-health.js

@@ -0,0 +1,29 @@
+import { warn } from "./messages.js";
+// src/source-health.ts
+/**
+* Whether the flag source is failing: a failure is said (`flags_source_failed`) once per failing
+* streak, and the streak ends with a request the source served with no failure, like the exposure
+* sink's. `openfeature()` says a failure of one flag here while it still answers the others.
+*/
+let failing = false;
+let failures = 0;
+/** A failure of the source (all of it, or one flag): said unless its streak was already said. */
+function source_failed(error) {
+	failures++;
+	if (failing) return;
+	failing = true;
+	warn("flags_source_failed", error);
+}
+/** Before a call of the source: what `source_answered` compares against. */
+function source_mark() {
+	return failures;
+}
+/** The source answered: with no failure since `mark`, its streak ends. */
+function source_answered(mark) {
+	if (failures === mark) failing = false;
+}
+/** A new source: no streak. */
+function source_reset() {
+	failing = false;
+}
+export { source_answered, source_failed, source_mark, source_reset };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogygia/flags",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Feature flags and A/B tests for ogygia: one flag() primitive, decided server-side, zero JS",
   "keywords": [
     "ab-testing",
@@ -22,6 +22,7 @@
     "README.md"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -34,24 +35,29 @@
     "./vite": {
       "types": "./dist/vite.d.ts",
       "default": "./dist/vite.js"
+    },
+    "./internal/messages": {
+      "types": "./dist/messages.d.ts",
+      "default": "./dist/messages.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "@ogygia/machine": "^0.13.0",
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
+    "@ogygia/config": "0.0.0",
+    "@ogygia/core": "0.13.0",
     "@typescript/native": "npm:typescript@^7.0.2",
     "tsdown": "^0.23.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.12",
-    "@ogygia/core": "0.11.0",
-    "@ogygia/tooling": "0.0.0"
+    "vitest": "^4.1.12"
   },
   "peerDependencies": {
-    "@ogygia/core": "^0.11.0"
+    "@ogygia/core": "^0.13.0"
   },
   "scripts": {
     "build": "tsdown",