gremlin 3.8.1 → 4.0.0-beta.3

package/build/esm/driver/client.js

@@ -0,0 +1,172 @@
+/*
+ *  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.
+ */
+import Connection from './connection.js';
+import { RequestMessage } from "./request-message.js";
+import { Transaction } from '../process/transaction.js';
+/**
+ * A {@link Client} contains methods to send messages to a Gremlin Server.
+ */
+export default class Client {
+    url;
+    options;
+    _connection;
+    /**
+     * Creates a new instance of {@link Client}.
+     * @param {String} url The resource uri.
+     * @param {ClientOptions} [options] The connection options.
+     */
+    // Tracks open transactions for cascade rollback on close. JS Set iteration
+    // is safe during concurrent modification (deleting the current element during
+    // for-of is spec-guaranteed to not affect remaining iterations).
+    _trackedTransactions = new Set();
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = options;
+        this._connection = new Connection(url, options);
+    }
+    /**
+     * Opens the underlying connection to the Gremlin Server, if it's not already opened.
+     * @returns {Promise}
+     */
+    open() {
+        return this._connection.open();
+    }
+    /**
+     * Returns true if the underlying connection is open
+     * @returns {Boolean}
+     */
+    get isOpen() {
+        return this._connection.isOpen;
+    }
+    /**
+     * Send a request to the Gremlin Server and buffer the entire response.
+     * @param {string} message The script to send
+     * @param {Object|null} [parameters] The query parameters, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {Promise<ResultSet>}
+     */
+    submit(message, parameters, requestOptions) {
+        return this._connection.submit(this.#buildRequest(message, parameters, requestOptions));
+    }
+    /**
+     * Send a request to the Gremlin Server and stream results incrementally.
+     * Returns an AsyncGenerator that yields individual result items as they are
+     * deserialized from the response. For bulked responses, yields Traverser objects.
+     * @param {string} message The script to send
+     * @param {Object|null} [parameters] The query parameters, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {AsyncGenerator<any>}
+     */
+    async *stream(message, parameters, requestOptions) {
+        return yield* this._connection.stream(this.#buildRequest(message, parameters, requestOptions));
+    }
+    #buildRequest(message, parameters, requestOptions) {
+        const requestBuilder = RequestMessage.build(message)
+            .addG(this.options.traversalSource || 'g');
+        if (requestOptions?.language) {
+            requestBuilder.addLanguage(requestOptions.language);
+        }
+        if (requestOptions?.parameters) {
+            if (typeof requestOptions.parameters === 'string') {
+                requestBuilder.addParametersString(requestOptions.parameters);
+            }
+            else {
+                requestBuilder.addParameters(requestOptions.parameters);
+            }
+        }
+        if (parameters) {
+            if (typeof parameters === 'string') {
+                requestBuilder.addParametersString(parameters);
+            }
+            else {
+                requestBuilder.addParameters(parameters);
+            }
+        }
+        if (requestOptions?.materializeProperties) {
+            requestBuilder.addMaterializeProperties(requestOptions.materializeProperties);
+        }
+        if (requestOptions?.timeoutMillis) {
+            requestBuilder.addTimeoutMillis(requestOptions.timeoutMillis);
+        }
+        // Per-request value wins (including an explicit `false`); otherwise apply the
+        // connection-level default only when it is true.
+        if (requestOptions?.bulkResults !== undefined) {
+            requestBuilder.addBulkResults(requestOptions.bulkResults);
+        }
+        else if (this._connection.bulkResults) {
+            requestBuilder.addBulkResults(true);
+        }
+        // Fill the per-request batchSize from the connection-level default when unset.
+        const batchSize = requestOptions?.batchSize ?? this._connection.batchSize;
+        if (batchSize !== undefined) {
+            requestBuilder.addBatchSize(batchSize);
+        }
+        if (requestOptions?.transactionId) {
+            requestBuilder.addField('transactionId', requestOptions.transactionId);
+        }
+        return requestBuilder.create();
+    }
+    /**
+     * Closes the underlying connection
+     * @returns {Promise}
+     */
+    async close() {
+        // Best-effort rollback of any open transactions before closing connections
+        for (const tx of this._trackedTransactions) {
+            try {
+                await tx.close();
+            }
+            catch { }
+        }
+        this._trackedTransactions.clear();
+        return this._connection.close();
+    }
+    trackTransaction(tx) {
+        this._trackedTransactions.add(tx);
+    }
+    untrackTransaction(tx) {
+        this._trackedTransactions.delete(tx);
+    }
+    /**
+     * Creates a new Transaction for executing operations within an explicit transaction.
+     * Transactions are short-lived and single-use. After commit or rollback,
+     * create a new Transaction for the next unit of work.
+     * The traversal source (g alias) is inherited from this Client.
+     * @returns {Transaction}
+     */
+    transact() {
+        return new Transaction(this);
+    }
+    /**
+     * Adds an event listener to the connection
+     * @param {String} event The event name that you want to listen to.
+     * @param {Function} handler The callback to be called when the event occurs.
+     */
+    addListener(event, handler) {
+        this._connection.on(event, handler);
+    }
+    /**
+     * Removes a previously added event listener to the connection
+     * @param {String} event The event name that you want to listen to.
+     * @param {Function} handler The event handler to be removed.
+     */
+    removeListener(event, handler) {
+        this._connection.removeListener(event, handler);
+    }
+}

