Standardized gremlin-js connection options

[GumpacG]

Standardize gremlin-javascript connection options

Implements the JavaScript portion of the TinkerPop 4.x GLV connection-options standardization. Adopts undici as a pinned dependency and builds an explicit dispatcher so the standardized options take effect, adds a set of new options, removes dead WebSocket-era fields, and deprecates headers. JavaScript driver changes only; the other GLVs follow in separate PRs.

Proposal: https://lists.apache.org/thread/yqtr2wnb1kq2pqqq4002cz511q5o0bkg

New options

• maxConnections (128) - caps concurrent connections per origin on the default dispatcher (previously uncapped). (breaking)
• readTimeout - per-read idle (body) timeout in ms (undici bodyTimeout); resets per chunk, so it is streaming-safe.
• maxResponseHeaderBytes - maximum response header size in bytes (undici maxHeaderSize).
• keepAliveTime (30000 ms) - idle time before TCP keep-alive probes begin; enables SO_KEEPALIVE via a custom undici connector. Set 0 to disable.
• proxy - HTTP proxy URI; routes requests through an undici ProxyAgent.
• compression ('none'/'deflate', default 'deflate') - the wire compression negotiated with the server. (breaking)
• defaultBatchSize (64) - connection-level default that fills a request's batchSize when unset.
• bulkResults (default false) - connection-level default for bulkResults, applied to every request unless overridden per-request. The DriverRemoteConnection traversal path defaults to true regardless of this setting.
• logger - a logger object (with debug/info/warn/error methods) or a (level, message, ...args) callback. Disabled when unset.

Behavior changes (breaking)

• Adopted undici as a pinned dependency (6.27.0). The driver now builds and owns an explicit undici dispatcher from the discrete options above; previously the options were declared but not wired to anything.
• compression defaults to 'deflate' (on), so the driver sends Accept-Encoding: deflate by default. Set compression: 'none' to disable; this also suppresses the auto-injected Accept-Encoding so compression is not silently negotiated. Defaulting on is a deliberate deviation from the proposal's agreed default-off, applied consistently across the GLVs by later agreement.
• maxConnections now caps concurrent connections at 128 (was uncapped).

Removed (breaking)

• The dead agent, ca, cert, pfx, and rejectUnauthorized TLS fields - they were declared (WebSocket-era leftovers) but never wired to the HTTP transport. TLS is now configured through the Node/undici runtime (NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED).

Deprecated

• headers - retained as a deprecated option (implemented via a synthesized interceptor that emits a one-time warning). Set custom headers via an interceptor instead, e.g. interceptors: (req) => { req.headers['X-Custom'] = 'value'; }.

Bug fix

• Fixed Client.submit() so that an explicit bulkResults: false request option is forwarded to the server instead of being silently dropped.

Notes

• Per the proposal, JS does not expose connectTimeout/idleTimeout/writeTimeout as driver options (the undici runtime defaults are used), and TLS is runtime-delegated rather than a driver option. No public dispatcher option is exposed; the dispatcher is built internally from the discrete options.

Testing

• gremlin-javascript builds (dual CJS/ESM) and all 358 unit tests pass, including new client, connection, dispatcher, and logger suites covering the option-to-undici mapping, compression negotiation, keep-alive wiring, and bulkResults precedence.

Assisted-by: Kiro: Claude Opus 4.8

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.43%. Comparing base (a28cd1f) to head (ba19599).
⚠️ Report is 126 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3472      +/-   ##
============================================
+ Coverage     76.35%   76.43%   +0.07%     
- Complexity    13424    13666     +242     
============================================
  Files          1012     1025      +13     
  Lines         60341    61656    +1315     
  Branches       7075     7204     +129     
============================================
+ Hits          46076    47127    +1051     
- Misses        11548    11676     +128     
- Partials       2717     2853     +136     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kenhuuu]

A community member spent quite a bit of effort trying to make the javascript driver work in the browser. Will this dependency make it impossible for it to work in the browser moving forward?

[spmallette]

not sure what's possible, but can we produce a smoke test of some sort that would help defend that functionality?

[GumpacG]

I added dispatcher.browser.ts for browsers and throw if users try to set the unsupported connection options in a browser.

I tested this manually with example in examples/browser. As for a smoke test, I created a follow up ticket https://issues.apache.org/jira/browse/TINKERPOP-3260 to implement this.