@qooxdoo/framework 7.0.0-beta.2 → 7.0.0-beta.6

package/source/class/qx/io/jsonrpc/Client.js

@@ -0,0 +1,323 @@
+/* ************************************************************************
+
+   qooxdoo - the new era of web development
+
+   http://qooxdoo.org
+
+   Copyright:
+      2020 Christian Boulanger
+
+   License:
+     MIT: https://opensource.org/licenses/MIT
+     See the LICENSE file in the project's top-level directory for details.
+
+   Authors:
+     * Christian Boulanger (cboulanger)
+
+************************************************************************ */
+
+/**
+ * This class provides a JSON-RPC client object with auto-configuration of the
+ * transport used (based on the URI passed).
+ */
+qx.Class.define("qx.io.jsonrpc.Client",
+{
+  extend : qx.io.transport.AbstractClient,
+
+  statics: {
+    // statics are not inherited from parent class
+    registerTransport : qx.io.transport.AbstractClient.registerTransport
+  },
+
+  events : {
+    /**
+     * Event fired before a request message is sent to the server.
+     * Event data is the {@link qx.io.jsonrpc.protocol.Message} to
+     * be sent. This also allows listeners to configure the transport
+     * object beforehand.
+     */
+    "outgoingRequest": "qx.event.type.Data",
+
+    /**
+     * Event fired when a request results in an error. Event data is an instance of
+     * {@link qx.io.exception.Transport}, {@link qx.io.exception.Protocol},
+     * or {@link qx.io.exception.Cancel}.
+     * Event fired when a message is received from the endpoint. Event data
+     * is an UTF-8 encoded string
+     */
+    "error" : "qx.event.type.Data",
+
+    /**
+     * Event fired when a peer-originated JSON-RPC message has been
+     * received from the peer endpoint. Event data is an instance of {@link
+     * qx.io.jsonrpc.message.Batch}, {@link qx.io.jsonrpc.message.Request}
+     * or {@link qx.io.jsonrpc.protocol.Notification}.
+     */
+    "incomingRequest" : "qx.event.type.Data"
+  },
+
+  /**
+   * @param {qx.io.transport.ITransport|String} transportOrUri
+   *    Transport object, which must implement {@link qx.io.transport.ITransport}
+   *    or a string URI, which will trigger auto-detection of transport, as long as an
+   *    appropriate transport has been registered with the static `registerTransport()` function.
+   * @param {String?} methodPrefix
+   *    Optional service name which will be prepended to the method
+   * @param {qx.io.jsonrpc.protocol.Parser?} parser
+   *    Optional parser object, which needs to be an instance of a subclass of {@link qx.io.jsonrpc.protocol.Parser}
+   */
+  construct : function(transportOrUri, methodPrefix, parser) {
+    this.base(arguments);
+    this.selectTransport(transportOrUri);
+    // listen for incoming messages
+    this.getTransport().addListener("message", evt => this.handleIncoming(evt.getData()));
+    if (!methodPrefix) {
+      methodPrefix = "";
+    }
+    this.setMethodPrefix(methodPrefix);
+    if (!parser) {
+      parser = new qx.io.jsonrpc.protocol.Parser();
+    }
+    this.setParser(parser);
+    this.__requests = [];
+  },
+
+  properties :
+  {
+    /**
+     * An optional string which is prepended to the method name by the {@link #sendRequest}
+     * and {@link #sendNotification} methods
+     */
+    methodPrefix :
+    {
+      check : "String",
+      nullable : true
+    },
+
+    /**
+     * The parser object, which must be a subclass of {@link qx.io.jsonrpc.protocol.Parser}
+      */
+    parser: {
+      check : "qx.io.jsonrpc.protocol.Parser"
+    }
+  },
+
+  members :
+  {
+
+    /**
+     * A cache of the requests which have been sent out and are still pending
+     */
+    __requests : null,
+
+    /**
+     * If a service name has been configured, prepend it to the method name,
+     * unless it has already been prefixed
+     * @param {String} method
+     * @return {String}
+     * @private
+     */
+    _prependMethodPrefix(method) {
+      qx.core.Assert.assertString(method);
+      let methodPrefix = this.getMethodPrefix();
+      if (methodPrefix && !method.startsWith(methodPrefix)) {
+        return `${methodPrefix}${method}`;
+      }
+      return method;
+    },
+
+    /**
+     * Fires "error" event and throws the error after informing pending requests
+     * about the error.
+     * @param exception
+     * @private
+     */
+    _throwTransportException(exception) {
+      this.fireDataEvent("error", exception);
+      this.__requests.forEach(request => {
+        if (request instanceof qx.io.jsonrpc.protocol.Request) {
+          request.handleTransportException(exception);
+        }
+      });
+      throw exception;
+    },
+
+    /**
+     * Send the given JSON-RPC message object using the configured transport
+     *
+     * @param {qx.io.jsonrpc.protocol.Message|qx.io.jsonrpc.protocol.Batch} message
+     * @return {qx.Promise} Promise that resolves (with no data)
+     * when the message has been successfully sent out, and rejects
+     * when there is an error or a cancellation up to that point.
+     */
+    async send(message) {
+      if (!(message instanceof qx.io.jsonrpc.protocol.Message || message instanceof qx.io.jsonrpc.protocol.Batch)) {
+        throw new Error("Argument must be instanceof qx.io.jsonrpc.protocol.Message or qx.io.jsonrpc.protocol.Batch");
+      }
+
+      // filter by type
+      let messages = message instanceof qx.io.jsonrpc.protocol.Batch ? message.getBatch().toArray() : [message];
+      let requests = messages.filter(message => message instanceof qx.io.jsonrpc.protocol.Request);
+
+      // store requests
+      requests.forEach(request => {
+        let id = request.getId();
+        if (this.__requests[id] !== undefined) {
+          throw new qx.io.exception.Transport(`Request ID ${id} is already in use`, qx.io.exception.Transport.INVALID_ID, {request: message.toObject()});
+        }
+        this.__requests[id] = request;
+      });
+
+      // inform listeners
+      this.fireDataEvent("outgoingRequest", message);
+
+      // debugging
+      if (qx.core.Environment.get("qx.io.jsonrpc.debug")) {
+        this.debug(">>> Outgoing json-rpc message: " + message);
+      }
+
+      // send it async, using transport-specific implementation
+      return this.getTransport().send(message.toString());
+    },
+
+    /**
+     * Sends a single JSON-RPC request. If a method prefix name has been configured,
+     * it will be prepended to the method name.
+     * @param {String} method
+     * @param {Array|Object?} params
+     * @return {qx.Promise} Promise that resolves with the result to that request,
+     * and rejects with an exception in the {@link qx.io.jsonrpc.exception} namespace.
+     */
+    async sendRequest(method, params) {
+      const request = new qx.io.jsonrpc.protocol.Request(this._prependMethodPrefix(method), params);
+      await this.send(request);
+      return await request.getPromise();
+    },
+
+    /**
+     * Sends a single JSON-RPC notification. Will use the method prefix
+     * @param {String} method
+     * @param {Array|Object?} params
+     * @return {qx.Promise} Promise that resolves immediately, (i.e. when the
+     * notification has been sent out (which is synchronous)
+     */
+    async sendNotification(method, params) {
+      const notification = new qx.io.jsonrpc.protocol.Notification(this._prependMethodPrefix(method), params);
+      await this.send(notification);
+    },
+
+    /**
+     * Send the given message batch. Will use the method prefix.
+     * @param {qx.io.jsonrpc.protocol.Batch} batch
+     * @return {qx.Promise} Promise that resolves with an array of the responses
+     * to all requests in the batch, or rejects with any error that occurs.
+     */
+    async sendBatch(batch) {
+      qx.core.Assert.assertInstance(batch, qx.io.jsonrpc.protocol.Batch);
+      if (this.getMethodPrefix()) {
+        batch.getBatch().forEach(message => message.setMethod(this._prependMethodPrefix(message.getMethod())));
+      }
+      await this.send(batch);
+      return await qx.Promise.all(batch.getPromises());
+    },
+
+    /**
+     * Receives and handles an incoming JSON-RPC compliant message data
+     * @param {String} json JSON data
+     */
+    handleIncoming(json) {
+      if (qx.core.Environment.get("qx.io.jsonrpc.debug")) {
+        this.debug("<<< Incoming json-rpc message: " + json);
+      }
+      let message;
+      try {
+        message = this.getParser().parse(json);
+        // act on each message
+        this.handleMessage(message);
+      } catch (e) {
+        this._throwTransportException(e);
+      } finally {
+        // cleanup
+        if (message instanceof qx.io.jsonrpc.protocol.Batch) {
+          message.getBatch().forEach(msg => this._cleanup(msg));
+        } else if (message instanceof qx.io.jsonrpc.protocol.Message) {
+          this._cleanup(message);
+        }
+      }
+    },
+
+    /**
+     * Clean up after a message has been received
+     * @param {qx.io.jsonrpc.protocol.Message} message
+     * @private
+     */
+    _cleanup(message) {
+      message.dispose();
+    },
+
+    /**
+     * Handle an incoming message or batch of messages
+     * @param {qx.io.jsonrpc.protocol.Message|qx.io.jsonrpc.protocol.Batch} message Message or Batch
+     */
+    handleMessage(message) {
+      // handle batches
+      if (message instanceof qx.io.jsonrpc.protocol.Batch) {
+        message.getBatch().forEach(msg => this.handleMessage(msg));
+        return;
+      }
+      // handle individual message
+      qx.core.Assert.assertInstance(message, qx.io.jsonrpc.protocol.Message);
+      let request;
+      let id;
+      if (message instanceof qx.io.jsonrpc.protocol.Result || message instanceof qx.io.jsonrpc.protocol.Error) {
+        // handle results and errors, which are responses to sent requests
+        id = message.getId();
+        request = this.__requests[id];
+        if (request === undefined) {
+          // no request with this id exists
+          throw new qx.io.exception.Transport(
+            `Invalid jsonrpc response data: Unknown id ${id}.`,
+            qx.io.exception.Transport.UNKNOWN_ID,
+            message.toObject()
+          );
+        }
+        if (request === true) {
+          // the request has already been responded to
+          throw new qx.io.exception.Transport(
+              `Invalid jsonrpc response data: multiple responses with same id ${id}.`,
+              qx.io.exception.Transport.DUPLICATE_ID,
+              message.toObject()
+          );
+        }
+      }
+      // handle the different message types
+      if (message instanceof qx.io.jsonrpc.protocol.Result) {
+        // resolve the individual promise
+        request.getPromise().resolve(message.getResult());
+      } else if (message instanceof qx.io.jsonrpc.protocol.Error) {
+
+        let error = message.getError();
+        let ex = new qx.io.exception.Protocol(
+          error.message,
+          error.code,
+          message.toObject()
+        );
+        // inform listeners
+        this.fireDataEvent("error", ex);
+        // reject the individual promise
+        request.getPromise().reject(ex);
+      } else if (message instanceof qx.io.jsonrpc.protocol.Request || message instanceof qx.io.jsonrpc.protocol.Notification) {
+        // handle peer-originated requests and notifications
+        this.fireDataEvent("incomingRequest", message);
+      } else {
+        throw new Error("Unhandled message:" + message.toString());
+      }
+      // mark request as handled (and remove reference so it can be gc'ed)
+      this.__requests[id] = true;
+    }
+  },
+
+  environment: {
+    "qx.io.jsonrpc.debug" : false
+  }
+});

