Add fallthrough option

closes #33
closes #36

Author: dougwilson

HISTORY.md

@@ -1,6 +1,9 @@
 unreleased
 ==========
 
+  * Add `fallthrough` option
+    - Allows declaring this middleware is the final destination
+    - Provides better integration with Express patterns
   * Fix reading options from options prototype
   * Improve the default redirect response headers
   * deps: [email protected]

README.md

@@ -41,8 +41,8 @@ to "deny").
 The default value is `'ignore'`.
 
   - `'allow'` No special treatment for dotfiles.
-  - `'deny'` Send a 403 for any request for a dotfile.
-  - `'ignore'` Pretend like the dotfile does not exist and call `next()`.
+  - `'deny'` Deny a request for a dotfile and 403/`next()`.
+  - `'ignore'` Pretend like the dotfile does not exist and 404/`next()`.
 
 ##### etag
 
@@ -56,6 +56,25 @@ exists will be served. Example: `['html', 'htm']`.
 
 The default value is `false`.
 
+##### fallthrough
+
+Set the middleware to have client errors fall-through as just unhandled
+requests, otherwise forward a client error. The difference is that client
+errors like a bad request or a request to a non-existent file will cause
+this middleware to simply `next()` to your next middleware when this value
+is `true`. When this value is `false`, these errors (even 404s), will invoke
+`next(err)`.
+
+Typically `true` is desired such that multiple physical directories can be
+mapped to the same web address or for routes to fill in non-existent files.
+
+The value `false` can be used if this middleware is mounted at a path that
+is designed to be strictly a single file system directory, which allows for
+short-circuiting 404s for less overhead. This middleware will also reply to
+all methods.
+
+The default value is `true`.
+
 ##### index
 
 By default this module will send "index.html" files in response to a request

index.js

@@ -13,11 +13,11 @@
  * @private
  */
 
-var escapeHtml = require('escape-html');
-var parseurl = require('parseurl');
-var resolve = require('path').resolve;
-var send = require('send');
-var url = require('url');
+var escapeHtml = require('escape-html')
+var parseUrl = require('parseurl')
+var resolve = require('path').resolve
+var send = require('send')
+var url = require('url')
 
 /**
  * Module exports.
@@ -46,12 +46,14 @@ function serveStatic(root, options) {
   // copy options object
   var opts = Object.create(options || null)
 
+  // fall-though
+  var fallthrough = opts.fallthrough !== false
+
   // default redirect
   var redirect = opts.redirect !== false
 
   // headers listener
   var setHeaders = opts.setHeaders
-  opts.setHeaders = undefined
 
   if (setHeaders && typeof setHeaders !== 'function') {
     throw new TypeError('option setHeaders must be function')
@@ -61,59 +63,61 @@ function serveStatic(root, options) {
   opts.maxage = opts.maxage || opts.maxAge || 0
   opts.root = resolve(root)
 
+  // construct directory listener
+  var onDirectory = redirect
+    ? createRedirectDirectoryListener()
+    : createNotFoundDirectoryListener()
+
   return function serveStatic(req, res, next) {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
-      return next()
+      if (fallthrough) {
+        return next()
+      }
+
+      // method not allowed
+      res.statusCode = 405
+      res.setHeader('Allow', 'GET, HEAD')
+      res.setHeader('Content-Length', '0')
+      res.end()
+      return
     }
 
-    var originalUrl = parseurl.original(req)
-    var path = parseurl(req).pathname
-    var hasTrailingSlash = originalUrl.pathname[originalUrl.pathname.length - 1] === '/'
+    var forwardError = !fallthrough
+    var originalUrl = parseUrl.original(req)
+    var path = parseUrl(req).pathname
 
-    if (path === '/' && !hasTrailingSlash) {
-      // make sure redirect occurs at mount
+    // make sure redirect occurs at mount
+    if (path === '/' && originalUrl.pathname.substr(-1) !== '/') {
       path = ''
     }
 
     // create send stream
     var stream = send(req, path, opts)
 
-    if (redirect) {
-      // redirect relative to originalUrl
-      stream.on('directory', function redirect() {
-        if (hasTrailingSlash) {
-          return next()
-        }
-
-        // append trailing slash
-        originalUrl.path = null
-        originalUrl.pathname = collapseLeadingSlashes(originalUrl.pathname + '/')
-
-        // reformat the URL
-        var loc = url.format(originalUrl)
-        var msg = 'Redirecting to <a href="' + escapeHtml(loc) + '">' + escapeHtml(loc) + '</a>\n'
-
-        // send redirect response
-        res.statusCode = 303
-        res.setHeader('Content-Type', 'text/html; charset=UTF-8')
-        res.setHeader('Content-Length', Buffer.byteLength(msg))
-        res.setHeader('X-Content-Type-Options', 'nosniff')
-        res.setHeader('Location', loc)
-        res.end(msg)
-      })
-    } else {
-      // forward to next middleware on directory
-      stream.on('directory', next)
-    }
+    // add directory handler
+    stream.on('directory', onDirectory)
 
     // add headers listener
     if (setHeaders) {
       stream.on('headers', setHeaders)
     }
 
-    // forward non-404 errors
+    // add file listener for fallthrough
+    if (fallthrough) {
+      stream.on('file', function onFile() {
+        // once file is determined, always forward error
+        forwardError = true
+      })
+    }
+
+    // forward errors
     stream.on('error', function error(err) {
-      next(err.status === 404 ? null : err)
+      if (forwardError || !(err.statusCode < 500)) {
+        next(err)
+        return
+      }
+
+      next()
     })
 
     // pipe
@@ -136,3 +140,48 @@ function collapseLeadingSlashes(str) {
     ? '/' + str.substr(i)
     : str
 }
+
+/**
+ * Create a directory listener that just 404s.
+ * @private
+ */
+
+function createNotFoundDirectoryListener() {
+  return function notFound() {
+    this.error(404)
+  }
+}
+
+/**
+ * Create a directory listener that performs a redirect.
+ * @private
+ */
+
+function createRedirectDirectoryListener() {
+  return function redirect() {
+    if (this.hasTrailingSlash()) {
+      this.error(404)
+      return
+    }
+
+    // get original URL
+    var originalUrl = parseUrl.original(this.req)
+
+    // append trailing slash
+    originalUrl.path = null
+    originalUrl.pathname = collapseLeadingSlashes(originalUrl.pathname + '/')
+
+    // reformat the URL
+    var loc = url.format(originalUrl)
+    var msg = 'Redirecting to <a href="' + escapeHtml(loc) + '">' + escapeHtml(loc) + '</a>\n'
+    var res = this.res
+
+    // send redirect response
+    res.statusCode = 303
+    res.setHeader('Content-Type', 'text/html; charset=UTF-8')
+    res.setHeader('Content-Length', Buffer.byteLength(msg))
+    res.setHeader('X-Content-Type-Options', 'nosniff')
+    res.setHeader('Location', loc)
+    res.end(msg)
+  }
+}

test/fixtures/pets/names.txt

@@ -0,0 +1 @@
+tobi,loki