hello-lights 0.3.5 → 0.3.7

package/README.md

@@ -99,6 +99,34 @@ $ npm run cli -- serve --port 3000     # start the HTTP server on a custom port
 
 Use `--help` for the full list of options, including `--serial-num` to target a specific device and `--selector multi` to control multiple traffic lights at once.
 
+## HTTP Server REST API
+
+The `serve` command starts an HTTP server that exposes the Commander interface as a REST API. By default it listens on port 9000.
+
+| Endpoint | Method | Body | Response |
+|---|---|---|---|
+| `/run` | POST | Command string (plain text) | 202 Accepted |
+| `/run?reset=true` | POST | Command string (plain text) | 202 Accepted (resets lights first) |
+| `/cancel` | POST | — | 200 OK |
+| `/definitions` | POST | Definition string (plain text) | 202 Accepted |
+| `/commands` | GET | — | 200 + JSON array of command names |
+| `/commands/:name` | GET | — | 200 + help text (`text/x-ansi`) or 404 |
+| `/info` | GET | — | 200 + JSON array of `{ serialNum, status }` |
+
+Examples:
+
+```sh
+$ curl -X POST http://localhost:9000/run -d 'blink 3 green 300'
+$ curl -X POST http://localhost:9000/run?reset=true -d 'twinkle red 400'
+$ curl -X POST http://localhost:9000/cancel
+$ curl -X POST http://localhost:9000/definitions -d '(def foo (blink 1 green 300))'
+$ curl http://localhost:9000/commands
+$ curl http://localhost:9000/commands/turn
+$ curl http://localhost:9000/info
+```
+
+The server also serves a browser demo at the root URL (`/`).
+
 ## Running as a Linux Service
 
 You can set up `hello-lights serve` to run automatically as a systemd user service on Linux.

package/lib/cli/repl-command.js

@@ -13,8 +13,8 @@ class CommanderRepl {
     this.manager = this.commander.manager;
   }
 