package/source/class/qx/io/jsonrpc/__init__.js

@@ -0,0 +1,15 @@
+/**
+ * <p>This namespace provides an API implementing the <a
+ * href="https://www.jsonrpc.org/specification">JSON Remote
+ * Procedure Call (JSON-RPC) version 2 specification</a></p>
+ *
+ * <p>JSON-RPC v2 is transport-agnostic. We provide a high-level
+ * API interface (qx.io.jsonrpc.Client), a transport interface
+ * (qx.io.transport.ITransport) and an HTTP transport implementation.
+ * Other transports based on websockets or other mechanisms can be added later.</p>
+ *
+ * <p>Please refer to
+ * <a href="https://github.com/qooxdoo/incubator.qx.io.jsonrpc/blob/master/readme.md#usage">
+ *    the documentation on GitHub
+ *  </a></p>
+ */

package/source/class/qx/io/jsonrpc/protocol/Batch.js

@@ -0,0 +1,97 @@
+/* ************************************************************************
+
+   qooxdoo - the new era of web development
+
+   http://qooxdoo.org
+
+   Copyright:
+      2020 Christian Boulanger
+
+   License:
+     MIT: https://opensource.org/licenses/MIT
+     See the LICENSE file in the project's top-level directory for details.
+
+   Authors:
+     * Christian Boulanger (cboulanger)
+
+************************************************************************ */
+
+/**
+ * An object representing a JSON-RPC v2.0 batch message object. You can add
+ * one or more of the following message objects to the batch:
+ *  - {@link qx.io.jsonrpc.protocol.Request}
+ *  - {@link qx.io.jsonrpc.protocol.Notification}
+ *  - {@link qx.io.jsonrpc.protocol.Result}
+ *  - {@link qx.io.jsonrpc.protocol.Error}
+ *  @see https://www.jsonrpc.org/specification#batch
+ */
+qx.Class.define("qx.io.jsonrpc.protocol.Batch",{
+  extend: qx.core.Object,
+  properties: {
+    batch : {
+      check: "qx.data.Array"
+    }
+  },
+  construct() {
+    this.base(arguments);
+    this.setBatch(new qx.data.Array());
+  },
+  members: {
+
+    /**
+     * Adds a request or notification to the batch
+     * @param {qx.io.jsonrpc.protocol.Message} message
+     * @return {qx.io.jsonrpc.protocol.Batch}
+     */
+    add(message) {
+      qx.core.Assert.assertInstance(message, qx.io.jsonrpc.protocol.Message);
+      this.getBatch().push(message);
+      // return the instance for chaining
+      return this;
+    },
+
+    /**
+     * Adds a request to the batch
+     * @param method
+     * @param params
+     */
+    addRequest(method,params) {
+      this.add(new qx.io.jsonrpc.protocol.Request(method, params));
+      return this;
+    },
+
+    /**
+     * Adds a notification to the batch
+     * @param method
+     * @param params
+     */
+    addNotification(method,params) {
+      this.add(new qx.io.jsonrpc.protocol.Notification(method, params));
+      return this;
+    },
+
+    /**
+     * Returns an array of the promises of the requests in the batch
+     * @return {qx.Promise[]}
+     */
+    getPromises() {
+      return this.getBatch().map(message => message.getPromise());
+    },
+
+    /**
+     * Returns the message as a native object
+     * @return {*}
+     */
+    toObject() {
+      return this.getBatch().toArray().map(message => message.toObject());
+    },
+
+    /**
+     * Returns the message as a JSON string
+     * @return {String}
+     */
+    toString() {
+      return JSON.stringify(this.getBatch().toArray().map(message => message.toObject()));
+    }
+  }
+});

