kourou 0.22.0 → 0.23.0

package/README.md

@@ -26,7 +26,7 @@ $ npm install -g kourou
 $ kourou COMMAND
 running command...
 $ kourou (-v|--version|version)
-kourou/0.22.0 linux-x64 node-v16.15.0
+kourou/0.23.0 linux-x64 node-v14.18.2
 $ kourou --help [COMMAND]
 USAGE
   $ kourou COMMAND
@@ -129,6 +129,7 @@ All other arguments and options will be passed as-is to the `sdk:query` method.
 * [`kourou api-key:create USER`](#kourou-api-keycreate-user)
 * [`kourou api-key:delete USER ID`](#kourou-api-keydelete-user-id)
 * [`kourou api-key:search USER`](#kourou-api-keysearch-user)
+* [`kourou app:debug-proxy`](#kourou-appdebug-proxy)
 * [`kourou app:scaffold DESTINATION`](#kourou-appscaffold-destination)
 * [`kourou app:start-services`](#kourou-appstart-services)
 * [`kourou autocomplete [SHELL]`](#kourou-autocomplete-shell)
@@ -288,6 +289,41 @@ OPTIONS
 
 _See code: [src/commands/api-key/search.ts](src/commands/api-key/search.ts)_
 
+## `kourou app:debug-proxy`
+
+Create a Proxy Server that allows Chrome to debug Kuzzle remotely using the DebugController
+
+```
+USAGE
+  $ kourou app:debug-proxy
+
+OPTIONS
+  --api-key=api-key          Kuzzle user api-key
+  --as=as                    Impersonate a user
+  --forwardPort=forwardPort  [default: 9222] Port of the forwarding server
+  --help                     show CLI help
+  --host=host                [default: localhost] Kuzzle server host
+
+  --nonoAutoEnableDebugger   True if Kourou should not enable and disable the Debugger automatically before and after
+                             usage
+
+  --password=password        Kuzzle user password
+
+  --port=port                [default: 7512] Kuzzle server port
+
+  --protocol=protocol        [default: ws] Kuzzle protocol (http or ws)
+
+  --showDebuggerEvents       Verbose mode to display events sent to the Chrome Debugger
+
+  --showDebuggerPayloads     Verbose mode to display payloads sent by and to the Chrome Debugger
+
+  --ssl                      Use SSL to connect to Kuzzle
+
+  --username=username        [default: anonymous] Kuzzle username (local strategy)
+```
+
+_See code: [src/commands/app/debug-proxy.ts](src/commands/app/debug-proxy.ts)_
+
 ## `kourou app:scaffold DESTINATION`
 
 Scaffolds a new Kuzzle application
@@ -342,7 +378,7 @@ EXAMPLES
   $ kourou autocomplete --refresh-cache
 ```
 
-_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v1.2.0/src/commands/autocomplete/index.ts)_
+_See code: [@oclif/plugin-autocomplete](https://github.com/oclif/plugin-autocomplete/blob/v1.3.0/src/commands/autocomplete/index.ts)_
 
 ## `kourou collection:create INDEX COLLECTION [BODY]`
 

package/lib/commands/app/debug-proxy.d.ts

@@ -0,0 +1,24 @@
+import { flags } from '@oclif/command';
+import { Kommand } from '../../common';
+export default class DebugProxy extends Kommand {
+    static description: string;
+    static flags: {
+        host: flags.IOptionFlag<string>;
+        port: flags.IOptionFlag<string>;
+        ssl: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        username: flags.IOptionFlag<string>;
+        password: flags.IOptionFlag<string | undefined>;
+        protocol: flags.IOptionFlag<string>;
+        as: flags.IOptionFlag<string | undefined>;
+        'api-key': flags.IOptionFlag<string | undefined>;
+        help: import("@oclif/parser/lib/flags").IBooleanFlag<void>;
+        forwardPort: import("@oclif/parser/lib/flags").IOptionFlag<number>;
+        nonoAutoEnableDebugger: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        showDebuggerEvents: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+        showDebuggerPayloads: import("@oclif/parser/lib/flags").IBooleanFlag<boolean>;
+    };
+    static sdkOptions: {
+        protocol: string;
+    };
+    runSafe(): Promise<void>;
+}

package/lib/commands/app/debug-proxy.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const command_1 = require("@oclif/command");
+const common_1 = require("../../common");
+const kuzzle_1 = require("../../support/kuzzle");
+const http_1 = tslib_1.__importDefault(require("http"));
+const ws_1 = tslib_1.__importDefault(require("ws"));
+// Add the proper headers and send the body in the response
+function sendResponse(response, bodyObject) {
+    response.setHeader('Content-Type', 'application/json; charset=UTF-8');
+    response.setHeader('Cache-Control', 'no-cache');
+    const body = JSON.stringify(bodyObject);
+    response.setHeader('Content-Length', Buffer.byteLength(body));
+    response.writeHead(200);
+    response.end(body);
+}
+class DebugProxy extends common_1.Kommand {
+    async runSafe() {
+        const nodeVersionResponse = await this.sdk.query({
+            controller: 'debug',
+            action: 'nodeVersion'
+        });
+        this.logInfo(`Connected to Kuzzle node: ${nodeVersionResponse.node}`);
+        /**
+         * To allow the Chrome Debugger to see the proxy server we must implement the following routes:
+         * - /json/version
+         * - /json
+         */
+        const server = http_1.default.createServer((request, response) => {
+            if (request.url === '/json/version') {
+                sendResponse(response, {
+                    Browser: `node.js/${nodeVersionResponse.result}`,
+                    "Protocol-Version": "1.1"
+                });
+                return;
+            }
+            else if (request.url === '/json') {
+                // Here we send a bunch of information about the Remote Target to the Chrome Debugger
+                // Those are the informations that the Chrome Debugger uses to know how to connect to Remote Target
+                // We give the Chrome Inspector our own Websocket endpoint so that it can connect to our proxy server
+                sendResponse(response, [{
+                        description: 'node.js instance',
+                        devtoolsFrontendUrl: `devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=${request.headers.host}/kuzzle-debugger`,
+                        devtoolsFrontendUrlCompat: `devtools://devtools/bundled/inspector.html?experiments=true&v8only=true&ws=${request.headers.host}/kuzzle-debugger`,
+                        faviconUrl: 'https://nodejs.org/static/images/favicons/favicon.ico',
+                        id: 'kuzzle-debugger',
+                        title: `Kuzzle Debugger - ${this.flags.host}:${this.flags.port}`,
+                        type: 'node',
+                        webSocketDebuggerUrl: `ws://${request.headers.host}/kuzzle-debugger`
+                    }]);
+                return;
+            }
+            response.writeHead(404);
+        });
+        const closeServer = async () => {
+            this.logInfo('Connection closed.');
+            if (!this.flags.noAutoEnableDebugger) {
+                await this.sdk.query({
+                    controller: 'debug',
+                    action: 'disable'
+                });
+            }
+            this.sdk.disconnect();
+            server.close();
+        };
+        const wss = new ws_1.default.Server({
+            server
+        });
+        if (!this.flags.noAutoEnableDebugger) {
+            await this.sdk.query({
+                controller: 'debug',
+                action: 'enable'
+            });
+        }
+        // Listen to all events emitted by the Debug Controller
+        await this.sdk.query({
+            controller: 'debug',
+            action: 'addListener',
+            body: {
+                event: '*'
+            }
+        });
+        wss.on('connection', ws => {
+            this.logInfo('Connection established.');
+            /**
+             * Listen to the room were events from the DebugController are sent
+             * and only forward events from the Chrome  Devtools Protocol
+             */
+            this.sdk.sdk.protocol.on('kuzzle-debugger-event', (payload) => {
+                if (!payload.event || payload.event.startsWith('Kuzzle')) {
+                    return;
+                }
+                if (this.flags.showDebuggerEvents) {
+                    this.logInfo(JSON.stringify(payload.result, null, 2));
+                }
+                ws.send(JSON.stringify(payload.result));
+            });
+            // When receiving message from Chrome Devtools Protocol, we forward it to the DebugController
+            ws.on('message', async (message) => {
+                try {
+                    const json = JSON.parse(message.toString());
+                    if (json.id === undefined || json.method === undefined) {
+                        return;
+                    }
+                    if (this.flags.showDebuggerPayloads) {
+                        this.logInfo(JSON.stringify({
+                            method: json.method,
+                            params: json.params,
+                        }, null, 2));
+                    }
+                    const response = await this.sdk.query({
+                        controller: 'debug',
+                        action: 'post',
+                        body: {
+                            method: json.method,
+                            params: json.params,
+                        }
+                    });
+                    if (this.flags.showDebuggerPayloads) {
+                        this.logInfo(JSON.stringify({
+                            id: json.id,
+                            result: response.result
+                        }, null, 2));
+                    }
+                    // Send back the response using the same ID received
+                    ws.send(JSON.stringify({
+                        id: json.id,
+                        result: response.result
+                    }));
+                }
+                catch (e) {
+                    this.logKo(`${e}`);
+                }
+            });
+            ws.on('close', closeServer);
+        });
+        server.on('error', async (err) => {
+            this.logKo(err.message);
+            this.logKo(err.stack);
+            await closeServer();
+        });
+        server.listen(this.flags.forwardPort, () => {
+            this.logOk(`Listening on port ${this.flags.forwardPort}, forwarding to Kuzzle at ${this.flags.host}:${this.flags.port}`);
+            this.logInfo(`Showing to Chrome Debugger as "Kuzzle Debugger - ${this.flags.host}:${this.flags.port}"`);
+            this.logInfo('Waiting for Chrome Debugger to connect...');
+        });
+        let resolve;
+        const promise = new Promise(res => {
+            resolve = res;
+        });
+        server.on('close', () => {
+            resolve();
+        });
+        await promise;
+    }
+}
+exports.default = DebugProxy;
+DebugProxy.description = 'Create a Proxy Server that allows Chrome to debug Kuzzle remotely using the DebugController';
+DebugProxy.flags = Object.assign({ help: command_1.flags.help(), forwardPort: command_1.flags.integer({
+        description: 'Port of the forwarding server',
+        default: 9222
+    }), nonoAutoEnableDebugger: command_1.flags.boolean({
+        description: 'True if Kourou should not enable and disable the Debugger automatically before and after usage',
+        default: true
+    }), showDebuggerEvents: command_1.flags.boolean({
+        description: 'Verbose mode to display events sent to the Chrome Debugger',
+        default: false,
+    }), showDebuggerPayloads: command_1.flags.boolean({
+        description: 'Verbose mode to display payloads sent by and to the Chrome Debugger',
+        default: false,
+    }) }, kuzzle_1.kuzzleFlags);
+// Force the usage of Websocket otherwise each request might end up executed on a different Kuzzle Node
+DebugProxy.sdkOptions = {
+    protocol: 'ws'
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kourou",
   "description": "The CLI that helps you manage your Kuzzle instances",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "author": "The Kuzzle Team <support@kuzzle.io>",
   "bin": {
     "kourou": "./bin/run"
@@ -43,7 +43,8 @@
     "production": "0.0.2",
     "strip-json-comments": "^3.1.1",
     "tmp": "^0.2.1",
-    "tslib": "^2.3.1"
+    "tslib": "^2.3.1",
+    "ws": "^8.8.0"
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.1",
@@ -56,6 +57,7 @@
     "@types/node": "^14.14.41",
     "@types/node-emoji": "^1.8.1",
     "@types/node-fetch": "^2.6.1",
+    "@types/ws": "^8.5.3",
     "@typescript-eslint/eslint-plugin": "^4.22.0",
     "@typescript-eslint/parser": "^4.22.0",
     "chai": "^4.3.4",