server/Application.js

  1. 'use strict';
  3. // External modules
  4. const http = require('http');
  5. const { EventEmitter } = require('node:events');
  6. const os = require('os');
  7. const socket_io = require('socket.io');
  9. // Local classes, etc
  10. const { constants, Message } = require('../shared.js');
  11. const { addStaticDirectory, getLocalIP, listen, router } = require('../predefined/routing.js');
  12. const Switchboard = require('./Switchboard.js');
  13. const WorkSpace = require('./WorkSpace.js');
  14. const ViewSpace = require('./ViewSpace.js');
  15. const MessageHandler = require('./MessageHandler.js');
  17. /**
  18.  * This module defines the API endpoint.
  19.  *
  20.  * @memberof module:server
  21.  *
  22.  * @param {object} [settings={}] - Settings data to be forwarded to the server.
  23.  * @param {boolean} [settings.applySmoothing=true] - Whether to apply smoothing
  24.  * to gesture inputs on coarse pointer devices (e.g. touch screens).
  25.  * @param {boolean} [settings.shadows=false] - Whether to show shadows of other views.
  26.  * @param {boolean} [settings.status=false] - Whether to show debugging status information in the view.
  27.  * @param {string} [settings.backgroundImage=undefined] - Optional background image for canvas.
  28.  * Not recommended. Prefer defining your own HTML, CSS, server, and routing.
  29.  * @param {string} [settings.clientScripts=undefined] - Optional extra javascript to load in client.
  30.  * Not recommended. Prefer defining your own HTML, CSS, server, and routing.
  31.  * @param {string} [settings.color=undefined] Background color for the workspace.
  32.  * Not recommended. Prefer defining your own HTML, CSS, server, and routing.
  33.  * @param {number} [clientLimit=10] - The number of active clients that are allowed
  34.  * Not recommended. Prefer defining your own HTML, CSS, server, and routing.
  35.  * @param {express.app} [appRouter=predefined.routing.router()] - Route handler to use.
  36.  * @param {http.Server} [server=http.createServer()] - HTTP server to use.
  37.  */
  38. class Application {
  39.   constructor(settings = {}, appRouter = router(), server = undefined) {
  40.     /**
  41.      * Express app for routing.
  42.      * @type {express.app}
  43.      * @see {@link https://expressjs.com/en/4x/api.html#app}
  44.      */
  45.     this.router = appRouter;
  47.     /**
  48.      * HTTP server for sending and receiving data.
  49.      *
  50.      * @type {http.Server}
  51.      */
  52.     if (server) {
  53.       this.httpServer = server;
  54.     } else {
  55.       this.httpServer = http.createServer(this.router);
  56.     }
  58.     /**
  59.      * Socket.io instance using http server.
  60.      */
  61.     this.ioServer = new socket_io.Server(this.httpServer);
  63.     /**
  64.      * Socket.io namespace in which to operate.
  65.      *
  66.      * @type {Namespace}
  67.      * @see {@link https://socket.io/docs/v4/server-api/}
  68.      */
  69.     this.namespace = this.ioServer.of(constants.NS_WAMS);
  71.     /**
  72.      * Settings for the application.
  73.      *
  74.      * @type {object}
  75.      */
  76.     this.settings = { ...Application.DEFAULTS, ...settings };
  78.     /**
  79.      * The main model for items.
  80.      *
  81.      * @type {module:server.WorkSpace}
  82.      */
  83.     this.workspace = new WorkSpace(this.namespace);
  85.     /**
  86.      * The MessageHandler responds to messages.
  87.      *
  88.      * @type {module:server.MessageHandler}
  89.      */
  90.     this.messageHandler = new MessageHandler(this);
  92.     /**
  93.      * The main model for views.
  94.      *
  95.      * @type {module:server.ViewSpace}
  96.      */
  97.     this.viewspace = new ViewSpace(this.messageHandler);
  99.     /**
  100.      * The switchboard allows communication with clients
  101.      *
  102.      * @type {module:server.Switchboard}
  103.      */
  104.     this.switchboard = new Switchboard(this, this.namespace, this.settings.clientLimit);
  105.   }
  107.   /**
  108.    * Add a static route to the router.
  109.    *
  110.    * @memberof module:server.Application
  111.    *
  112.    * @param {string} staticDir - The path to the static directory to add
  113.    */
  114.   addStaticDirectory(staticDir) {
  115.     addStaticDirectory(this.router, staticDir);
  116.   }
  118.   /**
  119.    * Start the server on the given hostname and port.
  120.    *
  121.    * @memberof module:server.Application
  122.    *
  123.    * @param {number} [port=9000] - Valid port number on which to listen.
  124.    * @param {string} [host=getLocalIP()] - IP address or hostname on which to
  125.    * listen.
  126.    * @see module:server.Application~getLocalIP
  127.    */
  128.   listen(port = 9000, host = '0.0.0.0') {
  129.     listen(this.httpServer, host, port);
  130.   }
  132.   /**
  133.    * Remove the given item from the workspace.
  134.    *
  135.    * @param {module:server.ServerItem} item - Item to remove.
  136.    */
  137.   removeItem(item) {
  138.     this.workspace.removeItem(item);
  139.   }
  141.   /**
  142.    * Spawn a new element with the given values in the workspace.
  143.    *
  144.    * @param {Object} values - Data describing the element to spawn.
  145.    * @return {module:server.ServerElement} The newly spawned element.
  146.    */
  147.   spawnElement(values) {
  148.     return this.workspace.spawnElement(values);
  149.   }
  151.   /**
  152.    * Spawn a new image with the given values in the workspace.
  153.    *
  154.    * @param {Object} values - Data describing the image to spawn.
  155.    * @return {module:server.ServerImage} The newly spawned image.
  156.    */
  157.   spawnImage(values) {
  158.     return this.workspace.spawnImage(values);
  159.   }
  161.   /**
  162.    * Spawn a new item with the given values in the workspace.
  163.    *
  164.    * @param {Object} itemdata - Data describing the item to spawn.
  165.    * @return {module:server.ServerItem} The newly spawned item.
  166.    */
  167.   spawnItem(values) {
  168.     return this.workspace.spawnItem(values);
  169.   }
  171.   /**
  172.    * Spawn an object. Object type is determined by the
  173.    * `type` key value of the argument object.
  174.    *
  175.    * @param {Object} itemdata - Data describing the object to spawn.
  176.    * @return {module:server.ServerItem} The newly spawned object.
  177.    */
  178.   spawn(values) {
  179.     switch (values.type) {
  180.       case 'item':
  181.         return this.spawnItem(values);
  182.       case 'item/image':
  183.         return this.spawnImage(values);
  184.       case 'item/element':
  185.         return this.spawnElement(values);
  186.       default:
  187.         return this.spawnItem(values);
  188.     }
  189.   }
  191.   /**
  192.    * Create a group for existing items in the workspace.
  193.    * A group allows to interact with several elements simultaneously.
  194.    *
  195.    * @param  {object} values properties for the group
  196.    */
  197.   createItemGroup(values) {
  198.     return this.workspace.createItemGroup(values);
  199.   }
  201.   /**
  202.    * Create a group for views in the viewspace. The views in a group will be
  203.    * able to perform multi-device gestures together.
  204.    */
  205.   createViewGroup() {
  206.     return this.viewspace.createViewGroup();
  207.   }
  209.   /**
  210.    * Send Message to all clients to dispatch user-defined action.
  211.    *
  212.    * @param {string} action name of the user-defined action.
  213.    * @param {object} payload argument of the user-defined action function.
  214.    */
  215.   dispatch(action, payload) {
  216.     this.workspace.namespace.emit(Message.DISPATCH, { action, payload });
  217.   }
  218. }
  220. Object.assign(Application.prototype, EventEmitter.prototype);
  222. /**
  223.  * The default values for an Application.
  224.  *
  225.  * @type {object}
  226.  */
  227. Application.DEFAULTS = Object.freeze({
  228.   applySmoothing: true,
  229.   backgroundImage: undefined,
  230.   clientLimit: 10,
  231.   clientScripts: undefined,
  232.   color: undefined,
  233.   maximizeCanvas: true,
  234.   shadows: false,
  235.   status: false,
  236.   stylesheets: undefined,
  237. });
  239. module.exports = Application;