hello-lights 0.3.5 → 0.3.6

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/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', (req, res) => {
+    commander.cancel();
+    res.sendStatus(200);
+  });
+
+  app.post('/definitions', (req, res) => {
+    commander.runDefinitions(req.body || '');
+    res.sendStatus(202);
+  });
+
+  app.get('/commands', (req, res) => {
+    res.json(commander.commandNames);
+  });
+
+  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/package.json

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