configurapi-runner-ws 1.14.0 → 1.16.0

package/README.md

@@ -1,14 +1,264 @@
 # configurapi-runner-ws
 
-- Use `Event` for an incoming data.
-- User `Response` for a regular response data.
-- Use `StreamResponse` from `configurapi-handler-ws` for a stream response.
-  - With a stream response, data will be delivered from the server in chunks.
-    - A check will have `x-stream: chunk` header.
-    - The last chunk will have `x-stream: done` header.
-    - Check `x-stream-id: $id` header for the stream ID. A chunk belonging to the same stream will have the same stream ID.  
-- connectionId is available at `event.request.headers.connectionId`
-- `on_connect` and `on_disconnect` will be called when a new connection is made or closed.
-- Use `Request.headers['push-function']` to send an out-of-band message.  The function is async and accepts an object to send back to the caller.
-- Use `on_connect` to perform authorization.
-- `Sec-WebSocket-Protocol` is automatically returned for `on_connect` events.  
+This runner allows you to run **Configurapi** locally using a native
+Node.js WebSocket server.
+
+It mirrors the behavior of `configurapi-runner-lambda-ws`, but runs
+entirely on your local machine (or any Node.js host) without AWS.
+
+------------------------------------------------------------------------
+
+## Overview
+
+-   Use `Event` for incoming WebSocket messages.
+-   Use `Response` for regular response data.
+-   Use `StreamResponse` (from `configurapi-handler-ws`) for streaming
+    responses.
+-   Includes an optional HTTP management server.
+
+------------------------------------------------------------------------
+
+## Running Locally
+
+Example:
+
+``` js
+const HttpRunner = require('configurapi-runner-ws');
+
+const runner = new HttpRunner();
+
+runner.run({
+  port: 8000,
+  configPath: './config.yaml'
+});
+```
+
+Default ports:
+
+-   HTTP: `8000`
+-   HTTPS: `8443` (if `key` and `cert` provided)
+-   Management server: `9100`
+
+------------------------------------------------------------------------
+
+## Streaming Responses
+
+When returning a `StreamResponse`:
+
+-   Data is delivered in chunks.
+
+-   Each chunk includes:
+
+        x-stream: chunk
+
+-   The final frame includes:
+
+        x-stream: done
+
+-   Each stream includes:
+
+        x-stream-id: <id>
+
+All chunks belonging to the same stream share the same `x-stream-id`.
+
+The local runner supports backpressure handling using
+`ws.bufferedAmount`.
+
+------------------------------------------------------------------------
+
+## Connection Lifecycle
+
+### on_connect
+
+Triggered when a new WebSocket connection is established.
+
+Use this event for:
+
+-   Authentication
+-   Authorization
+-   Protocol negotiation
+
+If `on_connect` returns:
+
+    statusCode >= 400
+
+the connection is closed with:
+
+    1008 (Policy Violation)
+
+Example:
+
+``` js
+if (response.statusCode >= 400) {
+  ws.close(1008, 'Policy Violation');
+}
+```
+
+`Sec-WebSocket-Protocol` is automatically echoed back during
+`on_connect`.
+
+------------------------------------------------------------------------
+
+### on_disconnect
+
+Triggered when a WebSocket connection closes.
+
+Use this for:
+
+-   Cleanup
+-   Resource release
+-   Logging
+
+------------------------------------------------------------------------
+
+## Request Object Details
+
+Inside your Configurapi handler:
+
+-   `event.request.headers['connection-id']`
+    -   Generated UUID for each WebSocket connection
+-   `event.request.headers['push-function']`
+    -   Async function to send an out-of-band message to the same client
+
+Example:
+
+``` js
+await event.request.headers['push-function'](
+  new Response({ hello: "world" }, 200)
+);
+```
+
+-   `event.request.params`
+    -   Available if provided in the client message
+-   `event.request.query`
+    -   Comes from the WebSocket message body
+-   `event.request.payload`
+    -   Only set if `payload` exists in the client message
+
+If invalid JSON is received, the raw message is placed in `payload`.
+
+------------------------------------------------------------------------
+
+## Message Format Example
+
+Client sends:
+
+``` json
+{
+  "name": "getData",
+  "params": { "id": 123 },
+  "payload": { "foo": "bar" },
+  "headers": {
+    "message-id": "abc-123"
+  }
+}
+```
+
+The runner:
+
+-   Creates a `Configurapi.Event`
+-   Routes to event `getData`
+-   Echoes `message-id` in the response
+
+------------------------------------------------------------------------
+
+## Management Server
+
+A management HTTP server runs on port `9100` by default. The postback URL can be found from `event.request.headers['postback-url']`.
+
+Built-in internal routes:
+
+-   `list_@connections`
+    -   Returns active WebSocket connection IDs
+-   `post_@connection`
+    -   Sends a message to a specific connection
+
+Example:
+
+``` bash
+curl http://localhost:9100/list_@connections
+```
+
+Post back to connection:
+
+``` bash
+curl -X POST http://localhost:9100/post_@connection?id=<connectionId>
+```
+
+------------------------------------------------------------------------
+
+## Using wsPostbackFunction
+
+You can also use `wsPostbackFunction` directly when communicating through the local HTTP management bridge.
+
+The postback URL can be found from `event.request.headers['postback-url']`.
+
+### Import:
+
+```
+const { wsPostbackFunction } = require('configurapi-runner-ws');
+```
+
+### Example:
+
+```
+await wsPostbackFunction(
+  `http://localhost:9100/@connections/${connectionId}`,
+  {
+    statusCode: 200,
+    headers: { 'message-id': '123' },
+    body: { message: 'Hello' }
+  }
+);
+```
+
+## Error Handling
+
+-   `SyntaxError` → 400
+-   All other errors → 500
+-   `message-id` header is preserved in error responses
+
+------------------------------------------------------------------------
+
+## HTTPS Support
+
+If `key` and `cert` are provided:
+
+``` js
+runner.run({
+  sPort: 8443,
+  key: fs.readFileSync('./server.key'),
+  cert: fs.readFileSync('./server.cert')
+});
+```
+
+the server runs securely over HTTPS + WSS.
+
+------------------------------------------------------------------------
+
+## Transport Differences from Lambda Runner
+
+  -----------------------------------------------------------------------
+  Local Runner                        Lambda Runner
+  ----------------------------------- -----------------------------------
+  Uses native WebSocket               Uses API Gateway WebSocket
+
+  Close with `1008` for connect       Return HTTP 4xx/5xx from `$connect`
+  rejection                           
+
+  Backpressure via                    Frame queue with retry logic
+  `ws.bufferedAmount`                 
+
+  Direct `ws.send()`                  API Gateway `postToConnection()`
+  -----------------------------------------------------------------------
+
+Functionally, both runners behave the same at the Configurapi level.
+
+------------------------------------------------------------------------
+
+## Best Practices
+
+-   Use `on_connect` for authentication.
+-   Always include `name` in client messages.
+-   Use `StreamResponse` for progressive or large responses.
+-   Monitor active connections via the management server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configurapi-runner-ws",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "Websocket runner for configurapi.",
   "bin": {
     "configurapi-runner-ws": "src/app.mjs"

package/src/index.js

@@ -139,6 +139,12 @@ module.exports = class HttpRunner extends events.EventEmitter
 
             this.emit(LogLevel.Trace, `[connect] ${connectionId}`);
           
+            const protocol = req.headers['x-forwarded-proto'] || (req.socket.encrypted ? 'https' : 'http');
+            const host = req.headers.host;
+            const path = req.url.split('?')[0];
+            
+            ws.postbackUrl = `${protocol}://${host}${path}/@connections/${connectionId}`;
+
             ws.on("message", async (data) => 
             {
                 const incomingMessage = typeof data === "string" ? data : data.toString("utf8");
@@ -360,3 +366,5 @@ module.exports = class HttpRunner extends events.EventEmitter
         });
     }
 };
