feat(rest): switch to trie based routing

- validate and normalize paths for openapi
- add benchmark for routing
- make the router pluggable
- simplify app routing to plain functions
- optimize simple route mapping and use regexp as default
- add `rest.router` binding to allow customization
- add docs for routing requests

benchmark/README.md

@@ -12,17 +12,17 @@ _Average number of requests handled every second._
 
 | scenario          |  rps |
 | ----------------- | ---: |
-| find all todos    | 4569 |
-| create a new todo |  348 |
+| find all todos    | 6230 |
+| create a new todo |  377 |
 
 ### Latency
 
 _Average time to handle a request in milliseconds._
 
 | scenario          | latency |
 | ----------------- | ------: |
-| find all todos    |    1.68 |
-| create a new todo |   28.27 |
+| find all todos    |    1.11 |
+| create a new todo |   26.03 |
 
 ## Basic use
 

benchmark/package.json

@@ -18,6 +18,7 @@
     "pretest": "npm run clean && npm run build",
     "test": "lb-mocha \"dist/test\"",
     "prestart": "npm run build",
+    "benchmark:routing": "node ./dist/src/rest-routing/routing-table",
     "start": "node ."
   },
   "repository": {
@@ -35,13 +36,16 @@
   ],
   "dependencies": {
     "@loopback/example-todo": "^0.21.2",
+    "@loopback/openapi-spec-builder": "^0.9.5",
+    "@loopback/rest": "^0.25.4",
     "@types/byline": "^4.2.31",
-    "@types/debug": "0.0.30",
+    "@types/debug": "0.0.31",
     "@types/p-event": "^1.3.0",
     "@types/request-promise-native": "^1.0.15",
     "autocannon": "^3.0.0",
     "byline": "^5.0.0",
     "debug": "^4.0.1",
+    "path-to-regexp": "^2.4.0",
     "request": "^2.88.0",
     "request-promise-native": "^1.0.5"
   },

benchmark/src/rest-routing/README.md

