gremlin 3.8.0 → 4.0.0-beta.2

package/README.md

@@ -8,7 +8,7 @@
  "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
+   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
@@ -36,17 +36,31 @@ Gremlin-Javascript is designed to connect to a "server" that is hosting a Tinker
 could be [Gremlin Server][gs] or a [remote Gremlin provider][rgp] that exposes protocols by which Gremlin-Javascript 
 can connect.
 
-A typical connection to a server running on "localhost" that supports the Gremlin Server protocol using websockets 
-looks like this:
+A typical connection to a server running on "localhost" that supports the Gremlin Server protocol looks like this:
 
 ```javascript
 const gremlin = require('gremlin');
 const traversal = gremlin.process.AnonymousTraversalSource.traversal;
 const DriverRemoteConnection = gremlin.driver.DriverRemoteConnection;
 
-const g = traversal().with_(new DriverRemoteConnection('ws://localhost:8182/gremlin'));
+const g = traversal().with_(new DriverRemoteConnection('http://localhost:8182/gremlin'));
 ```
 
+Some graph providers may require additional request customization to connect. The driver supports request interceptors
+for these cases. For example, to connect with basic authentication:
+
+```javascript
+const gremlin = require('gremlin');
+const traversal = gremlin.process.AnonymousTraversalSource.traversal;
+const DriverRemoteConnection = gremlin.driver.DriverRemoteConnection;
+
+const g = traversal().with_(new DriverRemoteConnection('http://localhost:8182/gremlin', {
+  interceptors: gremlin.driver.auth.basic('username', 'password')
+}));
+```
+
+Refer to your graph provider's documentation for specific connection requirements.
+
 Once "g" has been created using a connection, it is then possible to start writing Gremlin traversals to query the 
 remote graph:
 

package/build/cjs/driver/auth.cjs

