Source: components/cli.js

  1. "use strict";
  2. var AppServiceRegistration = require("matrix-appservice").AppServiceRegistration;
  3. var ConfigValidator = require("./config-validator");
  4. var fs = require("fs");
  5. var nopt = require("nopt");
  6. var path = require("path");
  7. var yaml = require("js-yaml");
  9. var DEFAULT_PORT = 8090;
  10. var DEFAULT_FILENAME = "registration.yaml";
  11. const log = require("./logging").get("cli");
  13. /**
  14.  * @constructor
  15.  * @param {Object} opts CLI options
  16.  * @param {Cli~runBridge} opts.run The function called when you should run the bridge.
  17.  * @param {Cli~generateRegistration} opts.generateRegistration The function
  18.  * called when you should generate a registration.
  19.  * @param {Object=} opts.bridgeConfig Bridge-specific config info. If null, no
  20.  * --config option will be present in the CLI. Default: null.
  21.  * @param {boolean=} opts.bridgeConfig.affectsRegistration True to make the
  22.  * --config option required when generating the registration. The parsed config
  23.  * can be accessed via <code>Cli.getConfig()</code>.
  24.  * @param {string|Object=} opts.bridgeConfig.schema Path to a schema YAML file
  25.  * (string) or the parsed schema file (Object).
  26.  * @param {Object=} opts.bridgeConfig.defaults The default options for the
  27.  * config file.
  28.  * @param {boolean=} opts.enableRegistration Enable '--generate-registration'.
  29.  * Default True.
  30.  * @param {string=} opts.registrationPath The path to write the registration
  31.  * file to. Users can overwrite this with -f.
  32.  * @param {boolean=} opts.enableLocalpart Enable '--localpart [-l]'. Default: false.
  33.  */
  34. function Cli(opts) {
  35.     this.opts = opts || {};
  36.     if (this.opts.enableRegistration === undefined) {
  37.         this.opts.enableRegistration = true;
  38.     }
  39.     if (!this.opts.run || typeof this.opts.run !== "function") {
  40.         throw new Error("Requires 'run' function.");
  41.     }
  43.     if (this.opts.enableRegistration && !this.opts.generateRegistration) {
  44.         throw new Error(
  45.             "Registration generation is enabled but no " +
  46.             "'generateRegistration' function has been provided"
  47.         );
  48.     }
  49.     this.opts.enableLocalpart = Boolean(this.opts.enableLocalpart);
  51.     this.opts.registrationPath = this.opts.registrationPath || DEFAULT_FILENAME;
  52.     this.opts.port = this.opts.port || DEFAULT_PORT;
  53.     this._bridgeConfig = null;
  54. }
  56. /**
  57.  * Get the loaded and parsed bridge config. Only set after run() has been called.
  58.  * @return {?Object} The config
  59.  */
  60. Cli.prototype.getConfig = function() {
  61.     return this._bridgeConfig;
  62. };
  64. /**
  65.  * Get the path to the registration file. This may be different to the one supplied
  66.  * in the constructor if the user passed a -f flag.
  67.  * @return {string} The path to the registration file.
  68.  */
  69. Cli.prototype.getRegistrationFilePath = function() {
  70.     return this.opts.registrationPath;
  71. };
  73. /**
  74.  * Run the app from the command line. Will parse sys args.
  75.  */
  76. Cli.prototype.run = function() {
  77.     var args = nopt({
  78.         "generate-registration": Boolean,
  79.         "config": path,
  80.         "url": String,
  81.         "localpart": String,
  82.         "port": Number,
  83.         "file": path,
  84.         "help": Boolean
  85.     }, {
  86.         "c": "--config",
  87.         "u": "--url",
  88.         "r": "--generate-registration",
  89.         "l": "--localpart",
  90.         "p": "--port",
  91.         "f": "--file",
  92.         "h": "--help"
  93.     });
  95.     if (args.file) {
  96.         this.opts.registrationPath = args.file;
  97.     }
  99.     if (this.opts.enableRegistration && args["generate-registration"]) {
  100.         if (!args.url) {
  101.             this._printHelp();
  102.             console.log("Missing --url [-u]");
  103.             process.exit(1);
  104.         }
  105.         if (args.port) {
  106.             this._printHelp();
  107.             console.log("--port [-p] is not valid when generating a registration file.");
  108.             process.exit(1);
  109.         }
  110.         if (this.opts.bridgeConfig && this.opts.bridgeConfig.affectsRegistration) {
  111.             if (!args.config) {
  112.                 this._printHelp();
  113.                 console.log("Missing --config [-c]");
  114.                 process.exit(1);
  115.             }
  116.             this._assignConfigFile(args.config);
  117.         }
  118.         this._generateRegistration(args.url, args.localpart);
  119.         return;
  120.     }
  122.     if (args.help || (this.opts.bridgeConfig && !args.config)) {
  123.         this._printHelp();
  124.         process.exit(0);
  125.         return;
  126.     }
  127.     if (args.localpart) {
  128.         this._printHelp();
  129.         console.log(
  130.             "--localpart [-l] can only be provided when generating a registration."
  131.         );
  132.         process.exit(1);
  133.         return;
  134.     }
  136.     if (args.port) {
  137.         this.opts.port = args.port;
  138.     }
  139.     this._assignConfigFile(args.config);
  140.     this._startWithConfig(this._bridgeConfig);
  141. };
  143. Cli.prototype._assignConfigFile = function(configFilePath) {
  144.     var configFile = (this.opts.bridgeConfig && configFilePath) ? configFilePath : null;
  145.     var config = this._loadConfig(configFile);
  146.     this._bridgeConfig = config;
  147. };
  149. Cli.prototype._loadConfig = function(filename) {
  150.     if (!filename) { return {}; }
  151.     log.info("Loading config file %s", filename);
  152.     var cfg = this._loadYaml(filename);
  153.     if (typeof cfg === "string") {
  154.         throw new Error("Config file " + filename + " isn't valid YAML.");
  155.     }
  156.     if (!this.opts.bridgeConfig.schema) {
  157.         return cfg;
  158.     }
  159.     var validator = new ConfigValidator(this.opts.bridgeConfig.schema);
  160.     return validator.validate(cfg, this.opts.bridgeConfig.defaults);
  161. };
  163. Cli.prototype._generateRegistration = function(appServiceUrl, localpart) {
  164.     if (!appServiceUrl) {
  165.         throw new Error("Missing app service URL");
  166.     }
  167.     var self = this;
  168.     var reg = new AppServiceRegistration(appServiceUrl);
  169.     if (localpart) {
  170.         reg.setSenderLocalpart(localpart);
  171.     }
  172.     this.opts.generateRegistration.bind(this)(reg, function(completeReg) {
  173.         reg = completeReg;
  174.         reg.outputAsYaml(self.opts.registrationPath);
  175.         console.log("Output registration to: " + self.opts.registrationPath);
  176.         process.exit(0);
  177.     });
  178. };
  180. Cli.prototype._startWithConfig = function(config) {
  181.     this.opts.run(
  182.         this.opts.port, config,
  183.         AppServiceRegistration.fromObject(this._loadYaml(this.opts.registrationPath))
  184.     );
  185. };
  187. Cli.prototype._loadYaml = function(fpath) {
  188.     return yaml.safeLoad(fs.readFileSync(fpath, 'utf8'));
  189. };
  191. Cli.prototype._printHelp = function() {
  192.     var help = {
  193.         "--help -h": "Display this help message",
  194.         "--file -f": "The registration file to load or save to."
  195.     };
  196.     var appPart = (process.argv[0] === "node" ?
  197.         // node file/path
  198.         (process.argv[0] + " " + path.relative(process.cwd(), process.argv[1])) :
  199.         // app-name
  200.         process.argv[0]
  201.     );
  202.     var usages = [];
  204.     if (this.opts.enableRegistration) {
  205.         help["--generate-registration -r"] = "Create a registration YAML file " +
  206.         "for this application service";
  207.         help["--url -u"] = "Registration Option. Required if -r is set. The URL " +
  208.         "where the application service is listening for HS requests";
  209.         if (this.opts.enableLocalpart) {
  210.             help["--localpart -l"] = "Registration Option. Valid if -r is set. " +
  211.             "The user_id localpart to assign to the AS.";
  212.         }
  213.         var regUsage = "-r [-f /path/to/save/registration.yaml] " +
  214.             "-u 'http://localhost:6789/appservice'";
  215.         if (this.opts.bridgeConfig && this.opts.bridgeConfig.affectsRegistration) {
  216.             regUsage += " -c CONFIG_FILE";
  217.         }
  218.         if (this.opts.enableLocalpart) {
  219.             regUsage += " [-l my-app-service]";
  220.         }
  221.         usages.push(regUsage);
  222.     }
  223.     if (this.opts.bridgeConfig) {
  224.         help["--config -c"] = "The config file to load";
  225.         usages.push("-c CONFIG_FILE [-f /path/to/load/registration.yaml] [-p NUMBER]");
  226.     }
  227.     else {
  228.         usages.push("[-f /path/to/load/registration.yaml] [-p NUMBER]");
  229.     }
  230.     help["--port -p"] = "The port to listen on for HS requests";
  232.     console.log("Usage:\n");
  233.     console.log("Generating an application service registration file:");
  234.     console.log("%s %s\n", appPart, usages[0]);
  235.     console.log("Running an application service with an existing registration file:");
  236.     console.log("%s %s", appPart, usages[1]);
  238.     console.log("\nOptions:");
  239.     Object.keys(help).forEach(function(k) {
  240.         console.log("  %s", k);
  241.         console.log("      %s", help[k]);
  242.     });
  243. };
  245. module.exports = Cli;
  247. /**
  248.  * Invoked when you should generate a registration.
  249.  * @callback Cli~generateRegistration
  250.  * @param {AppServiceRegistration} reg A new registration object with the app
  251.  * service url provided by <code>--url</code> set.
  252.  * @param {Function} callback The callback that you should invoke when the
  253.  * registration has been generated. It should be called with the
  254.  * <code>AppServiceRegistration</code> provided in this function.
  255.  * @example
  256.  * generateRegistration: function(reg, callback) {
  257.  *   reg.setHomeserverToken(AppServiceRegistration.generateToken());
  258.  *   reg.setAppServiceToken(AppServiceRegistration.generateToken());
  259.  *   reg.setSenderLocalpart("my_first_bot");
  260.  *   callback(reg);
  261.  * }
  262.  */
  264.  /**
  265.  * Invoked when you should run the bridge.
  266.  * @callback Cli~runBridge
  267.  * @param {Number} port The port to listen on.
  268.  * @param {?Object} config The loaded and parsed config.
  269.  * @param {AppServiceRegistration} reg The registration to run as.
  270.  * @example
  271.  * runBridge: function(port, config, reg) {
  272.  *   // configure bridge
  273.  *   // listen on port
  274.  * }
  275.  */