Source: client/http-endpoint.js

  1. /*
  2.  * Copyright 2023, TeamDev. All rights reserved.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  * http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Redistribution and use in source and/or binary forms, with or without
  11.  * modification, must retain the above copyright notice and the following
  12.  * disclaimer.
  13.  *
  14.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  15.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  16.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  17.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  18.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  19.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  20.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  24.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25.  */
  27. "use strict";
  29. import {TypedMessage} from './typed-message';
  30. import {Subscriptions} from '../proto/spine/web/keeping_up_pb';
  31. import {HttpResponseHandler} from "./http-response-handler";
  33. /**
  34.  * @typedef {Object} SubscriptionRouting
  35.  *
  36.  * @property {string} create
  37.  *  the name of the subscription creation endpoint; defaults to "/subscription/create"
  38.  * @property {string} keepUp
  39.  *  the name of the subscription keep up endpoint; defaults to "/subscription/keep-up"
  40.  * @property {string} keepUpAll
  41.  *  the name of the subscription bulk keep up endpoint; defaults to "/subscription/keep-up-all"
  42.  * @property {string} cancel
  43.  *  the name of the subscription cancellation endpoint; defaults to "/subscription/cancel"
  44.  * @property {string} cancelAll
  45.  *  the name of the subscription bulk cancellation endpoint; defaults to "/subscription/cancel-all"
  46.  */
  48. /**
  49.  * @typedef {Object} Routing
  50.  *
  51.  * @property {string} query
  52.  *  the name of the query endpoint; defaults to "/query"
  53.  * @property {string} command
  54.  *  the name of the command endpoint; defaults to "/command"
  55.  * @property {!SubscriptionRouting} subscription
  56.  *  the config of the subscription endpoints
  57.  */
  59. class Endpoint {
  61.   /**
  62.    * Sends a command to the endpoint.
  63.    *
  64.    * @param {!TypedMessage<Command>} command a Command  to send to the Spine server
  65.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  66.    *                           an error occurs
  67.    */
  68.   command(command) {
  69.     return this._executeCommand(command);
  70.   }
  72.   /**
  73.    * Sends a query to the endpoint.
  74.    *
  75.    * @param {!spine.client.Query} query a Query to Spine server to retrieve some domain entities
  76.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  77.    *                           an error occurs
  78.    */
  79.   query(query) {
  80.     const typedQuery = TypedMessage.of(query);
  81.     return this._performQuery(typedQuery);
  82.   }
  84.   /**
  85.    * Sends a request to subscribe to a provided topic to an endpoint.
  86.    *
  87.    * @param {!spine.client.Topic} topic a topic for which a subscription is created
  88.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  89.    *                           an error occurs
  90.    */
  91.   subscribeTo(topic) {
  92.     const typedTopic = TypedMessage.of(topic);
  93.     return this._subscribeTo(typedTopic);
  94.   }
  96.   /**
  97.    * Sends a request to keep a subscription, stopping it from being closed by server.
  98.    *
  99.    * @param {!spine.client.Subscription} subscription a subscription that should be kept open
  100.    * @returns {Promise<Object>} a promise of a successful server response, rejected if
  101.    *                            an error occurs
  102.    */
  103.   keepUpSingleSubscription(subscription) {
  104.     const typedSubscription = TypedMessage.of(subscription);
  105.     return this._keepUp(typedSubscription);
  106.   }
  108.   /**
  109.    * Sends a request to keep up several subscriptions, preventing them
  110.    * from being closed by the server.
  111.    *
  112.    * @param {!Array<spine.client.Subscription>} subscriptions subscriptions that should be kept open
  113.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  114.    *                           an error occurs
  115.    */
  116.   keepUpSubscriptions(subscriptions) {
  117.     return this._keepUpAll(subscriptions);
  118.   }
  120.   /**
  121.    * Sends a request to cancel an existing subscription.
  122.    *
  123.    * Cancelling subscription stops the server from updating subscription with new values.
  124.    *
  125.    * @param {!spine.client.Subscription} subscription a subscription that should be kept open
  126.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  127.    *                           an error occurs
  128.    */
  129.   cancelSubscription(subscription) {
  130.     const typedSubscription = TypedMessage.of(subscription);
  131.     return this._cancel(typedSubscription);
  132.   }
  134.   /**
  135.    * Sends a request to cancel all the given subscriptions.
  136.    *
  137.    * Cancelling subscriptions stops the server from updating subscription with new values.
  138.    *
  139.    * @param {!Array<spine.client.Subscription>>} subscriptions subscriptions that should
  140.    *                                                           be cancelled
  141.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  142.    *                           an error occurs
  143.    */
  144.   cancelAll(subscriptions) {
  145.     return this._cancelAll(subscriptions);
  146.   }
  148.   /**
  149.    * @param {!TypedMessage<Command>} command a Command to send to the Spine server
  150.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  151.    *                           an error occurs
  152.    * @protected
  153.    * @abstract
  154.    */
  155.   _executeCommand(command) {
  156.     throw new Error('Not implemented in abstract base.');
  157.   }
  159.   /**
  160.    * @param {!TypedMessage<Query>} query a Query to Spine server to retrieve some domain entities
  161.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  162.    *                           an error occurs
  163.    * @protected
  164.    * @abstract
  165.    */
  166.   _performQuery(query) {
  167.     throw new Error('Not implemented in abstract base.');
  168.   }
  170.   /**
  171.    * @param {!TypedMessage<spine.client.Topic>} topic a topic to create a subscription for
  172.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  173.    *                           an error occurs
  174.    * @protected
  175.    * @abstract
  176.    */
  177.   _subscribeTo(topic) {
  178.     throw new Error('Not implemented in abstract base.');
  179.   }
  181.   /**
  182.    * @param {!TypedMessage<spine.client.Subscription>} subscription a subscription to keep alive
  183.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  184.    *                           an error occurs
  185.    * @protected
  186.    * @abstract
  187.    */
  188.   _keepUp(subscription) {
  189.     throw new Error('Not implemented in abstract base.');
  190.   }
  192.   /**
  193.    * @param {!Array<TypedMessage<spine.client.Subscription>>} subscriptions subscriptions to keep up
  194.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  195.    *                           an error occurs
  196.    * @protected
  197.    * @abstract
  198.    */
  199.   _keepUpAll(subscriptions) {
  200.     throw new Error('Not implemented in abstract base.');
  201.   }
  203.   /**
  204.    * @param {!TypedMessage<spine.client.Subscription>} subscription a subscription to be canceled
  205.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  206.    *                           an error occurs
  207.    * @protected
  208.    * @abstract
  209.    */
  210.   _cancel(subscription) {
  211.     throw new Error('Not implemented in abstract base.');
  212.   }
  215.   /**
  216.    * @param {!Array<spine.client.Subscription>} subscriptions subscriptions to be canceled
  217.    * @return {Promise<Object>} a promise of a successful server response, rejected if
  218.    *                           an error occurs
  219.    * @protected
  220.    * @abstract
  221.    */
  222.   _cancelAll(subscriptions) {
  223.     throw new Error('Not implemented in abstract base.');
  224.   }
  225. }
  227. /**
  228.  * Spine HTTP endpoint which is used to send Commands and Queries using
  229.  * the provided HTTP client.
  230.  */
  231. export class HttpEndpoint extends Endpoint {
  233.   /**
  234.    * @param {!HttpClient} httpClient a client sending requests to server
  235.    * @param {!HttpResponseHandler} responseHandler a handle for the HTTP responses from server
  236.    * @param {Routing} routing endpoint routing parameters
  237.    */
  238.   constructor(httpClient, responseHandler, routing) {
  239.     super();
  240.     this._httpClient = httpClient;
  241.     this._routing = routing;
  242.     this._responseHandler = responseHandler;
  243.   }
  245.   /**
  246.    * Sends a command to the endpoint.
  247.    *
  248.    * @param {!TypedMessage<Command>} command a Command to send to the Spine server
  249.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  250.    *                                      rejected if the client response is not `2xx`,
  251.    *                                      or a connection error occurs
  252.    * @protected
  253.    */
  254.   _executeCommand(command) {
  255.     const path = (this._routing && this._routing.command) || '/command';
  256.     return this._sendMessage(path, command);
  257.   }
  259.   /**
  260.    * Sends a query to the endpoint.
  261.    *
  262.    * @param {!TypedMessage<Query>} query a Query to Spine server to retrieve some domain entities
  263.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  264.    *                                      rejected if the client response is not `2xx`,
  265.    *                                      or a connection error occurs
  266.    * @protected
  267.    */
  268.   _performQuery(query) {
  269.     const path = (this._routing && this._routing.query) || '/query';
  270.     return this._sendMessage(path, query);
  271.   }
  273.   /**
  274.    * Sends a request to create a subscription for a topic.
  275.    *
  276.    * @param {!TypedMessage<spine.client.Topic>} topic a topic to subscribe to
  277.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  278.    *                                      rejected if the client response is not `2xx`,
  279.    *                                      or a connection error occurs
  280.    * @protected
  281.    */
  282.   _subscribeTo(topic) {
  283.     const path = (this._routing && this._routing.subscription && this._routing.subscription.create)
  284.         || '/subscription/create';
  285.     return this._sendMessage(path, topic);
  286.   }
  288.   /**
  289.    * Sends a request to keep alive the given subscription.
  290.    *
  291.    * @param {!TypedMessage<spine.client.Subscription>} subscription a subscription that is prevented
  292.    *                                                                  from being closed by server
  293.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  294.    *                                      rejected if the client response is not `2xx`,
  295.    *                                      or a connection error occurs
  296.    * @protected
  297.    */
  298.   _keepUp(subscription) {
  299.     const path = (this._routing && this._routing.subscription && this._routing.subscription.keepUp)
  300.         || '/subscription/keep-up';
  301.     return this._sendMessage(path, subscription);
  302.   }
  304.   /**
  305.    * Sends a request to keep alive the given subscriptions.
  306.    *
  307.    * @param {!Array<spine.client.Subscription>} subscriptions subscriptions that are prevented
  308.    *                                                          from being closed by the server
  309.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  310.    *                                      rejected if the client response is not `2xx`,
  311.    *                                      or a connection error occurs
  312.    * @protected
  313.    */
  314.   _keepUpAll(subscriptions) {
  315.     const path = (this._routing && this._routing.subscription && this._routing.subscription.keepUpAll)
  316.         || '/subscription/keep-up-all';
  317.     const request = new Subscriptions()
  318.     request.setSubscriptionList(subscriptions);
  319.     const typed = TypedMessage.of(request);
  320.     return this._sendMessage(path, typed);
  321.   }
  323.   /**
  324.    * Sends a request to cancel the given subscription.
  325.    *
  326.    * @param {!TypedMessage<spine.client.Subscription>} subscription a subscription to be canceled
  327.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  328.    *                                      rejected if the client response is not `2xx`,
  329.    *                                      or a connection error occurs
  330.    * @protected
  331.    */
  332.   _cancel(subscription) {
  333.     const path = (this._routing && this._routing.subscription && this._routing.subscription.cancel)
  334.         || '/subscription/cancel';
  335.     return this._sendMessage(path, subscription);
  336.   }
  338.   /**
  339.    * Sends a request to cancel the given subscriptions.
  340.    *
  341.    * @param {!Array<spine.client.Subscription>} subscriptions subscriptions to be canceled
  342.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  343.    *                                      rejected if the client response is not `2xx`,
  344.    *                                      or a connection error occurs
  345.    * @protected
  346.    */
  347.   _cancelAll(subscriptions) {
  348.     const path = (this._routing && this._routing.subscription && this._routing.subscription.cancelAll)
  349.         || '/subscription/cancel-all';
  350.     const request = new Subscriptions();
  351.     request.setSubscriptionList(subscriptions);
  352.     const typed = TypedMessage.of(request);
  353.     return this._sendMessage(path, typed);
  354.   }
  356.   /**
  357.    * Sends the given message to the given endpoint.
  358.    *
  359.    * @param {!string} endpoint an endpoint to send the message to
  360.    * @param {!TypedMessage} message a message to send, as a {@link TypedMessage}
  361.    * @return {Promise<Object|SpineError>} a promise of a successful server response JSON data,
  362.    *                                      rejected if the client response is not `2xx`,
  363.    *                                      or a connection error occurs
  364.    * @private
  365.    */
  366.   _sendMessage(endpoint, message) {
  367.     return new Promise((resolve, reject) => {
  368.       this._httpClient
  369.         .postMessage(endpoint, message)
  370.         .then(this._responseHandler.handle
  371.                 .bind(this._responseHandler),
  372.             this._responseHandler.onConnectionError
  373.                 .bind(this._responseHandler))
  374.         .then(resolve, reject);
  375.     });
  376.   }
  377. }