From ef5401d4c6108679fef7ebf2a0d929410ca9db07 Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Mon, 20 Jun 2016 22:27:55 +0100 Subject: [PATCH] docs --- README.md | 446 ++++-------------------------------------------- doc/blacklist.md | 9 + doc/https.md | 59 +++++++ doc/logging.md | 69 ++++++++ doc/mime-types.md | 12 ++ doc/mock-response.md | 241 ++++++++++++++++++++++++++ doc/rewrite.md | 37 ++++ doc/spa.md | 12 ++ doc/stored-config.md | 28 +++ jsdoc2md/README.hbs | 416 -------------------------------------------- lib/default-stack.js | 291 +++++++++++++++++++++++++++++++ lib/local-web-server.js | 17 +- lib/middleware-stack.js | 294 ++----------------------------- 13 files changed, 817 insertions(+), 1114 deletions(-) create mode 100644 doc/blacklist.md create mode 100644 doc/https.md create mode 100644 doc/logging.md create mode 100644 doc/mime-types.md create mode 100644 doc/mock-response.md create mode 100644 doc/rewrite.md create mode 100644 doc/spa.md create mode 100644 doc/stored-config.md create mode 100644 lib/default-stack.js diff --git a/README.md b/README.md index c261713..237b648 100644 --- a/README.md +++ b/README.md @@ -108,409 +108,6 @@ serving at http://localhost:8000 [Example](https://github.com/75lb/local-web-server/tree/master/example/simple). -### Single Page Application - -You're building a web app with client-side routing, so mark `index.html` as the SPA. -```sh -$ ws --spa index.html -``` - -By default, typical SPA paths (e.g. `/user/1`, `/login`) would return `404 Not Found` as a file does not exist with that path. By marking `index.html` as the SPA you create this rule: - -*If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.* - -[Example](https://github.com/75lb/local-web-server/tree/master/example/spa). - -### URL rewriting - -Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule: - -```sh -$ ws --rewrite '/css/style.css -> /build/css/style.css' -``` - -Or, more generally (matching any stylesheet under `/css`): - -```sh -$ ws --rewrite '/css/:stylesheet -> /build/css/:stylesheet' -``` - -With a deep CSS directory structure it may be easier to mount the entire contents of `/build/css` to the `/css` path: - -```sh -$ ws --rewrite '/css/* -> /build/css/$1' -``` - -this rewrites `/css/a` as `/build/css/a`, `/css/a/b/c` as `/build/css/a/b/c` etc. - -#### Proxied requests - -If the `to` URL contains a remote host, local-web-server will act as a proxy - fetching and responding with the remote resource. - -Mount the npm registry locally: -```sh -$ ws --rewrite '/npm/* -> http://registry.npmjs.org/$1' -``` - -Map local requests for repo data to the Github API: -```sh -$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name' -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite). - -### Mock Responses - -Mocks give you full control over the response headers and body returned to the client. They can be used to return anything from a simple html string to a resourceful REST API. Typically, they're used to mock services but can be used for anything. - -In the config, define an array called `mocks`. Each mock definition maps a [route](http://expressjs.com/guide/routing.html#route-paths) to a `response`. A simple home page: -```json -{ - "mocks": [ - { - "route": "/", - "response": { - "body": "

Welcome to the Mock Responses example

" - } - } - ] -} -``` - -Under the hood, the property values from the `response` object are written onto the underlying [koa response object](https://github.com/koajs/koa/blob/master/docs/api/response.md). You can set any valid koa response properies, for example [type](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsetype-1): -```json -{ - "mocks": [ - { - "route": "/", - "response": { - "type": "text/plain", - "body": "

Welcome to the Mock Responses example

" - } - } - ] -} -``` - -#### Conditional Response - -To define a conditional response, set a `request` object on the mock definition. The `request` value acts as a query - the response defined will only be returned if each property of the `request` query matches. For example, return an XML response *only* if the request headers include `accept: application/xml`, else return 404 Not Found. - -```json -{ - "mocks": [ - { - "route": "/two", - "request": { "accepts": "xml" }, - "response": { - "body": "" - } - } - ] -} -``` - -#### Multiple Potential Responses - -To specify multiple potential responses, set an array of mock definitions to the `responses` property. The first response with a matching request query will be sent. In this example, the client will get one of two responses depending on the request method: - -```json -{ - "mocks": [ - { - "route": "/three", - "responses": [ - { - "request": { "method": "GET" }, - "response": { - "body": "

Mock response for 'GET' request on /three

" - } - }, - { - "request": { "method": "POST" }, - "response": { - "status": 400, - "body": { "message": "That method is not allowed." } - } - } - ] - } - ] -} -``` - -#### Dynamic Response - -The examples above all returned static data. To define a dynamic response, create a mock module. Specify its path in the `module` property: -```json -{ - "mocks": [ - { - "route": "/four", - "module": "/mocks/stream-self.js" - } - ] -} -``` - -Here's what the `stream-self` module looks like. The module should export a mock definition (an object, or array of objects, each with a `response` and optional `request`). In this example, the module simply streams itself to the response but you could set `body` to *any* [valid value](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsebody-1). -```js -const fs = require('fs') - -module.exports = { - response: { - body: fs.createReadStream(__filename) - } -} -``` - -#### Response function - -For more power, define the response as a function. It will receive the [koa context](https://github.com/koajs/koa/blob/master/docs/api/context.md) as its first argument. Now you have full programmatic control over the response returned. -```js -module.exports = { - response: function (ctx) { - ctx.body = '

I can do anything i want.

' - } -} -``` - -If the route contains tokens, their values are passed to the response. For example, with this mock... -```json -{ - "mocks": [ - { - "route": "/players/:id", - "module": "/mocks/players.js" - } - ] -} -``` - -...the `id` value is passed to the `response` function. For example, a path of `/players/10?name=Lionel` would pass `10` to the response function. Additional, the value `Lionel` would be available on `ctx.query.name`: -```js -module.exports = { - response: function (ctx, id) { - ctx.body = `

id: ${id}, name: ${ctx.query.name}

