@lazyapps/change-notifier-socket-io 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Oliver Sturm
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @lazyapps/change-notifier-socket-io
+
+Socket.io-based change notification broadcaster. Pushes real-time read model change notifications to connected clients via WebSockets.
+
+## Installation
+
+```bash
+pnpm add @lazyapps/change-notifier-socket-io
+```
+
+## Part of LazyApps
+
+This package is part of the [LazyApps](https://github.com/oliversturm/lazyapps-libs) event-sourcing and CQRS framework.

package/express.js

@@ -0,0 +1,126 @@
+import express from 'express';
+import bodyParser from 'body-parser';
+import morgan from 'morgan';
+import cors from 'cors';
+import cookieParser from 'cookie-parser';
+import { expressjwt } from 'express-jwt';
+import { socketIoCookieJwt } from './socketIoCookieJwt.js';
+import { Server as SocketIoServer } from 'socket.io';
+import http from 'http';
+import { nanoid } from 'nanoid';
+
+import { getLogger, getStream } from '@lazyapps/logger';
+import { initSockets, createNotifier } from './notifier.js';
+
+const log = getLogger('Changes/HTTP', 'INIT');
+
+const correlationId = (correlationConfig) => (req, res, next) => {
+  // check where a correlation Id might already exist
+  const existingId = req.body.correlationId || req.headers['x-correlation-id'];
+
+  // since we want to use it in code, make sure the body
+  // now has an id in any case
+  req.body.correlationId =
+    existingId || `${correlationConfig?.serviceId || 'UNK'}-${nanoid()}`;
+
+  // also in the result, not needed right now but can't hurt
+  // for debugging
+  res.setHeader('X-Correlation-ID', req.body.correlationId);
+  next();
+};
+
+morgan.token('correlation-id', function (req) {
+  return req.body.correlationId;
+});
+
+const runExpress = (
+  correlationConfig,
+  {
+    port = 3008,
+    host = '0.0.0.0',
+    jwtSecret,
+    authCookieName,
+    credentialsRequired,
+    ioAuthHandler,
+    changeInfoAuthHandler,
+  },
+) => {
+  return new Promise((resolve, reject) => {
+    const app = express();
+    app.use(cors());
+    app.use(bodyParser.json());
+    app.use(correlationId(correlationConfig));
+    app.use(
+      morgan(
+        '[:correlation-id] :method :url :status :response-time ms - :res[content-length]',
+        { stream: getStream(log.debugBare) },
+      ),
+    );
+    app.use(cookieParser());
+
+    // Similar code as in express/runExpress.js -- refactor?
+    if (jwtSecret) {
+      app.use(
+        expressjwt({
+          secret: jwtSecret,
+          algorithms: ['HS256'],
+          credentialsRequired: credentialsRequired || false,
+          getToken: (req) => {
+            // check Authorization header first
+            if (
+              req.headers.authorization &&
+              req.headers.authorization.split(' ')[0] === 'Bearer'
+            ) {
+              return req.headers.authorization.split(' ')[1];
+            }
+            // consider cookie if a name has been given
+            if (authCookieName) {
+              const token = req.cookies[authCookieName || 'access_token'];
+              if (token) {
+                return token;
+              }
+            }
+            return null;
+          },
+        }),
+      );
+    }
+
+    const server = http.createServer(app);
+    const io = new SocketIoServer(server, {
+      cors: { origin: true },
+    });
+    io.use(socketIoCookieJwt({ jwtSecret, cookieName: authCookieName }));
+    initSockets(
+      correlationConfig,
+      io,
+      jwtSecret && ioAuthHandler ? ioAuthHandler : () => true,
+    );
+    const notifier = createNotifier(
+      io,
+      jwtSecret && changeInfoAuthHandler ? changeInfoAuthHandler : () => true,
+    );
+    app.post('/change', notifier);
+
+    server.listen(port, host);
+    server.on('listening', () => {
+      resolve(server);
+    });
+    server.on('error', reject);
+  })
+    .catch((err) => {
+      log.error(`Can't run HTTP server: ${err}`);
+    })
+    .then((server) => {
+      log.info(
+        `HTTP API listening on port ${port}, ${
+          jwtSecret && credentialsRequired ? 'requiring ' : 'checking for '
+        } a JWT Bearer token${
+          authCookieName ? ` or a cookie named ${authCookieName}` : ''
+        }`,
+      );
+      return server;
+    });
+};
+
+export { runExpress };

package/index.js

@@ -0,0 +1,4 @@
+import { runExpress } from './express.js';
+
+export const express = (config) => (correlationConfig) =>
+  runExpress(correlationConfig, config);

package/notifier.js

@@ -0,0 +1,92 @@
+import { getLogger } from '@lazyapps/logger';
+import { nanoid } from 'nanoid';
+
+const getRoomName = (endpointName, readModelName, resolverName) =>
+  `${endpointName}/${readModelName}/${resolverName}`;
+
+const ioInitLog = getLogger('Changes/IO', 'INIT');
+
+export const initSockets = (correlationConfig, io, ioAuthHandler) => {
+  ioInitLog.debug('Initializing sockets');
+  io.on('connect', (socket) => {
+    const existingId = socket.handshake.query?.correlationId;
+    socket.correlationId =
+      existingId || `${correlationConfig?.serviceId || 'UNK'}-${nanoid()}`;
+
+    const ioLog = getLogger('Changes/IO', socket.correlationId);
+    ioLog.debug(
+      `Connection: ${socket.id} (handshake: ${JSON.stringify(
+        socket.handshake,
+      )})${
+        socket.decoded_token
+          ? ` (JWT: ${JSON.stringify(socket.decoded_token)})`
+          : ' (no JWT)'
+      }`,
+    );
+
+    socket.on('disconnect', (reason) => {
+      ioLog.debug(`Disconnected ${socket.id}, reason: ${reason}`);
+    });
+
+    socket.on('error', (error) => {
+      ioLog.debug(`Communication error with ${socket.id}: ${error}`);
+    });
+
+    socket.on('register', (resolvers) => {
+      try {
+        if (!ioAuthHandler(socket.decoded_token, resolvers)) {
+          ioLog.error(
+            `Unauthorized register ${JSON.stringify(resolvers)} (claims ${
+              socket.decoded_token
+            })`,
+          );
+          socket.disconnect();
+          return;
+        }
+        socket.join(
+          resolvers.map(({ endpointName, readModelName, resolverName }) =>
+            getRoomName(endpointName, readModelName, resolverName),
+          ),
+        );
+        ioLog.debug(`Registered ${socket.id} for ${JSON.stringify(resolvers)}`);
+      } catch (err) {
+        ioLog.error(
+          `Can't register ${socket.id} for ${JSON.stringify(
+            resolvers,
+          )}: ${err}`,
+        );
+      }
+    });
+  });
+};
+
+export const createNotifier = (io, changeInfoAuthHandler) => {
+  const handler = (req, res) => {
+    const auth = req.auth;
+    const rmLog = getLogger('Changes/RM', req.body.correlationId);
+
+    if (!changeInfoAuthHandler(auth)) {
+      rmLog.error(
+        `Unauthorized changeInfo ${JSON.stringify(req.body)} (claims ${auth})`,
+      );
+      res.sendStatus(403);
+      return;
+    }
+
+    const changeInfo = req.body;
+    try {
+      const { endpointName, readModelName, resolverName } = changeInfo;
+      const roomName = getRoomName(endpointName, readModelName, resolverName);
+      io.to(roomName).emit('change', changeInfo);
+      rmLog.debug(`Forwarded changeInfo ${JSON.stringify(changeInfo)}`);
+      res.sendStatus(200);
+    } catch (err) {
+      rmLog.error(
+        `Can't forward changeInfo ${JSON.stringify(changeInfo)}: ${err}`,
+      );
+      res.sendStatus(500);
+    }
+  };
+
+  return handler;
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lazyapps/change-notifier-socket-io",
+  "version": "0.1.0",
+  "description": "Socket.io-based change notification broadcaster for LazyApps",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "*.js"
+  ],
+  "keywords": [
+    "event-sourcing",
+    "cqrs",
+    "lazyapps",
+    "change-notification",
+    "socket.io",
+    "websocket"
+  ],
+  "author": "Oliver Sturm",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oliversturm/lazyapps-libs.git",
+    "directory": "packages/change-notifier-socket-io"
+  },
+  "bugs": {
+    "url": "https://github.com/oliversturm/lazyapps-libs/issues"
+  },
+  "homepage": "https://github.com/oliversturm/lazyapps-libs/tree/main/packages/change-notifier-socket-io#readme",
+  "engines": {
+    "node": ">=18.20.3 || >=20.18.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "type": "module",
+  "dependencies": {
+    "body-parser": "^1.20.2",
+    "cookie": "^0.5.0",
+    "cookie-parser": "^1.4.6",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.2",
+    "morgan": "^1.10.0",
+    "nanoid": "^5.0.7",
+    "socket.io": "^4.7.2",
+    "socketio-jwt": "^4.6.2",
+    "@lazyapps/logger": "^0.1.0"
+  },
+  "scripts": {
+    "test": "vitest"
+  }
+}

package/socketIoCookieJwt.js

@@ -0,0 +1,35 @@
+import jwt from 'jsonwebtoken';
+import cookie from 'cookie';
+
+const decodeToken = (jwtSecret, token) => {
+  try {
+    return jwt.verify(token, jwtSecret);
+  } catch (err) {
+    return null;
+  }
+};
+
+// Note that this middleware is written to extract the token
+// if it can be found, but to simply proceed if it can't.
+
+// Also note: the headers are always the ones from the first
+// connection (https://github.com/socketio/socket.io/issues/2860#issuecomment-781411803) --
+// so if I needed to refresh the token on the client, it would
+// be necessary to reconnect to the server.
+export const socketIoCookieJwt =
+  ({ cookieName = 'access_token', jwtSecret }) =>
+  (socket, next) => {
+    const token = socket.handshake.auth?.token;
+    if (token) {
+      socket.decoded_token = decodeToken(jwtSecret, token);
+    } else {
+      const cookieHeader = socket.handshake.headers.cookie;
+      if (cookieHeader) {
+        const cookies = cookie.parse(cookieHeader);
+        if (cookies[cookieName]) {
+          socket.decoded_token = decodeToken(jwtSecret, cookies[cookieName]);
+        }
+      }
+    }
+    next();
+  };