package/source/class/qx/io/jsonrpc/protocol/Error.js

@@ -0,0 +1,63 @@
+/* ************************************************************************
+
+   qooxdoo - the new era of web development
+
+   http://qooxdoo.org
+
+   Copyright:
+      2020 Christian Boulanger
+
+   License:
+     MIT: https://opensource.org/licenses/MIT
+     See the LICENSE file in the project's top-level directory for details.
+
+   Authors:
+     * Christian Boulanger (cboulanger)
+
+************************************************************************ */
+
+/**
+ * A JSON-RPC v2.0 error message object, which is a response to a {@link qx.io.jsonrpc.protocol.Request},
+ * indicating a failure during the processing of the request on the server.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+qx.Class.define("qx.io.jsonrpc.protocol.Error",{
+  extend: qx.io.jsonrpc.protocol.Message,
+  properties: {
+
+    /**
+     * The integer id of the request
+     * @var {Number}
+     */
+    id : {
+      check: value => qx.lang.Type.isNumber(value) && parseInt(value, 10) === value
+    },
+
+    /**
+     * The error object
+     * @var {Object}
+     */
+    error : {
+      check : value => qx.lang.Type.isObject(value) && "code" in value && "message" in value
+    }
+  },
+  /**
+   * The response messsage constructor
+   * @param {Number} id^
+   * @param {Number} code
+   * @param {String} message
+   * @param {*?} data
+   */
+  construct(id, code, message, data) {
+    this.base(arguments);
+    this.setId(id);
+    if (!qx.lang.Type.isNumber(code) || parseInt(code, 10) !== code ) {
+      throw new Error("Code must be an integer");
+    }
+    let errorObj = {code, message};
+    if (data) {
+      errorObj.data = data;
+    }
+    this.setError(errorObj);
+  }
+});