` - } -} -``` - -#### RESTful Resource example - -Here's an example of a REST collection (users). We'll create two routes, one for actions on the resource collection, one for individual resource actions. - -```json -{ - "mocks": [ - { "route": "/users", "module": "/mocks/users.js" }, - { "route": "/users/:id", "module": "/mocks/user.js" } - ] -} -``` - -Define a module (`users.json`) defining seed data: - -```json -[ - { "id": 1, "name": "Lloyd", "age": 40, "nationality": "English" }, - { "id": 2, "name": "Mona", "age": 34, "nationality": "Palestinian" }, - { "id": 3, "name": "Francesco", "age": 24, "nationality": "Italian" } -] -``` - -The collection module: - -```js -const users = require('./users.json') - -/* responses for /users */ -const mockResponses = [ - /* Respond with 400 Bad Request for PUT and DELETE - inappropriate on a collection */ - { request: { method: 'PUT' }, response: { status: 400 } }, - { request: { method: 'DELETE' }, response: { status: 400 } }, - { - /* for GET requests return a subset of data, optionally filtered on 'minAge' and 'nationality' */ - request: { method: 'GET' }, - response: function (ctx) { - ctx.body = users.filter(user => { - const meetsMinAge = (user.age || 1000) >= (Number(ctx.query.minAge) || 0) - const requiredNationality = user.nationality === (ctx.query.nationality || user.nationality) - return meetsMinAge && requiredNationality - }) - } - }, - { - /* for POST requests, create a new user and return the path to the new resource */ - request: { method: 'POST' }, - response: function (ctx) { - const newUser = ctx.request.body - users.push(newUser) - newUser.id = users.length - ctx.status = 201 - ctx.response.set('Location', `/users/${newUser.id}`) - } - } -] - -module.exports = mockResponses -``` - -The individual resource module: - -```js -const users = require('./users.json') - -/* responses for /users/:id */ -const mockResponses = [ - /* don't support POST here */ - { request: { method: 'POST' }, response: { status: 400 } }, - - /* for GET requests, return a particular user */ - { - request: { method: 'GET' }, - response: function (ctx, id) { - ctx.body = users.find(user => user.id === Number(id)) - } - }, - - /* for PUT requests, update the record */ - { - request: { method: 'PUT' }, - response: function (ctx, id) { - const updatedUser = ctx.request.body - const existingUserIndex = users.findIndex(user => user.id === Number(id)) - users.splice(existingUserIndex, 1, updatedUser) - ctx.status = 200 - } - }, - - /* DELETE request: remove the record */ - { - request: { method: 'DELETE' }, - response: function (ctx, id) { - const existingUserIndex = users.findIndex(user => user.id === Number(id)) - users.splice(existingUserIndex, 1) - ctx.status = 200 - } - } -] - -module.exports = mockResponses -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/mock). - -### HTTPS Server - -Some modern techs (ServiceWorker, any `MediaDevices.getUserMedia()` request etc.) *must* be served from a secure origin (HTTPS). To launch an HTTPS server, supply a `--key` and `--cert` to local-web-server, for example: - -``` -$ ws --key localhost.key --cert localhost.crt -``` - -If you don't have a key and certificate it's trivial to create them. You do not need third-party verification (Verisign etc.) for development purposes. To get the green padlock in the browser, the certificate.. - -* must have a `Common Name` value matching the FQDN of the server -* must be verified by a Certificate Authority (but we can overrule this - see below) - -First create a certificate: - -1. Install openssl. - - `$ brew install openssl` - -2. Generate a RSA private key. - - `$ openssl genrsa -des3 -passout pass:x -out ws.pass.key 2048` - -3. Create RSA key. - - ``` - $ openssl rsa -passin pass:x -in ws.pass.key -out ws.key - ``` - -4. Create certificate request. The command below will ask a series of questions about the certificate owner. The most imporant answer to give is for `Common Name`, you can accept the default values for the others. **Important**: you **must** input your server's correct FQDN (`dev-server.local`, `laptop.home` etc.) into the `Common Name` field. The cert is only valid for the domain specified here. You can find out your computers host name by running the command `hostname`. For example, mine is `mba3.home`. - - `$ openssl req -new -key ws.key -out ws.csr` - -5. Generate self-signed certificate. - - `$ openssl x509 -req -days 365 -in ws.csr -signkey ws.key -out ws.crt` - -6. Clean up files we're finished with - - `$ rm ws.pass.key ws.csr` - -7. Launch HTTPS server. In iTerm, control-click the first URL (with the hostname matching `Common Name`) to launch your browser. - - ``` - $ ws --key ws.key --cert ws.crt - serving at https://mba3.home:8010, https://127.0.0.1:8010, https://192.168.1.203:8010 - ``` - -Chrome and Firefox will still complain your certificate has not been verified by a Certificate Authority. Firefox will offer you an `Add an exception` option, allowing you to ignore the warning and manually mark the certificate as trusted. In Chrome on Mac, you can manually trust the certificate another way: - -1. Open Keychain -2. Click File -> Import. Select the `.crt` file you created. -3. In the `Certificates` category, double-click the cert you imported. -4. In the `trust` section, underneath `when using this certificate`, select `Always Trust`. - -Now you have a valid, trusted certificate for development. - -#### Built-in certificate -As a quick win, you can run `ws` with the `https` flag. This will launch an HTTPS server using a [built-in certificate](https://github.com/75lb/local-web-server/tree/master/ssl) registered to the domain 127.0.0.1. - -### Stored config - -Use the same options every time? Persist then to `package.json`: -```json -{ - "name": "example", - "version": "1.0.0", - "local-web-server": { - "port": 8100, - "forbid": "*.json" - } -} -``` - -or `.local-web-server.json` -```json -{ - "port": 8100, - "forbid": "*.json" -} -``` - -local-web-server will merge and use all config found, searching from the current directory upward. In the case both `package.json` and `.local-web-server.json` config is found in the same directory, `.local-web-server.json` will take precedence. Options set on the command line take precedence over all. - -To inspect stored config, run: -```sh -$ ws --config -``` - -### Logging -By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`: - -```sh -$ ws --log-format combined -serving at http://localhost:8000 -::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36" -``` - -The format value supplied is passed directly to [morgan](https://github.com/expressjs/morgan). The exception is `--log-format none` which disables all output. - -### Access Control - -By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist: -```sh -$ ws --forbid '*.json' '*.yml' -serving at http://localhost:8000 -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid). - ### Other usage #### Debugging @@ -534,19 +131,6 @@ Disable etag response headers, forcing resources to be served in full every time $ ws --no-cache ``` -#### mime-types -You can set additional mime-type/extension mappings, or override the defaults by setting a `mime` value in the stored config. This value is passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine). Example: - -```json -{ - "mime": { - "text/plain": [ "php", "pl" ] - } -} -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override). - #### Log Visualisation Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md). @@ -597,7 +181,35 @@ serving at http://localhost:8100 ## API Reference -ERROR, Cannot find module. + +* [local-web-server](#module_local-web-server) + * [LocalWebServer](#exp_module_local-web-server--LocalWebServer) ⇐ [middleware-stack](#module_middleware-stack) ⏏ + * _instance_ + * [.add(middleware)](#) ↩︎ + * _inner_ + * [~collectUserOptions()](#module_local-web-server--LocalWebServer..collectUserOptions) + + + +### LocalWebServer ⇐ [middleware-stack](#module_middleware-stack) ⏏ +**Kind**: Exported class +**Extends:** [middleware-stack](#module_middleware-stack) + + +#### localWebServer.add(middleware) ↩︎ +**Kind**: instance method of [LocalWebServer](#exp_module_local-web-server--LocalWebServer) +**Chainable** +**Params** + +- middleware [middleware](#module_middleware-stack--MiddlewareStack..middleware) + + + +#### LocalWebServer~collectUserOptions() +Return default, stored and command-line options combined + +**Kind**: inner method of [LocalWebServer](#exp_module_local-web-server--LocalWebServer) + * * * © 2013-16 Lloyd Brookes <75pound@gmail.com>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown). diff --git a/doc/blacklist.md b/doc/blacklist.md new file mode 100644 index 0000000..6793d50 --- /dev/null +++ b/doc/blacklist.md @@ -0,0 +1,9 @@ +## Access Control + +By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist: +```sh +$ ws --forbid '*.json' '*.yml' +serving at http://localhost:8000 +``` + +[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid). diff --git a/doc/https.md b/doc/https.md new file mode 100644 index 0000000..8802915 --- /dev/null +++ b/doc/https.md @@ -0,0 +1,59 @@ +## HTTPS Server + +Some modern techs (ServiceWorker, any `MediaDevices.getUserMedia()` request etc.) *must* be served from a secure origin (HTTPS). To launch an HTTPS server, supply a `--key` and `--cert` to local-web-server, for example: + +``` +$ ws --key localhost.key --cert localhost.crt +``` + +If you don't have a key and certificate it's trivial to create them. You do not need third-party verification (Verisign etc.) for development purposes. To get the green padlock in the browser, the certificate.. + +* must have a `Common Name` value matching the FQDN of the server +* must be verified by a Certificate Authority (but we can overrule this - see below) + +First create a certificate: + +1. Install openssl. + + `$ brew install openssl` + +2. Generate a RSA private key. + + `$ openssl genrsa -des3 -passout pass:x -out ws.pass.key 2048` + +3. Create RSA key. + + ``` + $ openssl rsa -passin pass:x -in ws.pass.key -out ws.key + ``` + +4. Create certificate request. The command below will ask a series of questions about the certificate owner. The most imporant answer to give is for `Common Name`, you can accept the default values for the others. **Important**: you **must** input your server's correct FQDN (`dev-server.local`, `laptop.home` etc.) into the `Common Name` field. The cert is only valid for the domain specified here. You can find out your computers host name by running the command `hostname`. For example, mine is `mba3.home`. + + `$ openssl req -new -key ws.key -out ws.csr` + +5. Generate self-signed certificate. + + `$ openssl x509 -req -days 365 -in ws.csr -signkey ws.key -out ws.crt` + +6. Clean up files we're finished with + + `$ rm ws.pass.key ws.csr` + +7. Launch HTTPS server. In iTerm, control-click the first URL (with the hostname matching `Common Name`) to launch your browser. + + ``` + $ ws --key ws.key --cert ws.crt + serving at https://mba3.home:8010, https://127.0.0.1:8010, https://192.168.1.203:8010 + ``` + +Chrome and Firefox will still complain your certificate has not been verified by a Certificate Authority. Firefox will offer you an `Add an exception` option, allowing you to ignore the warning and manually mark the certificate as trusted. In Chrome on Mac, you can manually trust the certificate another way: + +1. Open Keychain +2. Click File -> Import. Select the `.crt` file you created. +3. In the `Certificates` category, double-click the cert you imported. +4. In the `trust` section, underneath `when using this certificate`, select `Always Trust`. + +Now you have a valid, trusted certificate for development. + +### Built-in certificate +As a quick win, you can run `ws` with the `https` flag. This will launch an HTTPS server using a [built-in certificate](https://github.com/75lb/local-web-server/tree/master/ssl) registered to the domain 127.0.0.1. diff --git a/doc/logging.md b/doc/logging.md new file mode 100644 index 0000000..c41cd21 --- /dev/null +++ b/doc/logging.md @@ -0,0 +1,69 @@ +# Logging +By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`: + +```sh +$ ws --log-format combined +serving at http://localhost:8000 +::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36" +``` + +The format value supplied is passed directly to [morgan](https://github.com/expressjs/morgan). The exception is `--log-format none` which disables all output. + +# Visualisation + +## Goaccess +To get live statistics in [goaccess](http://goaccess.io/), first create this config file at `~/.goaccessrc`: + +``` +time-format %T +date-format %d/%b/%Y +log-format %h %^[%d:%t %^] "%r" %s %b "%R" "%u" +``` + +Then, start the server, outputting `combined` format logs to disk: + +```sh +$ ws -f combined > web.log +``` + +In a separate tab, point goaccess at `web.log` and it will display statistics in real time: + +``` +$ goaccess -p ~/.goaccessrc -f web.log +``` + +## Logstalgia +local-web-server is compatible with [logstalgia](http://code.google.com/p/logstalgia/). + +### Install Logstalgia +On MacOSX, install with [homebrew](http://brew.sh): +```sh +$ brew install logstalgia +``` + +Alternatively, [download a release for your system from github](https://github.com/acaudwell/Logstalgia/releases/latest). + +Then pipe the `logstalgia` output format directly into logstalgia for real-time visualisation: +```sh +$ ws -f logstalgia | logstalgia - +``` + +![local-web-server with logstalgia](https://raw.githubusercontent.com/75lb/local-web-server/master/doc/img/logstagia.gif) + +## glTail +To use with [glTail](http://www.fudgie.org), write your log to disk using the "default" format: +```sh +$ ws -f default > web.log +``` + +Then specify this file in your glTail config: + +```yaml +servers: + dev: + host: localhost + source: local + files: /Users/Lloyd/Documents/MySite/web.log + parser: apache + color: 0.2, 0.2, 1.0, 1.0 +``` diff --git a/doc/mime-types.md b/doc/mime-types.md new file mode 100644 index 0000000..3251230 --- /dev/null +++ b/doc/mime-types.md @@ -0,0 +1,12 @@ +## mime-types +You can set additional mime-type/extension mappings, or override the defaults by setting a `mime` value in the stored config. This value is passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine). Example: + +```json +{ + "mime": { + "text/plain": [ "php", "pl" ] + } +} +``` + +[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override). diff --git a/doc/mock-response.md b/doc/mock-response.md new file mode 100644 index 0000000..2d2b796 --- /dev/null +++ b/doc/mock-response.md @@ -0,0 +1,241 @@ +## Mock Responses + +Mocks give you full control over the response headers and body returned to the client. They can be used to return anything from a simple html string to a resourceful REST API. Typically, they're used to mock services but can be used for anything. + +In the config, define an array called `mocks`. Each mock definition maps a [route](http://expressjs.com/guide/routing.html#route-paths) to a `response`. A simple home page: +```json +{ + "mocks": [ + { + "route": "/", + "response": { + "body": "

