gremlin 3.8.1 → 4.0.0-beta.2

package/lib/driver/client.js

@@ -1,199 +0,0 @@
-/*
- *  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.
- */
-'use strict';
-
-const utils = require('../utils');
-const Connection = require('./connection');
-const Bytecode = require('../process/bytecode');
-
-/**
- * A {@link Client} contains methods to send messages to a Gremlin Server.
- */
-class Client {
-  /**
-   * Creates a new instance of {@link Client}.
-   * @param {String} url The resource uri.
-   * @param {Object} [options] The connection options.
-   * @param {Array} [options.ca] Trusted certificates.
-   * @param {String|Array|Buffer} [options.cert] The certificate key.
-   * @param {String} [options.mimeType] The mime type to use.
-   * @param {String|Buffer} [options.pfx] The private key, certificate, and CA certs.
-   * @param {GraphSONReader} [options.reader] The reader to use.
-   * @param {Boolean} [options.rejectUnauthorized] Determines whether to verify or not the server certificate.
-   * @param {String} [options.traversalSource] The traversal source. Defaults to: 'g'.
-   * @param {GraphSONWriter} [options.writer] The writer to use.
-   * @param {Authenticator} [options.authenticator] The authentication handler to use.
-   * @param {Object} [options.headers] An associative array containing the additional header key/values for the initial request.
-   * @param {Boolean} [options.enableUserAgentOnConnect] Determines if a user agent will be sent during connection handshake. Defaults to: true
-   * @param {String} [options.processor] The name of the opProcessor to use, leave it undefined or set 'session' when session mode.
-   * @param {String} [options.session] The sessionId of Client in session mode. Defaults to null means session-less Client.
-   * @param {http.Agent} [options.agent] The http.Agent implementation to use.
-   * @param {Boolean} [options.enableCompression] Enable per-message deflate compression. Defaults to: false.
-   * @constructor
-   */
-  constructor(url, options = {}) {
-    this._options = options;
-    if (this._options.processor === 'session') {
-      // compatibility with old 'session' processor setting
-      this._options.session = options.session || utils.getUuid();
-    }
-    if (this._options.session) {
-      // re-assign processor to 'session' when in session mode
-      this._options.processor = options.processor || 'session';
-    }
-    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 {String} requestId - User specified request identifier which must be a UUID.
-   * @property {Number} batchSize - Indicates whether the Power component is present.
-   * @property {String} userAgent - The size in which the result of a request is to be 'batched' back to the client
-   * @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, can send a script or bytecode steps.
-   * @param {Bytecode|string} message The bytecode or script to send
-   * @param {Object} [bindings] The script bindings, if any.
-   * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
-   * @returns {Promise}
-   */
-  submit(message, bindings, requestOptions) {
-    const requestIdOverride = requestOptions && requestOptions.requestId;
-    if (requestIdOverride) {
-      delete requestOptions['requestId'];
-    }
-
-    const args = Object.assign(
-      {
-        gremlin: message,
-        aliases: { g: this._options.traversalSource || 'g' },
-      },
-      requestOptions,
-    );
-
-    if (this._options.session && this._options.processor === 'session') {
-      args['session'] = this._options.session;
-    }
-
-    if (message instanceof Bytecode) {
-      if (this._options.session && this._options.processor === 'session') {
-        return this._connection.submit('session', 'bytecode', args, requestIdOverride);
-      }
-      return this._connection.submit('traversal', 'bytecode', args, requestIdOverride);
-    } else if (typeof message === 'string') {
-      args['bindings'] = bindings;
-      args['language'] = 'gremlin-groovy';
-      args['accept'] = this._connection.mimeType;
-      return this._connection.submit(this._options.processor || '', 'eval', args, requestIdOverride);
-    }
-    throw new TypeError('message must be of type Bytecode or string');
-  }
-
-  /**
-   * Send a request to the Gremlin Server and receive a stream for the results, can send a script or bytecode steps.
-   * @param {Bytecode|string} message The bytecode or script to send
-   * @param {Object} [bindings] The script bindings, if any.
-   * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
-   * @returns {ReadableStream}
-   */
-  stream(message, bindings, requestOptions) {
-    const requestIdOverride = requestOptions && requestOptions.requestId;
-    if (requestIdOverride) {
-      delete requestOptions['requestId'];
-    }
-
-    const args = Object.assign(
-      {
-        gremlin: message,
-        aliases: { g: this._options.traversalSource || 'g' },
-      },
-      requestOptions,
-    );
-
-    if (this._options.session && this._options.processor === 'session') {
-      args['session'] = this._options.session;
-    }
-
-    if (message instanceof Bytecode) {
-      if (this._options.session && this._options.processor === 'session') {
-        return this._connection.stream('session', 'bytecode', args, requestIdOverride);
-      }
-      return this._connection.stream('traversal', 'bytecode', args, requestIdOverride);
-    } else if (typeof message === 'string') {
-      args['bindings'] = bindings;
-      args['language'] = 'gremlin-groovy';
-      args['accept'] = this._connection.mimeType;
-      return this._connection.stream(this._options.processor || '', 'eval', args, requestIdOverride);
-    }
-    throw new TypeError('message must be of type Bytecode or string');
-  }
-
-  /**
-   * Closes the underlying connection
-   * send session close request before connection close if session mode
-   * @returns {Promise}
-   */
-  close() {
-    if (this._options.session && this._options.processor === 'session') {
-      const args = { session: this._options.session };
-      return this._connection.submit(this._options.processor, 'close', args, null).then(() => this._connection.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);
-  }
-}
-
-module.exports = Client;

package/lib/driver/connection.js

@@ -1,467 +0,0 @@
-/*
- *  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
- */
-'use strict';
-
-const { Buffer } = require('buffer');
-const EventEmitter = require('eventemitter3');
-const Stream = require('readable-stream');
-const utils = require('../utils');
-const { DeferredPromise } = utils;
-const serializer = require('../structure/io/graph-serializer');
-const { graphBinaryReader, graphBinaryWriter } = require('../structure/io/binary/GraphBinary');
-const ResultSet = require('./result-set');
-const ResponseError = require('./response-error');
-
-const responseStatusCode = {
-  success: 200,
-  noContent: 204,
-  partialContent: 206,
-  authenticationChallenge: 407,
-};
-
-const defaultMimeType = 'application/vnd.graphbinary-v1.0';
-const graphSON2MimeType = 'application/vnd.gremlin-v2.0+json';
-const graphBinaryMimeType = 'application/vnd.graphbinary-v1.0';
-
-const uuidPattern = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
-
-/**
- * Represents a single connection to a Gremlin Server.
- */
-class Connection extends EventEmitter {
-  /**
-   * Creates a new instance of {@link Connection}.
-   * @param {String} url The resource uri.
-   * @param {Object} [options] The connection options.
-   * @param {Array} [options.ca] Trusted certificates.
-   * @param {String|Array|Buffer} [options.cert] The certificate key.
-   * @param {String} [options.mimeType] The mime type to use.
-   * @param {String|Buffer} [options.pfx] The private key, certificate, and CA certs.
-   * @param {GraphSONReader} [options.reader] The reader to use.
-   * @param {Boolean} [options.rejectUnauthorized] Determines whether to verify or not the server certificate.
-   * @param {String} [options.traversalSource] The traversal source. Defaults to: 'g'.
-   * @param {GraphSONWriter} [options.writer] The writer to use.
-   * @param {Authenticator} [options.authenticator] The authentication handler to use.
-   * @param {Object} [options.headers] An associative array containing the additional header key/values for the initial request.
-   * @param {Boolean} [options.enableUserAgentOnConnect] Determines if a user agent will be sent during connection handshake. Defaults to: true
-   * @param {http.Agent} [options.agent] The http.Agent implementation to use.
-   * @param {Boolean} [options.enableCompression] Enable per-message deflate compression. Defaults to: false.
-   * @constructor
-   */
-  constructor(url, options) {
-    super();
-
-    this.url = url;
-    this.options = options = options || {};
-
-    /**
-     * Gets the MIME type.
-     * @type {String}
-     */
-    this.mimeType = options.mimeType || defaultMimeType;
-
-    // A map containing the request id and the handler. The id should be in lower case to prevent string comparison issues.
-    this._responseHandlers = {};
-    this._reader = options.reader || this.#getDefaultReader(this.mimeType);
-    this._writer = options.writer || this.#getDefaultWriter(this.mimeType);
-    this._openPromise = null;
-    this._openCallback = null;
-    this._closePromise = null;
-    this._closeCallback = null;
-
-    this._header = String.fromCharCode(this.mimeType.length) + this.mimeType; // TODO: what if mimeType.length > 255
-    this._header_buf = Buffer.from(this._header);
-    this.isOpen = false;
-    this.traversalSource = options.traversalSource || 'g';
-    this._authenticator = options.authenticator;
-    this._enableUserAgentOnConnect = options.enableUserAgentOnConnect !== false;
-    this._enableCompression = this.options.enableCompression || false;
-  }
-
-  /**
-   * Opens the connection, if its not already opened.
-   * @returns {Promise}
-   */
-  async open() {
-    if (this.isOpen) {
-      return;
-    }
-    if (this._openPromise) {
-      return this._openPromise;
-    }
-
-    this._openPromise = DeferredPromise();
-
-    this.emit('log', 'ws open');
-    let headers = this.options.headers;
-    if (this._enableUserAgentOnConnect) {
-      if (!headers) {
-        headers = [];
-      }
-
-      const userAgent = await utils.getUserAgent();
-      if (userAgent !== undefined) {
-        headers[utils.getUserAgentHeader()] = await utils.getUserAgent();
-      }
-    }
-    // All these options are available to the `ws` package's constructor, but not the global WebSocket class
-    const wsSpecificOptions = new Set([
-      'headers',
-      'ca',
-      'cert',
-      'pfx',
-      'rejectUnauthorized',
-      'agent',
-      'perMessageDeflate',
-    ]);
-    // Check if any `ws` specific options are provided and are non-null / non-undefined
-    const hasWsSpecificOptions =
-      Object.entries(this.options).some(
-        ([key, value]) => wsSpecificOptions.has(key) && ![null, undefined].includes(value),
-      ) ||
-      this._enableCompression || // we need to check the presence of this variable and pass this into ws
-      this._enableUserAgentOnConnect; // global websocket will send "node" as user agent by default which doesn't comply with Gremlin
-    // Only use the global websocket if we don't have any unsupported options
-    const useGlobalWebSocket = !hasWsSpecificOptions && globalThis.WebSocket;
-    const WebSocket = useGlobalWebSocket || (await import('ws')).default;
-
-    this._ws = new WebSocket(
-      this.url,
-      !useGlobalWebSocket
-        ? {
-            headers: headers,
-            ca: this.options.ca,
-            cert: this.options.cert,
-            pfx: this.options.pfx,
-            rejectUnauthorized: this.options.rejectUnauthorized,
-            agent: this.options.agent,
-            perMessageDeflate: this._enableCompression,
-          }
-        : undefined,
-    );
-
-    if ('binaryType' in this._ws) {
-      this._ws.binaryType = 'arraybuffer';
-    }
-
-    this._ws.addEventListener('open', this.#handleOpen);
-    this._ws.addEventListener('error', this.#handleError);
-    // Only attach unexpected-response listener if WebSocket supports .on() method
-    // Browser WebSocket does not have this event and .on() method
-    if (this._ws && 'on' in this._ws) {
-      // The following listener needs to use `.on` and `.off` because the `ws` package's addEventListener only accepts certain event types
-      // Ref: https://github.com/websockets/ws/blob/8.16.0/lib/event-target.js#L202-L241
-      this._ws.on('unexpected-response', this.#handleUnexpectedResponse);
-    }
-    this._ws.addEventListener('message', this.#handleMessage);
-    this._ws.addEventListener('close', this.#handleClose);
-    return await this._openPromise;
-  }
-
-  /** @override */
-  submit(processor, op, args, requestId) {
-    // TINKERPOP-2847: Use lower case to prevent string comparison issues.
-    const rid = (requestId || utils.getUuid()).toLowerCase();
-    if (!rid.match(uuidPattern)) {
-      throw new Error('Provided requestId "' + rid + '" is not a valid UUID.');
-    }
-
-    return this.open().then(
-      () =>
-        new Promise((resolve, reject) => {
-          if (op !== 'authentication') {
-            this._responseHandlers[rid] = {
-              callback: (err, result) => (err ? reject(err) : resolve(result)),
-              result: null,
-            };
-          }
-
-          const request = {
-            requestId: rid,
-            op: op || 'bytecode',
-            // if using op eval need to ensure processor stays unset if caller didn't set it.
-            processor: !processor && op !== 'eval' ? 'traversal' : processor,
-            args: args || {},
-          };
-
-          const request_buf = this._writer.writeRequest(request);
-          const message = utils.toArrayBuffer(Buffer.concat([this._header_buf, request_buf]));
-          this._ws.send(message);
-        }),
-    );
-  }
-
-  /** @override */
-  stream(processor, op, args, requestId) {
-    // TINKERPOP-2847: Use lower case to prevent string comparison issues.
-    const rid = (requestId || utils.getUuid()).toLowerCase();
-    if (!rid.match(uuidPattern)) {
-      throw new Error('Provided requestId "' + rid + '" is not a valid UUID.');
-    }
-
-    const readableStream = new Stream.Readable({
-      objectMode: true,
-      read() {},
-    });
-
-    this._responseHandlers[rid] = {
-      callback: (err) => (err ? readableStream.destroy(err) : readableStream.push(null)),
-      result: readableStream,
-    };
-
-    this.open()
-      .then(() => {
-        const request = {
-          requestId: rid,
-          op: op || 'bytecode',
-          // if using op eval need to ensure processor stays unset if caller didn't set it.
-          processor: !processor && op !== 'eval' ? 'traversal' : processor,
-          args: args || {},
-        };
-
-        const request_buf = this._writer.writeRequest(request);
-        const message = utils.toArrayBuffer(Buffer.concat([this._header_buf, request_buf]));
-        this._ws.send(message);
-      })
-      .catch((err) => readableStream.destroy(err));
-
-    return readableStream;
-  }
-
-  #getDefaultReader(mimeType) {
-    if (mimeType === graphBinaryMimeType) {
-      return graphBinaryReader;
-    }
-
-    return mimeType === graphSON2MimeType ? new serializer.GraphSON2Reader() : new serializer.GraphSONReader();
-  }
-
-  #getDefaultWriter(mimeType) {
-    if (mimeType === graphBinaryMimeType) {
-      return graphBinaryWriter;
-    }
-
-    return mimeType === graphSON2MimeType ? new serializer.GraphSON2Writer() : new serializer.GraphSONWriter();
-  }
-
-  #handleOpen = () => {
-    this._openPromise.resolve();
-    this.isOpen = true;
-  };
-
-  /**
-   * @param {ClientRequest} _req
-   * @param {IncomingMessage} res
-   */
-  #handleUnexpectedResponse = async (_req, res) => {
-    const body = await new Promise((resolve, reject) => {
-      const chunks = [];
-      res.on('data', (data) => {
-        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
-      });
-      res.on('end', () => {
-        resolve(chunks.length ? Buffer.concat(chunks) : null);
-      });
-      res.on('error', reject);
-    });
-    const statusCodeErrorMessage = `Unexpected server response code ${res.statusCode}`;
-    const errorMessage = body ? `${statusCodeErrorMessage} with body:\n${body.toString()}` : statusCodeErrorMessage;
-    const error = new Error(errorMessage);
-    this.#handleError({
-      error,
-      message: errorMessage,
-      type: 'unexpected-response',
-      target: this._ws,
-    });
-  };
-
-  /**
-   * @param {Event} event
-   */
-  #handleError = ({ error }) => {
-    this._openPromise.reject(error);
-    this.emit('log', `ws error ${error}`);
-    this.#cleanupWebsocket(error);
-    this.emit('socketError', error);
-  };
-
-  /**
-   * @param {CloseEvent} event
-   */
-  #handleClose = ({ code, message }) => {
-    this.emit('log', `ws close code=${code} message=${message}`);
-    this.#cleanupWebsocket();
-    if (this._closeCallback) {
-      this._closeCallback();
-    }
-    this.emit('close', code, message);
-  };
-
-  /**
-   * @param {MessageEvent<any>} event
-   */
-  #handleMessage = ({ data: _data }) => {
-    const data = _data instanceof ArrayBuffer ? Buffer.from(_data) : _data;
-
-    const response = this._reader.readResponse(data);
-    if (response.requestId === null || response.requestId === undefined) {
-      // There was a serialization issue on the server that prevented the parsing of the request id
-      // We invoke any of the pending handlers with an error
-      Object.keys(this._responseHandlers).forEach((requestId) => {
-        const handler = this._responseHandlers[requestId];
-        this.#clearHandler(requestId);
-        if (response.status !== undefined && response.status.message) {
-          return handler.callback(
-            // TINKERPOP-2285: keep the old server error message in case folks are parsing that - fix in a future breaking version
-            new ResponseError(
-              `Server error (no request information): ${response.status.message} (${response.status.code})`,
-              response.status,
-            ),
-          );
-        }
-        // TINKERPOP-2285: keep the old server error message in case folks are parsing that - fix in a future breaking version
-        return handler.callback(
-          new ResponseError(`Server error (no request information): ${JSON.stringify(response)}`, response.status),
-        );
-      });
-      return;
-    }
-
-    // TINKERPOP-2847: Use lower case to prevent string comparison issues.
-    response.requestId = response.requestId.toLowerCase();
-    const handler = this._responseHandlers[response.requestId];
-
-    if (!handler) {
-      // The handler for a given request id was not found
-      // It was probably invoked earlier due to a serialization issue.
-      return;
-    }
-
-    if (response.status.code === responseStatusCode.authenticationChallenge && this._authenticator) {
-      this._authenticator
-        .evaluateChallenge(response.result.data)
-        .then((res) => this.submit(undefined, 'authentication', res, response.requestId))
-        .catch(handler.callback);
-
-      return;
-    } else if (response.status.code >= 400) {
-      this.#clearHandler(response.requestId);
-      // callback in error
-      return handler.callback(
-        // TINKERPOP-2285: keep the old server error message in case folks are parsing that - fix in a future breaking version
-        new ResponseError(`Server error: ${response.status.message} (${response.status.code})`, response.status),
-      );
-    }
-
-    const isStreamingResponse = handler.result instanceof Stream.Readable;
-
-    switch (response.status.code) {
-      case responseStatusCode.noContent:
-        this.#clearHandler(response.requestId);
-        if (isStreamingResponse) {
-          handler.result.push(new ResultSet(utils.emptyArray, response.status.attributes));
-          return handler.callback(null);
-        }
-        return handler.callback(null, new ResultSet(utils.emptyArray, response.status.attributes));
-      case responseStatusCode.partialContent:
-        if (isStreamingResponse) {
-          handler.result.push(new ResultSet(response.result.data, response.status.attributes));
-          break;
-        }
-        handler.result = handler.result || [];
-        handler.result.push.apply(handler.result, response.result.data);
-        break;
-      default:
-        if (isStreamingResponse) {
-          handler.result.push(new ResultSet(response.result.data, response.status.attributes));
-          return handler.callback(null);
-        }
-        if (handler.result) {
-          handler.result.push.apply(handler.result, response.result.data);
-        } else {
-          handler.result = response.result.data;
-        }
-        this.#clearHandler(response.requestId);
-        return handler.callback(null, new ResultSet(handler.result, response.status.attributes));
-    }
-  };
-
-  /**
-   * clean websocket context
-   */
-  #cleanupWebsocket(err) {
-    // Invoke waiting callbacks to complete Promises when closing the websocket
-    Object.keys(this._responseHandlers).forEach((requestId) => {
-      const handler = this._responseHandlers[requestId];
-      const isStreamingResponse = handler.result instanceof Stream.Readable;
-      if (isStreamingResponse) {
-        handler.callback(null);
-      } else {
-        const cause = err ? err : new Error('Connection has been closed.');
-        handler.callback(cause);
-      }
-    });
-    this._ws.removeEventListener('open', this.#handleOpen);
-    this._ws.removeEventListener('error', this.#handleError);
-    // Only remove unexpected-response listener for Node.js WebSocket (ws package)
-    // Browser WebSocket does not have this event and .off() method
-    if (this._ws && 'off' in this._ws) {
-      // The following listener needs to use `.on` and `.off` because the `ws` package's addEventListener only accepts certain event types
-      // Ref: https://github.com/websockets/ws/blob/8.16.0/lib/event-target.js#L202-L241
-      this._ws.off('unexpected-response', this.#handleUnexpectedResponse);
-    }
-    this._ws.removeEventListener('message', this.#handleMessage);
-    this._ws.removeEventListener('close', this.#handleClose);
-    this._openPromise = null;
-    this._closePromise = null;
-    this.isOpen = false;
-  }
-
-  /**
-   * Clears the internal state containing the callback and result buffer of a given request.
-   * @param requestId
-   * @private
-   */
-  #clearHandler(requestId) {
-    delete this._responseHandlers[requestId];
-  }
-
-  /**
-   * Closes the Connection.
-   * @return {Promise}
-   */
-  close() {
-    if (this.isOpen === false) {
-      return Promise.resolve();
-    }
-    if (!this._closePromise) {
-      this._closePromise = new Promise((resolve) => {
-        this._closeCallback = resolve;
-        this._ws.close();
-      });
-    }
-    return this._closePromise;
-  }
-}
-
-module.exports = Connection;