gremlin 3.8.0 → 4.0.0-beta.2

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

@@ -0,0 +1,85 @@
+import { ConnectionOptions } from './connection.js';
+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/esm/driver/client.js

@@ -0,0 +1,128 @@
+/*
+ *  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";
+/**
+ * A {@link Client} contains methods to send messages to a Gremlin Server.
+ */
+export default 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(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 = 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);
+    }
+}

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

@@ -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.js';
+import { RequestMessage } from "./request-message.js";
+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>;
+}

package/build/esm/driver/connection.js

@@ -0,0 +1,211 @@
+/*
+ *  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 from '../structure/io/binary/GraphBinary.js';
+import * as utils from '../utils.js';
+import ResultSet from './result-set.js';
+import ResponseError from './response-error.js';
+import { Traverser } from '../process/traversal.js';
+const { DeferredPromise } = utils;
+const { graphBinaryReader, graphBinaryWriter } = ioc;
+const responseStatusCode = {
+    success: 200,
+    noContent: 204,
+    partialContent: 206,
+    authenticationChallenge: 407,
+};
+/**
+ * Represents a single connection to a Gremlin Server.
+ */
+export default class Connection extends 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.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 ResponseError(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 ResponseError(errorMessage, {
+                        code: response.status,
+                        message: errorBody.message || errorBody.error || response.statusText,
+                        attributes: new Map(),
+                    });
+                }
+            }
+            catch (err) {
+                if (err instanceof ResponseError) {
+                    throw err;
+                }
+            }
+            throw new ResponseError(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 ResponseError(`Server error: ${deserialized.status.message || 'Unknown error'} (${deserialized.status.code})`, {
+                code: deserialized.status.code,
+                message: deserialized.status.message || '',
+                attributes: attributes,
+            });
+        }
+        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}
+     */
+    close() {
+        return Promise.resolve();
+    }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * @author Jorge Bay Gondra
+ */
+import * as rcModule from './remote-connection.js';
+declare const RemoteConnection: typeof rcModule.RemoteConnection;
+import GremlinLang from '../process/gremlin-lang.js';
+import { ConnectionOptions } from './connection.js';
+/**
+ * Represents the default `RemoteConnection` implementation.
+ */
+export default class DriverRemoteConnection extends RemoteConnection {
+    private readonly _client;
+    /**
+     * Creates a new instance of {@link DriverRemoteConnection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url: string, options?: ConnectionOptions);
+    /** @override */
+    open(): Promise<void>;
+    /** @override */
+    get isOpen(): boolean;
+    /** @override */
+    submit(gremlinLang: GremlinLang): Promise<rcModule.RemoteTraversal>;
+    commit(): Promise<any>;
+    rollback(): Promise<any>;
+    close(): Promise<void>;
+    /** @override */
+    addListener(event: string, handler: (...args: any[]) => unknown): void;
+    /** @override */
+    removeListener(event: string, handler: (...args: any[]) => unknown): void;
+}
+export {};

package/build/esm/driver/driver-remote-connection.js

@@ -0,0 +1,102 @@
+/*
+ *  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 * as rcModule from './remote-connection.js';
+const RemoteConnection = rcModule.RemoteConnection;
+const RemoteTraversal = rcModule.RemoteTraversal;
+import Client from './client.js';
+/**
+ * Represents the default `RemoteConnection` implementation.
+ */
+export default class DriverRemoteConnection extends RemoteConnection {
+    _client;
+    /**
+     * Creates a new instance of {@link DriverRemoteConnection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url, options = {}) {
+        super(url, options);
+        this._client = new Client(url, options);
+    }
+    /** @override */
+    open() {
+        return this._client.open();
+    }
+    /** @override */
+    get isOpen() {
+        return this._client.isOpen;
+    }
+    /** @override */
+    submit(gremlinLang) {
+        gremlinLang.addG(this.options.traversalSource || 'g');
+        let requestOptions = undefined;
+        const strategies = gremlinLang.getOptionsStrategies();
+        if (strategies.length > 0) {
+            requestOptions = {};
+            const allowedKeys = [
+                'evaluationTimeout',
+                'scriptEvaluationTimeout',
+                'batchSize',
+                'requestId',
+                'userAgent',
+                'materializeProperties',
+                'bulkResults',
+            ];
+            for (const strategy of strategies) {
+                for (const key in strategy.configuration) {
+                    if (allowedKeys.indexOf(key) > -1) {
+                        requestOptions[key] = strategy.configuration[key];
+                    }
+                }
+            }
+        }
+        if (!requestOptions) {
+            requestOptions = {};
+        }
+        if (!('bulkResults' in requestOptions)) {
+            requestOptions.bulkResults = true;
+        }
+        const params = gremlinLang.getParameters();
+        if (params.size > 0) {
+            requestOptions.params = Object.fromEntries(params);
+        }
+        return this._client.submit(gremlinLang.getGremlin(), null, requestOptions)
+            .then((result) => new RemoteTraversal(result.toArray()));
+    }
+    commit() {
+        return this._client.submit('g.tx().commit()', null);
+    }
+    rollback() {
+        return this._client.submit('g.tx().rollback()', null);
+    }
+    close() {
+        return this._client.close();
+    }
+    /** @override */
+    addListener(event, handler) {
+        return this._client.addListener(event, handler);
+    }
+    /** @override */
+    removeListener(event, handler) {
+        return this._client.removeListener(event, handler);
+    }
+}