@adonis-agora/flags 0.0.0-beta-20261112141227

package/dist/src/relay/results_cache.js

@@ -0,0 +1,31 @@
+import { jsonValue, parseJson, query } from '../sql.js';
+export class MemoryResultsCache {
+    #map = new Map();
+    async get(environment, experiment) {
+        return this.#map.get(`${environment}\u0000${experiment}`) ?? null;
+    }
+    async set(environment, experiment, results) {
+        this.#map.set(`${environment}\u0000${experiment}`, results);
+    }
+}
+/** `flags_results`, shared by every replica. */
+export class LucidResultsCache {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async get(environment, experiment) {
+        const rows = await query(this.db, 'SELECT payload FROM flags_results WHERE environment = ? AND experiment = ?', [environment, experiment]);
+        return rows[0] ? parseJson(rows[0].payload) : null;
+    }
+    async set(environment, experiment, results) {
+        await this.db.transaction(async (trx) => {
+            await trx.rawQuery('DELETE FROM flags_results WHERE environment = ? AND experiment = ?', [
+                environment,
+                experiment,
+            ]);
+            await trx.rawQuery('INSERT INTO flags_results (environment, experiment, payload, computed_at) VALUES (?, ?, ?, ?)', [environment, experiment, jsonValue(results), Date.now()]);
+        });
+    }
+}
+//# sourceMappingURL=results_cache.js.map

package/dist/src/relay/results_cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results_cache.js","sourceRoot":"","sources":["../../../src/relay/results_cache.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAoB,MAAM,WAAW,CAAC;AAQ1E,MAAM,OAAO,kBAAkB;IAC7B,IAAI,GAAG,IAAI,GAAG,EAA6B,CAAC;IAC5C,KAAK,CAAC,GAAG,CAAC,WAAmB,EAAE,UAAkB;QAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,SAAS,UAAU,EAAE,CAAC,IAAI,IAAI,CAAC;IACpE,CAAC;IACD,KAAK,CAAC,GAAG,CAAC,WAAmB,EAAE,UAAkB,EAAE,OAA0B;QAC3E,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,SAAS,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,gDAAgD;AAChD,MAAM,OAAO,iBAAiB;IACC,EAAE;IAA/B,YAA6B,EAAe;kBAAf,EAAE;IAAgB,CAAC;IAEhD,KAAK,CAAC,GAAG,CAAC,WAAmB,EAAE,UAAkB;QAC/C,MAAM,IAAI,GAAG,MAAM,KAAK,CACtB,IAAI,CAAC,EAAE,EACP,4EAA4E,EAC5E,CAAC,WAAW,EAAE,UAAU,CAAC,CAC1B,CAAC;QACF,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAoB,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,WAAmB,EAAE,UAAkB,EAAE,OAA0B;QAC3E,MAAM,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;YACtC,MAAM,GAAG,CAAC,QAAQ,CAAC,oEAAoE,EAAE;gBACvF,WAAW;gBACX,UAAU;aACX,CAAC,CAAC;YACH,MAAM,GAAG,CAAC,QAAQ,CAChB,+FAA+F,EAC/F,CAAC,WAAW,EAAE,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAC1D,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/src/relay/worker.d.ts

