feat: add X-LaunchDarkly-Instance-Id header to server-node SDK (SDK-2358) by keelerm84 · Pull Request #1377 · launchdarkly/js-core

keelerm84 · 2026-05-12T20:59:47Z

Summary

Adds the X-LaunchDarkly-Instance-Id header to every outbound polling, streaming, and event request from @launchdarkly/node-server-sdk. Value is a v4 UUID generated once per LDClientImpl via platform.crypto.randomUUID() and shared with the requestor, streaming processor, and event processor through baseHeaders.

The instanceId parameter on the shared defaultHeaders helper is opt-in so the client SDK and edge SDKs in this monorepo (akamai-base, cloudflare, fastly, vercel, shopify-oxygen, server-ai) are unaffected — they go through different code paths and continue to omit the header.

Test plan

`@launchdarkly/js-sdk-common` — 473 / 473 passing (17 http tests incl. 3 new)
`@launchdarkly/js-server-sdk-common` — 990 / 990 passing (3 new instance-id tests)
`@launchdarkly/node-server-sdk` — 63 / 63 passing
Lint clean across all 3 affected workspaces
Edge SDKs (cloudflare, vercel, akamai-base) still build
CI green

Note

Medium Risk
Changes default outbound HTTP headers for the Node server SDK by adding a new per-instance UUID, which could impact integrations that validate/forward headers. Logic is straightforward and gated via server-only internal options, but it affects every request path (polling/streaming/events).

Overview
Adds opt-in support for the X-LaunchDarkly-Instance-Id header via defaultHeaders, including new typing and tests to ensure the header is omitted unless a non-empty instance id is provided.

Updates LDClientImpl (FDv1 and FDv2 construction) to pass internalOptions.instanceId into defaultHeaders, and updates the Node server SDK to generate a v4 UUID once per LDClientNode instance (platform.crypto.randomUUID()) and supply it via ServerInternalOptions. Contract tests now advertise the instance-id capability, with new unit tests validating UUID format and per-instance uniqueness.

^{Reviewed by Cursor Bugbot for commit 3f90b3a. Bugbot is set up for automated code reviews on this repo. Configure here.}

…K-2358) Per SCMP-server-connection-minutes-polling section 1.1, server SDKs must send a per-instance v4 GUID on every polling request to enable Server Connection Minutes estimation. The GUID is generated once per SDK instance and stable for that instance's lifetime. We attach the GUID to the shared base headers in LDClientImpl (constructFDv1 and constructFDv2), so it rides on every outbound request -- polling, streaming, and events -- matching the cross-SDK contract tests. The shared defaultHeaders helper now accepts an optional instanceId parameter so client / edge SDKs are not affected. Section 1.3 (polling-interval header) is out of scope for this ticket. Changes: - packages/shared/common/src/utils/http.ts: extend LDHeaders and defaultHeaders to support an optional instanceId - packages/shared/sdk-server/src/LDClientImpl.ts: generate one UUID per client (via platform.crypto.randomUUID) and pass it to defaultHeaders - packages/sdk/server-node/contract-tests: register "instance-id" capability - Unit tests for both layers; updated bigSegments test mock crypto

github-actions · 2026-05-12T21:01:20Z

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 26389 bytes
Compressed size limit: 29000
Uncompressed size: 129320 bytes

github-actions · 2026-05-12T21:01:41Z

@launchdarkly/browser size report
This is the brotli compressed size of the ESM build.
Compressed size: 179469 bytes
Compressed size limit: 200000
Uncompressed size: 830878 bytes

github-actions · 2026-05-12T21:01:46Z

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Compressed size: 38487 bytes
Compressed size limit: 39000
Uncompressed size: 211236 bytes

github-actions · 2026-05-12T21:01:55Z

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Compressed size: 31884 bytes
Compressed size limit: 34000
Uncompressed size: 113699 bytes

cursor

Cursor Bugbot has reviewed your changes using default mode and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 3996e7e. Configure here.}

