mongo-realtime 3.0.0 → 3.0.1

package/README.md

@@ -219,16 +219,16 @@ or:
 
 ### Server internal events
 
-The server emit internal events that can be listened inside the backend code using `server.on('MY_INTERNAL_EVENT', handler)`.\
+The server emit internal events that can be listened inside the backend code using `server.on('MY_INTERNAL_EVENT', handler)`. Registring the same event will override the previous handler.\
 `MY_INTERNAL_EVENT` follows these patterns:
 
 - `db:OPERATION_TYPE` : For any operation type on any collection
 - `db:OPERATION_TYPE:COLLECTION_NAME` : For a specific operation type on a specific collection
 - `db:OPERATION_TYPE:COLLECTION_NAME:DOCUMENT_ID` : For a specific operation type on a specific document
 
-`OPERATION_TYPE` can be `insert`, `update`, `delete` or `change` (matches all).\
-`COLLECTION_NAME` is the name of the collection, e.g. `users`.\
-`DOCUMENT_ID` is the string representation of the document's `_id`, e.g. `507f1f77bcf86cd799439011`.
+**`OPERATION_TYPE`** can be `insert`, `update`, `delete` or `change` (matches all).\
+**`COLLECTION_NAME`** is the name of the collection, e.g. `users`.\
+**`DOCUMENT_ID`** is the string representation of the document's `_id`, e.g. `507f1f77bcf86cd799439011`.
 
 Example:
 
