chore: Add Node platform abstraction for node-client by joker23 · Pull Request #1393 · launchdarkly/js-core

joker23 · 2026-05-26T22:51:09Z

Summary

Adds the Node platform abstraction layer for @launchdarkly/node-client-sdk: HeaderWrapper, NodeCrypto, NodeEncoding, NodeInfo, NodePlatform, NodeRequests, NodeResponse, NodeStorage. These implement the Platform contract from @launchdarkly/js-client-sdk-common.
Adds runtime dependencies the platform code imports: @launchdarkly/js-client-sdk-common, https-proxy-agent, launchdarkly-eventsource.
Modernizes packages/sdk/node-client/tsconfig.json to module: ESNext + moduleResolution: bundler (tsup handles emit), adds esModuleInterop, types: ["jest", "node"], skipLibCheck. Matches the pattern used by packages/sdk/server-ai.
Part of the SDK-2195 stacked migration of launchdarkly-node-client-sdk into js-core. Follows PR chore: scaffolding node-client-sdk migration #1352 (scaffold).

Note

Medium Risk
New TLS, HTTP streaming, and on-disk cache behavior affect runtime networking and local persistence, though it is isolated behind platform interfaces and covered by unit tests; the public client API is not wired yet.

Overview
Adds the Node platform layer for @launchdarkly/node-client-sdk so the package can plug into @launchdarkly/js-client-sdk-common: NodePlatform wires info, crypto, encoding, file-backed storage, and HTTP/HTTPS + EventSource requests. New NodeOptions covers TLS (tlsParams), optional POST gzip for events, and localStoragePath (default ldclient-user-cache).

NodeRequests / NodeResponse implement fetch-like behavior (timeouts, gzip on GET, optional body compression, custom CA for HTTPS) via launchdarkly-eventsource. NodeStorage persists a JSON cache with atomic writes and a process singleton.

Also adds Jest coverage for the platform modules, a sdk/node-client GitHub Actions job (Node 18 & 22), package test script and dependencies, tsconfig shift to ESNext / bundler, and release-please bumping NodeInfo.ts for version stamps.

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

github-actions · 2026-05-26T22:52:29Z

@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-26T22:52:47Z

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

github-actions · 2026-05-26T22:52:57Z

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

github-actions · 2026-05-26T22:53:02Z

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

joker23 · 2026-05-27T14:08:59Z

@cursor review

joker23 · 2026-05-27T16:05:59Z

@cursor review

joker23 · 2026-05-27T16:11:21Z

+
+  encoding?: platform.Encoding = new NodeEncoding();
+
+  storage?: platform.Storage;


I think we should allow for overriding the storage. Similar to what we do in the react-native sdk

Filed SDK-2420 internally to track. Addressing separately as this will be a new feature for this SDK

kinyoklion · 2026-05-28T17:48:19Z

+  proxyOptions?: LDProxyOptions;
+  tlsParams?: LDTLSOptions;
+  enableEventCompression?: boolean;
+  localStoragePath?: string;


We may want something like:

storage: {type: 'file', localStoragePath: string} | {type: 'custom', implementation: NCStorage}

I'll include this when I add support for overriding (#1393 (comment))