package/source/class/qx/io/jsonrpc/protocol/Message.js

@@ -0,0 +1,48 @@
+/* ************************************************************************
+
+   qooxdoo - the new era of web development
+
+   http://qooxdoo.org
+
+   Copyright:
+      2020 Christian Boulanger
+
+   License:
+     MIT: https://opensource.org/licenses/MIT
+     See the LICENSE file in the project's top-level directory for details.
+
+   Authors:
+     * Christian Boulanger (cboulanger)
+
+************************************************************************ */
+
+/**
+ * The base class for all JSON-RPC v2.0 object except {@link qx.io.jsonrpc.protocol.Batch}
+ */
+qx.Class.define("qx.io.jsonrpc.protocol.Message",{
+  extend: qx.core.Object,
+  properties: {
+    jsonrpc : {
+      check: "String",
+      init: "2.0"
+    }
+  },
+
+  members : {
+    /**
+     * Serialize to JSON string
+     * @return {String}
+     */
+    toString() {
+      return qx.util.Serializer.toJson(this);
+    },
+
+    /**
+     * Serialize to a native javascript object
+     * @return {Object}
+     */
+    toObject() {
+      return qx.util.Serializer.toNativeObject(this);
+    }
+  }
+});

package/source/class/qx/io/jsonrpc/protocol/Notification.js