@@ -244,6 +244,26 @@ server.on("db:update:orders:507f1f77bcf86cd799439011", (change) => {
 });
 ```
 
+It can also be listened inside the client on the event `realtime:db:change`.
+
+```js
+/* Client-side
+Receives this object
+{
+  operationType: 'insert' | 'update' | 'delete',
+  collection: 'users',
+  docId: '507f1f77bcf86cd799439011',
+  fullDocument: { ... }, // for insert and update
+}*/
+
+socket.addEventListener("message", (event) => {
+  const message = JSON.parse(event.data);
+  if (message.type === "realtime:db:change") {
+    console.log("Database change:", message);
+  }
+});
+```
+
 ### Error responses
 
 If a request fails, the server sends:
@@ -306,16 +326,20 @@ Returns a MongoDB collection handle for direct access.
 
 ## Authentication
 
-Provide an `authenticate` function to validate WebSocket connections. The incoming payload is read from the `auth` request header and parsed as JSON when possible.
+Provide an `authenticate` function to validate WebSocket connections. The incoming payload is read from the `auth` request header and parsed as JSON when possible. If the `auth` header is missing, the server falls back to the `token` query parameter from the WebSocket URL.
 
 Example:
 
 ```js
 const server = new MongoRealTimeServer({
-  authenticate: async (authData) => {
-    // Perform your authentication logic here, e.g. check a token or session.
-    // In this example, we simply check if the authData matches a hardcoded token.
-    return authData === "my-auth-token";
+  authenticate: async (authData, request) => {
+    // `authData` is the parsed `auth` header when present,
+    // otherwise it falls back to the `token` query parameter.
+    const token = new URL(
+      request.url,
+      "http://localhost:3000",
+    ).searchParams.get("token");
+    return authData?.session === "ok" || token === "my-auth-token";
   },
 });
 ```

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "mongo-realtime",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "main": "src/index.js",
-  "scripts": {},
   "exports": {
     ".": "./src/index.js"
   },
@@ -35,5 +34,6 @@
     "dotenv": "^17.4.2",
     "mongodb": "^7.2.0",
     "ws": "^8.20.0"
-  }
+  },
+  "scripts": {}
 }

package/src/server.js

@@ -13,7 +13,6 @@ const {
   isPlainObject,
   matchesFilter,
 } = require("./query");
-const Stream = require("node:stream");
 
 /**
  * MongoRealTime WebSocket server backed by MongoDB.
@@ -46,7 +45,7 @@ class MongoRealTimeServer {
    * @param {string} [options.mongoUri] MongoDB connection URI.
    * @param {string} [options.dbName] MongoDB database name.
    * @param {number} [options.cacheTtlMs] Cache TTL in milliseconds.
-   * @param {(authData:any)=>Promise<boolean>} [options.authenticate] Cache TTL in milliseconds.
+   * @param {(authData:any, request: import('node:http').IncomingMessage)=>boolean|Promise<boolean>} [options.authenticate] Optional connection authenticator.
    * @param {import('node:http').Server} [options.server] Existing HTTP server to attach to.
    * @param {import('mongodb').MongoClient} [options.mongoClient] Existing Mongo client to reuse.
    * @param {import('mongodb').Db} [options.db] Existing Mongo database handle to reuse.
@@ -127,9 +126,7 @@ class MongoRealTimeServer {
 
     if (!this.#connectionAttached) {
       this.#connectionAttached = true;
-      this.#wss.on("connection", (socket, req, stream) =>
-        this.#handleConnection(socket, req, stream),
-      );
+      this.#wss.on("connection", (socket) => this.#handleConnection(socket));
     }
 
     if (!this.#upgradeAttached) {
@@ -140,6 +137,25 @@ class MongoRealTimeServer {
           return;
         }
 
+        if (typeof this.#authenticate === "function") {
+          const authData =
+            parseAuthHeader(request.headers.auth) ??
+            parseTokenFromUrl(request.url);
+          let authenticated = false;
+
+          try {
+            authenticated = await this.#authenticate(authData, request);
+          } catch (error) {
+            this.logger.warn?.("Authenticate exception", error);
+          }
+
+          if (!authenticated) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+          }
+        }
+
         this.#wss.handleUpgrade(request, socket, head, (webSocket) => {
           this.#wss.emit("connection", webSocket, request, socket);
         });
@@ -201,9 +217,20 @@ class MongoRealTimeServer {
               eventName += `:${c.name}`;
               if (!!docId) eventName += `:${docId}`;
             }
+
             const handler = this.#eventHandlers.get(eventName);
             try {
               handler?.(change);
+              for (let socket of this.#socketSubscriptions.keys()) {
+                this.#send(socket, {
+                  type: "realtime:db:change",
+                  key: eventName,
+                  collection: c.name,
+                  docId: change.documentKey._id,
+                  operationType: change.operationType,
+                  fullDocument: change.fullDocument,
+                });
+              }
             } catch (_) {}
           };
 
@@ -260,33 +287,10 @@ class MongoRealTimeServer {
   /**
    *
    * @param {import('ws').WebSocket} socket
-   * @param {http.IncomingMessage} req
-   * @param {Stream.Duplex} stream
    */
-  async #handleConnection(socket, req, stream) {
+  async #handleConnection(socket) {
     this.#socketSubscriptions.set(socket, new Set());
 
-    if (typeof this.#authenticate === "function") {
-      let authData = req.headers.auth;
-      try {
-        authData = JSON.parse(authData);
-      } catch (_) {}
-
-      let authenticated = false;
-      try {
-        authenticated = await this.#authenticate(authData);
-      } catch (e) {
-        this.logger.warn("Authenticate exception", e);
-      }
-
-      if (!authenticated) {
-        this.#sendError(socket, "Socket authentification failed");
-        stream.destroy();
-        socket.close();
-        return;
-      }
-    }
-
     socket.on("message", (buffer) => {
       Promise.resolve(this.#handleMessage(socket, buffer)).catch((error) => {
         this.#sendError(socket, error);
@@ -789,6 +793,45 @@ function normalizeQuery(message) {
   };
 }
 
+function parseAuthHeader(headerValue) {
+  if (Array.isArray(headerValue)) {
+    return parseAuthHeader(headerValue[0]);
+  }
+
+  if (typeof headerValue !== "string") {
+    return headerValue;
+  }
+
+  try {
+    return JSON.parse(headerValue);
+  } catch (_) {
+    return headerValue;
+  }
+}
+
+function parseTokenFromUrl(url) {
+  if (!url) {
+    return undefined;
+  }
+
+  try {
+    const searchParams = new URL(url, "http://localhost:3000").searchParams;
+    return (
+      searchParams.get("auth-token") ??
+      searchParams.get("authToken") ??
+      undefined
+    );
+  } catch {
+    const [, rawQuery = ""] = String(url).split("?");
+    const searchParams = new URLSearchParams(rawQuery);
+    return (
+      searchParams.get("auth-token") ??
+      searchParams.get("authToken") ??
+      undefined
+    );
+  }
+}
+
 function requiredString(value, field) {
   if (typeof value !== "string" || value.trim() === "") {
     throw new TypeError(`Expected "${field}" to be a non-empty string.`);
@@ -917,7 +960,7 @@ function toPathname(url) {
   }
 
   try {
-    return new URL(url, "http://localhost").pathname;
+    return new URL(url, "http://localhost:3000").pathname;
   } catch {
     return String(url).split("?")[0] || "/";
   }