Skip to content

client: prepare etcd3 2.0 for Node.js 24 and ESM - #222

Merged
Connor Peet (connor4312) merged 15 commits into
mainfrom
connor4312/2.0-improvements-rebased
Oct 10, 2026
Merged

client: prepare etcd3 2.0 for Node.js 24 and ESM#222
Connor Peet (connor4312) merged 15 commits into
mainfrom
connor4312/2.0-improvements-rebased

Conversation

@connor4312

@connor4312 Connor Peet (connor4312) commented Oct 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

  • Modernize for Node.js 24, strict TypeScript, native bigint, and an ESM-only 2.0 release; refresh dependencies, tooling, generated APIs, and documentation.
  • Add async-iterable range streaming, dynamic endpoint management, queued distributed mutexes with fencing tokens, and explicit resource disposal.
  • Harden client lifecycle, namespaced reads, watches, leases, elections, locks, and transactions with expanded regression coverage.
  • Rebase the vacation work onto current main, retaining upstream dependency fixes and regenerating the lockfile for reproducible cross-platform installs.

Review notes

  • Breaking changes and migration examples are documented in changelog.md. Node.js 24+ and ESM imports are required.
  • The original connor4312/2.0-improvements remote branch is unchanged; this PR uses a separately published rebased branch.
  • The large documentation diff is the branch鈥檚 existing regenerated TypeDoc reference.

Verified CI compatibility fixes

  • Reproduced queued-watch creation failure against actual etcd 3.3.9 and checked the server implementation. Older servers stop receiving requests after a permission-denied creation; reopen the stream so existing and queued watchers recover. Added deterministic protocol regression coverage rather than skipping the integration regression.
  • Verified etcd 3.1 has no ignore_value field; gate tests for that etcd 3.2+ feature and document the touch requirement. Also avoid an empty conditional watch suite on 3.1.

Validation

  • Reproducible install, TypeScript build, lint, test type checking, documentation build, and diff whitespace checks passed locally.
  • Affected suites passed against actual etcd 3.3.9 and 3.6.14.
  • All five etcd targets passed in both push and pull-request CI: 3.1.5, 3.2.4, 3.3.9, 3.5.33, and 3.6.14 on Node.js 24.
  • CodeQL analysis and CLA checks passed.

Marked ready for review after CI passed.

Connor Peet (connor4312) and others added 15 commits October 9, 2026 16:50
@connor4312
feat!: modernize for Node.js 24
8440732 
Replace the legacy test and dependency toolchain, use native bigint revisions, enable strict TypeScript, and prepare the unreleased 2.0.0 line.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
feat!: publish as ESM only
7fc59e2 
Adopt NodeNext module semantics, ESM package exports, explicit runtime specifiers, and ESM-compatible maintenance tooling.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
feat: refresh etcd APIs and add range streaming
5e93976 
Regenerate RPC definitions from current upstream etcd, expose range responses as async iterables, and correct grpc-js server-stream argument ordering.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
chore: remove lodash dependency
fb41691 
Replace Lodash usage in build scripts with native helpers while preserving generated output.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
docs: refresh TypeDoc API reference
b6a6c6b 
Regenerate the API documentation with the current TypeDoc theme and remove the obsolete HTML post-processing step. Preserve exact-case generated paths so links work on case-sensitive GitHub Pages hosts.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
test: restore watch interruption coverage
cb35528 
Re-enable reconnect and historical replay scenarios while making the TLS proxy lifecycle deterministic and leak-free.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
fix: harden coordination and transaction correctness
9d5a532 
Add regression coverage and correct watch queue recovery, election and lock lifecycle handling, STM conflict and write semantics, namespace root ranges, and role and lease error behavior.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
fix: harden client lifecycle and range correctness
2e64668 
Make watch and election lifecycle transitions terminal and race-safe, preserve cleanup call semantics, and correct transaction and range state handling. Add regressions for each failure across coordination, STM, namespacing, authentication, and transport behavior.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
fix: harden asynchronous client state
e86e468 
Preserve watch and election lifecycle state across races, make lease and STM operations internally consistent, and handle authentication per etcd member. Add bounded token refresh, safe stream cancellation, awaitable transaction builders, and regressions for each corrected call flow.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
fix: harden namespaced reads and stream recovery
dea32da 
Return logical keys from namespaced raw and previous-value reads without mutating STM caches, and make transaction thenables handle zero-argument assimilation safely.\n\nAllow authentication retries to progress across members, classify iterator aborts as local stream cancellation, and deduplicate watch error/end termination.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
feat: add dynamic endpoint management
e4e6df1 
Allow endpoint lists to be replaced at runtime and synchronized from voting cluster members. Support configurable automatic synchronization, mutable intervals, warning events, and safe pool reconciliation across auth and TLS settings.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 22302cc3-f672-4b8b-829d-aea289a49011
@connor4312
feat: add queued distributed mutexes
c588525 
Add FIFO lease-backed mutex acquisition with async-disposable guards, cancellation, fencing tokens, and atomic ownership checks. Preserve the existing immediate Lock API and owner-key protocol for rolling-upgrade compatibility.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: d3c3a109-a377-48db-bb6f-7cbb8294426b
@connor4312
feat: add explicit resource disposal
4b57088 
Support using for clients and low-level streams, and await using for watchers, leases, legacy locks, campaigns, and election observers. Delegate disposal to the existing lifecycle methods so explicit cleanup remains compatible.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: e09b36b9-47d1-4e7a-9e66-5dd01a1572a0
@connor4312
chore: normalize lockfile after rebasing onto main
5387fd5 
Keep the npm v3 lockfile format and include all optional platform dependencies while retaining upstream dependency fixes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
fix: recover watches after legacy etcd creation rejection
6f7b907 
Older etcd servers stop receiving watch requests after a denied creation. Reopen the stream so existing and queued watchers can recover, with protocol and integration regression coverage.

Skip unsupported ignore_value tests on etcd 3.1, document the etcd 3.2 minimum for touch, and avoid empty version-dependent test suites.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@connor4312
Connor Peet (connor4312) marked this pull request as ready for review October 10, 2026 00:04
@connor4312
Connor Peet (connor4312) merged commit a0d1d3c into main Oct 10, 2026
15 checks passed
@connor4312
Connor Peet (connor4312) deleted the connor4312/2.0-improvements-rebased branch October 10, 2026 00:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rzhao271 Raymond Zhao (rzhao271) rzhao271 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@connor4312 @rzhao271