-  formatCommandNames() {
-    let names = this.commander.commandNames;
+  async formatCommandNames() {
+    let names = await this.commander.fetchCommandNames();
     let parts = ['  '];
     names.forEach((name, i) => {
       parts.push(`  ${name}`);
@@ -23,7 +23,7 @@ class CommanderRepl {
     return parts.join('');
   }
 
-  help(commandName) {
+  async help(commandName) {
     if (commandName === undefined) {
       this.logger.log([
         `Commands for the traffic light`,
@@ -34,30 +34,30 @@ class CommanderRepl {
         `> [command]`,
         `> { [... multi line command] }`,
         `  available commands:`,
-        this.formatCommandNames()
+        await this.formatCommandNames()
       ].join('\n'));
     } else {
-      this.commander.help(commandName);
+      await this.commander.help(commandName);
     }
   }
 
-  execute(text, context, filename, callback) {
+  async execute(text, context, filename, callback) {
     text = text.trim();
     let match;
     if (!text) {
     } else if (text === 'cancel') {
-      this.commander.cancel();
+      await this.commander.cancel();
     } else if (text === 'help') {
-      this.help();
+      await this.help();
     } else if (match = text.match(/^help\s+(.+)/)) { // eslint-disable-line no-cond-assign
-      this.help(match[1]);
+      await this.help(match[1]);
     } else if (text === 'exit' || text === 'quit') {
-      this.commander.cancel();
+      await this.commander.cancel();
       this.commander.close();
       this.logger.log('Bye');
       process.exit(0);
     } else if (text === 'check device') {
-      this.commander.logInfo();
+      await this.commander.logInfo();
     } else if (this.supportsNewDevice() && text === 'new device') {
       this.newDevice();
     } else if (text.startsWith('{')) {

package/lib/cli/serve/index.js

@@ -10,14 +10,44 @@ function createApp(commander) {
   const app = express();
 
   app.use(express.static(path.join(__dirname, 'public')));
+  app.use(express.text({type: '*/*'}));
+
   app.post('/run', (req, res) => {
-    let commandStr = '';
-    req.on('data', data => commandStr += data);
-    req.on('end', () => {
-      commander.run(commandStr);
-      res.statusCode = 202; // accepted
-      res.end();
-    });
+    let reset = req.query.reset === 'true';
+    commander.run(req.body || '', reset);
+    res.sendStatus(202);
+  });
+
+  app.post('/cancel', async (req, res) => {
+    await commander.cancel();
+    res.sendStatus(200);
+  });
+
+  app.post('/definitions', (req, res) => {
+    commander.runDefinitions(req.body || '');
+    res.sendStatus(202);
+  });
+
+  app.get('/commands', async (req, res) => {
+    res.json(await commander.fetchCommandNames());
+  });
+
+  app.get('/commands/:name', (req, res) => {
+    let command = commander.interpreter.lookup(req.params.name);
+    if (!command) {
+      res.status(404).send(`Command not found: "${req.params.name}"`);
+      return;
+    }
+    let helpText = commander.formatter.format(command.meta);
+    res.type('text/x-ansi').send(helpText);
+  });
+
+  app.get('/info', (req, res) => {
+    if (commander.manager) {
+      res.json(commander.manager.info());
+    } else {
+      res.json([]);
+    }
   });
 
   return app;

package/lib/commander.js

@@ -89,7 +89,7 @@ class Commander {
   /**
    * Cancels any currently executing command.
    */
-  cancel() {
+  async cancel() {
     this.interpreter.cancel();
   }
 
@@ -248,11 +248,19 @@ class Commander {
     return this.interpreter.commands;
   }
 
+  /**
+   * Fetches all supported command names.
+   * @returns {Promise<string[]>} A promise that resolves with the command names.
+   */
+  async fetchCommandNames() {
+    return this.interpreter.commandNames;
+  }
+
   /**
    * Logs the help info for the given command name.
    * @param {string} commandName - Name of the command to log help info.
    */
-  help(commandName) {
+  async help(commandName) {
     let command = this.interpreter.lookup(commandName);
     if (!command) {
       this.logger.error(`Command not found: "${commandName}"`);
@@ -264,7 +272,7 @@ class Commander {
   /**
    * Logs information about known traffic lights.
    */
-  logInfo() {
+  async logInfo() {
     this.selector.logInfo(this.logger);
   }
 

package/lib/index.js

@@ -1,4 +1,5 @@
 const {Commander} = require('./commander');
+const {RestCommander} = require('./rest-commander');
 
 module.exports = {
   commands: require('./commands'),
@@ -6,5 +7,6 @@ module.exports = {
   physical: require('./physical'),
   devices: require('./devices'),
   selectors: require('./selectors'),
-  Commander
+  Commander,
+  RestCommander
 };

package/lib/rest-commander.js

@@ -0,0 +1,126 @@
+////////////////////////////////////////////////
+
+const http = require('http');
+const https = require('https');
+
+////////////////////////////////////////////////
+
+function request(baseUrl, method, path, body) {
+  return new Promise((resolve, reject) => {
+    let url = new URL(path, baseUrl);
+    let client = url.protocol === 'https:' ? https : http;
+    let options = {
+      method,
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      headers: {}
+    };
+    if (body != null) {
+      options.headers['Content-Type'] = 'text/plain';
+    }
+    let req = client.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve({statusCode: res.statusCode, body: data}));
+    });
+    req.on('error', reject);
+    if (body != null) req.write(body);
+    req.end();
+  });
+}
+
+////////////////////////////////////////////////
+
+/**
+ * A Commander client that controls a traffic light via a remote REST API.
+ * Communicates with a server started by the `serve` command.
+ */
+class RestCommander {
+
+  /**
+   * Creates a new RestCommander instance.
+   * @param {object} [options] - Options.
+   * @param {string} [options.host='http://localhost:9000'] - The base URL of
+   *   the remote server (e.g. `http://localhost:9000`).
+   * @param {object} [options.logger=console] - A Console-like object for logging.
+   */
+  constructor({host = 'http://localhost:9000', logger = console} = {}) {
+    this.host = host.replace(/\/+$/, ''); // strip trailing slashes
+    this.logger = logger;
+  }
+
+  /**
+   * Executes a command on the remote server (fire-and-forget).
+   * @param {string} command - Command to execute.
+   * @param {boolean} [reset=false] - Whether to reset the traffic light first.
+   */
+  async run(command, reset = false) {
+    let path = reset ? '/run?reset=true' : '/run';
+    await request(this.host, 'POST', path, command);
+  }
+
+  /**
+   * Cancels any currently executing command on the remote server.
+   */
+  async cancel() {
+    await request(this.host, 'POST', '/cancel');
+  }
+
+  /**
+   * Executes definition-only commands on the remote server.
+   * @param {string} command - Command with definitions to execute.
+   */
+  async runDefinitions(command) {
+    await request(this.host, 'POST', '/definitions', command);
+  }
+
+  /**
+   * Fetches all available command names from the remote server.
+   * @returns {Promise<string[]>} Array of command names.
+   */
+  async fetchCommandNames() {
+    let res = await request(this.host, 'GET', '/commands');
+    return JSON.parse(res.body);
+  }
+
+  /**
+   * Logs the help info for the given command name from the remote server.
+   * @param {string} commandName - Name of the command.
+   */
+  async help(commandName) {
+    let res = await request(this.host, 'GET', `/commands/${encodeURIComponent(commandName)}`);
+    if (res.statusCode === 404) {
+      this.logger.error(res.body);
+    } else {
+      this.logger.log(res.body);
+    }
+  }
+
+  /**
+   * Logs information about known traffic lights from the remote server.
+   */
+  async logInfo() {
+    let res = await request(this.host, 'GET', '/info');
+    let devicesInfo = JSON.parse(res.body);
+    if (devicesInfo.length === 0) {
+      this.logger.log('No devices found');
+    } else {
+      this.logger.log('Known devices:');
+      devicesInfo.forEach(info =>
+        this.logger.log(`device ${info.serialNum}: ${info.status}`));
+    }
+  }
+
+  /**
+   * Closes this instance. No-op for REST client.
+   */
+  close() {}
+
+}
+
+////////////////////////////////////////////////
+
+module.exports = {RestCommander};
+
+////////////////////////////////////////////////

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hello-lights",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Commands to control a traffic light",
   "main": "index.js",
   "bin": {