docs(api): regenerate

Peter Marton · hekike · commit 09b46dc196e0 · 2018-03-20T16:00:35.000-07:00
diff --git a/docs/_api/plugins.md b/docs/_api/plugins.md
@@ -31,6 +31,7 @@ permalink: /docs/plugins-api/
         -   [Using an external storage mechanism for key/bucket mappings.](#using-an-external-storage-mechanism-for-keybucket-mappings)
     -   [inflightRequestThrottle](#inflightrequestthrottle)
     -   [cpuUsageThrottle](#cpuusagethrottle)
+    -   [conditionalHandler](#conditionalhandler)
     -   [conditionalRequest](#conditionalrequest)
     -   [auditLogger](#auditlogger)
     -   [metrics](#metrics)
@@ -534,7 +535,7 @@ _The serveStatic module is different than most of the other plugins, in that
 it is expected that you are going to map it to a route, as below:_
 
 ```javascript
-server.get(/\/docs\/current\/?.*\//, restify.plugins.serveStatic({
+server.get('/docs/current/*', restify.plugins.serveStatic({
   directory: './documentation/v1',
   default: 'index.html'
 }));
@@ -562,7 +563,12 @@ serveStatic method as an option. The following will serve index.html from
 the documentation/v1/ directory anytime a client requests `/home/`._
 
 ```javascript
-server.get(/\/home\//, restify.plugins.serveStatic({
+server.get('/home/*', restify.plugins.serveStatic({
+  directory: './documentation/v1',
+  file: 'index.html'
+}));
+// or
+server.get('/home/([a-z]+[.]html)', restify.plugins.serveStatic({
   directory: './documentation/v1',
   file: 'index.html'
 }));
@@ -853,6 +859,66 @@ plugin.update({ limit: .4, halfLife: 5000 });
 
 Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** middleware to be registered on server.pre
 
+### conditionalHandler
+
+Runs first handler that matches to the condition
+
+**Parameters**
+
+-   `candidates` **([Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)>)** candidates
+    -   `candidates.handler` **([Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)>)** handler(s)
+    -   `candidates.version` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)?** '1.1.0', ['1.1.0', '1.2.0']
+    -   `candidates.contentType` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** accepted content type, '\*\\/json'
+
+**Examples**
+
+```javascript
+server.use(restify.plugins.conditionalHandler({
+   contentType: 'application/json',
+   version: '1.0.0',
+   handler: function (req, res, next) {
+       next();
+   })
+});
+
+server.get('/hello/:name', restify.plugins.conditionalHandler([
+  {
+     version: '1.0.0',
+     handler: function(req, res, next) { res.send('1.x'); }
+  },
+  {
+     version: ['1.5.0', '2.0.0'],
+     handler: function(req, res, next) { res.send('1.5.x, 2.x'); }
+  },
+  {
+     version: '3.0.0',
+     contentType: ['text/html', 'text/html']
+     handler: function(req, res, next) { res.send('3.x, text'); }
+  },
+  {
+     version: '3.0.0',
+     contentType: 'application/json'
+     handler: function(req, res, next) { res.send('3.x, json'); }
+  },
+  // Array of handlers
+  {
+     version: '4.0.0',
+     handler: [
+         function(req, res, next) { next(); },
+         function(req, res, next) { next(); },
+         function(req, res, next) { res.send('4.x') }
+     ]
+  },
+]);
+// 'accept-version': '^1.1.0' => 1.5.x, 2.x'
+// 'accept-version': '3.x', accept: 'application/json' => '3.x, json'
+```
+
+-   Throws **InvalidVersionError** 
+-   Throws **UnsupportedMediaTypeError** 
+
+Returns **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Handler
+
 ### conditionalRequest
 
 Returns a set of plugins that will compare an already set `ETag` header with
@@ -1079,16 +1145,21 @@ Type: [Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Sta
     -   `metrics.statusCode` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** status code of the response. can be
           undefined in the case of an uncaughtException
     -   `metrics.method` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** http request verb
-    -   `metrics.latency` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** request latency
+    -   `metrics.totalLatency` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** latency includes both request is flushed
+                                             and all handlers finished
+    -   `metrics.latency` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** latency when request is flushed
+    -   `metrics.preLatency` **([Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | null)** pre handlers latency
+    -   `metrics.useLatency` **([Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | null)** use handlers latency
+    -   `metrics.routeLatency` **([Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | null)** route handlers latency
     -   `metrics.path` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** `req.path()` value
     -   `metrics.inflightRequests` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Number of inflight requests pending
           in restify.
     -   `metrics.unifinishedRequests` **[Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Same as `inflightRequests`
-    -   `metrics.connectionState` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** can be either `'close'`,
-          `'aborted'`, or `undefined`. If this value is set, err will be a
-          corresponding `RequestCloseError` or `RequestAbortedError`.
+    -   `metrics.connectionState` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** can be either `'close'` or
+         `undefined`. If this value is set, err will be a
+          corresponding `RequestCloseError`.
           If connectionState is either
-          `'close'` or `'aborted'`, then the `statusCode` is not applicable since the
+          `'close'`, then the `statusCode` is not applicable since the
           connection was severed before a response was written.
 -   `req` **[Request](https://developer.mozilla.org/Add-ons/SDK/High-Level_APIs/request)** the request obj
 -   `res` **[Response](https://developer.mozilla.org/docs/Web/Guide/HTML/HTML5)** the response obj
diff --git a/docs/_api/request.md b/docs/_api/request.md
@@ -356,9 +356,8 @@ Returns **[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Referenc
 Returns the connection state of the request. Current possible values are:
 
 -   `close` - when the request has been closed by the clien
--   `aborted` - when the socket was closed unexpectedly
 
-Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** connection state (`"closed"`, `"aborted"`)
+Returns **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** connection state (`"close"`)
 
 ### getRoute
 
diff --git a/docs/_api/server.md b/docs/_api/server.md
@@ -21,7 +21,6 @@ permalink: /docs/server-api/
     -   [pre](#pre)
     -   [use](#use)
     -   [param](#param)
-    -   [versionedUse](#versioneduse)
     -   [rm](#rm)
     -   [address](#address)
     -   [inflightRequests](#inflightrequests)
@@ -39,12 +38,11 @@ routes and handlers for incoming requests.
 
 **Parameters**
 
--   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** an options object
+-   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** an options object
     -   `options.name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Name of the server. (optional, default `"restify"`)
+    -   `options.dtrace` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** enable DTrace support (optional, default `false`)
     -   `options.router` **Router** Router (optional, default `newRouter(opts)`)
     -   `options.log` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** [bunyan](https://github.com/trentm/node-bunyan) instance. (optional, default `bunyan.createLogger(options.name||"restify")`)
-    -   `options.version` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array))?** Default version(s) to use in all
-        routes.
     -   `options.acceptable` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)?** String)|List of content-types this
         server can respond with.
     -   `options.url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Once listen() is called, this will be filled
@@ -59,7 +57,8 @@ routes and handlers for incoming requests.
         will use a domain to catch and respond to any uncaught
         exceptions that occur in it's handler stack.
         [bunyan](https://github.com/trentm/node-bunyan) instance.
-        response header, default is `restify`. Pass empty string to unset the header. (optional, default `false`)
+        response header, default is `restify`. Pass empty string to unset the header.
+        Comes with significant negative performance impact. (optional, default `false`)
     -   `options.spdy` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Any options accepted by
         [node-spdy](https://github.com/indutny/node-spdy).
     -   `options.http2` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Any options accepted by
@@ -96,11 +95,10 @@ Creates a new Server.
 
 -   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** an options object
     -   `options.name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Name of the server.
+    -   `options.dtrace` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** enable DTrace support (optional, default `false`)
     -   `options.router` **Router** Router
     -   `options.log` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** [bunyan](https://github.com/trentm/node-bunyan)
         instance.
-    -   `options.version` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array))?** Default version(s) to use in all
-        routes.
     -   `options.acceptable` **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>?** List of content-types this
         server can respond with.
     -   `options.url` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** Once listen() is called, this will be filled
@@ -114,6 +112,7 @@ Creates a new Server.
     -   `options.handleUncaughtExceptions` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** When true restify
         will use a domain to catch and respond to any uncaught
         exceptions that occur in it's handler stack.
+        Comes with significant negative performance impact.
         [bunyan](https://github.com/trentm/node-bunyan) instance.
         response header, default is `restify`. Pass empty string to unset the header. (optional, default `false`)
     -   `options.spdy` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Any options accepted by
@@ -123,13 +122,17 @@ Creates a new Server.
     -   `options.handleUpgrades` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Hook the `upgrade` event
         from the node HTTP server, pushing `Connection: Upgrade` requests through the
          regular request handling chain. (optional, default `false`)
+    -   `options.onceNext` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Prevents calling next multiple
+         times (optional, default `false`)
+    -   `options.strictNext` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** Throws error when next() is
+         called more than once, enabled onceNext option (optional, default `false`)
     -   `options.httpsServerOptions` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?** Any options accepted by
         [node-https Server](http://nodejs.org/api/https.html#https_https).
         If provided the following restify server options will be ignored:
         spdy, ca, certificate, key, passphrase, rejectUnauthorized, requestCert and
         ciphers; however these can all be specified on httpsServerOptions.
-    -   `options.strictRouting` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** If set, Restify
-        will treat "/foo" and "/foo/" as different paths. (optional, default `false`)
+    -   `options.noWriteContinue` **[Boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** prevents
+         `res.writeContinue()` in `server.on('checkContinue')` when proxing (optional, default `false`)
 
 **Examples**
 
@@ -340,37 +343,14 @@ Exposes an API:
 
 Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** returns self
 
-### versionedUse
-
-Piggy-backs on the `server.use` method. It attaches a new middleware
-function that only fires if the specified version matches the request.
-
-Note that if the client does not request a specific version, the middleware
-function always fires. If you don't want this set a default version with a
-pre handler on requests where the client omits one.
-
-Exposes an API:
-  server.versionedUse("version", function (req, res, next, ver) {
-    // do stuff that only applies to routes of this API version
-  });
-
-**Parameters**
-
--   `versions` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array))** the version(s) the URL to respond to
--   `fn` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)**       the middleware function to execute, the
-                                      fourth parameter will be the selected
-                                      version
-
-Returns **[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)** no return value
-
 ### rm
 
 Removes a route from the server.
 You pass in the route 'blob' you got from a mount call.
 
 **Parameters**
 
--   `route` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the route name.
+-   `routeName` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the route name.
 
 
 -   Throws **[TypeError](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError)** on bad input.
@@ -424,7 +404,6 @@ _Output:_
       input: '/',
       compiledRegex: /^[\/]*$/,
       compiledUrlParams: null,
-      versions: null,
       handlers: [Array]
      }
   ],
@@ -770,8 +749,8 @@ Type: ([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Glob
 **Properties**
 
 -   `name` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a name for the route
--   `path` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Regexp](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp))** a string or regex matching the route
--   `version` **([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)>)** versions supported by this route
+-   `path` **[String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** can be any String accepted by
+    [find-my-way](https://github.com/delvedor/find-my-way)
 
 **Examples**
 
@@ -781,10 +760,9 @@ server.get('/foo', function(req, res, next) {});
 // a parameterized route
 server.get('/foo/:bar', function(req, res, next) {});
 // a regular expression
-server.get(/^\/([a-zA-Z0-9_\.~-]+)\/(.*)/, function(req, res, next) {});
+server.get('/example/:file(^\\d+).png', function(req, res, next) {});
 // an options object
 server.get({
     path: '/foo',
-    version: ['1.0.0', '2.0.0']
 }, function(req, res, next) {});
 ```
diff --git a/test/plugins/dedupeSlashes.test.js b/test/plugins/dedupeSlashes.test.js
@@ -64,8 +64,7 @@ describe('dedupe forward slashes in URL', function() {
     });
 
     // eslint-disable-next-line
-    it('should remove duplicate slashes including trailing slashes',
-    function(done) {
+    it('should remove duplicate slashes including trailing slashes', function(done) {
         CLIENT.get('//foo//bar//', function(err, _, res, data) {
             assert.ifError(err);
             assert.equal(res.statusCode, 200);
