Source: client/client-factory.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 {ActorRequestFactory} from "./actor-request-factory";
  30. import {Client} from './client';
  31. import {CommandingClient} from "./commanding-client";
  32. import {HttpClient} from "./http-client";
  33. import {HttpEndpoint} from "./http-endpoint";
  34. import {HttpResponseHandler} from "./http-response-handler";
  36. /**
  37.  * @typedef {Object} ClientOptions a type of object for initialization of Spine client
  38.  *
  39.  * @property {!Array<Object>} protoIndexFiles
  40.  *  the list of the `index.js` files generated by {@link https://github.com/SpineEventEngine/base/tree/master/tools/proto-js-plugin the Protobuf plugin for JS}
  41.  * @property {?string} endpointUrl
  42.  *  the URL of the Spine-based backend endpoint
  43.  * @property {?HttpClient} httpClient
  44.  *  custom implementation of HTTP client to use; defaults to {@link HttpClient}.
  45.  * @property {?HttpResponseHandler} httpResponseHandler
  46.  *  custom implementation of HTTP response handler; defaults to {@link HttpResponseHandler}
  47.  * @property {?firebase.database.Database} firebaseDatabase
  48.  *  the Firebase Database that will be used to retrieve data from
  49.  * @property {?ActorProvider} actorProvider
  50.  *  the provider of the user interacting with Spine
  51.  * @property {?Client} implementation
  52.  *  the custom implementation of `Client`
  53.  * @property {?Routing} routing
  54.  *  custom configuration of HTTP endpoints
  55.  * @property {?TenantProvider} tenantProvider
  56.  *  the provider of an active tenant ID, if not specified, the application is considered
  57.  *  single-tenant
  58.  * @property {?Duration} subscriptionKeepUpInterval
  59.  *  the custom interval for sending requests to keep up subscriptions
  60.  */
  62. /**
  63.  * An abstract factory for creation of `Client` instances.
  64.  *
  65.  * Ensures that the `ClientOptions` contain list of the `index.js` files generated by
  66.  * {@link https://github.com/SpineEventEngine/base/tree/master/tools/proto-js-plugin the Protobuf plugin for JS}
  67.  * and performs registration of types and parsers containing in these files.
  68.  *
  69.  * Creation of the concrete implementation of `Client` instances is delegated to inheritors.
  70.  */
  71. export class AbstractClientFactory {
  73.   /**
  74.    * Creates a new instance of `Client` implementation in accordance with given options.
  75.    *
  76.    * @param {!ClientOptions} options client initialization options
  77.    * @return {Client} a `Client` instance
  78.    */
  79.   static createClient(options) {
  80.     this._ensureOptionsSufficient(options);
  81.     return this._clientFor(options);
  82.   }
  84.   /**
  85.    * Creates a new instance of `Client` implementation in accordance with given options.
  86.    *
  87.    * @param {!ClientOptions} options
  88.    * @return {Client}
  89.    * @protected
  90.    */
  91.   static _clientFor(options) {
  92.     throw new Error('Not implemented in abstract base')
  93.   }
  95.   /**
  96.    * Creates a new instance of `QueryingClient` implementation in accordance with given options.
  97.    *
  98.    * @param {!ClientOptions} options client initialization options
  99.    * @return {QueryingClient} a `QueryingClient` instance
  100.    */
  101.   static createQuerying(options) {
  102.     throw new Error('Not implemented in abstract base')
  103.   }
  105.   /**
  106.    * Creates a new instance of `SubscribingClient` implementation in accordance with given options.
  107.    *
  108.    * @param {!ClientOptions} options client initialization options
  109.    * @return {SubscribingClient} a `SubscribingClient` instance
  110.    */
  111.   static createSubscribing(options) {
  112.     throw new Error('Not implemented in abstract base')
  113.   }
  115.   /**
  116.    * Creates a new instance of `CommandingClient` implementation in accordance with given options.
  117.    *
  118.    * @param {!ClientOptions} options client initialization options
  119.    * @return {CommandingClient} a `CommandingClient` instance
  120.    */
  121.   static createCommanding(options) {
  122.     const httpClient = this._createHttpClient(options);
  123.     const httpResponseHandler = this._createHttpResponseHandler(options)
  124.     const endpoint = new HttpEndpoint(httpClient, httpResponseHandler, options.routing);
  125.     const requestFactory = ActorRequestFactory.create(options);
  127.     return new CommandingClient(endpoint, requestFactory);
  128.   }
  130.   /**
  131.    * Creates an HTTP client basing on the passed {@link ClientOptions}.
  132.    *
  133.    * In case a custom HTTP client is specified via the `options`, this instance is returned.
  134.    * Otherwise, a new instance of `HttpClient` is returned.
  135.    *
  136.    * @param {!ClientOptions} options client initialization options
  137.    * @return {HttpClient} an instance of HTTP client
  138.    * @protected
  139.    */
  140.   static _createHttpClient(options) {
  141.     const customClient = options.httpClient;
  142.     if (!!customClient) {
  143.       if (!customClient instanceof HttpClient) {
  144.         throw new Error('The custom HTTP client implementation passed via `options.httpClient` ' +
  145.             'must extend `HttpClient`.');
  146.       }
  147.       return customClient;
  148.     } else {
  149.       return new HttpClient(options.endpointUrl);
  150.     }
  151.   }
  153.   /**
  154.    * Creates an HTTP response handler judging on the passed {@link ClientOptions}.
  155.    *
  156.    * In case a custom HTTP response handler is specified via the `options`,
  157.    * this instance is returned. Otherwise, a new instance of `HttpResponseHandler` is returned.
  158.    *
  159.    * @param {!ClientOptions} options client initialization options
  160.    * @return {HttpResponseHandler} an instance of HTTP response handler
  161.    * @protected
  162.    */
  163.   static _createHttpResponseHandler(options) {
  164.     const customHandler = options.httpResponseHandler;
  165.     if (!!customHandler) {
  166.       if (!customHandler instanceof HttpResponseHandler) {
  167.         throw new Error('The custom HTTP response handler implementation' +
  168.             ' passed via `options.httpResponseHandler` must extend `HttpResponseHandler`.');
  169.       }
  170.       return customHandler;
  171.     } else {
  172.       return new HttpResponseHandler();
  173.     }
  174.   }
  176.   /**
  177.    * Ensures whether options object is sufficient for client initialization.
  178.    *
  179.    * @param {!ClientOptions} options
  180.    * @protected
  181.    */
  182.   static _ensureOptionsSufficient(options) {
  183.     if (!options) {
  184.       throw new Error('Unable to initialize client. The `ClientOptions` is undefined.');
  185.     }
  187.     const indexFiles = options.protoIndexFiles;
  188.     if (!Array.isArray(indexFiles) || indexFiles.length === 0) {
  189.       throw new Error('Only a non-empty array is allowed as ClientOptions.protoIndexFiles parameter.');
  190.     }
  192.     indexFiles.forEach(indexFile => {
  193.       if (typeof indexFile !== 'object'
  194.           || !(indexFile.types instanceof Map)
  195.           || !(indexFile.parsers instanceof Map) ) {
  196.         throw new Error('Unable to register Protobuf index files.' +
  197.           ' Check the `ClientOptions.protoIndexFiles` contains files' +
  198.           ' generated with "io.spine.tools:spine-proto-js-plugin".');
  199.       }
  200.     });
  201.   }
  202. }
  204. /**
  205.  * An implementation of the `AbstractClientFactory` that returns a client instance
  206.  * provided in `ClientOptions` parameter.
  207.  */
  208. export class CustomClientFactory extends AbstractClientFactory {
  210.   /**
  211.    * Returns a custom `Client` implementation provided in options. Expects that the given options
  212.    * contain an implementation which extends `Client`.
  213.    *
  214.    * Can be used to provide mock implementations of `Client`.
  215.    *
  216.    * @param {ClientOptions} options
  217.    * @return {Client} a custom `Client` implementation provided in options
  218.    * @override
  219.    */
  220.   static _clientFor(options) {
  221.     return options.implementation;
  222.   }
  224.   /**
  225.    * Returns a custom `QueryingClient` implementation provided in options. Expects that the given
  226.    * options contain an implementation which extends `QueryingClient`.
  227.    *
  228.    * Can be used to provide mock implementations of `QueryingClient`.
  229.    *
  230.    * @param {ClientOptions} options
  231.    * @return {QueryingClient} a custom `QueryingClient` implementation provided in options
  232.    * @override
  233.    */
  234.   static createQuerying(options) {
  235.     return options.implementation;
  236.   }
  238.   /**
  239.    * Returns a custom `SubscribingClient` implementation provided in options. Expects that the given
  240.    * options contain an implementation which extends `SubscribingClient`.
  241.    *
  242.    * Can be used to provide mock implementations of `SubscribingClient`.
  243.    *
  244.    * @param {ClientOptions} options
  245.    * @return {SubscribingClient} a custom `SubscribingClient` implementation provided in options
  246.    * @override
  247.    */
  248.   static createSubscribing(options) {
  249.     return options.implementation;
  250.   }
  252.   /**
  253.    * Returns a custom `CommandingClient` implementation provided in options. Expects that the given
  254.    * options contain an implementation which extends `CommandingClient`.
  255.    *
  256.    * Can be used to provide mock implementations of `CommandingClient`.
  257.    *
  258.    * @param {ClientOptions} options
  259.    * @return {CommandingClient} a custom `CommandingClient` implementation provided in options
  260.    * @override
  261.    */
  262.   static createCommanding(options) {
  263.     return options.implementation;
  264.   }
  266.   /**
  267.    * @override
  268.    */
  269.   static _ensureOptionsSufficient(options) {
  270.     super._ensureOptionsSufficient(options);
  271.     const customClient = options.implementation;
  272.     if (!customClient || !(customClient instanceof Client)) {
  273.       throw new Error('Unable to initialize custom client implementation.' +
  274.         ' The `ClientOptions.implementation` must extend `Client`.');
  275.     }
  276.   }
  277. }