package/build/esm/driver/connection.d.ts

@@ -0,0 +1,106 @@
+import { EventEmitter } from 'eventemitter3';
+import ResultSet from './result-set.js';
+import { RequestMessage } from "./request-message.js";
+import { RequestInterceptor } from './http-request.js';
+import { Logger } from './logger.js';
+/**
+ * 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/esm/driver/connection.js

@@ -0,0 +1,323 @@
+/*
+ *  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.
+ */
+/**
+ * @author Jorge Bay Gondra
+ */
+import { Buffer } from 'buffer';
+import { EventEmitter } from 'eventemitter3';
+import ioc, { createPreciseReader } from '../structure/io/binary/GraphBinary.js';
+import GraphBinaryReader from '../structure/io/binary/internals/GraphBinaryReader.js';
+import StreamReader from '../structure/io/binary/internals/StreamReader.js';
+import * as utils from '../utils.js';
+import ResultSet from './result-set.js';
+import { RequestMessage } from "./request-message.js";
+import { HttpRequest } from './http-request.js';
+import ResponseError from './response-error.js';
+import { Traverser } from '../process/traversal.js';
+import { buildDispatcher, httpFetch } from './dispatcher.js';
+import { normalizeLogger } from './logger.js';
+const responseStatusCode = {
+    success: 200,
+    noContent: 204,
+    partialContent: 206,
+};
+/** The default per-request batch size used when neither the request nor the connection sets one. */
+export const DEFAULT_BATCH_SIZE = 64;
+/**
+ * Represents a single connection to a Gremlin Server.
+ */
+export default class Connection extends 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 ? createPreciseReader() : new GraphBinaryReader(ioc));
+        if (options.pdtRegistry) {
+            this._responseSerializer.pdtRegistry = options.pdtRegistry;
+        }
+        this.traversalSource = options.traversalSource || 'g';
+        this._enableUserAgentOnConnect = options.enableUserAgentOnConnect !== false;
+        this._log = 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 ?? 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 = 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.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 ResponseError(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 ResponseError(errorMessage, {
+                        code: response.status,
+                        message: errorBody.message || errorBody.error || response.statusText,
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof ResponseError)
+                    throw err;
+            }
+            throw new ResponseError(errorMessage, {
+                code: response.status,
+                message: response.statusText,
+            });
+        }
+        if (!response.body) {
+            // 204 No Content - nothing to yield
+            return;
+        }
+        const streamReader = StreamReader.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 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 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 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.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 ResponseError(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 ResponseError(errorMessage, {
+                        code: response.status,
+                        message: errorBody.message || errorBody.error || response.statusText,
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof ResponseError) {
+                    throw err;
+                }
+            }
+            throw new ResponseError(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 ResponseError(`Server error: ${deserialized.status.message || 'Unknown error'} (${deserialized.status.code})`, {
+                code: deserialized.status.code,
+                message: deserialized.status.message || '',
+                exception: deserialized.status.exception,
+            });
+        }
+        return new ResultSet(deserialized.result.bulked
+            ? deserialized.result.data.map((item) => new 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();
+    }
+}

package/build/esm/driver/dispatcher.browser.d.ts

@@ -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.js` 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/esm/driver/dispatcher.browser.js

@@ -0,0 +1,53 @@
+/*
+ *  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.
+ */
+/**
+ * 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.
+ */
+export 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.
+ */
+export const httpFetch = {
+    fetch: globalThis.fetch.bind(globalThis),
+};