gremlin 3.8.1 → 4.0.0-beta.3

package/build/cjs/driver/connection.cjs

@@ -0,0 +1,363 @@
+"use strict";
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BATCH_SIZE = void 0;
+/**
+ * @author Jorge Bay Gondra
+ */
+const buffer_1 = require("node:buffer");
+const eventemitter3_1 = require("eventemitter3");
+const GraphBinary_js_1 = __importStar(require("../structure/io/binary/GraphBinary.cjs"));
+const GraphBinaryReader_js_1 = __importDefault(require("../structure/io/binary/internals/GraphBinaryReader.cjs"));
+const StreamReader_js_1 = __importDefault(require("../structure/io/binary/internals/StreamReader.cjs"));
+const utils = __importStar(require("../utils.cjs"));
+const result_set_js_1 = __importDefault(require("./result-set.cjs"));
+const request_message_js_1 = require("./request-message.cjs");
+const http_request_js_1 = require("./http-request.cjs");
+const response_error_js_1 = __importDefault(require("./response-error.cjs"));
+const traversal_js_1 = require("../process/traversal.cjs");
+const dispatcher_js_1 = require("./dispatcher.cjs");
+const logger_js_1 = require("./logger.cjs");
+const responseStatusCode = {
+    success: 200,
+    noContent: 204,
+    partialContent: 206,
+};
+/** The default per-request batch size used when neither the request nor the connection sets one. */
+exports.DEFAULT_BATCH_SIZE = 64;
+/**
+ * Represents a single connection to a Gremlin Server.
+ */
+class Connection extends eventemitter3_1.EventEmitter {
+    url;
+    options;
+    _responseSerializer;
+    isOpen = true;
+    traversalSource;
+    _enableUserAgentOnConnect;
+    _interceptors;
+    _dispatcher;
+    _compression;
+    _batchSize;
+    _bulkResults;
+    _log;
+    /**
+     * Creates a new instance of {@link Connection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url, options = {}) {
+        super();
+        this.url = url;
+        this.options = options;
+        this._responseSerializer =
+            options.responseSerializer || (options.preciseNumbers === true ? (0, GraphBinary_js_1.createPreciseReader)() : new GraphBinaryReader_js_1.default(GraphBinary_js_1.default));
+        if (options.pdtRegistry) {
+            this._responseSerializer.pdtRegistry = options.pdtRegistry;
+        }
+        this.traversalSource = options.traversalSource || 'g';
+        this._enableUserAgentOnConnect = options.enableUserAgentOnConnect !== false;
+        this._log = (0, logger_js_1.normalizeLogger)(options.logger);
+        if (options.compression === undefined) {
+            this._compression = 'deflate';
+        }
+        else if (options.compression === 'none' || options.compression === 'deflate') {
+            this._compression = options.compression;
+        }
+        else {
+            throw new TypeError(`compression must be 'none' or 'deflate'`);
+        }
+        this._batchSize = options.batchSize ?? exports.DEFAULT_BATCH_SIZE;
+        this._bulkResults = options.bulkResults ?? false;
+        // The driver builds and owns the undici dispatcher from the discrete options.
+        // TLS is configured through the Node/undici runtime (e.g. NODE_EXTRA_CA_CERTS),
+        // not through a driver option.
+        this._dispatcher = (0, dispatcher_js_1.buildDispatcher)({
+            maxConnections: options.maxConnections,
+            readTimeoutMillis: options.readTimeoutMillis,
+            maxResponseHeaderBytes: options.maxResponseHeaderBytes,
+            keepAliveTimeMillis: options.keepAliveTimeMillis,
+            proxy: options.proxy,
+        });
+        const interceptors = options.interceptors;
+        if (typeof interceptors === 'function') {
+            this._interceptors = [interceptors];
+        }
+        else if (Array.isArray(interceptors)) {
+            this._interceptors = [...interceptors];
+        }
+        else if (interceptors === undefined || interceptors === null) {
+            this._interceptors = [];
+        }
+        else {
+            throw new TypeError('interceptors must be a function, array, or undefined');
+        }
+        // Auth interceptor is always last so it runs after user interceptors
+        if (options.auth) {
+            this._interceptors.push(options.auth);
+        }
+        this._log('debug', `Connection created for ${this.url}`);
+    }
+    /**
+     * The connection-level default batch size, used to fill a request's `batchSize` when unset.
+     */
+    get batchSize() {
+        return this._batchSize;
+    }
+    /**
+     * The connection-level default for `bulkResults`, applied to every request unless overridden
+     * per-request. Defaults to `false`.
+     */
+    get bulkResults() {
+        return this._bulkResults;
+    }
+    /**
+     * Opens the connection, if its not already opened.
+     * @returns {Promise}
+     */
+    async open() {
+        // No-op for HTTP connections
+        return Promise.resolve();
+    }
+    /**
+     * Send a request and buffer the entire response. Returns a Promise<ResultSet>.
+     */
+    async submit(request) {
+        const response = await this.#makeHttpRequest(request);
+        return this.#handleResponse(response);
+    }
+    /**
+     * Send a request and stream the response incrementally.
+     * Returns an AsyncGenerator that yields deserialized result items.
+     * For bulked responses, yields Traverser objects.
+     *
+     * In the GraphBinary v4 streaming protocol, the server sends the status after all
+     * result data. If the server encounters an error mid-traversal, values yielded before
+     * the error are valid partial results. A ResponseError is thrown after the last value
+     * has been yielded.
+     *
+     * @param {RequestMessage} request
+     * @returns {AsyncGenerator<any>}
+     */
+    async *stream(request) {
+        const abortController = new AbortController();
+        let response;
+        try {
+            response = await this.#makeHttpRequest(request, abortController.signal);
+        }
+        catch (e) {
+            throw new Error(`Stream request failed: ${e.message}`, { cause: e });
+        }
+        if (!response.ok) {
+            // For error responses, buffer and parse the error body
+            const buffer = buffer_1.Buffer.from(await response.arrayBuffer());
+            const errorMessage = `Server returned HTTP ${response.status}: ${response.statusText}`;
+            const contentType = response.headers.get("Content-Type");
+            const reader = this.#getReaderForContentType(contentType);
+            try {
+                if (reader) {
+                    const deserialized = await reader.readResponse(buffer);
+                    throw new response_error_js_1.default(errorMessage, {
+                        code: deserialized.status.code,
+                        message: deserialized.status.message || response.statusText,
+                        exception: deserialized.status.exception,
+                    });
+                }
+                else if (contentType === 'application/json') {
+                    const errorBody = JSON.parse(buffer.toString());
+                    throw new response_error_js_1.default(errorMessage, {
+                        code: response.status,
+                        message: errorBody.message || errorBody.error || response.statusText,
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof response_error_js_1.default)
+                    throw err;
+            }
+            throw new response_error_js_1.default(errorMessage, {
+                code: response.status,
+                message: response.statusText,
+            });
+        }
+        if (!response.body) {
+            // 204 No Content - nothing to yield
+            return;
+        }
+        const streamReader = StreamReader_js_1.default.fromReadableStream(response.body);
+        let completed = false;
+        try {
+            yield* this._responseSerializer.readResponseStream(streamReader);
+            completed = true;
+        }
+        finally {
+            if (!completed) {
+                // Consumer broke out early or an error occurred - abort to release the connection
+                abortController.abort();
+            }
+        }
+    }
+    #getReaderForContentType(contentType) {
+        if (!contentType) {
+            return this._responseSerializer;
+        }
+        if (contentType === this._responseSerializer.mimeType) {
+            return this._responseSerializer;
+        }
+        return null;
+    }
+    async #makeHttpRequest(request, signal) {
+        const headers = {
+            'Accept': this._responseSerializer.mimeType,
+        };
+        if (this._compression === 'deflate') {
+            headers['Accept-Encoding'] = 'deflate';
+        }
+        if (this._enableUserAgentOnConnect) {
+            const userAgent = await utils.getUserAgent();
+            if (userAgent !== undefined) {
+                headers[utils.getUserAgentHeader()] = userAgent;
+            }
+        }
+        const httpRequest = new http_request_js_1.HttpRequest('POST', this.url, headers, request);
+        // Promote transactionId to HTTP header before interceptors run.
+        // The field remains in the serialized body as well (dual transmission
+        // per the HTTP transaction protocol specification).
+        if (request instanceof request_message_js_1.RequestMessage) {
+            const fields = request.getFields();
+            if (fields.has('transactionId')) {
+                httpRequest.headers['X-Transaction-Id'] = fields.get('transactionId');
+            }
+        }
+        for (let i = 0; i < this._interceptors.length; i++) {
+            try {
+                await this._interceptors[i](httpRequest);
+            }
+            catch (e) {
+                throw new Error(`Request interceptor at index ${i} failed: ${e.message}`, { cause: e });
+            }
+        }
+        // Auto-serialize body to JSON after interceptors run (idempotent if already serialized)
+        httpRequest.serializeBody();
+        this._log('debug', `Sending ${httpRequest.method} request to ${httpRequest.url}`);
+        return dispatcher_js_1.httpFetch.fetch(httpRequest.url, {
+            method: httpRequest.method,
+            headers: httpRequest.headers,
+            body: httpRequest.body,
+            signal,
+            // Node only: the undici dispatcher carries the connection-pool options. In the browser
+            // it is undefined and the field is omitted, letting the user agent manage the transport.
+            ...(this._dispatcher ? { dispatcher: this._dispatcher } : {}),
+        });
+    }
+    async #handleResponse(response) {
+        const contentType = response.headers.get("Content-Type");
+        const buffer = buffer_1.Buffer.from(await response.arrayBuffer());
+        const reader = this.#getReaderForContentType(contentType);
+        if (!response.ok) {
+            const errorMessage = `Server returned HTTP ${response.status}: ${response.statusText}`;
+            try {
+                if (reader) {
+                    const deserialized = await reader.readResponse(buffer);
+                    throw new response_error_js_1.default(errorMessage, {
+                        code: deserialized.status.code,
+                        message: deserialized.status.message || response.statusText,
+                        exception: deserialized.status.exception,
+                    });
+                }
+                else if (contentType === 'application/json') {
+                    const errorBody = JSON.parse(buffer.toString());
+                    throw new response_error_js_1.default(errorMessage, {
+                        code: response.status,
+                        message: errorBody.message || errorBody.error || response.statusText,
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof response_error_js_1.default) {
+                    throw err;
+                }
+            }
+            throw new response_error_js_1.default(errorMessage, {
+                code: response.status,
+                message: response.statusText,
+            });
+        }
+        if (!reader) {
+            throw new Error(`Response Content-Type '${contentType}' does not match the configured response serializer (expected '${this._responseSerializer.mimeType}')`);
+        }
+        const deserialized = await reader.readResponse(buffer);
+        if (deserialized.status.code && deserialized.status.code !== responseStatusCode.success && deserialized.status.code !== responseStatusCode.noContent && deserialized.status.code !== responseStatusCode.partialContent) {
+            throw new response_error_js_1.default(`Server error: ${deserialized.status.message || 'Unknown error'} (${deserialized.status.code})`, {
+                code: deserialized.status.code,
+                message: deserialized.status.message || '',
+                exception: deserialized.status.exception,
+            });
+        }
+        return new result_set_js_1.default(deserialized.result.bulked
+            ? deserialized.result.data.map((item) => new traversal_js_1.Traverser(item.v, item.bulk))
+            : deserialized.result.data, new Map());
+    }
+    /**
+     * Closes the Connection.
+     * @return {Promise}
+     */
+    async close() {
+        this._log('debug', `Closing connection to ${this.url}`);
+        await this._dispatcher?.close();
+    }
+}
+exports.default = Connection;

package/build/cjs/driver/connection.d.cts

@@ -0,0 +1,106 @@
+import { EventEmitter } from 'eventemitter3';
+import ResultSet from './result-set.cjs';
+import { RequestMessage } from "./request-message.cjs";
+import { RequestInterceptor } from './http-request.cjs';
+import { Logger } from './logger.cjs';
+/**
+ * Selects the content encoding requested from, and decoded for, the server. `'deflate'` (the
+ * default) sends an `Accept-Encoding: deflate` header and decodes deflate responses; `'none'`
+ * turns compression off.
+ */
+export type Compression = 'none' | 'deflate';
+export type ConnectionOptions = {
+    preciseNumbers?: boolean;
+    pdtRegistry?: any;
+    responseSerializer?: any;
+    traversalSource?: string;
+    enableUserAgentOnConnect?: boolean;
+    /** Maximum number of concurrent connections per origin. Defaults to 128. */
+    maxConnections?: number;
+    /** Read timeout in ms, applied to the default dispatcher. Maps to undici `headersTimeout` (wait for first response byte) and `bodyTimeout` (idle between body chunks). */
+    readTimeoutMillis?: number;
+    /** Maximum size of the response headers in bytes, applied to the default dispatcher. */
+    maxResponseHeaderBytes?: number;
+    /**
+     * Idle time in milliseconds before TCP keep-alive probes begin on a connection. Defaults to
+     * 30000 (30s) when unset. Set to `0` to disable keep-alive entirely.
+     */
+    keepAliveTimeMillis?: number;
+    /** HTTP proxy URI. When set, requests are routed through an undici `ProxyAgent`. */
+    proxy?: string;
+    /** Response compression codec. Defaults to `'deflate'` (on). */
+    compression?: Compression;
+    /** Connection-level default that fills a request's `batchSize` when it is left unset. Defaults to 64. */
+    batchSize?: number;
+    /** Connection-level default for `bulkResults`, applied to every request unless overridden per-request. Defaults to `false`. */
+    bulkResults?: boolean;
+    /** An optional logger (a logger object or a callback). Logging is disabled when unset. */
+    logger?: Logger;
+    interceptors?: RequestInterceptor | RequestInterceptor[];
+    /** An optional auth interceptor. As a convenience, this is always appended to the end of the
+     *  interceptor list so it runs last, after any user interceptors have modified the request. */
+    auth?: RequestInterceptor;
+};
+/** The default per-request batch size used when neither the request nor the connection sets one. */
+export declare const DEFAULT_BATCH_SIZE = 64;
+/**
+ * Represents a single connection to a Gremlin Server.
+ */
+export default class Connection extends EventEmitter {
+    #private;
+    readonly url: string;
+    readonly options: ConnectionOptions;
+    private readonly _responseSerializer;
+    isOpen: boolean;
+    traversalSource: string;
+    private readonly _enableUserAgentOnConnect;
+    private readonly _interceptors;
+    private readonly _dispatcher;
+    private readonly _compression;
+    private readonly _batchSize;
+    private readonly _bulkResults;
+    private readonly _log;
+    /**
+     * Creates a new instance of {@link Connection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url: string, options?: ConnectionOptions);
+    /**
+     * The connection-level default batch size, used to fill a request's `batchSize` when unset.
+     */
+    get batchSize(): number;
+    /**
+     * The connection-level default for `bulkResults`, applied to every request unless overridden
+     * per-request. Defaults to `false`.
+     */
+    get bulkResults(): boolean;
+    /**
+     * Opens the connection, if its not already opened.
+     * @returns {Promise}
+     */
+    open(): Promise<void>;
+    /**
+     * Send a request and buffer the entire response. Returns a Promise<ResultSet>.
+     */
+    submit(request: RequestMessage): Promise<ResultSet>;
+    /**
+     * Send a request and stream the response incrementally.
+     * Returns an AsyncGenerator that yields deserialized result items.
+     * For bulked responses, yields Traverser objects.
+     *
+     * In the GraphBinary v4 streaming protocol, the server sends the status after all
+     * result data. If the server encounters an error mid-traversal, values yielded before
+     * the error are valid partial results. A ResponseError is thrown after the last value
+     * has been yielded.
+     *
+     * @param {RequestMessage} request
+     * @returns {AsyncGenerator<any>}
+     */
+    stream(request: RequestMessage): AsyncGenerator<any>;
+    /**
+     * Closes the Connection.
+     * @return {Promise}
+     */
+    close(): Promise<void>;
+}

package/build/cjs/driver/dispatcher.browser.cjs

@@ -0,0 +1,57 @@
+"use strict";
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpFetch = void 0;
+exports.buildDispatcher = buildDispatcher;
+/**
+ * Connection-pool / transport options that only the Node (`undici`) dispatcher can honor. The
+ * browser's HTTP stack owns these concerns and exposes no `fetch` API to configure them, so they
+ * are rejected here rather than silently ignored. `readTimeoutMillis` is intentionally not in this list:
+ * it has a browser analog (an `AbortSignal`-based timeout) and is handled by the connection.
+ */
+const NODE_ONLY_OPTIONS = [
+    'maxConnections',
+    'keepAliveTimeMillis',
+    'maxResponseHeaderBytes',
+    'proxy',
+];
+/**
+ * In the browser there is no `undici` dispatcher, so `fetch` is issued without one and the browser
+ * manages the transport. Any {@link NODE_ONLY_OPTIONS} set explicitly cannot be honored and throws,
+ * so a misconfiguration surfaces immediately instead of being silently dropped. With none set this
+ * returns `undefined` and the connection omits the `dispatcher` field.
+ */
+function buildDispatcher(options = {}) {
+    const unsupported = NODE_ONLY_OPTIONS.filter((key) => options[key] !== undefined);
+    if (unsupported.length > 0) {
+        throw new Error(`The following connection options are not supported in the browser and are managed by the ` +
+            `browser's HTTP stack: ${unsupported.join(', ')}. Remove them when running in a browser ` +
+            `(they are supported in Node).`);
+    }
+    return undefined;
+}
+/**
+ * Browser counterpart of the Node `httpFetch` holder. There is no `undici` in the browser, so
+ * requests use the global `fetch` and the user agent manages the transport. Same holder shape as
+ * the Node build.
+ */
+exports.httpFetch = {
+    fetch: globalThis.fetch.bind(globalThis),
+};

package/build/cjs/driver/dispatcher.browser.d.cts

@@ -0,0 +1,35 @@
+/**
+ * Browser counterpart of {@link ./dispatcher.ts}. The Node build configures the underlying HTTP
+ * transport through an `undici` dispatcher, but `undici` is built on `node:net`/`node:tls` and
+ * cannot run in a browser. Bundlers pick this file up via the `"browser"` field in `package.json`,
+ * so a browser bundle never imports `undici`.
+ *
+ * The browser's HTTP stack manages the connection-pool options that the Node dispatcher carries,
+ * so {@link buildDispatcher} throws if any is set explicitly (rather than silently ignoring it)
+ * and otherwise returns `undefined`, leaving the connection to issue a plain `fetch`. It is the
+ * only export the connection imports through the swapped `./dispatcher.cjs` path.
+ */
+/** Transport options accepted by {@link buildDispatcher}; mirrors the Node dispatcher's options. */
+type DispatcherOptions = {
+    maxConnections?: number;
+    readTimeoutMillis?: number;
+    maxResponseHeaderBytes?: number;
+    keepAliveTimeMillis?: number;
+    proxy?: string;
+};
+/**
+ * In the browser there is no `undici` dispatcher, so `fetch` is issued without one and the browser
+ * manages the transport. Any {@link NODE_ONLY_OPTIONS} set explicitly cannot be honored and throws,
+ * so a misconfiguration surfaces immediately instead of being silently dropped. With none set this
+ * returns `undefined` and the connection omits the `dispatcher` field.
+ */
+export declare function buildDispatcher(options?: DispatcherOptions): undefined;
+/**
+ * Browser counterpart of the Node `httpFetch` holder. There is no `undici` in the browser, so
+ * requests use the global `fetch` and the user agent manages the transport. Same holder shape as
+ * the Node build.
+ */
+export declare const httpFetch: {
+    fetch: typeof globalThis.fetch;
+};
+export {};

package/build/cjs/driver/dispatcher.cjs

@@ -0,0 +1,101 @@
+"use strict";
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpFetch = exports.DEFAULT_KEEP_ALIVE_TIME = exports.DEFAULT_MAX_CONNECTIONS = void 0;
+exports.resolveKeepAliveTime = resolveKeepAliveTime;
+exports.buildKeepAliveConnector = buildKeepAliveConnector;
+exports.buildAgentOptions = buildAgentOptions;
+exports.buildDispatcher = buildDispatcher;
+const undici_1 = require("undici");
+/** Default concurrent-connections-per-origin cap (Node's global fetch is uncapped). */
+exports.DEFAULT_MAX_CONNECTIONS = 128;
+/** Canonical TinkerPop 4.x default TCP keep-alive idle time (30s), shared across the GLVs. */
+exports.DEFAULT_KEEP_ALIVE_TIME = 30000;
+/**
+ * Resolves the effective keep-alive idle delay: unset falls back to {@link DEFAULT_KEEP_ALIVE_TIME},
+ * a non-positive value disables keep-alive (returns `null`).
+ */
+function resolveKeepAliveTime(keepAliveTime) {
+    const effective = keepAliveTime ?? exports.DEFAULT_KEEP_ALIVE_TIME;
+    return effective > 0 ? effective : null;
+}
+/**
+ * Builds an undici connector that sets `SO_KEEPALIVE` with the given idle delay on each new socket.
+ * `baseConnector` is parameterised so the wiring can be unit-tested with a fake connector.
+ */
+function buildKeepAliveConnector(delay, baseConnector = (0, undici_1.buildConnector)({})) {
+    return (connectOptions, callback) => {
+        baseConnector(connectOptions, (err, socket) => {
+            if (err) {
+                callback(err, null);
+                return;
+            }
+            if (socket) {
+                socket.setKeepAlive(true, delay);
+            }
+            callback(null, socket);
+        });
+    };
+}
+/**
+ * Maps the discrete driver options onto undici {@link Agent.Options} (the single source of truth
+ * for that mapping). Exported as a seam so the mapping can be asserted in unit tests.
+ */
+function buildAgentOptions(options = {}) {
+    const maxConnections = options.maxConnections ?? exports.DEFAULT_MAX_CONNECTIONS;
+    const agentOptions = {
+        connections: maxConnections,
+    };
+    // Connect/idle timeouts are intentionally left to undici defaults (the GLV spec marks the JS
+    // connect/idle timeout as N/A), not exposed as driver options.
+    if (options.readTimeoutMillis !== undefined) {
+        agentOptions.headersTimeout = options.readTimeoutMillis;
+        agentOptions.bodyTimeout = options.readTimeoutMillis;
+    }
+    if (options.maxResponseHeaderBytes !== undefined) {
+        agentOptions.maxHeaderSize = options.maxResponseHeaderBytes;
+    }
+    const keepAliveDelay = resolveKeepAliveTime(options.keepAliveTimeMillis);
+    if (keepAliveDelay !== null) {
+        agentOptions.connect = buildKeepAliveConnector(keepAliveDelay);
+    }
+    return agentOptions;
+}
+/**
+ * Builds the default undici {@link Dispatcher}: a {@link ProxyAgent} when `proxy` is set, otherwise
+ * a plain {@link Agent}. (Agent and ProxyAgent share one dispatcher slot, so only one is built.)
+ */
+function buildDispatcher(options = {}) {
+    const agentOptions = buildAgentOptions(options);
+    if (options.proxy) {
+        return new undici_1.ProxyAgent({ uri: options.proxy, ...agentOptions });
+    }
+    return new undici_1.Agent(agentOptions);
+}
+/**
+ * HTTP `fetch` for the Node build. Uses undici's own `fetch` (not the global one) so `fetch` and the
+ * {@link buildDispatcher} dispatcher share one undici version, whatever undici the Node runtime
+ * bundles (e.g. Node 26 ships undici 8, incompatible with an undici 6 dispatcher). A holder object,
+ * not a bare export, so tests can swap `fetch` (an ESM export can't be reassigned, an object
+ * property can). The cast aligns undici's `fetch` type with the global one.
+ */
+exports.httpFetch = {
+    fetch: undici_1.fetch,
+};