@@ -0,0 +1,69 @@
+"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.basic = basic;
+exports.sigv4 = sigv4;
+const buffer_1 = require("node:buffer");
+function basic(username, password) {
+    return (request) => {
+        request.headers['authorization'] = 'Basic ' + buffer_1.Buffer.from(`${username}:${password}`).toString('base64');
+        return request;
+    };
+}
+function sigv4(region, service, credentialsProvider) {
+    let signer;
+    let resolvedProvider;
+    return async (request) => {
+        // Lazy-initialize signer and credentials provider on first use
+        if (!signer) {
+            const { SignatureV4 } = await import('@smithy/signature-v4');
+            const { Hash } = await import('@smithy/hash-node');
+            if (credentialsProvider) {
+                resolvedProvider = credentialsProvider;
+            }
+            else {
+                const { fromNodeProviderChain } = await import('@aws-sdk/credential-providers');
+                const chain = fromNodeProviderChain({ clientConfig: { region } });
+                resolvedProvider = () => chain();
+            }
+            signer = new SignatureV4({
+                service,
+                region,
+                sha256: Hash.bind(null, 'sha256'),
+                credentials: () => Promise.resolve(resolvedProvider()),
+            });
+        }
+        const url = new URL(request.url);
+        const signed = await signer.sign({
+            method: request.method,
+            protocol: url.protocol,
+            hostname: url.hostname,
+            port: url.port ? Number(url.port) : undefined,
+            path: url.pathname + url.search,
+            headers: {
+                ...request.headers,
+                host: url.host,
+            },
+            body: request.body,
+        });
+        request.headers = signed.headers;
+        return request;
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { RequestInterceptor } from './connection.cjs';
+export declare function basic(username: string, password: string): RequestInterceptor;
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export type AwsCredentialsProvider = () => AwsCredentials | Promise<AwsCredentials>;
+export declare function sigv4(region: string, service: string, credentialsProvider?: AwsCredentialsProvider): RequestInterceptor;

package/build/cjs/driver/client.cjs

@@ -0,0 +1,134 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const connection_js_1 = __importDefault(require("./connection.cjs"));
+const request_message_js_1 = require("./request-message.cjs");
+/**
+ * A {@link Client} contains methods to send messages to a Gremlin Server.
+ */
+class Client {
+    options;
+    _connection;
+    /**
+     * Creates a new instance of {@link Client}.
+     * @param {String} url The resource uri.
+     * @param {ClientOptions} [options] The connection options.
+     */
+    constructor(url, options = {}) {
+        this.options = options;
+        this._connection = new connection_js_1.default(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;
+    }
+    /**
+     * Configuration specific to the current request.
+     * @typedef {Object} RequestOptions
+     * @property {any} bindings - The parameter bindings to apply to the script.
+     * @property {String} language - The language of the script to execute. Defaults to 'gremlin-lang'.
+     * @property {String} accept - The MIME type expected in the response.
+     * @property {Boolean} bulkResults - Indicates whether results should be returned in bulk format.
+     * @property {Object} params - Additional parameters to include with the request.
+     * @property {Number} batchSize - The size in which the result of a request is to be 'batched' back to the client.
+     * @property {String} userAgent - The user agent string to send with the request.
+     * @property {Number} evaluationTimeout - The timeout for the evaluation of the request.
+     * @property {String} materializeProperties - Indicates whether element properties should be returned or not.
+     */
+    /**
+     * Send a request to the Gremlin Server.
+     * @param {string} message The script to send
+     * @param {Object|null} [bindings] The script bindings, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {Promise}
+     */ //TODO:: tighten return type to Promise<ResultSet>
+    submit(message, bindings, requestOptions) {
+        const requestBuilder = request_message_js_1.RequestMessage.build(message)
+            .addG(this.options.traversalSource || 'g');
+        if (requestOptions?.language) {
+            requestBuilder.addLanguage(requestOptions.language);
+        }
+        if (requestOptions?.bindings) {
+            requestBuilder.addBindings(requestOptions.bindings);
+        }
+        if (bindings) {
+            requestBuilder.addBindings(bindings);
+        }
+        if (requestOptions?.materializeProperties) {
+            requestBuilder.addMaterializeProperties(requestOptions.materializeProperties);
+        }
+        if (requestOptions?.evaluationTimeout) {
+            requestBuilder.addTimeoutMillis(requestOptions.evaluationTimeout);
+        }
+        if (requestOptions?.bulkResults) {
+            requestBuilder.addBulkResults(requestOptions.bulkResults);
+        }
+        return this._connection.submit(requestBuilder.create());
+    }
+    /**
+     * Send a request to the Gremlin Server and receive a stream for the results.
+     * @param {string} message The script to send
+     * @param {Object} [bindings] The script bindings, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {ReadableStream}
+     */
+    //TODO:: Update stream() to mirror submit()
+    stream(message, bindings, requestOptions) {
+        throw new Error("Stream not yet implemented");
+    }
+    /**
+     * Closes the underlying connection
+     * send session close request before connection close if session mode
+     * @returns {Promise}
+     */
+    close() {
+        return this._connection.close();
+    }
+    /**
+     * 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 previowsly 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);
+    }
+}
+exports.default = Client;

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

@@ -0,0 +1,85 @@
+import { ConnectionOptions } from './connection.cjs';
+import { Readable } from 'stream';
+export type RequestOptions = {
+    bindings?: any;
+    language?: string;
+    accept?: string;
+    evaluationTimeout?: number;
+    batchSize?: number;
+    userAgent?: string;
+    materializeProperties?: string;
+    bulkResults?: boolean;
+    params?: Record<string, any>;
+};
+export type ClientOptions = ConnectionOptions & RequestOptions & {
+    processor?: string;
+};
+/**
+ * A {@link Client} contains methods to send messages to a Gremlin Server.
+ */
+export default class Client {
+    private readonly options;
+    private readonly _connection;
+    /**
+     * Creates a new instance of {@link Client}.
+     * @param {String} url The resource uri.
+     * @param {ClientOptions} [options] The connection options.
+     */
+    constructor(url: string, options?: ClientOptions);
+    /**
+     * Opens the underlying connection to the Gremlin Server, if it's not already opened.
+     * @returns {Promise}
+     */
+    open(): Promise<void>;
+    /**
+     * Returns true if the underlying connection is open
+     * @returns {Boolean}
+     */
+    get isOpen(): boolean;
+    /**
+     * Configuration specific to the current request.
+     * @typedef {Object} RequestOptions
+     * @property {any} bindings - The parameter bindings to apply to the script.
+     * @property {String} language - The language of the script to execute. Defaults to 'gremlin-lang'.
+     * @property {String} accept - The MIME type expected in the response.
+     * @property {Boolean} bulkResults - Indicates whether results should be returned in bulk format.
+     * @property {Object} params - Additional parameters to include with the request.
+     * @property {Number} batchSize - The size in which the result of a request is to be 'batched' back to the client.
+     * @property {String} userAgent - The user agent string to send with the request.
+     * @property {Number} evaluationTimeout - The timeout for the evaluation of the request.
+     * @property {String} materializeProperties - Indicates whether element properties should be returned or not.
+     */
+    /**
+     * Send a request to the Gremlin Server.
+     * @param {string} message The script to send
+     * @param {Object|null} [bindings] The script bindings, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {Promise}
+     */ submit(message: string, bindings: any | null, requestOptions?: RequestOptions): Promise<any>;
+    /**
+     * Send a request to the Gremlin Server and receive a stream for the results.
+     * @param {string} message The script to send
+     * @param {Object} [bindings] The script bindings, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {ReadableStream}
+     */
+    stream(message: string, bindings: any, requestOptions?: RequestOptions): Readable;
+    /**
+     * Closes the underlying connection
+     * send session close request before connection close if session mode
+     * @returns {Promise}
+     */
+    close(): Promise<void>;
+    /**
+     * 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: string, handler: (...args: any[]) => unknown): void;
+    /**
+     * Removes a previowsly 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: string, handler: (...args: any[]) => unknown): void;
+}

package/build/cjs/driver/connection.cjs

@@ -0,0 +1,250 @@
+"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 });
+/**
+ * @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 utils = __importStar(require("../utils.cjs"));
+const result_set_js_1 = __importDefault(require("./result-set.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 responseStatusCode = {
+    success: 200,
+    noContent: 204,
+    partialContent: 206,
+    authenticationChallenge: 407,
+};
+/**
+ * Represents a single connection to a Gremlin Server.
+ */
+class Connection extends eventemitter3_1.EventEmitter {
+    url;
+    options;
+    _reader;
+    _writer;
+    isOpen = true;
+    traversalSource;
+    _enableUserAgentOnConnect;
+    _interceptors;
+    /**
+     * 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._reader = options.reader || graphBinaryReader;
+        this._writer = 'writer' in options ? options.writer : graphBinaryWriter;
+        this.traversalSource = options.traversalSource || 'g';
+        this._enableUserAgentOnConnect = options.enableUserAgentOnConnect !== false;
+        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');
+        }
+    }
+    /**
+     * Opens the connection, if its not already opened.
+     * @returns {Promise}
+     */
+    async open() {
+        // 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);
+        });
+    }
+    /** @override */
+    stream(request) {
+        throw new Error('stream() is not yet implemented');
+    }
+    #getReaderForContentType(contentType) {
+        if (!contentType) {
+            return this._reader;
+        }
+        if (contentType === this._reader.mimeType) {
+            return this._reader;
+        }
+        return null;
+    }
+    async #makeHttpRequest(body) {
+        const headers = {
+            'Accept': this._reader.mimeType
+        };
+        if (this._writer) {
+            headers['Content-Type'] = this._writer.mimeType;
+        }
+        if (this._enableUserAgentOnConnect) {
+            const userAgent = await utils.getUserAgent();
+            if (userAgent !== undefined) {
+                headers[utils.getUserAgentHeader()] = userAgent;
+            }
+        }
+        if (this.options.headers) {
+            Object.entries(this.options.headers).forEach(([key, value]) => {
+                headers[key] = Array.isArray(value) ? value.join(', ') : value;
+            });
+        }
+        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);
+            }
+            catch (e) {
+                throw new Error(`Request interceptor at index ${i} failed: ${e.message}`, { cause: e });
+            }
+        }
+        return fetch(httpRequest.url, {
+            method: httpRequest.method,
+            headers: httpRequest.headers,
+            body: httpRequest.body,
+        });
+    }
+    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 = reader.readResponse(buffer);
+                    const attributes = new Map();
+                    if (deserialized.status.exception) {
+                        attributes.set('exceptions', deserialized.status.exception);
+                        attributes.set('stackTrace', deserialized.status.exception);
+                    }
+                    throw new response_error_js_1.default(errorMessage, {
+                        code: deserialized.status.code,
+                        message: deserialized.status.message || response.statusText,
+                        attributes: attributes,
+                    });
+                }
+                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,
+                        attributes: new Map(),
+                    });
+                }
+            }
+            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,
+                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 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,
+            });
+        }
+        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}
+     */
+    close() {
+        return Promise.resolve();
+    }
+}
+exports.default = Connection;

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