Welcome to the Mock Responses example

" + } + } + ] +} +``` + +Under the hood, the property values from the `response` object are written onto the underlying [koa response object](https://github.com/koajs/koa/blob/master/docs/api/response.md). You can set any valid koa response properies, for example [type](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsetype-1): +```json +{ + "mocks": [ + { + "route": "/", + "response": { + "type": "text/plain", + "body": "

Welcome to the Mock Responses example

" + } + } + ] +} +``` + +### Conditional Response + +To define a conditional response, set a `request` object on the mock definition. The `request` value acts as a query - the response defined will only be returned if each property of the `request` query matches. For example, return an XML response *only* if the request headers include `accept: application/xml`, else return 404 Not Found. + +```json +{ + "mocks": [ + { + "route": "/two", + "request": { "accepts": "xml" }, + "response": { + "body": "" + } + } + ] +} +``` + +### Multiple Potential Responses + +To specify multiple potential responses, set an array of mock definitions to the `responses` property. The first response with a matching request query will be sent. In this example, the client will get one of two responses depending on the request method: + +```json +{ + "mocks": [ + { + "route": "/three", + "responses": [ + { + "request": { "method": "GET" }, + "response": { + "body": "

Mock response for 'GET' request on /three

" + } + }, + { + "request": { "method": "POST" }, + "response": { + "status": 400, + "body": { "message": "That method is not allowed." } + } + } + ] + } + ] +} +``` + +### Dynamic Response + +The examples above all returned static data. To define a dynamic response, create a mock module. Specify its path in the `module` property: +```json +{ + "mocks": [ + { + "route": "/four", + "module": "/mocks/stream-self.js" + } + ] +} +``` + +Here's what the `stream-self` module looks like. The module should export a mock definition (an object, or array of objects, each with a `response` and optional `request`). In this example, the module simply streams itself to the response but you could set `body` to *any* [valid value](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsebody-1). +```js +const fs = require('fs') + +module.exports = { + response: { + body: fs.createReadStream(__filename) + } +} +``` + +### Response function + +For more power, define the response as a function. It will receive the [koa context](https://github.com/koajs/koa/blob/master/docs/api/context.md) as its first argument. Now you have full programmatic control over the response returned. +```js +module.exports = { + response: function (ctx) { + ctx.body = '

