@voltro/plugin-flags 0.86.0 → 0.87.0

package/dist/config-testing.d.ts

@@ -0,0 +1,336 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { PluginLifecycleContext } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/** `TypedFlag` with the value type erased — what the plugin and the registry
+ *  hold. Sound because `TypedFlag` is covariant in `A` (see the annotation). */
+declare type AnyTypedFlag = TypedFlag<unknown>;
+
+export declare const configCatalogFixture: () => DefinedConfig<{
+    readonly 'xp.multiplier': number;
+    readonly 'arena.maxPlayers': number;
+    readonly 'shop.featured': readonly string[];
+}>;
+
+declare interface ConfigEntry<out A> {
+    readonly key: string;
+    readonly flag: TypedFlag<A>;
+    readonly public: boolean;
+    readonly restartRequired: 'room' | 'live';
+    readonly min: number | null;
+    readonly max: number | null;
+}
+
+/** Typed Config failures contain no private value, subject or decode body. */
+declare class ConfigError extends ConfigError_base {
+}
+
+declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_value", "not_found", "unavailable"]>;
+}>, YieldableError>;
+
+export declare const configFakeLayer: Layer.Layer<ConfigPort, ConfigError, never>;
+
+export declare const configFixtureLifecycle: PluginLifecycleContext;
+
+declare class ConfigPort extends ConfigPort_base {
+}
+
+declare const ConfigPort_base: Context.ServiceClass<ConfigPort, "@voltro/ConfigPort", ConfigService>;
+
+export declare const configPortFixture: Effect.Effect<{
+    catalog: DefinedConfig<{
+        readonly 'xp.multiplier': number;
+        readonly 'arena.maxPlayers': number;
+        readonly 'shop.featured': readonly string[];
+    }>;
+    plugin: FlagsPlugin;
+    service: ConfigService;
+    close: Effect.Effect<void, never, never>;
+}, ConfigError, never>;
+
+export declare const configPortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof ConfigPort;
+    fakeLayer: Layer.Layer<ConfigPort, ConfigError, never>;
+    probe: {
+        run: () => Effect.Effect<{
+            value: unknown;
+            mine: Readonly<Record<string, unknown>>;
+            room: Readonly<Record<string, unknown>>;
+            live: Readonly<Record<string, unknown>>;
+        }, ConfigError, never>;
+        expected: {
+            value: number;
+            mine: {
+                'xp.multiplier': number;
+                'shop.featured': string[];
+            };
+            room: {
+                'xp.multiplier': number;
+                'arena.maxPlayers': number;
+            };
+            live: {
+                'shop.featured': string[];
+            };
+        };
+    };
+}>;
+
+declare interface ConfigResolutionContext {
+    readonly entry: ConfigEntry<unknown>;
+    readonly value: FlagValue;
+    readonly subject: FlagSubject;
+    readonly now: number;
+}
+
+declare type ConfigResolver = (context: ConfigResolutionContext) => unknown;
+
+export declare const configResolverSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: ConfigResolver;
+    defaultProbe: {
+        run: () => Effect.Effect<unknown, never, never>;
+        expected: number;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<unknown, never, never>;
+        expected: number;
+    };
+}>;
+
+declare interface ConfigService {
+    readonly get: (key: string, subject: FlagSubject) => Effect.Effect<unknown, ConfigError>;
+    readonly mine: (subject: FlagSubject) => Effect.Effect<Readonly<Record<string, unknown>>, ConfigError>;
+    /** Snapshot outside a Room tick, then pass it through creation or app messages. */
+    readonly snapshot: (subject: FlagSubject, mode: 'room' | 'live') => Effect.Effect<Readonly<Record<string, unknown>>, ConfigError>;
+}
+
+declare interface ConfigSetInput {
+    readonly key: string;
+    readonly value: unknown;
+    readonly actor?: string | null;
+}
+
+declare interface DefinedConfig<Values extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    readonly entries: {
+        readonly [Key in keyof Values]: ConfigEntry<Values[Key]>;
+    };
+    readonly keys: readonly (keyof Values & string)[];
+    readonly typedFlags: readonly AnyTypedFlag[];
+}
+
+/** The result of decoding an UNTRUSTED value (a DB override, a dashboard edit)
+ *  against a flag's Schema. Deliberately not an exception: the caller's correct
+ *  response is to keep the code-declared value and say so, not to unwind. */
+declare type FlagDecodeResult<A> = {
+    readonly ok: true;
+    readonly value: A;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+
+declare interface FlagDefinition {
+    /** Master switch. `false` → off for everyone regardless of rollout/targeting. Default true. */
+    readonly enabled?: boolean;
+    /** Percentage rollout 0..100 — deterministic per (key, subject/tenant) so a
+     *  caller stays in/out consistently. Omit = 100 (everyone the targeting allows). */
+    readonly rollout?: number;
+    /** OR-of-rules targeting. When present, the caller must match at least one
+     *  rule (in addition to passing the rollout). Omit = everyone. */
+    readonly targeting?: ReadonlyArray<FlagTargetingRule>;
+    /** Bucket on the tenant id instead of the subject id (rollout by tenant). */
+    readonly rolloutBy?: 'subject' | 'tenant';
+    /** Multivariate flag — a set of named variants the flag resolves ONE of per
+     *  subject, deterministically weighted (see `FlagVariant.weight`). A subject
+     *  stays in the same variant across calls. When present, `variant.evaluate`
+     *  serves the resolved variant; the boolean resolution is `enabled && variant
+     *  is served` (the flag is "on" for the caller unless a variant named in
+     *  `offVariant` is served — omit ⇒ any served variant counts as on). */
+    readonly variants?: ReadonlyArray<FlagVariant>;
+    /** Variant name treated as the "off" state for boolean resolution. Omit ⇒
+     *  passing targeting+rollout with any served variant counts as on. */
+    readonly offVariant?: string;
+    /** Time-boxed / ramping schedule, evaluated against the current time. */
+    readonly schedule?: FlagSchedule;
+    /** Surfaced in the dashboard / `flags.evaluate`. */
+    readonly description?: string;
+}
+
+/** A time-boxed / ramping schedule. Evaluated against the current time.
+ *  Order: outside [activateAt, deactivateAt) ⇒ off; a `ramp` interpolates the
+ *  effective rollout % linearly across its window. */
+declare interface FlagSchedule {
+    /** Flag is off before this instant (epoch millis or ISO string). Omit ⇒ no lower bound. */
+    readonly activateAt?: number | string;
+    /** Flag is off at/after this instant (epoch millis or ISO string). Omit ⇒ no upper bound. */
+    readonly deactivateAt?: number | string;
+    /** A ramping rollout: exposure grows linearly from `from`% to `to`% across
+     *  [`startAt`, `endAt`). Before `startAt` ⇒ `from`%, after `endAt` ⇒ `to`%.
+     *  The interpolated % REPLACES the flag's static `rollout` while active. */
+    readonly ramp?: {
+        readonly from: number;
+        readonly to: number;
+        readonly startAt: number | string;
+        readonly endAt: number | string;
+    };
+}
+
+declare interface FlagsPlugin extends VoltroPlugin {
+    readonly config?: () => ConfigService;
+    /** Set a typed Config value for everyone (validated against its schema, min and max): live at
+     *  once, durable and audited with the actor and the previous variants on the postgres tier. */
+    readonly setConfig?: (input: ConfigSetInput) => Effect.Effect<{
+        readonly key: string;
+        readonly value: unknown;
+    }, ConfigError>;
+    /** Flip a flag's kill-switch: live at once, durable and audited (actor) on the postgres tier.
+     *  The same path as the inspect `/toggle` endpoint; typed Config values are refused. */
+    readonly toggle: (input: FlagToggleInput) => Effect.Effect<FlagToggleReceipt, FlagToggleRefused>;
+}
+
+/** The minimal subject shape evaluation needs (avoids a hard `Subject` dep). */
+/**
+ * The subject shape the flag guards read. Deliberately LOOSER than the
+ * framework `Subject` so a bare `{ tenantId }` works in a test — but it has to
+ * be a genuine supertype, and every optional therefore spells `| undefined`
+ * explicitly. Under `exactOptionalPropertyTypes` (which this repo enables)
+ * `id?: string | null` means "absent or string-or-null" and REJECTS an
+ * explicit `undefined`, so a real `Subject` — whose fields are `?: T |
+ * undefined` — did not satisfy it. That is what made `requireFlag(ctx, …)`
+ * refuse the very `AppContext` its doc comment promises to accept.
+ */
+declare interface FlagSubject {
+    readonly id?: string | null | undefined;
+    readonly type?: string | undefined;
+    readonly tenantId?: string | null | undefined;
+    /**
+     * READONLY index signature, not `Record<string, unknown>`.
+     *
+     * The framework's `Subject.metadata` is `{ readonly [x: string]: unknown }`,
+     * and a readonly index signature is not assignable to a mutable one — so the
+     * mutable form made `requireFlag(ctx, …)` reject the very `AppContext` its
+     * own doc comment promises to accept ("the framework `AppContext`
+     * (`ctx.request.subject`)"). The shipped `api-feature-flags` template failed
+     * to typecheck on exactly that line while its tests passed, because
+     * `voltro test` transpiles without checking.
+     */
+    readonly metadata?: {
+        readonly [key: string]: unknown;
+    } | null | undefined;
+}
+
+/** One targeting rule — ANDs its conditions; a flag's `targeting` is an OR of rules. */
+declare interface FlagTargetingRule {
+    /** Match specific subject ids. */
+    readonly subjectIds?: ReadonlyArray<string>;
+    /** Match specific tenant ids. */
+    readonly tenantIds?: ReadonlyArray<string>;
+    /** Match `subject.type` (user / apiKey / serviceAccount / anonymous). */
+    readonly subjectTypes?: ReadonlyArray<string>;
+    /** Match `subject.metadata[key] === value` for every entry. */
+    readonly metadata?: Record<string, string>;
+}
+
+declare interface FlagToggleInput {
+    readonly key: string;
+    readonly enabled: boolean;
+    readonly actor?: string | null;
+}
+
+declare interface FlagToggleReceipt {
+    readonly key: string;
+    readonly enabled: boolean;
+    readonly previous: boolean;
+}
+
+/** A refused kill-switch flip: unknown key, a typed Config value (it has its own writer),
+ *  a store that is not bound yet, or a write whose commit could not be confirmed. */
+declare class FlagToggleRefused extends FlagToggleRefused_base {
+}
+
+declare const FlagToggleRefused_base: Schema.Class<FlagToggleRefused, Schema.TaggedStruct<"FlagToggleRefused", {
+    readonly key: Schema.String;
+    readonly reason: Schema.Literals<readonly ["unknown_flag", "config_value", "not_ready", "unconfirmed"]>;
+}>, YieldableError>;
+
+/** A flag value as authored: bare boolean (kill-switch) OR a rich definition. */
+declare type FlagValue = boolean | FlagDefinition;
+
+/** One multivariate variant: a named value with an optional rollout weight. */
+declare interface FlagVariant {
+    /** Stable variant name (the resolution returns this). */
+    readonly name: string;
+    /** The value served for this variant (string / number / boolean / JSON). */
+    readonly value: FlagVariantValue;
+    /** Relative allocation weight. Omit ⇒ equal split of the remaining weight.
+     *  Weights are normalised, so `[3, 1]` is 75% / 25%. */
+    readonly weight?: number;
+}
+
+/** A concrete variant value — string / number / boolean / JSON. Kept browser-safe. */
+declare type FlagVariantValue = string | number | boolean | null | ReadonlyArray<unknown> | Record<string, unknown>;
+
+/**
+ * A flag with a value type.
+ *
+ * `out A` is load-bearing rather than decorative: the plugin holds these in one
+ * `ReadonlyArray<TypedFlag<unknown>>`, which is only sound while every member
+ * that mentions `A` is a read position. If you add a field that CONSUMES an `A`
+ * (a `(value: A) => …` callback, say), that annotation is what will stop you —
+ * and the fix is to erase it behind a function returning a result, the way
+ * `decode` already does, not to drop the annotation.
+ */
+declare interface TypedFlag<out A> {
+    /** Brand — lets the plugin discriminate a typed flag from a bare `FlagValue`. */
+    readonly _voltroTypedFlag: true;
+    /** The flag key. Shares the flag namespace with `flags: { … }` entries; a
+     *  duplicate is refused at plugin construction. */
+    readonly key: string;
+    /** Human label of the value Schema (`number`, `"a" | "b"`, …) — for the
+     *  dashboard panel and for the refusal message when an override fails to
+     *  decode. Derived from the Schema's AST, so it cannot drift from it. */
+    readonly valueType: string;
+    /** The value served whenever the flag does not resolve to a variant: it is
+     *  off for this caller, or it declares no variants at all. Compile-checked
+     *  against the Schema. */
+    readonly defaultValue: A;
+    /** The value arms. Empty ⇒ the flag always serves `defaultValue` (which the
+     *  lifecycle report classifies as `constantOn`/`constantOff` — a flag that
+     *  cannot serve anything else is one to delete). */
+    readonly variants: ReadonlyArray<TypedFlagVariant<A>>;
+    /** Decode an untrusted value against the flag's Schema — the runtime half of
+     *  the contract `default` gets at compile time. */
+    readonly decode: (input: unknown) => FlagDecodeResult<A>;
+    /** The evaluator-facing definition. This is what goes into the registry the
+     *  existing `evaluateFlag` / `resolveVariant` already read; nothing about
+     *  evaluation changes because a flag is typed. */
+    readonly definition: FlagDefinition;
+    /**
+     * IN-11 — the `defineExperiment` this flag's variants report uplift for.
+     *
+     * A NAME rather than the definition object, on purpose: `defineExperiment`
+     * lives in `@voltro/runtime`, which is server-only, and this module has to
+     * stay loadable in a browser bundle. The link is validated at BOOT, where
+     * both sides are known (`assertFlagExperimentLinkage`) — a flag naming an
+     * experiment that does not exist, or whose arms disagree with the flag's,
+     * refuses to start rather than reporting uplift for arms nobody is served.
+     */
+    readonly experiment?: string;
+}
+
+/** One named arm of a typed flag. `value` is checked against the flag's Schema
+ *  at COMPILE time. Weights behave exactly as `FlagVariant.weight`. */
+declare interface TypedFlagVariant<out A> {
+    readonly name: string;
+    readonly value: A;
+    /** Relative allocation weight. Omit ⇒ equal split. */
+    readonly weight?: number;
+}
+
+export { }

package/dist/config-testing.js

@@ -0,0 +1,114 @@
+import { configError as e, defineConfig as t } from "./config.js";
+import { ConfigPort as n, defaultConfigResolver as r } from "./config-port.js";
+import { flagsPlugin as i } from "./index.js";
+import { Effect as a, Layer as o, Schema as s } from "effect";
+//#region src/configTesting.ts
+var c = {
+	app: {
+		name: "config-fixture",
+		type: "api",
+		voltroVersion: "0.83.1"
+	},
+	env: {},
+	config: {},
+	logger: {
+		info() {},
+		warn() {},
+		error() {},
+		debug() {}
+	}
+}, l = () => t({
+	"xp.multiplier": {
+		schema: s.Number,
+		default: 1,
+		min: .5,
+		max: 5,
+		public: !0,
+		variants: [{
+			name: "weekend",
+			value: 2
+		}]
+	},
+	"arena.maxPlayers": {
+		schema: s.Int,
+		default: 32,
+		min: 1,
+		max: 256,
+		restartRequired: "room"
+	},
+	"shop.featured": {
+		schema: s.Array(s.String),
+		default: ["fixture.skin"],
+		public: !0,
+		restartRequired: "live"
+	}
+}), u = a.tryPromise({
+	try: async () => {
+		let e = l(), t = i({
+			flags: { chat: !0 },
+			config: e
+		});
+		return await a.runPromise(t.onActivate(c)), {
+			catalog: e,
+			plugin: t,
+			service: t.config(),
+			close: a.suspend(() => t.onDeactivate(c)).pipe(a.orDie)
+		};
+	},
+	catch: () => e("unavailable")
+}), d = o.effect(n, a.acquireRelease(u, (e) => e.close).pipe(a.map((e) => e.service))), f = Object.freeze({
+	kind: "port",
+	tag: n,
+	fakeLayer: d,
+	probe: {
+		run: () => a.scoped(a.gen(function* () {
+			let e = yield* n, t = {
+				id: "owner",
+				tenantId: "tenant",
+				type: "user"
+			};
+			return {
+				value: yield* e.get("xp.multiplier", t),
+				mine: yield* e.mine(t),
+				room: yield* e.snapshot(t, "room"),
+				live: yield* e.snapshot(t, "live")
+			};
+		}).pipe(a.provide(d))),
+		expected: {
+			value: 2,
+			mine: {
+				"xp.multiplier": 2,
+				"shop.featured": ["fixture.skin"]
+			},
+			room: {
+				"xp.multiplier": 2,
+				"arena.maxPlayers": 32
+			},
+			live: { "shop.featured": ["fixture.skin"] }
+		}
+	}
+}), p = () => {
+	let e = l().entries["xp.multiplier"];
+	return {
+		entry: e,
+		value: e.flag.definition,
+		subject: {
+			id: "owner",
+			tenantId: "tenant"
+		},
+		now: 1e3
+	};
+}, m = Object.freeze({
+	kind: "slot",
+	defaultImplementation: r,
+	defaultProbe: {
+		run: () => a.sync(() => r(p())),
+		expected: 2
+	},
+	overrideProbe: {
+		run: () => a.sync(() => (() => 3)(p())),
+		expected: 3
+	}
+});
+//#endregion
+export { l as configCatalogFixture, d as configFakeLayer, c as configFixtureLifecycle, u as configPortFixture, f as configPortSystemFixture, m as configResolverSystemFixture };