gremlin 4.0.0-beta.2 → 4.0.0-beta.3

package/build/cjs/driver/connection.cjs

@@ -54,36 +54,46 @@ 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 = __importDefault(require("../structure/io/binary/GraphBinary.cjs"));
+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 { DeferredPromise } = utils;
-const { graphBinaryReader, graphBinaryWriter } = GraphBinary_js_1.default;
+const dispatcher_js_1 = require("./dispatcher.cjs");
+const logger_js_1 = require("./logger.cjs");
 const responseStatusCode = {
     success: 200,
     noContent: 204,
     partialContent: 206,
-    authenticationChallenge: 407,
 };
+/** 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;
-    _reader;
-    _writer;
+    _responseSerializer;
     isOpen = true;
     traversalSource;
     _enableUserAgentOnConnect;
     _interceptors;
+    _dispatcher;
+    _compression;
+    _batchSize;
+    _bulkResults;
+    _log;
     /**
      * Creates a new instance of {@link Connection}.
      * @param {String} url The resource uri.
@@ -93,16 +103,41 @@ class Connection extends eventemitter3_1.EventEmitter {
         super();
         this.url = url;
         this.options = options;
-        this._reader = options.reader || graphBinaryReader;
-        this._writer = 'writer' in options ? options.writer : graphBinaryWriter;
+        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;
+            this._interceptors = [...interceptors];
         }
         else if (interceptors === undefined || interceptors === null) {
             this._interceptors = [];
@@ -110,6 +145,24 @@ class Connection extends eventemitter3_1.EventEmitter {
         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.
@@ -119,34 +172,99 @@ class Connection extends eventemitter3_1.EventEmitter {
         // No-op for HTTP connections
         return Promise.resolve();
     }
-    /** @override */
-    submit(request) {
-        // The user may not want the body to be serialized if they are using an interceptor.
-        const body = this._writer ? this._writer.writeRequest(request) : request;
-        return this.#makeHttpRequest(body)
-            .then((response) => {
-            return this.#handleResponse(response);
-        });
+    /**
+     * 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);
     }
-    /** @override */
-    stream(request) {
-        throw new Error('stream() is not yet implemented');
+    /**
+     * 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._reader;
+            return this._responseSerializer;
         }
-        if (contentType === this._reader.mimeType) {
-            return this._reader;
+        if (contentType === this._responseSerializer.mimeType) {
+            return this._responseSerializer;
         }
         return null;
     }
-    async #makeHttpRequest(body) {
+    async #makeHttpRequest(request, signal) {
         const headers = {
-            'Accept': this._reader.mimeType
+            'Accept': this._responseSerializer.mimeType,
         };
-        if (this._writer) {
-            headers['Content-Type'] = this._writer.mimeType;
+        if (this._compression === 'deflate') {
+            headers['Accept-Encoding'] = 'deflate';
         }
         if (this._enableUserAgentOnConnect) {
             const userAgent = await utils.getUserAgent();
@@ -154,29 +272,35 @@ class Connection extends eventemitter3_1.EventEmitter {
                 headers[utils.getUserAgentHeader()] = userAgent;
             }
         }
-        if (this.options.headers) {
-            Object.entries(this.options.headers).forEach(([key, value]) => {
-                headers[key] = Array.isArray(value) ? value.join(', ') : value;
-            });
+        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');
+            }
         }
-        let httpRequest = {
-            url: this.url,
-            method: 'POST',
-            headers,
-            body,
-        };
         for (let i = 0; i < this._interceptors.length; i++) {
             try {
-                httpRequest = await this._interceptors[i](httpRequest);
+                await this._interceptors[i](httpRequest);
             }
             catch (e) {
                 throw new Error(`Request interceptor at index ${i} failed: ${e.message}`, { cause: e });
             }
         }
-        return fetch(httpRequest.url, {
+        // 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) {
@@ -187,16 +311,11 @@ class Connection extends eventemitter3_1.EventEmitter {
             const errorMessage = `Server returned HTTP ${response.status}: ${response.statusText}`;
             try {
                 if (reader) {
-                    const deserialized = reader.readResponse(buffer);
-                    const attributes = new Map();
-                    if (deserialized.status.exception) {
-                        attributes.set('exceptions', deserialized.status.exception);
-                        attributes.set('stackTrace', deserialized.status.exception);
-                    }
+                    const deserialized = await reader.readResponse(buffer);
                     throw new response_error_js_1.default(errorMessage, {
                         code: deserialized.status.code,
                         message: deserialized.status.message || response.statusText,
-                        attributes: attributes,
+                        exception: deserialized.status.exception,
                     });
                 }
                 else if (contentType === 'application/json') {
@@ -204,7 +323,6 @@ class Connection extends eventemitter3_1.EventEmitter {
                     throw new response_error_js_1.default(errorMessage, {
                         code: response.status,
                         message: errorBody.message || errorBody.error || response.statusText,
-                        attributes: new Map(),
                     });
                 }
             }
@@ -216,23 +334,17 @@ class Connection extends eventemitter3_1.EventEmitter {
             throw new response_error_js_1.default(errorMessage, {
                 code: response.status,
                 message: response.statusText,
-                attributes: new Map(),
             });
         }
         if (!reader) {
-            throw new Error(`Response Content-Type '${contentType}' does not match the configured reader (expected '${this._reader.mimeType}')`);
-        }
-        const deserialized = reader.readResponse(buffer);
-        if (deserialized.status.code && deserialized.status.code !== 200 && deserialized.status.code !== 204 && deserialized.status.code !== 206) {
-            const attributes = new Map();
-            if (deserialized.status.exception) {
-                attributes.set('exceptions', deserialized.status.exception);
-                attributes.set('stackTrace', deserialized.status.exception);
-            }
+            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 || '',
-                attributes: attributes,
+                exception: deserialized.status.exception,
             });
         }
         return new result_set_js_1.default(deserialized.result.bulked
@@ -243,8 +355,9 @@ class Connection extends eventemitter3_1.EventEmitter {
      * Closes the Connection.
      * @return {Promise}
      */
-    close() {
-        return Promise.resolve();
+    async close() {
+        this._log('debug', `Closing connection to ${this.url}`);
+        await this._dispatcher?.close();
     }
 }
 exports.default = Connection;

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

@@ -1,32 +1,48 @@
-/**
- * @author Jorge Bay Gondra
- */
-import { Buffer } from 'buffer';
 import { EventEmitter } from 'eventemitter3';
-import type { Agent } from 'node:http';
 import ResultSet from './result-set.cjs';
 import { RequestMessage } from "./request-message.cjs";
-import { Readable } from "stream";
-export type HttpRequest = {
-    url: string;
-    method: string;
-    headers: Record<string, string>;
-    body: any;
-};
-export type RequestInterceptor = (request: HttpRequest) => HttpRequest | Promise<HttpRequest>;
+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 = {
-    ca?: string[];
-    cert?: string | string[] | Buffer;
-    pfx?: string | Buffer;
-    reader?: any;
-    rejectUnauthorized?: boolean;
+    preciseNumbers?: boolean;
+    pdtRegistry?: any;
+    responseSerializer?: any;
     traversalSource?: string;
-    writer?: any | null;
-    headers?: Record<string, string | string[]>;
     enableUserAgentOnConnect?: boolean;
-    agent?: Agent;
+    /** 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.
  */
@@ -34,27 +50,54 @@ export default class Connection extends EventEmitter {
     #private;
     readonly url: string;
     readonly options: ConnectionOptions;
-    private readonly _reader;
-    private readonly _writer;
+    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>;
-    /** @override */
+    /**
+     * Send a request and buffer the entire response. Returns a Promise<ResultSet>.
+     */
     submit(request: RequestMessage): Promise<ResultSet>;
-    /** @override */
-    stream(request: RequestMessage): Readable;
+    /**
+     * 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}

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 {};