@@ -0,0 +1,66 @@
+import type { FlagsAdmin } from '../admin.js';
+import type { AnalyticsBackend } from '../analytics/backend.js';
+import type { MetricDefinition } from '../analytics/metrics.js';
+import { type ExperimentResults } from '../analytics/results.js';
+import type { ExperimentConfig } from '../define_config.js';
+import type { RulesetSource } from '../ruleset_source.js';
+import type { SqlClient } from '../sql.js';
+import type { Transport } from '../transports/transport.js';
+import type { Relay } from './relay.js';
+import type { ResultsCache } from './results_cache.js';
+export interface WorkerOptions {
+    relay?: Relay;
+    /** Default drain interval per sink (ms). */
+    relayIntervalMs?: number;
+    admin?: FlagsAdmin;
+    source: RulesetSource;
+    /** The environment this process reads (results default to it). */
+    environment?: string;
+    /** Environments whose experiment results the worker recomputes. Default: `[environment]`. */
+    resultsEnvironments?: string[];
+    analytics?: AnalyticsBackend;
+    resultsCache?: ResultsCache;
+    metrics?: Record<string, MetricDefinition>;
+    experiments?: Record<string, ExperimentConfig>;
+    resultsIntervalMs?: number;
+    transport?: Transport;
+    /** The db transport's client, for partition maintenance and pruning. */
+    eventsDb?: SqlClient;
+    retentionDays?: number;
+    logger?: {
+        info?(message: string): void;
+        warn(message: string): void;
+        error(message: string): void;
+    };
+}
+export type TaskName = 'relay' | 'schedules' | 'results' | 'maintenance';
+/**
+ * The background work of a flags deployment: relaying events to sinks, executing scheduled changes,
+ * recomputing experiment results, and maintaining the event log. Every task is safe to run on many
+ * replicas at once (leases, schedule claims, idempotent writes), so where it runs is a deployment
+ * choice (`role` / `dispatcher`), not a correctness one.
+ */
+export declare class FlagsWorker {
+    #private;
+    readonly options: WorkerOptions;
+    constructor(options: WorkerOptions);
+    /** Runs whatever is due. In-process mode calls this every second. */
+    tick(now?: number): Promise<void>;
+    /** Runs every task once, regardless of schedule (`flags:work --once`). */
+    runAll(): Promise<void>;
+    relaySink(name: string): Promise<import("./relay.js").DrainResult | undefined>;
+    runSchedules(): Promise<{
+        id: string;
+        ok: boolean;
+        error?: string;
+    }[]>;
+    /** Recomputes and caches results for every configured experiment. */
+    computeAllResults(): Promise<ExperimentResults[]>;
+    /** Computes and caches one experiment's results for an environment (default: this process's). */
+    computeResults(key: string, environment?: string): Promise<ExperimentResults | null>;
+    maintenance(): Promise<void>;
+    /** In-process scheduling: a 1s timer that runs what is due. */
+    start(): void;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=worker.d.ts.map

package/dist/src/relay/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/relay/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6FAA6F;IAC7F,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B,CAAC;CACH;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,aAAa,CAAC;AAEzE;;;;;GAKG;AACH,qBAAa,WAAW;;IAKV,QAAQ,CAAC,OAAO,EAAE,aAAa;IAA3C,YAAqB,OAAO,EAAE,aAAa,EAAI;IAU/C,qEAAqE;IAC/D,IAAI,CAAC,GAAG,SAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAkB1C;IAED,0EAA0E;IACpE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAK5B;IAEK,SAAS,CAAC,IAAI,EAAE,MAAM,yDAS3B;IAEK,YAAY;;;;SAYjB;IAED,qEAAqE;IAC/D,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkBtD;IAMD,iGAAiG;IAC3F,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,WAAW,SAAoB,GAC9B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA2CnC;IAEK,WAAW,kBAYhB;IAED,+DAA+D;IAC/D,KAAK,SAGJ;IAEK,IAAI,kBAKT;CACF"}

package/dist/src/relay/worker.js

@@ -0,0 +1,177 @@
+import { computeResults } from '../analytics/results.js';
+import { ensureEventPartitions, pruneEvents } from '../schema.js';
+/**
+ * The background work of a flags deployment: relaying events to sinks, executing scheduled changes,
+ * recomputing experiment results, and maintaining the event log. Every task is safe to run on many
+ * replicas at once (leases, schedule claims, idempotent writes), so where it runs is a deployment
+ * choice (`role` / `dispatcher`), not a correctness one.
+ */
+export class FlagsWorker {
+    options;
+    #timer;
+    #nextRun = new Map();
+    #running = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Due-ness check for in-process scheduling. */
+    #due(key, intervalMs, now) {
+        const next = this.#nextRun.get(key) ?? 0;
+        if (now < next)
+            return false;
+        this.#nextRun.set(key, now + intervalMs);
+        return true;
+    }
+    /** Runs whatever is due. In-process mode calls this every second. */
+    async tick(now = Date.now()) {
+        if (this.#running)
+            return;
+        this.#running = true;
+        try {
+            const relay = this.options.relay;
+            if (relay) {
+                for (const name of relay.sinkNames) {
+                    const interval = relay.sink(name)?.intervalMs ?? this.options.relayIntervalMs ?? 5000;
+                    if (this.#due(`relay:${name}`, interval, now))
+                        await this.relaySink(name);
+                }
+            }
+            if (this.options.admin && this.#due('schedules', 15_000, now))
+                await this.runSchedules();
+            if (this.#due('results', this.options.resultsIntervalMs ?? 600_000, now))
+                await this.computeAllResults();
+            if (this.#due('maintenance', 3_600_000, now))
+                await this.maintenance();
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+    /** Runs every task once, regardless of schedule (`flags:work --once`). */
+    async runAll() {
+        for (const name of this.options.relay?.sinkNames ?? [])
+            await this.relaySink(name);
+        await this.runSchedules();
+        await this.computeAllResults();
+        await this.maintenance();
+    }
+    async relaySink(name) {
+        try {
+            const result = await this.options.relay.drain(name);
+            if (result.error)
+                this.options.logger?.warn(`[flags] sink "${name}" failed: ${result.error}`);
+            return result;
+        }
+        catch (error) {
+            this.options.logger?.error(`[flags] relay to "${name}" crashed: ${error.message}`);
+            return undefined;
+        }
+    }
+    async runSchedules() {
+        if (!this.options.admin)
+            return [];
+        try {
+            const results = await this.options.admin.runDueSchedules();
+            for (const r of results) {
+                if (!r.ok)
+                    this.options.logger?.warn(`[flags] scheduled change ${r.id} failed: ${r.error}`);
+            }
+            return results;
+        }
+        catch (error) {
+            this.options.logger?.error(`[flags] schedules crashed: ${error.message}`);
+            return [];
+        }
+    }
+    /** Recomputes and caches results for every configured experiment. */
+    async computeAllResults() {
+        const { analytics, resultsCache, experiments } = this.options;
+        if (!analytics || !resultsCache || !experiments)
+            return [];
+        const out = [];
+        const environments = this.options.resultsEnvironments ?? [this.#environment];
+        for (const environment of environments) {
+            for (const key of Object.keys(experiments)) {
+                try {
+                    const result = await this.computeResults(key, environment);
+                    if (result)
+                        out.push(result);
+                }
+                catch (error) {
+                    this.options.logger?.error(`[flags] results for "${key}" (${environment}) failed: ${error.message}`);
+                }
+            }
+        }
+        return out;
+    }
+    get #environment() {
+        return this.options.environment ?? 'production';
+    }
+    /** Computes and caches one experiment's results for an environment (default: this process's). */
+    async computeResults(key, environment = this.#environment) {
+        const { analytics, resultsCache, experiments, metrics = {} } = this.options;
+        const experiment = experiments?.[key];
+        if (!analytics || !resultsCache || !experiment)
+            return null;
+        const flagKey = experiment.flag ?? key;
+        const ruleset = environment === this.#environment || !this.options.admin
+            ? this.options.source.current()
+            : await this.options.admin.store.readRuleset(environment);
+        const definitions = {};
+        for (const name of new Set([...experiment.metrics, ...(experiment.guardrails ?? [])])) {
+            const definition = metrics[name];
+            if (!definition)
+                throw new Error(`experiment "${key}" uses unknown metric "${name}"`);
+            definitions[name] = definition;
+        }
+        const previous = (await resultsCache.get(environment, key)) ?? undefined;
+        const result = await computeResults(analytics, {
+            key,
+            flag: flagKey,
+            environment,
+            metrics: definitions,
+            ...(experiment.guardrails ? { guardrails: experiment.guardrails } : {}),
+            ...(experiment.control ? { control: experiment.control } : {}),
+            ...(experiment.confidence ? { confidence: experiment.confidence } : {}),
+        }, ruleset.flags[flagKey], previous);
+        await resultsCache.set(environment, key, result);
+        for (const metric of result.metrics) {
+            if (metric.alert)
+                this.options.logger?.warn(`[flags] guardrail "${metric.name}" regressed in experiment "${key}"`);
+        }
+        if (result.srm?.mismatch) {
+            this.options.logger?.warn(`[flags] experiment "${key}" has a sample ratio mismatch (p=${result.srm.pValue.toExponential(2)})`);
+        }
+        return result;
+    }
+    async maintenance() {
+        const db = this.options.eventsDb;
+        if (!db)
+            return;
+        try {
+            await ensureEventPartitions(db, Date.now());
+            const sinks = this.options.relay?.sinkNames ?? [];
+            const safeId = (await this.options.transport?.safePruneId?.(sinks)) ?? 0;
+            const before = Date.now() - (this.options.retentionDays ?? 30) * 86_400_000;
+            if (safeId > 0)
+                await pruneEvents(db, before, safeId);
+        }
+        catch (error) {
+            this.options.logger?.error(`[flags] maintenance failed: ${error.message}`);
+        }
+    }
+    /** In-process scheduling: a 1s timer that runs what is due. */
+    start() {
+        this.#timer ??= setInterval(() => void this.tick(), 1000);
+        this.#timer.unref();
+    }
+    async stop() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = undefined;
+        // Let a tick in progress finish.
+        while (this.#running)
+            await new Promise((resolve) => setTimeout(resolve, 20));
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/src/relay/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/relay/worker.ts"],"names":[],"mappings":"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"}

package/dist/src/ruleset_source.d.ts

@@ -0,0 +1,73 @@
+import { type Ruleset } from '@adonis-agora/flags-core';
+import type { FlagsStore } from './stores/store.js';
+export interface SourceStatus {
+    version: string;
+    loadedAt: Date | null;
+    lastError: string | null;
+    /** Serving a ruleset loaded before the latest failure (last known good). */
+    stale: boolean;
+    /** How the source learns about changes right now. */
+    mode: 'notify' | 'poll' | 'stream';
+}
+/**
+ * Where a process gets its ruleset. Every implementation keeps the last ruleset it loaded and serves
+ * it when the backing store or the control-plane is unreachable — evaluation never waits on I/O.
+ */
+export interface RulesetSource {
+    start(): Promise<void>;
+    current(): Ruleset;
+    /** Reloads if the version moved. Resolves `true` when a new ruleset was loaded. */
+    refresh(): Promise<boolean>;
+    onChange(listener: (ruleset: Ruleset) => void): () => void;
+    status(): SourceStatus;
+    stop(): Promise<void>;
+}
+declare abstract class BaseSource implements RulesetSource {
+    #private;
+    protected ruleset: Ruleset;
+    protected loadedAt: Date | null;
+    protected lastError: string | null;
+    abstract start(): Promise<void>;
+    abstract refresh(): Promise<boolean>;
+    abstract stop(): Promise<void>;
+    abstract status(): SourceStatus;
+    current(): Ruleset;
+    onChange(listener: (ruleset: Ruleset) => void): () => void;
+    protected set(ruleset: Ruleset): void;
+}
+/** A ruleset the app sets by hand (tests, `flags.fake()`, static configs). */
+export declare class StaticSource extends BaseSource {
+    constructor(ruleset?: Ruleset);
+    start(): Promise<void>;
+    refresh(): Promise<boolean>;
+    stop(): Promise<void>;
+    replace(ruleset: Ruleset): void;
+    status(): SourceStatus;
+}
+export interface StoreSourceOptions {
+    environment: string;
+    /** Version poll interval (ms). Default 5000; the fallback when notifications are unavailable. */
+    intervalMs?: number;
+    /**
+     * Subscribe to change notifications (Postgres `LISTEN`) for near-instant propagation. Holds one
+     * pool connection per process. Default `true` when the store supports it.
+     */
+    notify?: boolean;
+    onError?: (error: unknown) => void;
+}
+/** Store-backed source for `standalone` and `control-plane` processes. */
+export declare class StoreSource extends BaseSource {
+    #private;
+    private readonly store;
+    private readonly options;
+    constructor(store: FlagsStore & {
+        listen?(onMessage: (payload: string) => void): Promise<() => Promise<void>>;
+        canListen?: boolean;
+    }, options: StoreSourceOptions);
+    start(): Promise<void>;
+    refresh(): Promise<boolean>;
+    status(): SourceStatus;
+    stop(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=ruleset_source.d.ts.map

package/dist/src/ruleset_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset_source.d.ts","sourceRoot":"","sources":["../../src/ruleset_source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;IACf,qDAAqD;IACrD,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,OAAO,CAAC;IACnB,mFAAmF;IACnF,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,MAAM,IAAI,YAAY,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,uBAAe,UAAW,YAAW,aAAa;;IAChD,SAAS,CAAC,OAAO,EAAE,OAAO,CAAqB;IAC/C,SAAS,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAQ;IACvC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAG1C,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,MAAM,IAAI,YAAY,CAAC;IAEhC,OAAO,IAAI,OAAO,CAEjB;IAED,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAGzD;IAED,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,QAW7B;CACF;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,UAAU;IAC1C,YAAY,OAAO,GAAE,OAA2B,EAI/C;IAEK,KAAK,kBAAK;IACV,OAAO,qBAEZ;IACK,IAAI,kBAAK;IACf,OAAO,CAAC,OAAO,EAAE,OAAO,QAEvB;IACD,MAAM,IAAI,YAAY,CAQrB;CACF;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED,0EAA0E;AAC1E,qBAAa,WAAY,SAAQ,UAAU;;IAMvC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAItB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,YACmB,KAAK,EAAE,UAAU,GAAG;QACnC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,EACgB,OAAO,EAAE,kBAAkB,EAG7C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAiB3B;IAED,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAK1B;IAsBD,MAAM,IAAI,YAAY,CAQrB;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1B;CACF"}

package/dist/src/ruleset_source.js

@@ -0,0 +1,128 @@
+import { emptyRuleset } from '@adonis-agora/flags-core';
+class BaseSource {
+    ruleset = emptyRuleset('0');
+    loadedAt = null;
+    lastError = null;
+    #listeners = new Set();
+    current() {
+        return this.ruleset;
+    }
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    set(ruleset) {
+        this.ruleset = ruleset;
+        this.loadedAt = new Date();
+        this.lastError = null;
+        for (const listener of this.#listeners) {
+            try {
+                listener(ruleset);
+            }
+            catch {
+                // A listener must never break reloading.
+            }
+        }
+    }
+}
+/** A ruleset the app sets by hand (tests, `flags.fake()`, static configs). */
+export class StaticSource extends BaseSource {
+    constructor(ruleset = emptyRuleset('0')) {
+        super();
+        this.ruleset = ruleset;
+        this.loadedAt = new Date();
+    }
+    async start() { }
+    async refresh() {
+        return false;
+    }
+    async stop() { }
+    replace(ruleset) {
+        this.set(ruleset);
+    }
+    status() {
+        return {
+            version: this.ruleset.version,
+            loadedAt: this.loadedAt,
+            lastError: null,
+            stale: false,
+            mode: 'poll',
+        };
+    }
+}
+/** Store-backed source for `standalone` and `control-plane` processes. */
+export class StoreSource extends BaseSource {
+    store;
+    options;
+    #timer;
+    #unlisten;
+    #refreshing;
+    constructor(store, options) {
+        super();
+        this.store = store;
+        this.options = options;
+    }
+    async start() {
+        try {
+            this.set(await this.store.readRuleset(this.options.environment));
+        }
+        catch (error) {
+            this.#fail(error);
+        }
+        if (this.options.notify !== false && this.store.listen && this.store.canListen !== false) {
+            try {
+                this.#unlisten = await this.store.listen((payload) => {
+                    if (payload.startsWith(`${this.options.environment}:`))
+                        void this.refresh();
+                });
+            }
+            catch (error) {
+                this.#fail(error);
+            }
+        }
+        this.#timer = setInterval(() => void this.refresh(), this.options.intervalMs ?? 5000);
+        this.#timer.unref();
+    }
+    refresh() {
+        this.#refreshing ??= this.#refresh().finally(() => {
+            this.#refreshing = undefined;
+        });
+        return this.#refreshing;
+    }
+    async #refresh() {
+        try {
+            const version = await this.store.version(this.options.environment);
+            if (version === this.ruleset.version && this.loadedAt) {
+                this.lastError = null;
+                return false;
+            }
+            this.set(await this.store.readRuleset(this.options.environment));
+            return true;
+        }
+        catch (error) {
+            this.#fail(error);
+            return false;
+        }
+    }
+    #fail(error) {
+        this.lastError = error instanceof Error ? error.message : String(error);
+        this.options.onError?.(error);
+    }
+    status() {
+        return {
+            version: this.ruleset.version,
+            loadedAt: this.loadedAt,
+            lastError: this.lastError,
+            stale: this.lastError !== null && this.loadedAt !== null,
+            mode: this.#unlisten ? 'notify' : 'poll',
+        };
+    }
+    async stop() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = undefined;
+        await this.#unlisten?.().catch(() => { });
+        this.#unlisten = undefined;
+    }
+}
+//# sourceMappingURL=ruleset_source.js.map

package/dist/src/ruleset_source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ruleset_source.js","sourceRoot":"","sources":["../../src/ruleset_source.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime.d.ts

@@ -0,0 +1,70 @@
+import { FlagsAdmin } from './admin.js';
+import type { AnalyticsBackend } from './analytics/backend.js';
+import type { FactoryContext, FlagsConfig } from './define_config.js';
+import { type Enricher } from './enrichers.js';
+import { EventBuffer } from './events/buffer.js';
+import type { BrowserTokens } from './http/browser_tokens.js';
+import { FlagsManager } from './manager.js';
+import { Relay } from './relay/relay.js';
+import { type ResultsCache } from './relay/results_cache.js';
+import { FlagsWorker } from './relay/worker.js';
+import { type RulesetSource } from './ruleset_source.js';
+import type { Sink } from './sinks/sink.js';
+import { type SqlDatabase } from './sql.js';
+import type { FlagsStore } from './stores/store.js';
+import { type TokenSource } from './topology/token.js';
+import type { Transport } from './transports/transport.js';
+import { UsageCounter } from './usage.js';
+export interface Logger {
+    info?(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export type Topology = 'standalone' | 'control-plane' | 'tenant';
+export type Role = 'all' | 'api' | 'worker';
+/** Everything a flags deployment is made of, built from `config/flags.ts`. */
+export interface FlagsRuntime {
+    config: FlagsConfig;
+    topology: Topology;
+    role: Role;
+    manager: FlagsManager;
+    source: RulesetSource;
+    admin?: FlagsAdmin;
+    store?: FlagsStore;
+    transport?: Transport;
+    sinks: Map<string, Sink>;
+    relay?: Relay;
+    analytics?: AnalyticsBackend;
+    resultsCache?: ResultsCache;
+    worker?: FlagsWorker;
+    buffer?: EventBuffer;
+    usage?: UsageCounter;
+    enrichers: Enricher[];
+    /** Tenant only: how it authenticates to the control-plane. */
+    token?: TokenSource;
+    /** Issues browser tokens, when `browser` is configured (set by the provider). */
+    browser?: BrowserTokens | undefined;
+    close(): Promise<void>;
+}
+export interface RuntimeOptions {
+    logger?: Logger;
+    /** Called after a ruleset change applied in this process (to notify browsers, etc.). */
+    onApplied?: (environment: string, version: string) => void;
+    /** Start timers (source polling, buffer, usage, in-process worker). Default `true`. */
+    start?: boolean;
+    /** Whether this process runs the in-process worker loop. Decided by the provider. */
+    runWorker?: boolean;
+    /**
+     * Hold a connection for Postgres `LISTEN` (instant ruleset changes). Default `true`; the provider
+     * turns it off in ace commands and the REPL: a held connection keeps Lucid from closing its
+     * pool, so `node ace migration:run` and friends would never exit.
+     */
+    listen?: boolean;
+}
+/** Builds (and starts) the runtime. Shared by the provider, the commands and the tests. */
+export declare function createRuntime(config: FlagsConfig, ctx: FactoryContext, options?: RuntimeOptions): Promise<FlagsRuntime>;
+/** A database for factories, from a Lucid `Database` (or anything with `connection()`). */
+export declare function lucidContext(db: {
+    connection(name?: string): SqlDatabase;
+} | undefined, options?: Partial<Pick<FactoryContext, 'autoCreateSchema' | 'partitionEvents' | 'redis' | 'app'>>): FactoryContext;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/src/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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"}