Get api routes from server:publicApi (#421)

Get API URLs list from the new `server:publicApi` route instead of the static routes file.  

If the protocol can not fetch the URLs from `server:publicApi`, there is some fallback:
 - if the route is not available for anonymous user: print warning message and use static routes
 - if the route does not exists (Kuzzle version < 1.9.0): get routes from `server:info`
    - if `server:info` is restricted: print warning message and use static routes

Author: Aschen

.travis.yml

@@ -82,7 +82,7 @@ jobs:
 
       before_script:
         - npm run doc-prepare
-        - npm run --prefix doc/framework clone-repos
+        - npm run --prefix doc/framework repositories -- clone
       script:
         - gem install typhoeus
         - HYDRA_MAX_CONCURRENCY=20 npm run --prefix doc/framework dead-links

doc/6/protocols/http/constructor/index.md

@@ -31,6 +31,20 @@ Http protocol connection options.
 | --------------- | -------------------------------- | ----------------------------------- |
 | `port`          | <pre>number</pre><br/>(`7512`)   | Kuzzle server port                  |
 | `sslConnection` | <pre>boolean</pre><br/>(`false`) | Use SSL to connect to Kuzzle server |
+| `customRoutes` | <pre>object</pre><br/>(`{}`) | Add custom routes <SinceBadge version="6.2.0"/> |
+
+**Note:**
+
+`customRoutes` are used to define plugins API routes or to overwrite existing API routes.  
+They must have the following format:
+```js
+{
+  'my-plugin/my-controller': {
+    action: { verb: 'GET', url: '/some/url' },
+    action2: { verb: 'GET', url: '/some/url/with/:parameter' }
+  }
+}
+```
 
 ## Return
 

doc/6/protocols/http/constructor/snippets/constructor.js

@@ -5,7 +5,15 @@ const
     Http
   } = require('kuzzle-sdk');
 
+const customRoutes = {
+  'nyc-open-data-plugin/driver': {
+    enroll: { verb: 'POST', url: '/_plugin/nyc-open-data-plugin/drivers' },
+    remove: { verb: 'DELETE', url: '/_plugin/nyc-open-data-plugin/drivers/:driverId' }
+  }
+};
+
 const options = {
+  customRoutes,
   sslConnection: false
 };
 

doc/6/protocols/http/introduction/index.md

@@ -10,8 +10,21 @@ order: 0
 
 The Http protocol can be used by an instance of the SDK to communicate with your Kuzzle server.
 
-:::info
+::: info
 This protocol does not allow to use the [real-time notifications](/sdk/js/6/essentials/realtime-notifications/).
 
 If you need real-time features, then you have to use either [WebSocket](/sdk/js/6/protocols/websocket) or [SocketIO](/sdk/js/6/protocols/socketio) protocols.
 :::
+
+## About HTTP routing
+
+<SinceBadge version="6.2.0"/>
+
+This protocol needs to build routes from the name of the controller and the action used. These routes are made available by Kuzzle via the [server:publicApi](/core/1/api/controllers/server/public-api) method or the [server:info](/core/1/api/controllers/server/info) method.  
+
+
+<SinceBadge version="Kuzzle 1.9.0"/>
+For confidentiality reasons, it is preferable to expose only the `server:publicApi` route to the anonymous user.  
+If this route is not available, the SDK will use the static definition of API routes that does not include routes developed in plugins.  
+
+Finally, it is also possible to manually define the routes to the actions of its plugins using the `customRoutes` option with the [Http protocol constructor](/sdk/js/6/protocols/http/constructor).

doc/6/protocols/http/properties/index.md

@@ -13,7 +13,8 @@ order: 10
 | -------------------- | -------- | ---------------------|
 | `connected`  | <pre>boolean</pre>  | Always returns `true` |
 | `host`  | <pre>string</pre>  | Kuzzle server host |
-| `http`  | <pre>object</pre>  | Returns a list of available routes |
+| `http`  | <pre>object</pre>  | Returns a list of available routes <DeprecatedBadge version="6.2.0"/> |
+| `routes`  | <pre>object</pre>  | Returns a list of available routes <SinceBadge version="6.2.0"/> |
 | `port`  | <pre>number</pre>  | Kuzzle server port |
 | `protocol`  | <pre>string</pre>  | `https` or `http` |
 | `ssl`  | <pre>boolean</pre>  | `true` if ssl is active |

doc/doc.sh

@@ -40,6 +40,11 @@ case $1 in
     ./framework/node_modules/.bin/vuepress build $DOC_VERSION/ $ARGS
   ;;
 
+  build-netlify)
+    export SITE_BASE="/"
+    ./framework/node_modules/.bin/vuepress build $DOC_VERSION/ $ARGS
+  ;;
+
   upload)
     aws s3 sync $DOC_VERSION/.vuepress/dist s3://$S3_BUCKET$SITE_BASE --delete
   ;;

features/features

@@ -1,9 +1,8 @@
 'use strict';
 
 const
