@launchdarkly/js-sdk-common 2.24.3 → 2.25.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `@launchdarkly/js-sdk-common` will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [2.25.0](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.24.4...js-sdk-common-v2.25.0) (2026-05-21)
+
+
+### Features
+
+* add X-LaunchDarkly-Instance-Id header to server-node SDK (SDK-2358) ([#1377](https://github.com/launchdarkly/js-core/issues/1377)) ([814dc0b](https://github.com/launchdarkly/js-core/commit/814dc0bfd6b152385f3a758f9eeca37a0f9f08e8))
+
+## [2.24.4](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.24.3...js-sdk-common-v2.24.4) (2026-05-06)
+
+
+### Bug Fixes
+
+* **server-node:** honor x-ld-fd-fallback directive in FDv2 initializer phase ([#1342](https://github.com/launchdarkly/js-core/issues/1342)) ([a80eaca](https://github.com/launchdarkly/js-core/commit/a80eacaafa6174e5f1b4fe21ba11534fdf1f92a8))
+
 ## [2.24.3](https://github.com/launchdarkly/js-core/compare/js-sdk-common-v2.24.2...js-sdk-common-v2.24.3) (2026-04-30)
 
 

package/dist/cjs/api/subsystem/DataSystem/DataSource.d.ts

@@ -1,19 +1,9 @@
-/**
- * @experimental
- * This feature is not stable and not subject to any backwards compatibility guarantees or semantic
- * versioning.  It is not suitable for production usage.
- */
 export declare enum DataSourceState {
     Valid = 0,
     Initializing = 1,
     Interrupted = 2,
     Closed = 3
 }
-/**
- * @experimental
- * This feature is not stable and not subject to any backwards compatibility guarantees or semantic
- * versioning.  It is not suitable for production usage.
- */
 export interface DataSource {
     /**
      * May be called any number of times, if already started, has no effect
@@ -28,10 +18,5 @@ export interface DataSource {
      */
     stop(): void;
 }
-/**
- * @experimental
- * This feature is not stable and not subject to any backwards compatibility guarantees or semantic
- * versioning.  It is not suitable for production usage.
- */
 export type LDDataSourceFactory = () => DataSource;
 //# sourceMappingURL=DataSource.d.ts.map

package/dist/cjs/api/subsystem/DataSystem/DataSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataSource.d.ts","sourceRoot":"","sources":["../../../../src/api/subsystem/DataSystem/DataSource.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,oBAAY,eAAe;IAEzB,KAAK,IAAA;IAEL,YAAY,IAAA;IAEZ,WAAW,IAAA;IAEX,MAAM,IAAA;CACP;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,KAAK,CACH,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,EACjD,cAAc,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,EAC5D,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GACxC,IAAI,CAAC;IAER;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,UAAU,CAAC"}
+{"version":3,"file":"DataSource.d.ts","sourceRoot":"","sources":["../../../../src/api/subsystem/DataSystem/DataSource.ts"],"names":[],"mappings":"AACA,oBAAY,eAAe;IAEzB,KAAK,IAAA;IAEL,YAAY,IAAA;IAEZ,WAAW,IAAA;IAEX,MAAM,IAAA;CACP;AAED,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,KAAK,CACH,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,EACjD,cAAc,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,EAC5D,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GACxC,IAAI,CAAC;IAER;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,MAAM,mBAAmB,GAAG,MAAM,UAAU,CAAC"}

package/dist/cjs/datasource/CompositeDataSource.d.ts

@@ -26,6 +26,7 @@ export declare class CompositeDataSource implements DataSource {
     private _initFactories;
     private _syncFactories;
     private _fdv1Synchronizers;
+    private _fdv1FallbackEngaged;
     private _stopped;
     private _externalTransitionPromise;
     private _externalTransitionResolve?;

package/dist/cjs/datasource/CompositeDataSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompositeDataSource.d.ts","sourceRoot":"","sources":["../../src/datasource/CompositeDataSource.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EACL,UAAU,EACV,eAAe,EACf,mBAAmB,EACpB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAOpD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;KAChC,CAAC,IAAI,eAAe,CAAC,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE;CACxE,CAAC;AAOF;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IAyBlD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,qBAAqB;IAUtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjC3B,OAAO,CAAC,gBAAgB,CAAU;IAClC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,kBAAkB,CAAsC;IAEhE,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,0BAA0B,CAA6B;IAC/D,OAAO,CAAC,0BAA0B,CAAC,CAAqC;IACxE,OAAO,CAAC,aAAa,CAAsB;IAE3C;;;;;;;OAOG;gBAED,YAAY,EAAE,mBAAmB,EAAE,EACnC,aAAa,EAAE,mBAAmB,EAAE,EACpC,iBAAiB,EAAE,mBAAmB,EAAE,EACvB,OAAO,CAAC,sBAAU,EAClB,qBAAqB,GAAE,oBASvC,EACgB,QAAQ,GAAE,OAAyC;IAWhE,KAAK,CACT,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,EACjD,cAAc,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,EAC5D,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GACxC,OAAO,CAAC,IAAI,CAAC;IAwJV,IAAI;IAMV,OAAO,CAAC,MAAM;IAYd;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA0DvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,iBAAiB,CAcvB;IAEF,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;CAgCzC"}
+{"version":3,"file":"CompositeDataSource.d.ts","sourceRoot":"","sources":["../../src/datasource/CompositeDataSource.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,OAAO,EACL,UAAU,EACV,eAAe,EACf,mBAAmB,EACpB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAOpD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;KAChC,CAAC,IAAI,eAAe,CAAC,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE;CACxE,CAAC;AAOF;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IA8BlD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,qBAAqB;IAUtC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAtC3B,OAAO,CAAC,gBAAgB,CAAU;IAClC,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,cAAc,CAAsC;IAC5D,OAAO,CAAC,kBAAkB,CAAsC;IAKhE,OAAO,CAAC,oBAAoB,CAAkB;IAE9C,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,0BAA0B,CAA6B;IAC/D,OAAO,CAAC,0BAA0B,CAAC,CAAqC;IACxE,OAAO,CAAC,aAAa,CAAsB;IAE3C;;;;;;;OAOG;gBAED,YAAY,EAAE,mBAAmB,EAAE,EACnC,aAAa,EAAE,mBAAmB,EAAE,EACpC,iBAAiB,EAAE,mBAAmB,EAAE,EACvB,OAAO,CAAC,sBAAU,EAClB,qBAAqB,GAAE,oBASvC,EACgB,QAAQ,GAAE,OAAyC;IAWhE,KAAK,CACT,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,KAAK,IAAI,EACjD,cAAc,EAAE,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,EAC5D,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,GACxC,OAAO,CAAC,IAAI,CAAC;IAyMV,IAAI;IAMV,OAAO,CAAC,MAAM;IAad;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA0DvB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,iBAAiB,CAcvB;IAEF,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;CAgCzC"}

package/dist/cjs/index.cjs

@@ -985,11 +985,6 @@ class CallbackHandler {
 }
 
 // TODO: refactor client-sdk to use this enum
-/**
- * @experimental
- * This feature is not stable and not subject to any backwards compatibility guarantees or semantic
- * versioning.  It is not suitable for production usage.
- */
 var DataSourceState;
 (function (DataSourceState) {
     // Positive confirmation of connection/data receipt
@@ -1155,6 +1150,11 @@ class CompositeDataSource {
         this._logger = _logger;
         this._transitionConditions = _transitionConditions;
         this._backoff = _backoff;
+        // Set after the server-directed FDv1 fallback has been engaged. The directive is
+        // one-way: subsequent fallback signals from the FDv1 synchronizer (e.g. if the FDv1
+        // endpoint were to echo `x-ld-fd-fallback`) are ignored so the data source does not
+        // loop replacing its synchronizer list with itself.
+        this._fdv1FallbackEngaged = false;
         this._stopped = true;
         this._cancelTokens = [];
         this._cancellableDelay = (delayMS) => {
@@ -1202,10 +1202,36 @@ class CompositeDataSource {
                     // secondary has been valid for N many seconds)
                     let lastState;
                     let cancelScheduledTransition = () => { };
+                    // Engages the FDv1 Fallback Directive: swaps the synchronizer list to FDv1 (or
+                    // empties it when no FDv1 fallback is configured), reports the in-progress status
+                    // through the sanitizer, cancels any pending scheduled transition, and resolves
+                    // a switchToSync transition. The directive is one-way; the engagement flag is
+                    // checked by the callers so we don't re-enter this branch on repeated signals.
+                    const engageFDv1Fallback = (statusToReport, err) => {
+                        if (this._fdv1Synchronizers.length() > 0) {
+                            this._logger?.warn(`Falling back to FDv1`);
+                        }
+                        else {
+                            this._logger?.warn(`FDv1 fallback was requested but no FDv1 fallback synchronizer is configured; data source will terminate`);
+                        }
+                        this._fdv1FallbackEngaged = true;
+                        this._syncFactories = this._fdv1Synchronizers;
+                        sanitizedStatusCallback(statusToReport, err);
+                        this._consumeCancelToken(cancelScheduledTransition);
+                        transitionResolve({ transition: 'switchToSync', err: err });
+                    };
                     // this callback handler can be disabled and ensures only one transition request occurs
                     const callbackHandler = new CallbackHandler((basis, data) => {
                         this._backoff.success();
                         dataCallback(basis, data);
+                        // The FDv1 fallback directive can ride along on the same data callback that
+                        // delivers a payload, so the swap to FDv1 is atomic with payload application.
+                        // Once engaged, the directive is one-way -- subsequent signals are ignored.
+                        if (data?.fallbackToFDv1 && !this._fdv1FallbackEngaged) {
+                            callbackHandler.disable();
+                            engageFDv1Fallback(DataSourceState.Interrupted, undefined);
+                            return;
+                        }
                         if (basis && this._initPhaseActive) {
                             // transition to sync if we get basis during init
                             callbackHandler.disable();
@@ -1224,11 +1250,13 @@ class CompositeDataSource {
                                 // don't use this datasource's factory again
                                 this._logger?.debug(`Culling data source due to err ${err}`);
                                 cullDSFactory?.();
-                                // this error indicates we should fallback to only using FDv1 synchronizers
-                                if (err instanceof LDFlagDeliveryFallbackError) {
-                                    this._logger?.debug(`Falling back to FDv1`);
-                                    this._syncFactories = this._fdv1Synchronizers;
-                                }
+                            }
+                            // Status-callback path for the FDv1 Fallback Directive (used when the
+                            // server-directed signal arrives without an accompanying payload, e.g. on
+                            // an HTTP error or a malformed body).
+                            if (err instanceof LDFlagDeliveryFallbackError && !this._fdv1FallbackEngaged) {
+                                engageFDv1Fallback(state, err);
+                                return;
                             }
                             sanitizedStatusCallback(state, err);
                             this._consumeCancelToken(cancelScheduledTransition);
@@ -1275,7 +1303,16 @@ class CompositeDataSource {
             ]);
             // stop the underlying datasource before transitioning to next state
             currentDS?.stop();
-            if (transitionRequest.err && transitionRequest.transition !== 'stop') {
+            // Skip backoff only on the initial server-directed FDv1 engagement (a `switchToSync`
+            // transition resolved by `engageFDv1Fallback` carries an `LDFlagDeliveryFallbackError`).
+            // Any subsequent `LDFlagDeliveryFallbackError` is an ordinary retry from the FDv1
+            // synchronizer (or a follow-up FDv1 factory) and must be throttled like any other
+            // error retry.
+            const isInitialFDv1Engagement = transitionRequest.transition === 'switchToSync' &&
+                transitionRequest.err instanceof LDFlagDeliveryFallbackError;
+            if (transitionRequest.err &&
+                transitionRequest.transition !== 'stop' &&
+                !isInitialFDv1Engagement) {
                 // if the transition was due to an error we're not in the initializer phase, throttle the transition. Fallback between initializers is not throttled.
                 const delay = this._initPhaseActive ? 0 : this._backoff.fail();
                 const { promise, cancel: cancelDelay } = this._cancellableDelay(delay);
@@ -1313,6 +1350,7 @@ class CompositeDataSource {
         this._initFactories.reset();
         this._syncFactories.reset();
         this._fdv1Synchronizers.reset();
+        this._fdv1FallbackEngaged = false;
         this._externalTransitionPromise = new Promise((tr) => {
             this._externalTransitionResolve = tr;
         });
@@ -2197,7 +2235,7 @@ function fastDeepEqual(a, b) {
     return a !== a && b !== b;
 }
 
-function defaultHeaders(sdkKey, info, tags, includeAuthorizationHeader = true, userAgentHeaderName = 'user-agent') {
+function defaultHeaders(sdkKey, info, tags, includeAuthorizationHeader = true, userAgentHeaderName = 'user-agent', instanceId) {
     const { userAgentBase, version, wrapperName, wrapperVersion } = info.sdkData();
     const headers = {
         [userAgentHeaderName]: `${userAgentBase ?? 'NodeJSClient'}/${version}`,
@@ -2215,6 +2253,14 @@ function defaultHeaders(sdkKey, info, tags, includeAuthorizationHeader = true, u
     if (tags?.value) {
         headers['x-launchdarkly-tags'] = tags.value;
     }
+    // Per SCMP-server-connection-minutes-polling (spec section 1.1), server SDKs include a
+    // per-instance v4 GUID on every polling request. The caller (a server SDK) is responsible
+    // for generating the GUID once per SDK instance and passing it here, so that it rides on
+    // every outbound request via this shared default-headers map. Client/edge SDKs do not pass
+    // this value, so the header is omitted for them.
+    if (instanceId) {
+        headers['x-launchdarkly-instance-id'] = instanceId;
+    }
     return headers;
 }
 function httpErrorMessage(err, context, retryMessage) {