added --verbose option to aid debugging

README.md

@@ -128,6 +128,13 @@ The format value supplied is passed directly to [morgan](https://github.com/expr
 
 ### Other usage
 
+#### Debugging
+
+Prints information about loaded middleware, arguments, remote proxy fetches etc.
+```sh
+$ ws --verbose
+```
+
 #### Compression
 
 Serve gzip-compressed resources, where applicable

bin/cli.js

@@ -6,6 +6,7 @@ const commandLineArgs = require('command-line-args')
 const ansi = require('ansi-escape-sequences')
 const loadConfig = require('config-master')
 const path = require('path')
+const s = require('string-tools')
 
 const cli = commandLineArgs(cliOptions.definitions)
 const usage = cli.getUsage(cliOptions.usageData)
@@ -23,7 +24,7 @@ if (options.misc.config) {
   process.exit(0)
 }
 
-localWebServer({
+const app = localWebServer({
   static: {
     root: options.server.directory,
     options: {
@@ -45,8 +46,15 @@ localWebServer({
   forbid: options.server.forbid,
   spa: options.server.spa,
   'no-cache': options.server['no-cache'],
-  rewrite: options.server.rewrite
-}).listen(options.server.port, onServerUp)
+  rewrite: options.server.rewrite,
+  verbose: options.server.verbose
+})
+
+app
+  .on('verbose', (category, message) => {
+    console.error(ansi.format(s.padRight(category, 14), 'bold'), message)
+  })
+  .listen(options.server.port, onServerUp)
 
 function halt (err) {
   console.log(ansi.format(`Error: ${err.message}`, 'red'))

jsdoc2md/README.hbs

@@ -128,6 +128,13 @@ The format value supplied is passed directly to [morgan](https://github.com/expr
 
 ### Other usage
 
+#### Debugging
+
+Prints information about loaded middleware, arguments, remote proxy fetches etc.
+```sh
+$ ws --verbose
+```
+
 #### Compression
 
 Serve gzip-compressed resources, where applicable

lib/cli-options.js

@@ -33,6 +33,10 @@ module.exports = {
       description: 'Path to a Single Page App, e.g. app.html', group: 'server'
     },
     {
+      name: 'verbose', type: Boolean,
+      description: 'Verbose output, useful for debugging.', group: 'server'
+    },
+    {
       name: 'help', alias: 'h', type: Boolean,
       description: 'Print these usage instructions', group: 'misc'
     },

lib/local-web-server.js

@@ -39,7 +39,8 @@ function localWebServer (options) {
     compress: false,
     mime: {},
     forbid: [],
-    rewrite: []
+    rewrite: [],
+    verbose: false
   }, options)
 
   const log = options.log
@@ -48,6 +49,16 @@ function localWebServer (options) {
   const app = new Koa()
   const _use = app.use
   app.use = x => _use.call(app, convert(x))
+  function verbose (category, message) {
+    if (options.verbose) {
+      process.nextTick(() => app.emit('verbose', category, message))
+    }
+  }
+  app._verbose = verbose
+
+  if (options.verbose && !log.format)  {
+    log.format = 'none'
+  }
 
   /* CORS: allow from any origin */
   app.use(cors())
@@ -57,9 +68,11 @@ function localWebServer (options) {
     options.rewrite.forEach(route => {
       if (route.to) {
         if (url.parse(route.to).host) {
-          app.use(_.all(route.from, proxyRequest(route)))
+          verbose('proxy rewrite', `${route.from} -> ${route.to}`)
+          app.use(_.all(route.from, proxyRequest(route, app)))
         } else {
           const rewrite = require('koa-rewrite')
+          verbose('local rewrite', `${route.from} -> ${route.to}`)
           app.use(rewrite(route.from, route.to))
         }
       }
@@ -68,6 +81,7 @@ function localWebServer (options) {
 
   /* path blacklist */
   if (options.forbid.length) {
+    verbose('forbid', options.forbid.join(', '))
     app.use(blacklist(options.forbid))
   }
 
@@ -75,12 +89,14 @@ function localWebServer (options) {
   if (!options['no-cache']) {
     const conditional = require('koa-conditional-get')
     const etag = require('koa-etag')
+    verbose('etag caching', 'enabled')
     app.use(conditional())
     app.use(etag())
   }
 
   /* mime-type overrides */
   if (options.mime) {
+    verbose('mime override', JSON.stringify(options.mime))
     app.use((ctx, next) => {
       return next().then(() => {
         const reqPathExtension = path.extname(ctx.path).slice(1)
@@ -95,6 +111,7 @@ function localWebServer (options) {
   /* compress response */
   if (options.compress) {
     const compress = require('koa-compress')
+    verbose('compression', 'enabled')
     app.use(compress())
   }
 
@@ -117,18 +134,21 @@ function localWebServer (options) {
   /* serve static files */
   if (options.static.root) {
     const serve = require('koa-static')
+    verbose('static', `root: ${options.static.root} options: ${JSON.stringify(options.static.options)}` )
     app.use(serve(options.static.root, options.static.options))
   }
 
   /* serve directory index */
   if (options.serveIndex.path) {
     const serveIndex = require('koa-serve-index')
+    verbose('serve-index', `root: ${options.serveIndex.path} options: ${JSON.stringify(options.serveIndex.options)}` )
     app.use(serveIndex(options.serveIndex.path, options.serveIndex.options))
   }
 
   /* for any URL not matched by static (e.g. `/search`), serve the SPA */
   if (options.spa) {
     const send = require('koa-send')
+    verbose('SPA', options.spa)
     app.use(_.all('*', function * () {
       yield send(this, options.spa, { root: path.resolve(options.static.root) || process.cwd() })
     }))
@@ -141,7 +161,7 @@ function logstalgiaDate () {
   return (`${d.getDate()}/${d.getUTCMonth()}/${d.getFullYear()}:${d.toTimeString()}`).replace('GMT', '').replace(' (BST)', '')
 }
 
-function proxyRequest (route) {
+function proxyRequest (route, app) {
   const httpProxy = require('http-proxy')
   const proxy = httpProxy.createProxyServer({
     changeOrigin: true
@@ -168,12 +188,13 @@ function proxyRequest (route) {
     }
 
     this.response = false
+    app._verbose('proxy request', `from: ${this.path}, to: ${url.parse(route.new).href}`)
 
     proxy.once('error', err => {
       this.throw(500, `[PROXY] ${err.message}: ${route.new}`)
     })
     proxy.once('proxyReq', function (proxyReq) {
-      proxyReq.path = url.parse(route.new).path;
+      proxyReq.path = url.parse(route.new).path
     })
     proxy.web(this.req, this.res, { target: route.new })
   }

package.json

@@ -45,7 +45,8 @@
     "koa-serve-index": "^1.1.0",
     "koa-static": "^1.5.2",
     "path-to-regexp": "^1.2.1",
-    "stream-log-stats": "^v1.1.0-0"
+    "stream-log-stats": "^v1.1.0-0",
+    "string-tools": "^1.0.0"
   },
   "devDependencies": {
     "req-then": "^0.2.2",