@@ -0,0 +1,39 @@
+# REST routing benchmark
+
+This directory contains a simple benchmarking to measure the performance of two
+router implementations for REST APIs. See
+https://loopback.io/doc/en/lb4/Routing-requests.html for more information.
+
+- [TrieRouter](https://github.com/strongloop/loopback-next/tree/master/packages/rest/src/router/trie-router.ts)
+- [RegExpRouter](https://github.com/strongloop/loopback-next/tree/master/packages/rest/src/router/regexp-router.ts)
+
+## Basic use
+
+```sh
+npm run -s benchmark:routing // default to 1000 routes
+npm run -s benchmark:routing -- <number-of-routes>
+```
+
+## Base lines
+
+```
+name                 duration    count    found   missed
+TrieRouter          0,1453883       10        8        2
+RegExpRouter        0,1220030       10        8        2
+
+name                 duration    count    found   missed
+TrieRouter          0,2109957       40       35        5
+RegExpRouter        0,8762936       40       35        5
+
+name                 duration    count    found   missed
+TrieRouter          0,4895252      160      140       20
+RegExpRouter       0,52156699      160      140       20
+
+name                 duration    count    found   missed
+TrieRouter         0,16065852      640      560       80
+RegExpRouter      0,304921026      640      560       80
+
+name                 duration    count    found   missed
+TrieRouter         0,60165877     2560     2240      320
+RegExpRouter      4,592089555     2560     2240      320
+```

benchmark/src/rest-routing/routing-table.ts

@@ -0,0 +1,111 @@
+// Copyright IBM Corp. 2017,2018. All Rights Reserved.
+// Node module: @loopback/rest
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {anOpenApiSpec} from '@loopback/openapi-spec-builder';
+import {
+  RoutingTable,
+  TrieRouter,
+  RestRouter,
+  RegExpRouter,
+  OpenApiSpec,
+} from '@loopback/rest';
+
+function runBenchmark(count = 1000) {
+  const spec = givenNumberOfRoutes('/hello', count);
+
+  const trieTest = givenRouter(new TrieRouter(), spec, count);
+  const regexpTest = givenRouter(new RegExpRouter(), spec, count);
+
+  const result1 = trieTest();
+  const result2 = regexpTest();
+
+  console.log(
+    '%s %s %s %s %s',
+    'name'.padEnd(12),
+    'duration'.padStart(16),
+    'count'.padStart(8),
+    'found'.padStart(8),
+    'missed'.padStart(8),
+  );
+  for (const r of [result1, result2]) {
+    console.log(
+      '%s %s %s %s %s',
+      `${r.name}`.padEnd(12),
+      `${r.duration}`.padStart(16),
+      `${r.count}`.padStart(8),
+      `${r.found}`.padStart(8),
+      `${r.missed}`.padStart(8),
+    );
+  }
+}
+
+function givenNumberOfRoutes(base: string, num: number) {
+  const spec = anOpenApiSpec();
+  let i = 0;
+  while (i < num) {
+    // Add 1/4 paths with vars
+    if (i % 4 === 0) {
+      spec.withOperationReturningString(
+        'get',
+        `${base}/group${i}/{version}`,
+        `greet${i}`,
+      );
+    } else {
+      spec.withOperationReturningString(
+        'get',
+        `${base}/group${i}/version_${i}`,
+        `greet${i}`,
+      );
+    }
+    i++;
+  }
+  const result = spec.build();
+  result.basePath = '/my';
+  return result;
+}
+
+function givenRouter(router: RestRouter, spec: OpenApiSpec, count: number) {
+  const name = router.constructor.name;
+  class TestController {}
+
+  return (log?: (...args: unknown[]) => void) => {
+    log = log || (() => {});
+    log('Creating %s, %d', name, count);
+    let start = process.hrtime();
+
+    const table = new RoutingTable(router);
+    table.registerController(spec, TestController);
+    router.list(); // Force sorting
+    log('Created %s %s', name, process.hrtime(start));
+
+    log('Starting %s %d', name, count);
+    let found = 0,
+      missed = 0;
+    start = process.hrtime();
+    for (let i = 0; i < count; i++) {
+      let group = `group${i}`;
+      if (i % 8 === 0) {
+        // Make it not found
+        group = 'groupX';
+      }
+      // tslint:disable-next-line:no-any
+      const request: any = {
+        method: 'get',
+        path: `/my/hello/${group}/version_${i}`,
+      };
+
+      try {
+        table.find(request);
+        found++;
+      } catch (e) {
+        missed++;
+      }
+    }
+    log('Done %s', name);
+    return {name, duration: process.hrtime(start), count, found, missed};
+  };
+}
+
+runBenchmark(+process.argv[2] || 1000);

docs/site/Routes.md

@@ -130,8 +130,7 @@ function greet(name: string) {
 }
 
 const app = new RestApplication();
-const route = new Route('get', '/', spec, greet);
-app.route(route); // attaches route to RestServer
+app.route('get', '/', spec, greet); // attaches route to RestServer
 
 app.start();
 ```

docs/site/Routing-requests.md

@@ -0,0 +1,92 @@
+---
+lang: en
+title: 'Routing requests'
+keywords: LoopBack 4.0, LoopBack 4
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/Routing-requests.html
+---
+
+## Routing Requests
+
+This is an action in the default HTTP sequence. Its responsibility is to find a
+route that can handle a given http request. By default, the `FindRoute` action
+uses the `RoutingTable` from `@loopback/rest` to match requests against
+registered routes including controller methods using `request.method` and
+`request.path`. For example:
+
+- GET /orders => OrderController.getOrders (`@get('/orders')`)
+- GET /orders/123 => OrderController.getOrderById (`@get('/orders/{id}')`)
+- GET /orders/count => OrderController.getOrderCount (`@get('/orders/count')`)
+- POST /orders => OrderController.createOrder (`@post('/orders')`)
+
+## Customize the `FindRoute` action
+
+The `FindRoute` action is bound to `SequenceActions.FIND_ROUTE`
+('rest.sequence.actions.findRoute') and injected into the default sequence.
+
+To create your own `FindRoute` action, bind your implementation as follows:
+
+```ts
+const yourFindRoute: FindRoute = ...;
+app.bind(SequenceActions.FIND_ROUTE).to(yourFindRoute);
+```
+
+## Customize the REST Router
+
+Instead of rewriting `FindRoute` action completely, LoopBack 4 also allows you
+to simply replace the `RestRouter` implementation.
+
+The `@loopback/rest` module ships two built-in routers:
+
+- TrieRouter: it keeps routes as a `trie` tree and uses traversal to match
+  `request` to routes based on the hierarchy of the path
+- RegExpRouter: it keeps routes as an array and uses `path-to-regexp` to match
+  `request` to routes based on the path pattern
+
+For both routers, routes without variables are optimized in a map so that any
+requests matching to a fixed path can be resolved quickly.
+
+By default, `@loopback/rest` uses `TrieRouter` as it performs better than
+`RegExpRouter`. There is a simple benchmarking for `RegExpRouter` and
+`TrieRouter` at
+https://githhub.com/strongloop/loopback-next/benchmark/src/rest-routing/routing-table.ts.
+
+To change the router for REST routing, we can bind the router class as follows:
+
+```ts
+import {RestBindings, RegExpRouter} from '@loopback/rest';
+app.bind(RestBindings.ROUTER).toClass(RegExpRouter);
+```
+
+It's also possible to have your own implementation of `RestRouter` interface
+below:
+
+```ts
+/**
+ * Interface for router implementation
+ */
+export interface RestRouter {
+  /**
+   * Add a route to the router
+   * @param route A route entry
+   */
+  add(route: RouteEntry): boolean;
+
+  /**
+   * Find a matching route for the given http request
+   * @param request Http request
+   * @returns The resolved route, if not found, `undefined` is returned
+   */
+  find(request: Request): ResolvedRoute | undefined;
+
+  /**
+   * List all routes
+   */
+  list(): RouteEntry[];
+}
+```
+
+See examples at:
+
+- [TrieRouter](https://github.com/strongloop/loopback-next/tree/master/packages/rest/src/router/trie-router.ts)
+- [RegExpRouter](https://github.com/strongloop/loopback-next/tree/master/packages/rest/src/router/regexp-router.ts)

docs/site/sidebars/lb4_sidebar.yml

@@ -140,6 +140,10 @@ children:
     output: 'web, pdf'
     children:
 
+    - title: 'Routing requests'
+      url: Routing-requests.html
+      output: 'web, pdf'
+
     - title: 'Parsing requests'
       url: Parsing-requests.html
       output: 'web, pdf'

packages/rest/src/http-handler.ts

@@ -21,12 +21,14 @@ import {RestBindings} from './keys';
 import {RequestContext} from './request-context';
 
 export class HttpHandler {
-  protected _routes: RoutingTable = new RoutingTable();
   protected _apiDefinitions: SchemasObject;
 
   public handleRequest: (request: Request, response: Response) => Promise<void>;
 
-  constructor(protected _rootContext: Context) {
+  constructor(
+    protected _rootContext: Context,
+    protected _routes = new RoutingTable(),
+  ) {
     this.handleRequest = (req, res) => this._handleRequest(req, res);
   }
 

packages/rest/src/index.ts

@@ -3,20 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-export {
-  RouteEntry,
-  RoutingTable,
-  Route,
-  ControllerRoute,
-  ResolvedRoute,
-  createResolvedRoute,
-  ControllerClass,
-  ControllerInstance,
-  ControllerFactory,
-  createControllerFactoryForBinding,
-  createControllerFactoryForClass,
-  createControllerFactoryForInstance,
-} from './router/routing-table';
+export * from './router';
 
 export * from './providers';
 

packages/rest/src/keys.ts

@@ -30,6 +30,7 @@ import {
 import {HttpProtocol} from '@loopback/http-server';
 import * as https from 'https';
 import {ErrorWriterOptions} from 'strong-error-handler';
+import {RestRouter} from './router';
 
 /**
  * RestServer-specific bindings
@@ -65,6 +66,12 @@ export namespace RestBindings {
    * Internal binding key for http-handler
    */
   export const HANDLER = BindingKey.create<HttpHandler>('rest.handler');
+
+  /**
+   * Internal binding key for rest router
+   */
+  export const ROUTER = BindingKey.create<RestRouter>('rest.router');
+
   /**
    * Binding key for setting and injecting Reject action's error handling
    * options.