+
+Object.assign(module.exports, require('./wsPostbackFunction'));

package/src/wsAdapter.js

@@ -199,7 +199,7 @@ module.exports = {
             }
             catch(e)
             {
-                throw new SyntaxError(`Invalid JSON payload: '${incomingMessage}'`);
+                data.payload = incomingMessage;
             }
         }
 
@@ -207,20 +207,18 @@ module.exports = {
 
         request.method = '';
         request.headers = {};
-        request.name =  data.name || undefined;
+        request.name =  data.name || data?.action || undefined;
         request.query = data.query || {};
         request.params = data.params || {};
         request.payload = data.payload || undefined;
         
-        if(data.headers)
+        for (const key of Object.keys(data.headers || {})) 
         {
-            for(let key of Object.keys(data.headers))
-            {
-                request.headers[key.toLowerCase()] = data.headers[key];
-            }
+            request.headers[key.toLowerCase()] = data.headers[key];
         }
 
         request.headers['connection-id'] = ws.connectionId;
+        request.headers['postback-url'] = ws.postbackUrl;
         request.headers['push-function'] = async (data)=>await this.write(ws, data);
         
         request.headers['sec-websocket-protocol'] = ws.protocol

package/src/wsPostbackFunction.js

@@ -0,0 +1,36 @@
+const ErrorResponse = require('configurapi').ErrorResponse;
+
+async function wsPostbackFunction(endpoint, response) 
+{
+    let message = response;
+
+    if(message?.statusCode && message?.headers)
+    {
+        message = message.body;
+    }
+
+    let resp = await fetch(endpoint, {
+        method: 'POST',
+        headers: response.headers || {},
+        body: typeof message === 'object' ? JSON.stringify(message) : message
+    });
+
+    if(resp.status >= 400) 
+    {
+        const contentType = resp.headers.get("content-type") || "";
+        let errorBody = undefined;
+    
+        try 
+        {
+            errorBody = contentType.includes("application/json") ? await resp.json() : await resp.text();
+        } 
+        catch(e)
+        {
+            errorBody = await resp.text().catch(() => undefined);
+        }
+    
+        throw new ErrorResponse(errorBody, resp.status);
+    }
+}
+
+module.exports = { wsPostbackFunction };