-  KuzzleAbstractProtocol = require('./abstract/common'),
-  _routes = require('./routes.json');
-
+  staticHttpRoutes = require('./routes.json'),
+  KuzzleAbstractProtocol = require('./abstract/common');
 
 class HttpWrapper extends KuzzleAbstractProtocol {
   constructor(host, options = {}) {
@@ -13,20 +12,31 @@ class HttpWrapper extends KuzzleAbstractProtocol {
       throw new Error('host is required');
     }
 
-    // Application-side HTTP route overrides:
-    if (options.http && options.http.customRoutes) {
-      for (const controller in options.http.customRoutes) {
-        if (options.http.customRoutes.hasOwnProperty(controller)) {
-          this.http.routes[controller] = Object.assign(
-            this.http.routes[controller] || {},
-            options.http.customRoutes[controller]);
+    this._routes = {};
+
+    this.customRoutes = options.customRoutes || {};
+
+    for (const [controller, definition] of Object.entries(this.customRoutes)) {
+      for (const [action, route] of Object.entries(definition)) {
+        if (!(typeof route.url === 'string' && route.url.length > 0)) {
+          throw new Error(
+            `Incorrect URL for custom route ${controller}:${action}.`);
+        }
+        if (!(typeof route.verb === 'string' && route.verb.length > 0)) {
+          throw new Error(
+            `Incorrect VERB for custom route ${controller}:${action}.`);
         }
       }
     }
   }
 
+  // @deprecated
   get http () {
-    return _routes;
+    return this.routes;
+  }
+
+  get routes () {
+    return this._routes;
   }
 
   get protocol () {
@@ -38,15 +48,61 @@ class HttpWrapper extends KuzzleAbstractProtocol {
   }
 
   /**
-   * Connect to the websocket server
+   * Connect to the server
    */
   connect () {
     if (this.state === 'ready') {
       return Promise.resolve();
     }
 
-    return this._sendHttpRequest('GET', '/')
+    return this._sendHttpRequest('GET', '/_publicApi')
+      .then(({ result, error }) => {
+        if (! error) {
+          this._routes = this._constructRoutes(result);
+
+          return;
+        }
+
+        if (error.status === 401 || error.status === 403) {
+          this._warn('"server:publicApi" route is restricted for anonymous user.');
+          this._warn('This route is used by the HTTP protocol to build API URLs.');
+          this._warn('Fallback to static routes, some API routes may be unavailable as well as plugin custom routes');
+
+          // fallback to static http routes
+          this._routes = staticHttpRoutes;
+
+          return;
+        } else if (error.status === 404) {
+          // fallback to server:info route
+          // server:publicApi is only available since Kuzzle 1.9.0
+          return this._sendHttpRequest('GET', '/')
+            .then(({ result: res, error: err }) => {
+              if (! err) {
+                this._routes = this._constructRoutes(res.serverInfo.kuzzle.api.routes);
+                this._staticRoutes = false;
+
+                return;
+              }
+
+              if (err.status !== 401 && err.status !== 403) {
+                throw err;
+              }
+
+              this._warn('"server:info" route is restricted for anonymous user.');
+              this._warn('This route is used by the HTTP protocol to build API URLs.');
+              this._warn('If you want to expose your API routes without disclosing server information you can use "server:publicApi" (available in Kuzzle 1.9.0).');
+              this._warn('Fallback to static routes, some API routes may be unavailable as well as plugin custom routes');
+
+              // fallback to static http routes
+              this._routes = staticHttpRoutes;
+            });
+        }
+
+        throw error;
+      })
       .then(() => {
+        this._routes = Object.assign(this._routes, this.customRoutes);
+
         // Client is ready
         this.clientConnected();
       })
@@ -101,12 +157,15 @@ class HttpWrapper extends KuzzleAbstractProtocol {
       }
     }
 
-    const
-      route = this.http.routes[payload.controller] && this.http.routes[payload.controller][payload.action];
+    const route = this.routes[payload.controller]
+        && this.routes[payload.controller][payload.action];
 
-    if (route === undefined) {
-      const error = new Error(`No route found for ${payload.controller}/${payload.action}`);
+    if (! route) {
+      const error =
+        new Error(`No URL found for "${payload.controller}:${payload.action}".`);
       this.emit(payload.requestId, {status: 400, error});
+
+      return;
     }
 
     const
@@ -208,6 +267,65 @@ class HttpWrapper extends KuzzleAbstractProtocol {
     });
   }
 
+  _constructRoutes (publicApi) {
+    const apiRoutes = Object.entries(publicApi)
+      .reduce((routes, [controller, definition]) => {
+        routes[controller] = {};
+
+        for (const [action, { http }] of Object.entries(definition)) {
+          if (http && http.length === 1) {
+            routes[controller][action] = http[0];
+          } else if (http && http.length > 1) {
+            routes[controller][action] = getCorrectRoute(http);
+          }
+        }
+
+        return routes;
+      }, {});
+
+    for (const [controller, definition] of Object.entries(this.customRoutes)) {
+      apiRoutes[controller] = definition;
+    }
+
+    return apiRoutes;
+  }
+
+  _warn (message) {
+    console.warn(message); // eslint-disable-line no-console
+  }
+
+}
+
+function getCorrectRoute (routes) {
+  let
+    shortestRoute = routes[0],
+    postRoute,
+    minLength = routes[0].url.length,
+    sameLength = true;
+
+  for (const route of routes) {
+    if (route.url.length !== minLength) {
+      sameLength = false;
+    }
+
+    if (route.url.length < minLength) {
+      shortestRoute = route;
+      minLength = route.url.length;
+    }
+
+    if (route.verb === 'POST') {
+      postRoute = route;
+    }
+  }
+
+  if (sameLength) {
+    // with same URL size, we keep the POST route
+    return postRoute;
+  }
+
+  // with differents URL sizes, we keep the shortest because URL params
+  // will be in the query string
+  return shortestRoute;
 }
 
 module.exports = HttpWrapper;