@@ -0,0 +1,45 @@
+/* ************************************************************************
+
+   qooxdoo - the new era of web development
+
+   http://qooxdoo.org
+
+   Copyright:
+      2020 Christian Boulanger
+
+   License:
+     MIT: https://opensource.org/licenses/MIT
+     See the LICENSE file in the project's top-level directory for details.
+
+   Authors:
+     * Christian Boulanger (cboulanger)
+
+************************************************************************ */
+
+/**
+ * A JSON-RPC v2.0 notification object
+ * @see https://www.jsonrpc.org/specification#request_object
+ */
+qx.Class.define("qx.io.jsonrpc.protocol.Notification",{
+  extend: qx.io.jsonrpc.protocol.Message,
+  properties: {
+    method : {
+      check: "String",
+      nullable: false
+    },
+    params : {
+      check: "Object",
+      nullable: true,
+      init: null
+    }
+  },
+  /**
+   * Notification constructor
+   * @param {String} method
+   * @param {Object?} params
+   */
+  construct(method, params=null) {
+    this.base(arguments);
+    this.set({method, params});
+  }
+});

package/source/class/qx/io/jsonrpc/protocol/Parser.js

@@ -0,0 +1,81 @@
+/* ************************************************************************
+
+   qooxdoo - the new era of web development
+
+   http://qooxdoo.org
+
+   Copyright:
+      2020 Christian Boulanger
+
+   License:
+     MIT: https://opensource.org/licenses/MIT
+     See the LICENSE file in the project's top-level directory for details.
+
+   Authors:
+     * Christian Boulanger (cboulanger)
+
+************************************************************************ */
+
+
+/**
+ * The parser object has a parse() method, which takes a UTF-encoded string and
+ * returns an instance of the correponding subclass of {@link qx.io.jsonrpc.protocol.Message} or
+ * a {@link qx.io.jsonrpc.protocol.Batch} instance.
+ */
+qx.Class.define("qx.io.jsonrpc.protocol.Parser", {
+  extend: qx.core.Object,
+  members: {
+    /**
+     * Given an UTF-8 encoded string, return the corresponding message object,
+     * which is one of {@link qx.io.jsonrpc.protocol.Batch}, {@link qx.io.jsonrpc.protocol.Notification},
+     * {@link qx.io.jsonrpc.protocol.Request}, {@link qx.io.jsonrpc.protocol.Result}, or
+     * {@link qx.io.jsonrpc.protocol.Error}.
+     *
+     * @param {String} message
+     * @return {qx.io.jsonrpc.protocol.Message}
+     * @throws {qx.io.exception.Transport}
+     */
+    parse(message) {
+      try {
+        message = JSON.parse(message);
+      } catch (e) {
+        throw new qx.io.exception.Transport(
+          e.toString(),
+          qx.io.exception.Transport.INVALID_JSON,
+          {message}
+        );
+      }
+      if (message === null) {
+        throw new qx.io.exception.Transport(
+          "No data",
+          qx.io.exception.Transport.NO_DATA
+        );
+      }
+      // batch
+      if (qx.lang.Type.isArray(message)) {
+        const batch = new qx.io.jsonrpc.protocol.Batch();
+        message.forEach(item => batch.add(this.parse(JSON.stringify(item))));
+        return batch;
+      }
+      // individual message
+      let {id, result, method, params, error} = message;
+      if (id !== undefined && result !== undefined && error === undefined && method === undefined) {
+        return new qx.io.jsonrpc.protocol.Result(id, result);
+      }
+      if (id !== undefined && result === undefined && error !== undefined && method === undefined) {
+        return new qx.io.jsonrpc.protocol.Error(id, error.code, error.message, error.data);
+      }
+      if (id !== undefined && result === undefined && error === undefined && method !== undefined) {
+        return new qx.io.jsonrpc.protocol.Request(method, params, id);
+      }
+      if (id === undefined && result === undefined && error === undefined && method !== undefined) {
+        return new qx.io.jsonrpc.protocol.Notification(method, params);
+      }
+      throw new qx.io.exception.Transport(
+        "Cannot parse message data.",
+        qx.io.exception.Transport.INVALID_MSG_DATA,
+        {message}
+      );
+    }
+  }
+});