The previous commit (3996e7e) called platform.crypto.randomUUID() from LDClientImpl.constructFDv1/constructFDv2, but LDClientImpl is also the base class for the Akamai, Cloudflare, Fastly, Vercel, and Shopify Oxygen edge SDKs. Those edge platforms either don't provide a working randomUUID() in their test mocks (Akamai) or shouldn't be advertising instance-id at all. This commit moves UUID generation to LDClientNode, which uses the Node platform's always-available crypto.randomUUID, and threads the generated value through ServerInternalOptions.instanceId. LDClientImpl attaches the header only when instanceId is supplied, leaving edge SDKs unaffected. Also reverts the workaround in the big-segments test crypto mock — no longer needed now that LDClientImpl doesn't call randomUUID on its own. Tests: - @launchdarkly/js-server-sdk-common: 989 passing (5 skipped) - @launchdarkly/node-server-sdk: 65 passing (+2 new instance-id tests) - @launchdarkly/akamai-server-base-sdk: 6 passing (previously 6 failing) - Lint clean

kinyoklion · 2026-05-13T19:50:24Z

    delete baseOptions.plugins;

+    const platform = new NodePlatform({ ...options, logger });
+    // Per SCMP-server-connection-minutes-polling section 1.1, generate one v4 GUID per SDK


I think we want to leave out the spec reference.