@@ -0,0 +1,63 @@
+/**
+ * @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>;
+export type ConnectionOptions = {
+    ca?: string[];
+    cert?: string | string[] | Buffer;
+    pfx?: string | Buffer;
+    reader?: any;
+    rejectUnauthorized?: boolean;
+    traversalSource?: string;
+    writer?: any | null;
+    headers?: Record<string, string | string[]>;
+    enableUserAgentOnConnect?: boolean;
+    agent?: Agent;
+    interceptors?: RequestInterceptor | RequestInterceptor[];
+};
+/**
+ * Represents a single connection to a Gremlin Server.
+ */
+export default class Connection extends EventEmitter {
+    #private;
+    readonly url: string;
+    readonly options: ConnectionOptions;
+    private readonly _reader;
+    private readonly _writer;
+    isOpen: boolean;
+    traversalSource: string;
+    private readonly _enableUserAgentOnConnect;
+    private readonly _interceptors;
+    /**
+     * Creates a new instance of {@link Connection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url: string, options?: ConnectionOptions);
+    /**
+     * Opens the connection, if its not already opened.
+     * @returns {Promise}
+     */
+    open(): Promise<void>;
+    /** @override */
+    submit(request: RequestMessage): Promise<ResultSet>;
+    /** @override */
+    stream(request: RequestMessage): Readable;
+    /**
+     * Closes the Connection.
+     * @return {Promise}
+     */
+    close(): Promise<void>;
+}