Holistic-branch commit containing the entire migration of the standalone launchdarkly/node-client-sdk repo into the js-core monorepo as @launchdarkly/node-client-sdk. Sliced for review into atomic PRs per the stack manifest at .claude/stacked-pr/plan.json (SDK-2309..SDK-2315). This commit shrinks as each atomic PR merges to main and the holistic branch is rebased. Contents: - packages/sdk/node-client/ -- the new SDK workspace - Modern js-core layout: tsup dual ESM/CJS, ts-jest, eslint, typedoc - tsconfig uses module=ESNext + moduleResolution=bundler (tsup handles emit), types=[jest, node], skipLibCheck - src/ ports the legacy SDK onto @launchdarkly/js-client-sdk-common - Public API: createClient + start (no auto-start), basicLogger, version, plus export * from common - Node-specific options: localStoragePath, tlsParams (10-key whitelist), hash for Secure Mode - platform/ adapts NodeCrypto/Info/Requests/Response/HeaderWrapper from packages/sdk/server-node and adds an fs/promises-backed NodeStorage with the no-throw storage contract. Storage is a process-level singleton matching the electron pattern, with an @internal resetNodeStorage exported for tests. - __tests__/ smoke test - examples/hello-node-client/ following the EXAM/HELLO spec: streaming flag-change listener, continuous-run mode with CI opt-out, ASCII LAUNCHDARKLY banner on true, env-var-driven credentials and flag key, tsconfig=nodenext for the ESM example - contract-tests/ with sdk-test-harness service entity. Includes run-contract-tests.sh for one-command local runs, npm scripts (contract-tests, contract-test-service), bridging in sdkClientEntity.ts that maps options.polling -> polling mode, options.hooks[] -> ClientSideTestHook instances, and disables the per-process flag cache so tests don't bleed state into each other. testharness-suppressions.txt suppresses three hook ordering tests pending an upstream fix in js-contract-test-utils. - temp_docs/MIGRATION.md describing the v3 -> v4 breaking changes - .github/workflows/node-client.yml -- CI build/lint/test plus contract-tests run, mirroring server-node.yml - Root package.json workspaces, tsconfig.json references, and release-please-config extra-files wired up; .release-please-manifest seeded at 0.0.1 (this is treated as a fresh package; release-please will track from there) BREAKING CHANGE: Package is renamed from launchdarkly-node-client-sdk to @launchdarkly/node-client-sdk and rebuilt on the modern @launchdarkly/js-client-sdk-common (FDv2-capable). Initialization now uses the createClient + start pattern: createClient returns a client that is not yet started, and the caller must await client.start() before the first variation or identify call. identify() now resolves to LDIdentifyResult instead of throwing. Minimum Node version is now 18. The persistent cache file format changed from node-localstorage's per-key files to a single JSON file in the same directory; existing v3 cache data will not be read. chore: Mark scaffold slice merged (PR #1352) chore: Mark port-platform slice in-flight (PR #1393) chore: Replan stack -- add contract-tests-features and storage-override slices - New `contract-tests-features` slice after `contract-tests` exercising hooks, identify result statuses, connection-mode switching, and FDv2 init markers + fallback. - New `storage-override` slice (SDK-2420) after `hello` providing caller-supplied storage override on NodeOptions. - per-slice MIGRATION.md updates: port-client owns hooks / inspectors / plugins / connection-mode / applicationInfo / proxy / TLS sections; storage-override owns its own section; archive becomes the final doc-pass. - Manifest now declares `tool: "sculptor"` so the SessionStart watch-arm hook activates for future cycles. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> chore: Reconcile holistic with PR #1393 reviewed content + manifest scope-update - Took PR #1393's reviewed source content as authoritative for the port-platform-only files: NodeInfo, NodePlatform, NodeRequests, NodeResponse, NodeStorage. The atomic's post-review versions (e.g., sdkName = 'node-client-sdk', NodeStorage logger param, direct getNodeStorage wiring) replace holistic's pre-review state. Reconciliation follows the same pattern advance uses when rebasing onto main. - release-please-config.json reverted to atomic's version (re-adds src/platform/NodeInfo.ts to extra-files for release-please version bumping). - Added atomic's PR-review additions: 10 platform unit tests under __tests__/platform/, __tests__/testHelpers.ts, and a package-level .gitignore. All 58 tests pass. - Manifest port-platform paths expanded to reflect actual ship scope (unit tests + .gitignore + testHelpers added during review); contract-tests-features.jira_subtask set to SDK-2422. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> feat: Add storage override on NodeOptions (SDK-2420) Replaces `localStoragePath` with a discriminated `storage` option: storage?: | { type: 'file'; localStoragePath?: string } | { type: 'custom'; implementation: Storage } - `undefined` or `{ type: 'file' }` -> file-backed default at `<cwd>/ldclient-user-cache`. - `{ type: 'file', localStoragePath: '/path' }` -> file-backed at the given path. - `{ type: 'custom', implementation }` -> caller-supplied store. Re-exports the common `Storage` interface as `LDStorage` so consumers can type their own implementations without depending on common. Adds 10 new unit tests; all 68 tests pass. Lint and build are clean. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> test: Declare common-base capabilities and wire harness commands Adds capability declarations for the new common-base features that were missing from node-client's contract-test surface: - anonymous-redaction - strongly-typed - event-gzip - flag-change-listeners - tls:skip-verify-peer - tls:custom-ca Wires the corresponding config + command handlers in sdkClientEntity: - makeSdkConfig: TLS options (skipVerifyPeer / customCAFile), proxy options (httpProxy URL -> proxyOptions), event-gzip (enableGzip -> enableEventCompression). - doCommand: RegisterFlagChangeListener (binds client.on('change'), fans out per-flag POSTs to the callback URI) and UnregisterListener. Also registers `packages/sdk/node-client/contract-tests` as a yarn workspace in root package.json so `yarn workspace @launchdarkly/node-client-sdk-contract-tests build` actually resolves. This belongs to the contract-tests slice; the manifest has been updated to claim root package.json with a single-line extraction note. The `http-proxy` capability is intentionally left undeclared -- node-client's NodeRequests only routes HTTPS targets through the proxy (https-proxy-agent), so the harness's HTTP-target proxy tests fail. Tracked separately as SDK-2423; the line in index.ts references the follow-up. Manifest also updated: contract-tests-features slice's paths now include contract-tests/src/index.ts (capability declarations live there), and its provides / extraction_notes reflect the revised scope. Harness baseline: 841 tests passed, 18 skipped, 0 failed. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> docs: Add MIGRATION sections for new common-base features Adds seven sections documenting feature surfaces that are new in node-client (relative to the legacy launchdarkly-node-client-sdk) and that are introduced by the port-client slice: - Evaluation, identify, and track hooks (Hook type + addHook method) - Inspectors (with deprecation note pointing to hooks) - Plugins and application metadata (LDPlugin + applicationInfo) - Runtime connection-mode control (setConnectionMode / getConnectionMode) - HTTP proxy options (proxyOptions, with note on HTTPS-target-only) - TLS configuration (tlsParams; fields mirror Node's https.request) - (Storage configuration already documented as part of SDK-2420) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Hardens the Node platform layer landed in #1393, ahead of the client-side SDK implementation that builds on it. First atomic in the node-client port stack. - **NodeStorage**: log (no longer swallow) flush errors; validate/log on malformed cache reads and ignore non-string cache values; write the temp file via an exclusive `wx` open so the write cannot be redirected through a symlink; warn when `getNodeStorage` is called with a `localStoragePath` that differs from the process singleton's.  --- > [!NOTE] > **Medium Risk** > Changes on-disk cache semantics and filesystem write behavior; low blast radius but incorrect handling could affect flag persistence or local file security. > > **Overview** > Hardens the Node client **platform** layer around flag disk cache and tightens related tests. > > **`NodeStorage`** now treats a missing cache file as a normal first run (no warning, no empty rewrite). Malformed or unreadable cache files trigger a **warn** and recovery write; loaded JSON must be a plain object and only **string** values are kept. Persists via an exclusive **`wx`** temp open (after removing any existing temp path) so writes cannot follow a symlink planted on the temp file path. **`getNodeStorage`** records the first `localStoragePath` and **warns** if a later call passes a different path; **`resetNodeStorage`** clears that path tracking too. > > **Tests** cover first-run behavior, malformed JSON warnings, non-string cache entries, symlink safety, singleton path mismatch warnings, and **`NodeInfo`** no longer pins the SDK **version** string in expectations. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 1962f54. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>  --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> Co-authored-by: Ryan Lamb <4955475+kinyoklion@users.noreply.github.com>

joker23 added a commit that referenced this pull request May 26, 2026

chore: Mark port-platform slice in-flight (PR #1393)

5e8fb6c

This comment was marked as resolved.

Sign in to view

joker23 marked this pull request as ready for review May 27, 2026 16:06

joker23 requested a review from a team as a code owner May 27, 2026 16:06

joker23 commented May 27, 2026

View reviewed changes

Comment thread packages/sdk/node-client/src/platform/NodeStorage.ts

This comment was marked as resolved.

Sign in to view

joker23 commented May 27, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

joker23 force-pushed the skz/sdk-2195/node-client-sdk-next-port-platform branch from e92eaf7 to 1f7be22 Compare May 27, 2026 17:01

This comment was marked as resolved.

Sign in to view

joker23 force-pushed the skz/sdk-2195/node-client-sdk-next-port-platform branch from fef5d25 to 8eb2ea3 Compare May 28, 2026 13:46

joker23 commented May 28, 2026

View reviewed changes

Comment thread packages/sdk/node-client/.gitignore Outdated

joker23 requested a review from kinyoklion May 28, 2026 14:29

This comment was marked as resolved.

Sign in to view

joker23 changed the title ~~feat: Add Node platform abstraction for node-client~~ chore: Add Node platform abstraction for node-client May 28, 2026

kinyoklion reviewed May 28, 2026

View reviewed changes

Comment thread packages/sdk/node-client/src/NodeOptions.ts

joker23 requested a review from kinyoklion May 28, 2026 17:21

joker23 force-pushed the skz/sdk-2195/node-client-sdk-next-port-platform branch from 25f5b8f to 9bfa020 Compare May 28, 2026 17:28

joker23 added a commit that referenced this pull request May 28, 2026

chore: Mark port-platform slice in-flight (PR #1393)

b1012c7

kinyoklion reviewed May 28, 2026

View reviewed changes

kinyoklion requested changes May 28, 2026

View reviewed changes

Comment thread packages/sdk/node-client/src/platform/NodeStorage.ts

joker23 requested a review from kinyoklion May 28, 2026 19:07

This comment was marked as resolved.

Sign in to view

joker23 added 12 commits May 29, 2026 09:48

feat: Add Node platform abstraction for node-client

3ec0694

test: adding unit tests for platform implementation

9ccfa48

ci: adding unit tests to CI

ed32841

chore: fix unit test

1578f9b

chore: bot comment

84c7cfb

chore: bot comment

0b0fad8

chore: lint issue

ef058c0

chore: bot comment

fded2ec

chore: adding jsdocs to options

bb3e8c0

chore: addressing PR comment

26962d2

chore: bot comment

b1e1075

chore: remove http proxy

eb89832

joker23 force-pushed the skz/sdk-2195/node-client-sdk-next-port-platform branch from 9a720a6 to eb89832 Compare May 29, 2026 13:48

kinyoklion approved these changes May 29, 2026

View reviewed changes

joker23 merged commit bce024c into main May 29, 2026
46 checks passed

joker23 deleted the skz/sdk-2195/node-client-sdk-next-port-platform branch May 29, 2026 15:56

joker23 mentioned this pull request Jun 1, 2026

chore(node-client): harden existing platform implementation #1403

Merged


		encoding?: platform.Encoding = new NodeEncoding();

		storage?: platform.Storage;

Conversation

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

Uh oh!

Summary

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

github-actions Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

github-actions Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joker23 commented May 27, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

joker23 commented May 27, 2026

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

joker23 May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kinyoklion May 28, 2026

Choose a reason for hiding this comment

Uh oh!

joker23 May 28, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

kinyoklion May 28, 2026

Choose a reason for hiding this comment

Uh oh!

joker23 May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

joker23 commented May 26, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented May 26, 2026 •

edited

Loading

github-actions Bot commented May 26, 2026 •

edited

Loading

joker23 May 27, 2026 •

edited

Loading