🤖 I have created a release *beep* *boop* --- <details><summary>akamai-edgeworker-sdk-common: 2.0.22</summary> ## [2.0.22](akamai-edgeworker-sdk-common-v2.0.21...akamai-edgeworker-sdk-common-v2.0.22) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common bumped from ^2.18.7 to ^2.19.0 </details> <details><summary>akamai-server-base-sdk: 3.0.23</summary> ## [3.0.23](akamai-server-base-sdk-v3.0.22...akamai-server-base-sdk-v3.0.23) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/akamai-edgeworker-sdk-common bumped from ^2.0.21 to ^2.0.22 * @launchdarkly/js-server-sdk-common bumped from ^2.18.7 to ^2.19.0 </details> <details><summary>akamai-server-edgekv-sdk: 1.4.25</summary> ## [1.4.25](akamai-server-edgekv-sdk-v1.4.24...akamai-server-edgekv-sdk-v1.4.25) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/akamai-edgeworker-sdk-common bumped from ^2.0.21 to ^2.0.22 * @launchdarkly/js-server-sdk-common bumped from ^2.18.7 to ^2.19.0 </details> <details><summary>browser: 0.1.22</summary> ## [0.1.22](browser-v0.1.21...browser-v0.1.22) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk bumped from 4.7.0 to 4.7.1 </details> <details><summary>cloudflare-server-sdk: 2.7.24</summary> ## [2.7.24](cloudflare-server-sdk-v2.7.23...cloudflare-server-sdk-v2.7.24) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common-edge bumped from 2.6.20 to 2.6.21 </details> <details><summary>fastly-server-sdk: 0.2.14</summary> ## [0.2.14](fastly-server-sdk-v0.2.13...fastly-server-sdk-v0.2.14) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 </details> <details><summary>jest: 1.0.17</summary> ## [1.0.17](jest-v1.0.16...jest-v1.0.17) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/react-native-client-sdk bumped from ~10.17.5 to ~10.17.6 </details> <details><summary>js-client-sdk: 4.7.1</summary> ## [4.7.1](js-client-sdk-v4.7.0...js-client-sdk-v4.7.1) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk-common bumped from 1.27.0 to 1.27.1 </details> <details><summary>js-client-sdk-common: 1.27.1</summary> ## [1.27.1](js-client-sdk-common-v1.27.0...js-client-sdk-common-v1.27.1) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-sdk-common bumped from 2.24.4 to 2.25.0 </details> <details><summary>js-sdk-common: 2.25.0</summary> ## [2.25.0](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](#1377)) ([814dc0b](814dc0b)) </details> <details><summary>js-server-sdk-common: 2.19.0</summary> ## [2.19.0](js-server-sdk-common-v2.18.7...js-server-sdk-common-v2.19.0) (2026-05-21) ### Features * add X-LaunchDarkly-Instance-Id header to server-node SDK (SDK-2358) ([#1377](#1377)) ([814dc0b](814dc0b)) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-sdk-common bumped from 2.24.4 to 2.25.0 </details> <details><summary>js-server-sdk-common-edge: 2.6.21</summary> ## [2.6.21](js-server-sdk-common-edge-v2.6.20...js-server-sdk-common-edge-v2.6.21) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 </details> <details><summary>node-server-sdk: 9.11.0</summary> ## [9.11.0](node-server-sdk-v9.10.14...node-server-sdk-v9.11.0) (2026-05-21) ### Features * add X-LaunchDarkly-Instance-Id header to server-node SDK (SDK-2358) ([#1377](#1377)) ([814dc0b](814dc0b)) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 </details> <details><summary>node-server-sdk-dynamodb: 6.2.28</summary> ## [6.2.28](node-server-sdk-dynamodb-v6.2.27...node-server-sdk-dynamodb-v6.2.28) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/node-server-sdk bumped from 9.10.14 to 9.11.0 * peerDependencies * @launchdarkly/node-server-sdk bumped from >=9.10.14 to >=9.11.0 </details> <details><summary>node-server-sdk-otel: 1.3.15</summary> ## [1.3.15](node-server-sdk-otel-v1.3.14...node-server-sdk-otel-v1.3.15) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/node-server-sdk bumped from 9.10.14 to 9.11.0 * peerDependencies * @launchdarkly/node-server-sdk bumped from >=9.10.14 to >=9.11.0 </details> <details><summary>node-server-sdk-redis: 4.2.27</summary> ## [4.2.27](node-server-sdk-redis-v4.2.26...node-server-sdk-redis-v4.2.27) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/node-server-sdk bumped from 9.10.14 to 9.11.0 * peerDependencies * @launchdarkly/node-server-sdk bumped from >=9.10.14 to >=9.11.0 </details> <details><summary>openfeature-js-server-common: 0.1.2</summary> ## [0.1.2](openfeature-js-server-common-v0.1.1...openfeature-js-server-common-v0.1.2) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-sdk-common bumped from 2.24.4 to 2.25.0 </details> <details><summary>openfeature-node-server: 1.2.1</summary> ## [1.2.1](openfeature-node-server-v1.2.0...openfeature-node-server-v1.2.1) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-sdk-common bumped from 2.24.4 to 2.25.0 * @launchdarkly/openfeature-js-server-common bumped from 0.1.1 to 0.1.2 * devDependencies * @launchdarkly/node-server-sdk bumped from 9.10.12 to 9.11.0 * peerDependencies * @launchdarkly/node-server-sdk bumped from 9.x to 9.11.0 </details> <details><summary>react-native-client-sdk: 10.17.6</summary> ## [10.17.6](react-native-client-sdk-v10.17.5...react-native-client-sdk-v10.17.6) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk-common bumped from 1.27.0 to 1.27.1 </details> <details><summary>react-sdk: 4.0.3</summary> ## [4.0.3](react-sdk-v4.0.2...react-sdk-v4.0.3) (2026-05-21) ### Bug Fixes * **deps:** update dependency next to v16.2.6 [security] ([#1374](#1374)) ([24487f4](24487f4)) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-client-sdk bumped from ^4.7.0 to ^4.7.1 * @launchdarkly/js-server-sdk-common bumped from ^2.18.7 to ^2.19.0 </details> <details><summary>server-sdk-ai: 1.0.1</summary> ## [1.0.1](server-sdk-ai-v1.0.0...server-sdk-ai-v1.0.1) (2026-05-21) ### Bug Fixes * Remove pre-release caution note from server-ai README ([#1387](#1387)) ([0bafcbf](0bafcbf)) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 * peerDependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 </details> <details><summary>server-sdk-ai-langchain: 0.8.1</summary> ## [0.8.1](server-sdk-ai-langchain-v0.8.0...server-sdk-ai-langchain-v0.8.1) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/server-sdk-ai bumped from ^1.0.0 to ^1.0.1 * peerDependencies * @launchdarkly/server-sdk-ai bumped from ^1.0.0 to ^1.0.1 </details> <details><summary>server-sdk-ai-openai: 0.7.1</summary> ## [0.7.1](server-sdk-ai-openai-v0.7.0...server-sdk-ai-openai-v0.7.1) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 * @launchdarkly/server-sdk-ai bumped from ^1.0.0 to ^1.0.1 * peerDependencies * @launchdarkly/server-sdk-ai bumped from ^1.0.0 to ^1.0.1 </details> <details><summary>server-sdk-ai-vercel: 0.7.1</summary> ## [0.7.1](server-sdk-ai-vercel-v0.7.0...server-sdk-ai-vercel-v0.7.1) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * devDependencies * @launchdarkly/server-sdk-ai bumped from ^1.0.0 to ^1.0.1 * peerDependencies * @launchdarkly/server-sdk-ai bumped from ^1.0.0 to ^1.0.1 </details> <details><summary>shopify-oxygen-sdk: 0.1.12</summary> ## [0.1.12](shopify-oxygen-sdk-v0.1.11...shopify-oxygen-sdk-v0.1.12) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common bumped from 2.18.7 to 2.19.0 </details> <details><summary>vercel-server-sdk: 1.3.47</summary> ## [1.3.47](vercel-server-sdk-v1.3.46...vercel-server-sdk-v1.3.47) (2026-05-21) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/js-server-sdk-common-edge bumped from 2.6.20 to 2.6.21 </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).  --- > [!NOTE] > **Low Risk** > Mostly automated release housekeeping: version constants, manifests, and changelogs, plus dependency/peerDependency bumps across many packages. Low functional risk, but downstream consumers may see behavior changes from the underlying dependency upgrades (notably `@launchdarkly/node-server-sdk` 9.11.0 and `next` security bump in `@launchdarkly/react-sdk`). > > **Overview** > **Release-please version rollup.** Updates `.release-please-manifest.json`, per-package `package.json` versions, and `CHANGELOG.md` entries across AI providers, client/server SDKs, stores, telemetry, and tooling. > > Propagates dependency bumps (e.g., `@launchdarkly/js-sdk-common` 2.25.0, `@launchdarkly/js-server-sdk-common` 2.19.0, `@launchdarkly/js-client-sdk-common` 1.27.1) and updates embedded `sdkVersion`/`wrapperVersion` constants in several SDK platform info files. Includes a `@launchdarkly/react-sdk` patch with a `next` dependency security update and adds a new `openfeature-node-server` changelog entry. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit dfe4ebb. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

keelerm84 requested a review from a team as a code owner May 12, 2026 20:59

cursor Bot reviewed May 12, 2026

View reviewed changes

Comment thread packages/shared/sdk-server/src/LDClientImpl.ts

kinyoklion reviewed May 13, 2026

View reviewed changes

kinyoklion approved these changes May 13, 2026

View reviewed changes

drop spec number

3f90b3a

keelerm84 merged commit 814dc0b into main May 19, 2026
43 checks passed

keelerm84 deleted the mk/sdk-2358-instance-id branch May 19, 2026 15:47

github-actions Bot mentioned this pull request May 19, 2026

chore: release main #1388

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add X-LaunchDarkly-Instance-Id header to server-node SDK (SDK-2358)#1377

feat: add X-LaunchDarkly-Instance-Id header to server-node SDK (SDK-2358)#1377
keelerm84 merged 3 commits into
mainfrom
mk/sdk-2358-instance-id

keelerm84 commented May 12, 2026 •

edited by cursor Bot

Loading

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

kinyoklion May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

keelerm84 commented May 12, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

github-actions Bot commented May 12, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kinyoklion May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

keelerm84 commented May 12, 2026 •

edited by cursor Bot

Loading