I can do anything i want.

' + } +} +``` + +If the route contains tokens, their values are passed to the response. For example, with this mock... +```json +{ + "mocks": [ + { + "route": "/players/:id", + "module": "/mocks/players.js" + } + ] +} +``` + +...the `id` value is passed to the `response` function. For example, a path of `/players/10?name=Lionel` would pass `10` to the response function. Additional, the value `Lionel` would be available on `ctx.query.name`: +```js +module.exports = { + response: function (ctx, id) { + ctx.body = `

id: ${id}, name: ${ctx.query.name}

` + } +} +``` + +### RESTful Resource example + +Here's an example of a REST collection (users). We'll create two routes, one for actions on the resource collection, one for individual resource actions. + +```json +{ + "mocks": [ + { "route": "/users", "module": "/mocks/users.js" }, + { "route": "/users/:id", "module": "/mocks/user.js" } + ] +} +``` + +Define a module (`users.json`) defining seed data: + +```json +[ + { "id": 1, "name": "Lloyd", "age": 40, "nationality": "English" }, + { "id": 2, "name": "Mona", "age": 34, "nationality": "Palestinian" }, + { "id": 3, "name": "Francesco", "age": 24, "nationality": "Italian" } +] +``` + +The collection module: + +```js +const users = require('./users.json') + +/* responses for /users */ +const mockResponses = [ + /* Respond with 400 Bad Request for PUT and DELETE - inappropriate on a collection */ + { request: { method: 'PUT' }, response: { status: 400 } }, + { request: { method: 'DELETE' }, response: { status: 400 } }, + { + /* for GET requests return a subset of data, optionally filtered on 'minAge' and 'nationality' */ + request: { method: 'GET' }, + response: function (ctx) { + ctx.body = users.filter(user => { + const meetsMinAge = (user.age || 1000) >= (Number(ctx.query.minAge) || 0) + const requiredNationality = user.nationality === (ctx.query.nationality || user.nationality) + return meetsMinAge && requiredNationality + }) + } + }, + { + /* for POST requests, create a new user and return the path to the new resource */ + request: { method: 'POST' }, + response: function (ctx) { + const newUser = ctx.request.body + users.push(newUser) + newUser.id = users.length + ctx.status = 201 + ctx.response.set('Location', `/users/${newUser.id}`) + } + } +] + +module.exports = mockResponses +``` + +The individual resource module: + +```js +const users = require('./users.json') + +/* responses for /users/:id */ +const mockResponses = [ + /* don't support POST here */ + { request: { method: 'POST' }, response: { status: 400 } }, + + /* for GET requests, return a particular user */ + { + request: { method: 'GET' }, + response: function (ctx, id) { + ctx.body = users.find(user => user.id === Number(id)) + } + }, + + /* for PUT requests, update the record */ + { + request: { method: 'PUT' }, + response: function (ctx, id) { + const updatedUser = ctx.request.body + const existingUserIndex = users.findIndex(user => user.id === Number(id)) + users.splice(existingUserIndex, 1, updatedUser) + ctx.status = 200 + } + }, + + /* DELETE request: remove the record */ + { + request: { method: 'DELETE' }, + response: function (ctx, id) { + const existingUserIndex = users.findIndex(user => user.id === Number(id)) + users.splice(existingUserIndex, 1) + ctx.status = 200 + } + } +] + +module.exports = mockResponses +``` + +[Example](https://github.com/75lb/local-web-server/tree/master/example/mock). \ No newline at end of file diff --git a/doc/rewrite.md b/doc/rewrite.md new file mode 100644 index 0000000..af1907a --- /dev/null +++ b/doc/rewrite.md @@ -0,0 +1,37 @@ +## URL rewriting + +Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule: + +```sh +$ ws --rewrite '/css/style.css -> /build/css/style.css' +``` + +Or, more generally (matching any stylesheet under `/css`): + +```sh +$ ws --rewrite '/css/:stylesheet -> /build/css/:stylesheet' +``` + +With a deep CSS directory structure it may be easier to mount the entire contents of `/build/css` to the `/css` path: + +```sh +$ ws --rewrite '/css/* -> /build/css/$1' +``` + +this rewrites `/css/a` as `/build/css/a`, `/css/a/b/c` as `/build/css/a/b/c` etc. + +### Proxied requests + +If the `to` URL contains a remote host, local-web-server will act as a proxy - fetching and responding with the remote resource. + +Mount the npm registry locally: +```sh +$ ws --rewrite '/npm/* -> http://registry.npmjs.org/$1' +``` + +Map local requests for repo data to the Github API: +```sh +$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name' +``` + +[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite). diff --git a/doc/spa.md b/doc/spa.md new file mode 100644 index 0000000..1c277e6 --- /dev/null +++ b/doc/spa.md @@ -0,0 +1,12 @@ +## Single Page Application + +You're building a web app with client-side routing, so mark `index.html` as the SPA. +```sh +$ ws --spa index.html +``` + +By default, typical SPA paths (e.g. `/user/1`, `/login`) would return `404 Not Found` as a file does not exist with that path. By marking `index.html` as the SPA you create this rule: + +*If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.* + +[Example](https://github.com/75lb/local-web-server/tree/master/example/spa). diff --git a/doc/stored-config.md b/doc/stored-config.md new file mode 100644 index 0000000..3a63ec3 --- /dev/null +++ b/doc/stored-config.md @@ -0,0 +1,28 @@ +## Stored config + +Use the same options every time? Persist then to `package.json`: +```json +{ + "name": "example", + "version": "1.0.0", + "local-web-server": { + "port": 8100, + "forbid": "*.json" + } +} +``` + +or `.local-web-server.json` +```json +{ + "port": 8100, + "forbid": "*.json" +} +``` + +local-web-server will merge and use all config found, searching from the current directory upward. In the case both `package.json` and `.local-web-server.json` config is found in the same directory, `.local-web-server.json` will take precedence. Options set on the command line take precedence over all. + +To inspect stored config, run: +```sh +$ ws --config +``` \ No newline at end of file diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs index e28d4ce..56d74d1 100644 --- a/jsdoc2md/README.hbs +++ b/jsdoc2md/README.hbs @@ -108,409 +108,6 @@ serving at http://localhost:8000 [Example](https://github.com/75lb/local-web-server/tree/master/example/simple). -### Single Page Application - -You're building a web app with client-side routing, so mark `index.html` as the SPA. -```sh -$ ws --spa index.html -``` - -By default, typical SPA paths (e.g. `/user/1`, `/login`) would return `404 Not Found` as a file does not exist with that path. By marking `index.html` as the SPA you create this rule: - -*If a static file at the requested path exists (e.g. `/css/style.css`) then serve it, if it does not (e.g. `/login`) then serve the specified SPA and handle the route client-side.* - -[Example](https://github.com/75lb/local-web-server/tree/master/example/spa). - -### URL rewriting - -Your application requested `/css/style.css` but it's stored at `/build/css/style.css`. To avoid a 404 you need a rewrite rule: - -```sh -$ ws --rewrite '/css/style.css -> /build/css/style.css' -``` - -Or, more generally (matching any stylesheet under `/css`): - -```sh -$ ws --rewrite '/css/:stylesheet -> /build/css/:stylesheet' -``` - -With a deep CSS directory structure it may be easier to mount the entire contents of `/build/css` to the `/css` path: - -```sh -$ ws --rewrite '/css/* -> /build/css/$1' -``` - -this rewrites `/css/a` as `/build/css/a`, `/css/a/b/c` as `/build/css/a/b/c` etc. - -#### Proxied requests - -If the `to` URL contains a remote host, local-web-server will act as a proxy - fetching and responding with the remote resource. - -Mount the npm registry locally: -```sh -$ ws --rewrite '/npm/* -> http://registry.npmjs.org/$1' -``` - -Map local requests for repo data to the Github API: -```sh -$ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name' -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/rewrite). - -### Mock Responses - -Mocks give you full control over the response headers and body returned to the client. They can be used to return anything from a simple html string to a resourceful REST API. Typically, they're used to mock services but can be used for anything. - -In the config, define an array called `mocks`. Each mock definition maps a [route](http://expressjs.com/guide/routing.html#route-paths) to a `response`. A simple home page: -```json -{ - "mocks": [ - { - "route": "/", - "response": { - "body": "

