@zenxdigitalholdings/zenflags 0.2.0 → 0.2.1

package/dist/evaluator.js

@@ -18,14 +18,17 @@ class Evaluator {
         const key = (0, spec_1.specKey)(spec);
         try {
             const res = await this.provider.evaluate(spec, rc);
+            // The flag is protected if the caller declared it OR the server did — so
+            // a central PROTECTED marking is honoured even if a call site forgot it.
+            const isProtected = !!spec.protected || !!res.protected;
             if (!(0, state_1.isValidState)(res.state)) {
-                return new decision_1.Decision(key, 'DISABLED_HARD', !!spec.protected, '', false, `invalid state "${res.state}" -> DISABLED_HARD`, new Error('invalid state'));
+                return new decision_1.Decision(key, 'DISABLED_HARD', isProtected, '', false, `invalid state "${res.state}" -> DISABLED_HARD`, new Error('invalid state'));
             }
             if (res.state === 'DRAIN') {
                 const ramped = (0, ramp_1.inRamp)(key, rc.entityId ?? '', res.rampPercent ?? 0);
-                return new decision_1.Decision(key, 'DRAIN', !!spec.protected, res.variant ?? '', ramped, `DRAIN ${res.rampPercent ?? 0}%: inRamp=${ramped}`);
+                return new decision_1.Decision(key, 'DRAIN', isProtected, res.variant ?? '', ramped, `DRAIN ${res.rampPercent ?? 0}%: inRamp=${ramped}`);
             }
-            return new decision_1.Decision(key, res.state, !!spec.protected, res.variant ?? '', false, res.reason ?? '');
+            return new decision_1.Decision(key, res.state, isProtected, res.variant ?? '', false, res.reason ?? '');
         }
         catch (err) {
             if (spec.protected) {

package/dist/provider.d.ts

@@ -7,6 +7,8 @@ export interface EvalResult {
     rampPercent?: number;
     variant?: string;
     reason?: string;
+    /** Server-declared PROTECTED class — the SDK OR's this with Spec.protected. */
+    protected?: boolean;
 }
 /** Pluggable flag backend. FliptProvider is production; MemoryProvider backs tests. */
 export interface Provider {

package/dist/zen.js

@@ -41,7 +41,7 @@ class ZenProvider {
             if (!res.ok)
                 throw new Error(`zen flags: status ${res.status}`);
             const out = (await res.json());
-            return { state: out.state, rampPercent: out.rampPercent, reason: out.reason };
+            return { state: out.state, rampPercent: out.rampPercent, reason: out.reason, protected: out.protected };
         }
         finally {
             clearTimeout(timer);
@@ -66,7 +66,8 @@ class CachedZenProvider {
         this.etag = '';
         this.timer = null;
         this.stopped = false;
-        this.intervalMs = opts.refreshMs ?? 5000;
+        // Guard against a non-positive interval, which would busy-poll the server.
+        this.intervalMs = opts.refreshMs && opts.refreshMs > 0 ? opts.refreshMs : 5000;
         this.maxStaleMs = opts.maxStaleMs ?? 5 * 60_000;
         this.zen = new ZenProvider(opts);
         this.readyPromise = new Promise((resolve) => {
@@ -82,8 +83,12 @@ class CachedZenProvider {
      * fall back until it recovers.
      */
     ready(timeoutMs) {
-        if (!timeoutMs)
+        // Only an unspecified timeout waits indefinitely. An explicit 0 (or
+        // negative) means "don't block boot" and resolves false immediately.
+        if (timeoutMs === undefined)
             return this.readyPromise.then(() => true);
+        if (timeoutMs <= 0)
+            return Promise.resolve(false);
         return Promise.race([
             this.readyPromise.then(() => true),
             new Promise((r) => setTimeout(() => r(false), timeoutMs)),
@@ -101,11 +106,16 @@ class CachedZenProvider {
             this.timer.unref();
     }
     async refresh() {
+        // Bound the request: without this, a hung connection stalls the whole
+        // refresh loop (the next poll is chained off this one) until the snapshot
+        // crosses maxStale and every flag fails closed.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 4000);
         try {
             const headers = { authorization: `Bearer ${this.zen.apiKey}` };
             if (this.etag)
                 headers['if-none-match'] = this.etag;
-            const res = await fetch(`${this.zen.baseURL}/v1/snapshot`, { headers });
+            const res = await fetch(`${this.zen.baseURL}/v1/snapshot`, { headers, signal: controller.signal });
             if (res.status === 304) {
                 this.fetchedAt = Date.now(); // unchanged — refresh the staleness clock
                 this.markReady();
@@ -116,7 +126,7 @@ class CachedZenProvider {
             const out = (await res.json());
             const next = new Map();
             for (const f of out.flags ?? []) {
-                next.set(f.key, { state: f.state, rampPercent: f.rampPercent, reason: 'snapshot' });
+                next.set(f.key, { state: f.state, rampPercent: f.rampPercent, protected: f.protected, reason: 'snapshot' });
             }
             this.snapshot = next;
             this.fetchedAt = Date.now();
@@ -126,15 +136,22 @@ class CachedZenProvider {
         catch {
             /* keep last snapshot; staleness guard below handles prolonged outages */
         }
+        finally {
+            clearTimeout(timer);
+        }
     }
     async evaluate(spec, _rc) {
+        const entry = this.snapshot?.get((0, spec_1.specKey)(spec));
         if (!this.snapshot || Date.now() - this.fetchedAt > this.maxStaleMs) {
+            // Beyond maxStale the snapshot's values are no longer trusted. But if the
+            // last good snapshot marked this flag PROTECTED, fail it closed here
+            // rather than leaving it to a caller-supplied (possibly open) fallback.
+            if (entry?.protected || spec.protected) {
+                return { state: 'DISABLED_HARD', protected: true, reason: 'stale snapshot, protected -> fail closed' };
+            }
             throw new Error('zen flags: snapshot unavailable or stale');
         }
-        return (this.snapshot.get((0, spec_1.specKey)(spec)) ?? {
-            state: 'DISABLED_HARD',
-            reason: 'unknown flag -> baseline',
-        });
+        return entry ?? { state: 'DISABLED_HARD', reason: 'unknown flag -> baseline' };
     }
     async close() {
         this.stopped = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenxdigitalholdings/zenflags",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Zen Flags SDK \u2014 feature flags for Zen products, evaluated in-process from the Zen flags server.",
   "license": "UNLICENSED",
   "type": "commonjs",