@ductape/sdk 0.1.129 → 0.1.130

package/dist/features/features.service.d.ts

@@ -76,6 +76,33 @@ export declare class FeatureService {
      * Get or create a ProductBuilder instance for the given product tag
      */
     private getProductBuilder;
+    /** Per-process guard so the one-time "cold cache" bulk warm (fetchFeatures()) only ever runs
+     *  once per product per process, even under concurrent define() calls for many features at
+     *  boot -- without this, N concurrent cache-miss defines would each independently trigger
+     *  their own redundant bulk fetch. */
+    private featureCacheWarmed;
+    private featureFingerprintCacheKey;
+    /**
+     * A stable, deterministic fingerprint of exactly the fields that define a feature's real
+     * content (the same field set IFeatureConfig already establishes as "what a feature
+     * definition consists of" -- see features.types.ts). Deliberately excludes `tag` (redundant
+     * with the cache key) and any server-added bookkeeping fields (`_id`, timestamps) a remote
+     * IProductFeature carries that a locally-compiled schema never has -- comparing those would
+     * make every fingerprint mismatch even when the real, meaningful content is unchanged.
+     */
+    private computeFeatureFingerprint;
+    private getCachedFeatureFingerprint;
+    private setCachedFeatureFingerprint;
+    /**
+     * Fetches every real feature currently persisted for `productTag` in ONE bulk remote call
+     * (`builder.fetchFeatures()`, already existing -- the same call Ductape's own Workbench uses)
+     * and warms the Redis fingerprint cache for all of them at once. Real answer to "if Redis is
+     * empty, fetch all existing features, then check if the defined feature is already there
+     * before recreating it" -- this runs at most ONCE per product per process (concurrent
+     * define() calls for different features share the same in-flight promise, never triggering
+     * their own separate bulk fetch).
+     */
+    private warmFeatureCache;
     /**
      * Initialize logging service
      */

package/dist/features/features.service.js

@@ -66,6 +66,22 @@ const console = {
     warn: globalThis.console.warn.bind(globalThis.console),
     error: globalThis.console.error.bind(globalThis.console),
 };
+/**
+ * Deterministic JSON stringify: object keys are sorted recursively so two structurally-equal
+ * values always produce byte-identical output regardless of real-world key insertion order
+ * (a remote-fetched feature and a freshly-compiled local schema can legitimately differ only
+ * in property order, never in meaning). Array ORDER is preserved -- unlike object keys, array
+ * order is semantically meaningful here (`steps` is an ordered execution sequence).
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+    const keys = Object.keys(value).sort();
+    const entries = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+    return `{${entries.join(',')}}`;
+}
 /**
  * Error class for feature-related errors
  */
@@ -119,6 +135,21 @@ class FeatureService {
         this.cacheManager = null;
         /** Local cache for cache configurations to avoid repeated API calls */
         this.cacheConfigCache = new Map();
+        // ==================== FEATURE-DEFINITION REDIS CACHE ====================
+        // define() previously did fetchFeature -> [fetchFeature + fetchEnv*N + updateProduct] ->
+        // fetchFeature on EVERY call, unconditionally, even when the feature's compiled schema was
+        // byte-for-byte identical to what was already persisted -- 5-6 real remote round-trips per
+        // feature, on every process boot, for features that never actually changed. At real
+        // application scale (dozens of features registered at startup) this turned every boot into a
+        // multi-minute serial remote-call chain. This cache closes that gap using the SAME Redis
+        // client already threaded through this service's own config (`config.redis_client`, already
+        // used by CacheManager above) -- degrades safely to "cache disabled, always hit the remote
+        // path" when no redis_client is configured, matching this class's existing pattern.
+        /** Per-process guard so the one-time "cold cache" bulk warm (fetchFeatures()) only ever runs
+         *  once per product per process, even under concurrent define() calls for many features at
+         *  boot -- without this, N concurrent cache-miss defines would each independently trigger
+         *  their own redundant bulk fetch. */
+        this.featureCacheWarmed = new Map();
         //console.log('[FeatureService] constructor', { hasConfig: !!config, env_type: config?.env_type, hasRedis: !!config?.redis_client });
         this.config = config || null;
         this._privateKey = (config === null || config === void 0 ? void 0 : config.private_key) || '';
@@ -224,6 +255,89 @@ class FeatureService {
         }
         return builder;
     }
+    featureFingerprintCacheKey(productTag, tag) {
+        return `ductape:feature-fingerprint:${productTag}:${tag}`;
+    }
+    /**
+     * A stable, deterministic fingerprint of exactly the fields that define a feature's real
+     * content (the same field set IFeatureConfig already establishes as "what a feature
+     * definition consists of" -- see features.types.ts). Deliberately excludes `tag` (redundant
+     * with the cache key) and any server-added bookkeeping fields (`_id`, timestamps) a remote
+     * IProductFeature carries that a locally-compiled schema never has -- comparing those would
+     * make every fingerprint mismatch even when the real, meaningful content is unchanged.
+     */
+    computeFeatureFingerprint(feature) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const comparable = {
+            name: feature.name,
+            description: (_a = feature.description) !== null && _a !== void 0 ? _a : null,
+            input: (_b = feature.input) !== null && _b !== void 0 ? _b : null,
+            output: (_c = feature.output) !== null && _c !== void 0 ? _c : null,
+            steps: (_d = feature.steps) !== null && _d !== void 0 ? _d : [],
+            signals: (_e = feature.signals) !== null && _e !== void 0 ? _e : null,
+            queries: (_f = feature.queries) !== null && _f !== void 0 ? _f : null,
+            options: (_g = feature.options) !== null && _g !== void 0 ? _g : null,
+            envs: (_h = feature.envs) !== null && _h !== void 0 ? _h : null,
+        };
+        return (0, crypto_1.createHash)('sha256').update(stableStringify(comparable)).digest('hex');
+    }
+    async getCachedFeatureFingerprint(productTag, tag) {
+        var _a;
+        const redisClient = (_a = this.config) === null || _a === void 0 ? void 0 : _a.redis_client;
+        if (!redisClient)
+            return null;
+        try {
+            return await redisClient.get(this.featureFingerprintCacheKey(productTag, tag));
+        }
+        catch (error) {
+            console.log('[FeatureService] getCachedFeatureFingerprint failed (treating as cache miss)', { productTag, tag, error: error instanceof Error ? error.message : String(error) });
+            return null;
+        }
+    }
+    async setCachedFeatureFingerprint(productTag, tag, fingerprint) {
+        var _a;
+        const redisClient = (_a = this.config) === null || _a === void 0 ? void 0 : _a.redis_client;
+        if (!redisClient)
+            return;
+        try {
+            await redisClient.set(this.featureFingerprintCacheKey(productTag, tag), fingerprint);
+        }
+        catch (error) {
+            // A failed cache WRITE must never fail define() itself -- the remote write already
+            // succeeded (or was confirmed unchanged) by the time this runs; losing the cache entry
+            // only costs a future redundant remote round-trip, not correctness.
+            console.log('[FeatureService] setCachedFeatureFingerprint failed (non-fatal)', { productTag, tag, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /**
+     * Fetches every real feature currently persisted for `productTag` in ONE bulk remote call
+     * (`builder.fetchFeatures()`, already existing -- the same call Ductape's own Workbench uses)
+     * and warms the Redis fingerprint cache for all of them at once. Real answer to "if Redis is
+     * empty, fetch all existing features, then check if the defined feature is already there
+     * before recreating it" -- this runs at most ONCE per product per process (concurrent
+     * define() calls for different features share the same in-flight promise, never triggering
+     * their own separate bulk fetch).
+     */
+    async warmFeatureCache(productTag, builder) {
+        let warmPromise = this.featureCacheWarmed.get(productTag);
+        if (!warmPromise) {
+            warmPromise = (async () => {
+                console.log('[FeatureService] warmFeatureCache: cold cache, fetching all existing features', { productTag });
+                const all = await builder.fetchFeatures();
+                const byTag = new Map();
+                for (const feature of all) {
+                    if (!feature.tag)
+                        continue;
+                    byTag.set(feature.tag, feature);
+                    await this.setCachedFeatureFingerprint(productTag, feature.tag, this.computeFeatureFingerprint(feature));
+                }
+                console.log('[FeatureService] warmFeatureCache: cached fingerprints for existing features', { productTag, count: byTag.size });
+                return byTag;
+            })();
+            this.featureCacheWarmed.set(productTag, warmPromise);
+        }
+        return warmPromise;
+    }
     /**
      * Initialize logging service
      */
@@ -481,7 +595,7 @@ class FeatureService {
      * ```
      */
     async define(options) {
-        var _a, _b;
+        var _a, _b, _c;
         console.log('[FeatureService] define ENTRY', { tag: options.tag, name: options.name, product: options.product });
         // Validate required fields
         if (!options.tag || !options.name || !options.handler) {
@@ -494,18 +608,61 @@ class FeatureService {
         console.log('[FeatureService] define compiling handler (compileAsync)', { tag: options.tag });
         const schema = await compiler.compileAsync();
         console.log('[FeatureService] define compiled schema', { tag: schema.tag, stepsCount: (_b = (_a = schema.steps) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0 });
-        // If product is specified, create the feature
+        // If product is specified, create the feature -- but first check the Redis fingerprint
+        // cache (see the "FEATURE-DEFINITION REDIS CACHE" section above) so an unaltered feature
+        // that is ALREADY known to be persisted correctly never touches the remote API at all.
         if (options.product) {
-            console.log('[FeatureService] define creating feature on backend', { product: options.product, tag: schema.tag });
-            const builder = await this.getProductBuilder(options.product);
-            const existing = await builder.fetchFeature(schema.tag);
-            if (existing)
-                await builder.updateFeature(schema.tag, schema);
-            else
-                await builder.createFeature(schema, true);
-            const persisted = await builder.fetchFeature(schema.tag);
-            if (!persisted) {
-                throw new FeatureError(`Feature ${schema.tag} was acknowledged but is absent from the catalogue read path`, 'FEATURE_CATALOGUE_INCONSISTENT');
+            const fingerprint = this.computeFeatureFingerprint(schema);
+            const cachedFingerprint = await this.getCachedFeatureFingerprint(options.product, schema.tag);
+            if (cachedFingerprint === fingerprint) {
+                console.log('[FeatureService] define SKIPPED remote calls (Redis cache hit, unaltered)', { product: options.product, tag: schema.tag });
+            }
+            else {
+                console.log('[FeatureService] define creating feature on backend', { product: options.product, tag: schema.tag, cacheState: cachedFingerprint === null ? 'miss' : 'stale' });
+                const builder = await this.getProductBuilder(options.product);
+                let existing = await builder.fetchFeature(schema.tag);
+                // Real answer to "if Redis is empty, fetch all existing features, then check if the
+                // defined feature is there before recreating it": a cache miss AND no remote record for
+                // THIS tag could simply mean the cache was never warmed (e.g. first boot after a Redis
+                // flush) while the feature genuinely already exists remotely under normal operation --
+                // fetchFeature() above already covers that single-tag case, but warm the full cache here
+                // too (once per product per process) so every OTHER feature defined later in this same
+                // boot benefits from cache hits instead of each paying its own fetchFeature() call.
+                if (!this.featureCacheWarmed.has(options.product)) {
+                    const allExisting = await this.warmFeatureCache(options.product, builder);
+                    if (!existing)
+                        existing = (_c = allExisting.get(schema.tag)) !== null && _c !== void 0 ? _c : null;
+                }
+                // Only a genuine remote WRITE (create or update) needs the post-write re-fetch below to
+                // guard against "acknowledged but not actually persisted" backend inconsistencies -- when
+                // `existing` already proves the feature is there (whether from fetchFeature's own by-tag
+                // lookup or the bulk warm fallback) and its fingerprint already matches, re-fetching by
+                // tag is not just redundant, it can genuinely fail: `existing` reaching us via the bulk
+                // warm path exists PRECISELY BECAUSE the by-tag lookup lagged behind once already for
+                // this same feature -- re-running that same lookup immediately after is not a reliable
+                // verification, it is repeating the exact race the warm fallback exists to route around.
+                let wroteRemotely = false;
+                if (existing) {
+                    const existingFingerprint = this.computeFeatureFingerprint(existing);
+                    if (existingFingerprint === fingerprint) {
+                        console.log('[FeatureService] define: remote already matches compiled schema, skipping updateFeature', { product: options.product, tag: schema.tag });
+                    }
+                    else {
+                        await builder.updateFeature(schema.tag, schema);
+                        wroteRemotely = true;
+                    }
+                }
+                else {
+                    await builder.createFeature(schema, true);
+                    wroteRemotely = true;
+                }
+                if (wroteRemotely) {
+                    const persisted = await builder.fetchFeature(schema.tag);
+                    if (!persisted) {
+                        throw new FeatureError(`Feature ${schema.tag} was acknowledged but is absent from the catalogue read path`, 'FEATURE_CATALOGUE_INCONSISTENT');
+                    }
+                }
+                await this.setCachedFeatureFingerprint(options.product, schema.tag, fingerprint);
             }
         }
         // Store locally