Welcome to the Mock Responses example

" - } - } - ] -} -``` - -Under the hood, the property values from the `response` object are written onto the underlying [koa response object](https://github.com/koajs/koa/blob/master/docs/api/response.md). You can set any valid koa response properies, for example [type](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsetype-1): -```json -{ - "mocks": [ - { - "route": "/", - "response": { - "type": "text/plain", - "body": "

Welcome to the Mock Responses example

" - } - } - ] -} -``` - -#### Conditional Response - -To define a conditional response, set a `request` object on the mock definition. The `request` value acts as a query - the response defined will only be returned if each property of the `request` query matches. For example, return an XML response *only* if the request headers include `accept: application/xml`, else return 404 Not Found. - -```json -{ - "mocks": [ - { - "route": "/two", - "request": { "accepts": "xml" }, - "response": { - "body": "" - } - } - ] -} -``` - -#### Multiple Potential Responses - -To specify multiple potential responses, set an array of mock definitions to the `responses` property. The first response with a matching request query will be sent. In this example, the client will get one of two responses depending on the request method: - -```json -{ - "mocks": [ - { - "route": "/three", - "responses": [ - { - "request": { "method": "GET" }, - "response": { - "body": "

Mock response for 'GET' request on /three

" - } - }, - { - "request": { "method": "POST" }, - "response": { - "status": 400, - "body": { "message": "That method is not allowed." } - } - } - ] - } - ] -} -``` - -#### Dynamic Response - -The examples above all returned static data. To define a dynamic response, create a mock module. Specify its path in the `module` property: -```json -{ - "mocks": [ - { - "route": "/four", - "module": "/mocks/stream-self.js" - } - ] -} -``` - -Here's what the `stream-self` module looks like. The module should export a mock definition (an object, or array of objects, each with a `response` and optional `request`). In this example, the module simply streams itself to the response but you could set `body` to *any* [valid value](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsebody-1). -```js -const fs = require('fs') - -module.exports = { - response: { - body: fs.createReadStream(__filename) - } -} -``` - -#### Response function - -For more power, define the response as a function. It will receive the [koa context](https://github.com/koajs/koa/blob/master/docs/api/context.md) as its first argument. Now you have full programmatic control over the response returned. -```js -module.exports = { - response: function (ctx) { - ctx.body = '

I can do anything i want.

' - } -} -``` - -If the route contains tokens, their values are passed to the response. For example, with this mock... -```json -{ - "mocks": [ - { - "route": "/players/:id", - "module": "/mocks/players.js" - } - ] -} -``` - -...the `id` value is passed to the `response` function. For example, a path of `/players/10?name=Lionel` would pass `10` to the response function. Additional, the value `Lionel` would be available on `ctx.query.name`: -```js -module.exports = { - response: function (ctx, id) { - ctx.body = `

id: ${id}, name: ${ctx.query.name}

