gremlin 3.8.1 → 4.0.0-beta.3

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,76 @@
+"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');
+    };
+}
+function sigv4(region, service, credentialsProvider) {
+    let signer;
+    let resolvedProvider;
+    return async (request) => {
+        // Ensure body is serialized to JSON bytes before signing.
+        // serializeBody is idempotent: safe to call even if already serialized.
+        request.serializeBody();
+        // 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);
+        // Sign only the Host header; the signer itself adds (and signs) x-amz-date, the payload hash,
+        // and x-amz-security-token for session credentials. The request's own headers (accept,
+        // content-type, ...) are deliberately NOT fed into the signature: the HTTP stack may add or
+        // rewrite transport-managed headers such as accept-encoding after this interceptor runs, so a
+        // signature covering them would no longer match the bytes actually sent.
+        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: {
+                host: url.host,
+            },
+            body: request.body,
+        });
+        // Merge the signed auth headers onto the request; the request's other headers (accept,
+        // content-type, ...) still reach the wire, they are simply not part of the signature.
+        request.headers = { ...request.headers, ...signed.headers };
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { RequestInterceptor } from './http-request.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,178 @@
+"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");
+const transaction_js_1 = require("../process/transaction.cjs");
+/**
+ * A {@link Client} contains methods to send messages to a Gremlin Server.
+ */
+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_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;
+    }
+    /**
+     * 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 = request_message_js_1.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_js_1.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);
+    }
+}
+exports.default = Client;

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

@@ -0,0 +1,88 @@
+import { ConnectionOptions } from './connection.cjs';
+import { Transaction } from '../process/transaction.cjs';
+export type RequestOptions = {
+    parameters?: any;
+    language?: string;
+    accept?: string;
+    timeoutMillis?: number;
+    batchSize?: number;
+    userAgent?: string;
+    materializeProperties?: string;
+    bulkResults?: boolean;
+    params?: Record<string, any>;
+    transactionId?: string;
+};
+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 url: string;
+    readonly options: ClientOptions;
+    private readonly _connection;
+    /**
+     * Creates a new instance of {@link Client}.
+     * @param {String} url The resource uri.
+     * @param {ClientOptions} [options] The connection options.
+     */
+    private readonly _trackedTransactions;
+    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;
+    /**
+     * 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: string, parameters: any | null, requestOptions?: RequestOptions): Promise<any>;
+    /**
+     * 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>}
+     */
+    stream(message: string, parameters: any | null, requestOptions?: RequestOptions): AsyncGenerator<any>;
+    /**
+     * Closes the underlying connection
+     * @returns {Promise}
+     */
+    close(): Promise<void>;
+    trackTransaction(tx: any): void;
+    untrackTransaction(tx: any): void;
+    /**
+     * 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(): Transaction;
+    /**
+     * 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 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: string, handler: (...args: any[]) => unknown): void;
+}