` - } -} -``` - -#### RESTful Resource example - -Here's an example of a REST collection (users). We'll create two routes, one for actions on the resource collection, one for individual resource actions. - -```json -{ - "mocks": [ - { "route": "/users", "module": "/mocks/users.js" }, - { "route": "/users/:id", "module": "/mocks/user.js" } - ] -} -``` - -Define a module (`users.json`) defining seed data: - -```json -[ - { "id": 1, "name": "Lloyd", "age": 40, "nationality": "English" }, - { "id": 2, "name": "Mona", "age": 34, "nationality": "Palestinian" }, - { "id": 3, "name": "Francesco", "age": 24, "nationality": "Italian" } -] -``` - -The collection module: - -```js -const users = require('./users.json') - -/* responses for /users */ -const mockResponses = [ - /* Respond with 400 Bad Request for PUT and DELETE - inappropriate on a collection */ - { request: { method: 'PUT' }, response: { status: 400 } }, - { request: { method: 'DELETE' }, response: { status: 400 } }, - { - /* for GET requests return a subset of data, optionally filtered on 'minAge' and 'nationality' */ - request: { method: 'GET' }, - response: function (ctx) { - ctx.body = users.filter(user => { - const meetsMinAge = (user.age || 1000) >= (Number(ctx.query.minAge) || 0) - const requiredNationality = user.nationality === (ctx.query.nationality || user.nationality) - return meetsMinAge && requiredNationality - }) - } - }, - { - /* for POST requests, create a new user and return the path to the new resource */ - request: { method: 'POST' }, - response: function (ctx) { - const newUser = ctx.request.body - users.push(newUser) - newUser.id = users.length - ctx.status = 201 - ctx.response.set('Location', `/users/${newUser.id}`) - } - } -] - -module.exports = mockResponses -``` - -The individual resource module: - -```js -const users = require('./users.json') - -/* responses for /users/:id */ -const mockResponses = [ - /* don't support POST here */ - { request: { method: 'POST' }, response: { status: 400 } }, - - /* for GET requests, return a particular user */ - { - request: { method: 'GET' }, - response: function (ctx, id) { - ctx.body = users.find(user => user.id === Number(id)) - } - }, - - /* for PUT requests, update the record */ - { - request: { method: 'PUT' }, - response: function (ctx, id) { - const updatedUser = ctx.request.body - const existingUserIndex = users.findIndex(user => user.id === Number(id)) - users.splice(existingUserIndex, 1, updatedUser) - ctx.status = 200 - } - }, - - /* DELETE request: remove the record */ - { - request: { method: 'DELETE' }, - response: function (ctx, id) { - const existingUserIndex = users.findIndex(user => user.id === Number(id)) - users.splice(existingUserIndex, 1) - ctx.status = 200 - } - } -] - -module.exports = mockResponses -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/mock). - -### HTTPS Server - -Some modern techs (ServiceWorker, any `MediaDevices.getUserMedia()` request etc.) *must* be served from a secure origin (HTTPS). To launch an HTTPS server, supply a `--key` and `--cert` to local-web-server, for example: - -``` -$ ws --key localhost.key --cert localhost.crt -``` - -If you don't have a key and certificate it's trivial to create them. You do not need third-party verification (Verisign etc.) for development purposes. To get the green padlock in the browser, the certificate.. - -* must have a `Common Name` value matching the FQDN of the server -* must be verified by a Certificate Authority (but we can overrule this - see below) - -First create a certificate: - -1. Install openssl. - - `$ brew install openssl` - -2. Generate a RSA private key. - - `$ openssl genrsa -des3 -passout pass:x -out ws.pass.key 2048` - -3. Create RSA key. - - ``` - $ openssl rsa -passin pass:x -in ws.pass.key -out ws.key - ``` - -4. Create certificate request. The command below will ask a series of questions about the certificate owner. The most imporant answer to give is for `Common Name`, you can accept the default values for the others. **Important**: you **must** input your server's correct FQDN (`dev-server.local`, `laptop.home` etc.) into the `Common Name` field. The cert is only valid for the domain specified here. You can find out your computers host name by running the command `hostname`. For example, mine is `mba3.home`. - - `$ openssl req -new -key ws.key -out ws.csr` - -5. Generate self-signed certificate. - - `$ openssl x509 -req -days 365 -in ws.csr -signkey ws.key -out ws.crt` - -6. Clean up files we're finished with - - `$ rm ws.pass.key ws.csr` - -7. Launch HTTPS server. In iTerm, control-click the first URL (with the hostname matching `Common Name`) to launch your browser. - - ``` - $ ws --key ws.key --cert ws.crt - serving at https://mba3.home:8010, https://127.0.0.1:8010, https://192.168.1.203:8010 - ``` - -Chrome and Firefox will still complain your certificate has not been verified by a Certificate Authority. Firefox will offer you an `Add an exception` option, allowing you to ignore the warning and manually mark the certificate as trusted. In Chrome on Mac, you can manually trust the certificate another way: - -1. Open Keychain -2. Click File -> Import. Select the `.crt` file you created. -3. In the `Certificates` category, double-click the cert you imported. -4. In the `trust` section, underneath `when using this certificate`, select `Always Trust`. - -Now you have a valid, trusted certificate for development. - -#### Built-in certificate -As a quick win, you can run `ws` with the `https` flag. This will launch an HTTPS server using a [built-in certificate](https://github.com/75lb/local-web-server/tree/master/ssl) registered to the domain 127.0.0.1. - -### Stored config - -Use the same options every time? Persist then to `package.json`: -```json -{ - "name": "example", - "version": "1.0.0", - "local-web-server": { - "port": 8100, - "forbid": "*.json" - } -} -``` - -or `.local-web-server.json` -```json -{ - "port": 8100, - "forbid": "*.json" -} -``` - -local-web-server will merge and use all config found, searching from the current directory upward. In the case both `package.json` and `.local-web-server.json` config is found in the same directory, `.local-web-server.json` will take precedence. Options set on the command line take precedence over all. - -To inspect stored config, run: -```sh -$ ws --config -``` - -### Logging -By default, local-web-server outputs a simple, dynamic statistics view. To see traditional web server logs, use `--log-format`: - -```sh -$ ws --log-format combined -serving at http://localhost:8000 -::1 - - [16/Nov/2015:11:16:52 +0000] "GET / HTTP/1.1" 200 12290 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2562.0 Safari/537.36" -``` - -The format value supplied is passed directly to [morgan](https://github.com/expressjs/morgan). The exception is `--log-format none` which disables all output. - -### Access Control - -By default, access to all files is allowed (including dot files). Use `--forbid` to establish a blacklist: -```sh -$ ws --forbid '*.json' '*.yml' -serving at http://localhost:8000 -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/forbid). - ### Other usage #### Debugging @@ -534,19 +131,6 @@ Disable etag response headers, forcing resources to be served in full every time $ ws --no-cache ``` -#### mime-types -You can set additional mime-type/extension mappings, or override the defaults by setting a `mime` value in the stored config. This value is passed directly to [mime.define()](https://github.com/broofa/node-mime#mimedefine). Example: - -```json -{ - "mime": { - "text/plain": [ "php", "pl" ] - } -} -``` - -[Example](https://github.com/75lb/local-web-server/tree/master/example/mime-override). - #### Log Visualisation Instructions for how to visualise log output using goaccess, logstalgia or gltail [here](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md). diff --git a/lib/default-stack.js b/lib/default-stack.js new file mode 100644 index 0000000..df61838 --- /dev/null +++ b/lib/default-stack.js @@ -0,0 +1,291 @@ +'use strict' +const arrayify = require('array-back') +const path = require('path') +const url = require('url') +const debug = require('./debug') +const mw = require('./middleware') +const t = require('typical') +const compose = require('koa-compose') +const flatten = require('reduce-flatten') +const MiddlewareStack = require('./middleware-stack') + +class DefaultStack extends MiddlewareStack { + /** + * allow from any origin + */ + addCors () { + this.push({ middleware: require('kcors') }) + return this + } + + /* pretty print JSON */ + addJson () { + this.push({ middleware: require('koa-json') }) + return this + } + + /* rewrite rules */ + addRewrite (rewriteRules) { + this.push({ + optionDefinitions: { + name: 'rewrite', alias: 'r', type: String, multiple: true, + typeLabel: '[underline]{expression} ...', + description: "A list of URL rewrite rules. For each rule, separate the 'from' and 'to' routes with '->'. Whitespace surrounded the routes is ignored. E.g. '/from -> /to'." + }, + middleware: function (cliOptions) { + const options = parseRewriteRules(arrayify(cliOptions.rewrite || rewriteRules)) + if (options.length) { + return options.map(route => { + if (route.to) { + /* `to` address is remote if the url specifies a host */ + if (url.parse(route.to).host) { + const _ = require('koa-route') + debug('proxy rewrite', `${route.from} -> ${route.to}`) + return _.all(route.from, mw.proxyRequest(route)) + } else { + const rewrite = require('koa-rewrite') + const rmw = rewrite(route.from, route.to) + rmw._name = 'rewrite' + return rmw + } + } + }) + } + } + }) + return this + } + + /* must come after rewrite. + See https://github.com/nodejitsu/node-http-proxy/issues/180. */ + addBodyParser () { + this.push({ middleware: require('koa-bodyparser') }) + return this + } + + /* path blacklist */ + addBlacklist (forbidList) { + this.push({ + optionDefinitions: { + name: 'forbid', alias: 'b', type: String, + multiple: true, typeLabel: '[underline]{path} ...', + description: 'A list of forbidden routes.' + }, + middleware: function (cliOptions) { + forbidList = arrayify(cliOptions.forbid || forbidList) + if (forbidList.length) { + const pathToRegexp = require('path-to-regexp') + debug('forbid', forbidList.join(', ')) + return function blacklist (ctx, next) { + if (forbidList.some(expression => pathToRegexp(expression).test(ctx.path))) { + ctx.status = 403 + } else { + return next() + } + } + } + } + }) + return this + } + + /* cache */ + addCache () { + this.push({ + optionDefinitions: { + name: 'no-cache', alias: 'n', type: Boolean, + description: 'Disable etag-based caching - forces loading from disk each request.' + }, + middleware: function (cliOptions) { + const noCache = cliOptions['no-cache'] + if (!noCache) { + return [ + require('koa-conditional-get')(), + require('koa-etag')() + ] + } + } + }) + return this + } + + /* mime-type overrides */ + addMimeOverride (mime) { + this.push({ + middleware: function (cliOptions) { + mime = cliOptions.mime || mime + if (mime) { + debug('mime override', JSON.stringify(mime)) + return mw.mime(mime) + } + } + }) + return this + } + + /* compress response */ + addCompression (compress) { + this.push({ + optionDefinitions: { + name: 'compress', alias: 'c', type: Boolean, + description: 'Serve gzip-compressed resources, where applicable.' + }, + middleware: function (cliOptions) { + compress = t.isDefined(cliOptions.compress) + ? cliOptions.compress + : compress + if (compress) { + debug('compression', 'enabled') + return require('koa-compress')() + } + } + }) + return this + } + + /* Logging */ + addLogging (format, options) { + options = options || {} + this.push({ + optionDefinitions: { + name: 'log-format', + alias: 'f', + type: String, + description: "If a format is supplied an access log is written to stdout. If not, a dynamic statistics view is displayed. Use a preset ('none', 'dev','combined', 'short', 'tiny' or 'logstalgia') or supply a custom format (e.g. ':method -> :url')." + }, + middleware: function (cliOptions) { + format = cliOptions['log-format'] || format + + if (cliOptions.verbose && !format) { + format = 'none' + } + + if (format !== 'none') { + const morgan = require('koa-morgan') + + if (!format) { + const streamLogStats = require('stream-log-stats') + options.stream = streamLogStats({ refreshRate: 500 }) + return morgan('common', options) + } else if (format === 'logstalgia') { + morgan.token('date', () => { + var d = new Date() + return (`${d.getDate()}/${d.getUTCMonth()}/${d.getFullYear()}:${d.toTimeString()}`).replace('GMT', '').replace(' (BST)', '') + }) + return morgan('combined', options) + } else { + return morgan(format, options) + } + } + } + }) + return this + } + + /* Mock Responses */ + addMockResponses (mocks) { + this.push({ + middleware: function (cliOptions) { + mocks = arrayify(cliOptions.mocks || mocks) + return mocks.map(mock => { + if (mock.module) { + const modulePath = path.resolve(path.join(cliOptions.directory, mock.module)) + mock.responses = require(modulePath) + } + + if (mock.responses) { + return mw.mockResponses(mock.route, mock.responses) + } else if (mock.response) { + mock.target = { + request: mock.request, + response: mock.response + } + return mw.mockResponses(mock.route, mock.target) + } + }) + } + }) + return this + } + + /* for any URL not matched by static (e.g. `/search`), serve the SPA */ + addSpa (spa, assetTest) { + this.push({ + optionDefinitions: { + name: 'spa', alias: 's', type: String, typeLabel: '[underline]{file}', + description: 'Path to a Single Page App, e.g. app.html.' + }, + middleware: function (cliOptions) { + spa = cliOptions.spa || spa || 'index.html' + assetTest = new RegExp(cliOptions['spa-asset-test'] || assetTest || '\\.') + if (spa) { + const send = require('koa-send') + const _ = require('koa-route') + debug('SPA', spa) + return _.get('*', function spaMw (ctx, route, next) { + const root = path.resolve(cliOptions.directory || process.cwd()) + if (ctx.accepts('text/html') && !assetTest.test(route)) { + debug(`SPA request. Route: ${route}, isAsset: ${assetTest.test(route)}`) + return send(ctx, spa, { root: root }).then(next) + } else { + return send(ctx, route, { root: root }).then(next) + } + }) + } + } + }) + return this + } + + /* serve static files */ + addStatic (root, options) { + this.push({ + optionDefinitions: { + name: 'directory', alias: 'd', type: String, typeLabel: '[underline]{path}', + description: 'Root directory, defaults to the current directory.' + }, + middleware: function (cliOptions) { + /* update global cliOptions */ + cliOptions.directory = cliOptions.directory || root || process.cwd() + options = Object.assign({ hidden: true }, options) + if (cliOptions.directory) { + const serve = require('koa-static') + return serve(cliOptions.directory, options) + } + } + }) + return this + } + + /* serve directory index */ + addIndex (path, options) { + this.push({ + middleware: function (cliOptions) { + path = cliOptions.directory || path || process.cwd() + options = Object.assign({ icons: true, hidden: true }, options) + if (path) { + const serveIndex = require('koa-serve-index') + return serveIndex(path, options) + } + } + }) + return this + } +} + +module.exports = DefaultStack + +function parseRewriteRules (rules) { + return rules && rules.map(rule => { + if (t.isString(rule)) { + const matches = rule.match(/(\S*)\s*->\s*(\S*)/) + if (!(matches && matches.length >= 3)) throw new Error('Invalid rule: ' + rule) + return { + from: matches[1], + to: matches[2] + } + } else { + return rule + } + }) +} diff --git a/lib/local-web-server.js b/lib/local-web-server.js index 2852c2e..f8c4729 100644 --- a/lib/local-web-server.js +++ b/lib/local-web-server.js @@ -5,12 +5,20 @@ const path = require('path') const arrayify = require('array-back') const t = require('typical') const CommandLineTool = require('command-line-tool') -const MiddlewareStack = require('./middleware-stack') +const DefaultStack = require('./default-stack') const debug = require('./debug') +/** + * @module local-web-server + */ + const tool = new CommandLineTool() -class LocalWebServer extends MiddlewareStack { +/** + * @alias module:local-web-server + * @extends module:middleware-stack + */ +class LocalWebServer extends DefaultStack { _init (options) { this.options = this.options || Object.assign(options || {}, collectUserOptions(this.getOptionDefinitions())) } @@ -83,7 +91,7 @@ class LocalWebServer extends MiddlewareStack { } function onServerUp (port, directory, isHttps) { - const ipList = getIPList(isHttps) + const ipList = getIPList() .map(iface => `[underline]{${isHttps ? 'https' : 'http'}://${iface.address}:${port}}`) .join(', ') @@ -94,7 +102,8 @@ function onServerUp (port, directory, isHttps) { )) } -function getIPList (isHttps) { + +function getIPList () { const flatten = require('reduce-flatten') const os = require('os') diff --git a/lib/middleware-stack.js b/lib/middleware-stack.js index fda6a26..c8961e7 100644 --- a/lib/middleware-stack.js +++ b/lib/middleware-stack.js @@ -8,271 +8,21 @@ const t = require('typical') const compose = require('koa-compose') const flatten = require('reduce-flatten') +/** + * @module middleware-stack + */ + +/** + * @extends Array + * @alias module:middleware-stack + */ class MiddlewareStack extends Array { - add (middleware) { - this.push(middleware) - return this - } - /** - * allow from any origin + * @param {module:middleware-stack~middleware} + * @chainable */ - addCors () { - this.push({ middleware: require('kcors') }) - return this - } - - /* pretty print JSON */ - addJson () { - this.push({ middleware: require('koa-json') }) - return this - } - - /* rewrite rules */ - addRewrite (rewriteRules) { - this.push({ - optionDefinitions: { - name: 'rewrite', alias: 'r', type: String, multiple: true, - typeLabel: '[underline]{expression} ...', - description: "A list of URL rewrite rules. For each rule, separate the 'from' and 'to' routes with '->'. Whitespace surrounded the routes is ignored. E.g. '/from -> /to'." - }, - middleware: function (cliOptions) { - const options = parseRewriteRules(arrayify(cliOptions.rewrite || rewriteRules)) - if (options.length) { - return options.map(route => { - if (route.to) { - /* `to` address is remote if the url specifies a host */ - if (url.parse(route.to).host) { - const _ = require('koa-route') - debug('proxy rewrite', `${route.from} -> ${route.to}`) - return _.all(route.from, mw.proxyRequest(route)) - } else { - const rewrite = require('koa-rewrite') - const rmw = rewrite(route.from, route.to) - rmw._name = 'rewrite' - return rmw - } - } - }) - } - } - }) - return this - } - - /* must come after rewrite. - See https://github.com/nodejitsu/node-http-proxy/issues/180. */ - addBodyParser () { - this.push({ middleware: require('koa-bodyparser') }) - return this - } - - /* path blacklist */ - addBlacklist (forbidList) { - this.push({ - optionDefinitions: { - name: 'forbid', alias: 'b', type: String, - multiple: true, typeLabel: '[underline]{path} ...', - description: 'A list of forbidden routes.' - }, - middleware: function (cliOptions) { - forbidList = arrayify(cliOptions.forbid || forbidList) - if (forbidList.length) { - const pathToRegexp = require('path-to-regexp') - debug('forbid', forbidList.join(', ')) - return function blacklist (ctx, next) { - if (forbidList.some(expression => pathToRegexp(expression).test(ctx.path))) { - ctx.status = 403 - } else { - return next() - } - } - } - } - }) - return this - } - - /* cache */ - addCache () { - this.push({ - optionDefinitions: { - name: 'no-cache', alias: 'n', type: Boolean, - description: 'Disable etag-based caching - forces loading from disk each request.' - }, - middleware: function (cliOptions) { - const noCache = cliOptions['no-cache'] - if (!noCache) { - return [ - require('koa-conditional-get')(), - require('koa-etag')() - ] - } - } - }) - return this - } - - /* mime-type overrides */ - addMimeOverride (mime) { - this.push({ - middleware: function (cliOptions) { - mime = cliOptions.mime || mime - if (mime) { - debug('mime override', JSON.stringify(mime)) - return mw.mime(mime) - } - } - }) - return this - } - - /* compress response */ - addCompression (compress) { - this.push({ - optionDefinitions: { - name: 'compress', alias: 'c', type: Boolean, - description: 'Serve gzip-compressed resources, where applicable.' - }, - middleware: function (cliOptions) { - compress = t.isDefined(cliOptions.compress) - ? cliOptions.compress - : compress - if (compress) { - debug('compression', 'enabled') - return require('koa-compress')() - } - } - }) - return this - } - - /* Logging */ - addLogging (format, options) { - options = options || {} - this.push({ - optionDefinitions: { - name: 'log-format', - alias: 'f', - type: String, - description: "If a format is supplied an access log is written to stdout. If not, a dynamic statistics view is displayed. Use a preset ('none', 'dev','combined', 'short', 'tiny' or 'logstalgia') or supply a custom format (e.g. ':method -> :url')." - }, - middleware: function (cliOptions) { - format = cliOptions['log-format'] || format - - if (cliOptions.verbose && !format) { - format = 'none' - } - - if (format !== 'none') { - const morgan = require('koa-morgan') - - if (!format) { - const streamLogStats = require('stream-log-stats') - options.stream = streamLogStats({ refreshRate: 500 }) - return morgan('common', options) - } else if (format === 'logstalgia') { - morgan.token('date', () => { - var d = new Date() - return (`${d.getDate()}/${d.getUTCMonth()}/${d.getFullYear()}:${d.toTimeString()}`).replace('GMT', '').replace(' (BST)', '') - }) - return morgan('combined', options) - } else { - return morgan(format, options) - } - } - } - }) - return this - } - - /* Mock Responses */ - addMockResponses (mocks) { - this.push({ - middleware: function (cliOptions) { - mocks = arrayify(cliOptions.mocks || mocks) - return mocks.map(mock => { - if (mock.module) { - const modulePath = path.resolve(path.join(cliOptions.directory, mock.module)) - mock.responses = require(modulePath) - } - - if (mock.responses) { - return mw.mockResponses(mock.route, mock.responses) - } else if (mock.response) { - mock.target = { - request: mock.request, - response: mock.response - } - return mw.mockResponses(mock.route, mock.target) - } - }) - } - }) - return this - } - - /* for any URL not matched by static (e.g. `/search`), serve the SPA */ - addSpa (spa, assetTest) { - this.push({ - optionDefinitions: { - name: 'spa', alias: 's', type: String, typeLabel: '[underline]{file}', - description: 'Path to a Single Page App, e.g. app.html.' - }, - middleware: function (cliOptions) { - spa = cliOptions.spa || spa || 'index.html' - assetTest = new RegExp(cliOptions['spa-asset-test'] || assetTest || '\\.') - if (spa) { - const send = require('koa-send') - const _ = require('koa-route') - debug('SPA', spa) - return _.get('*', function spaMw (ctx, route, next) { - const root = path.resolve(cliOptions.directory || process.cwd()) - if (ctx.accepts('text/html') && !assetTest.test(route)) { - debug(`SPA request. Route: ${route}, isAsset: ${assetTest.test(route)}`) - return send(ctx, spa, { root: root }).then(next) - } else { - return send(ctx, route, { root: root }).then(next) - } - }) - } - } - }) - return this - } - - /* serve static files */ - addStatic (root, options) { - this.push({ - optionDefinitions: { - name: 'directory', alias: 'd', type: String, typeLabel: '[underline]{path}', - description: 'Root directory, defaults to the current directory.' - }, - middleware: function (cliOptions) { - /* update global cliOptions */ - cliOptions.directory = cliOptions.directory || root || process.cwd() - options = Object.assign({ hidden: true }, options) - if (cliOptions.directory) { - const serve = require('koa-static') - return serve(cliOptions.directory, options) - } - } - }) - return this - } - - /* serve directory index */ - addIndex (path, options) { - this.push({ - middleware: function (cliOptions) { - path = cliOptions.directory || path || process.cwd() - options = Object.assign({ icons: true, hidden: true }, options) - if (path) { - const serveIndex = require('koa-serve-index') - return serveIndex(path, options) - } - } - }) + add (middleware) { + this.push(middleware) return this } @@ -295,24 +45,14 @@ class MiddlewareStack extends Array { .filter(middleware => middleware) .reduce(flatten, []) .map(convert) - // console.error(require('util').inspect(middlewareStack, { depth: 3, colors: true })) return compose(middlewareStack) } } module.exports = MiddlewareStack -function parseRewriteRules (rules) { - return rules && rules.map(rule => { - if (t.isString(rule)) { - const matches = rule.match(/(\S*)\s*->\s*(\S*)/) - if (!(matches && matches.length >= 3)) throw new Error('Invalid rule: ' + rule) - return { - from: matches[1], - to: matches[2] - } - } else { - return rule - } - }) -} +/** + * @typedef middleware + * @property optionDefinitions {object|object[]} + * @property middleware {function} + */