@rvoh/psychic-websockets 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RVO Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+> ATTENTION: we are currently in the process of releasing this code to the world, as of the afternoon of March 10th, 2025. This notice will be removed, and the version of this repo will be bumped to 1.0.0, once all of the repos have been migrated to the new spaces and we can verify that it is all working. This is anticipated to take 1 day.
+
+# Psychic websockets
+
+Documentation for this repo can be found at [https://psychic-docs.netlify.app/docs/plugins/websockets/overview](https://psychic-docs.netlify.app/docs/plugins/websockets/overview)

package/dist/cjs/src/cable/index.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const psychic_1 = require("@rvoh/psychic");
+const redis_adapter_1 = require("@socket.io/redis-adapter");
+const colors = require("colorette");
+const socketio = require("socket.io");
+const MissingWsRedisConnection_js_1 = require("../error/ws/MissingWsRedisConnection.js");
+const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
+const index_js_1 = require("../psychic-application-websockets/index.js");
+class Cable {
+    app;
+    io;
+    httpServer;
+    config;
+    redisConnections = [];
+    constructor(app, config) {
+        this.app = app;
+        this.config = config;
+    }
+    connect() {
+        if (this.io)
+            return;
+        // for socket.io, we have to circumvent the normal process for starting a
+        // psychic server so that we can bind socket.io to the http instance.
+        this.httpServer = psychic_1.PsychicServer.createPsychicHttpInstance(this.app, this.config.psychicApp.sslCredentials);
+        this.io = new socketio.Server(this.httpServer, { cors: this.config.psychicApp.corsOptions });
+    }
+    async start(port, { withFrontEndClient = false, frontEndPort = 3000, } = {}) {
+        this.connect();
+        for (const hook of this.config.hooks.wsStart) {
+            await hook(this.io);
+        }
+        this.io.on('connect', async (socket) => {
+            try {
+                for (const hook of this.config.hooks.wsConnect) {
+                    await hook(socket);
+                }
+            }
+            catch (error) {
+                if (EnvInternal_js_1.default.boolean('PSYCHIC_DANGEROUSLY_PERMIT_WS_EXCEPTIONS'))
+                    throw error;
+                else {
+                    ;
+                    this.config.psychicApp.constructor.logWithLevel('error', `
+            An exception was caught in your websocket thread.
+            To prevent your server from crashing, we are rescuing this error here for you.
+            If you would like us to raise this exception, make sure to set
+
+            PSYCHIC_DANGEROUSLY_PERMIT_WS_EXCEPTIONS=1
+
+            the error received is:
+
+            ${error.message}
+          `);
+                    console.trace();
+                }
+            }
+        });
+        this.bindToRedis();
+        const psychicAppWebsockets = index_js_1.default.getOrFail();
+        await this.listen({
+            port: parseInt((port || psychicAppWebsockets.psychicApp.port).toString()),
+            withFrontEndClient,
+            frontEndPort,
+        });
+    }
+    async stop() {
+        try {
+            await this.io?.close();
+        }
+        catch {
+            // noop
+        }
+        for (const connection of this.redisConnections) {
+            try {
+                connection.disconnect();
+            }
+            catch {
+                // noop
+            }
+        }
+    }
+    async listen({ port, withFrontEndClient, frontEndPort, }) {
+        return new Promise(accept => {
+            this.httpServer.listen(port, () => {
+                if (!EnvInternal_js_1.default.isTest) {
+                    const app = index_js_1.default.getOrFail().psychicApp;
+                    app.logger.info(psychic_1.PsychicServer.asciiLogo());
+                    app.logger.info('\n');
+                    app.logger.info(colors.cyan('socket server started                                      '));
+                    app.logger.info(colors.cyan(`psychic dev server started at port ${colors.bgBlueBright(colors.green(port))}`));
+                    if (withFrontEndClient)
+                        app.logger.info(`client server started at port ${colors.cyan(frontEndPort)}`);
+                    app.logger.info('\n');
+                }
+                accept(true);
+            });
+        });
+    }
+    bindToRedis() {
+        const pubClient = this.config.websocketOptions.connection;
+        const subClient = this.config.websocketOptions.subConnection;
+        if (!pubClient || !subClient)
+            throw new MissingWsRedisConnection_js_1.default();
+        this.redisConnections.push(pubClient);
+        this.redisConnections.push(subClient);
+        pubClient.on('error', error => {
+            index_js_1.default.log('PUB CLIENT ERROR', error);
+        });
+        subClient.on('error', error => {
+            index_js_1.default.log('sub CLIENT ERROR', error);
+        });
+        try {
+            this.io.adapter((0, redis_adapter_1.createAdapter)(pubClient, subClient));
+        }
+        catch (error) {
+            index_js_1.default.log('FAILED TO ADAPT', error);
+        }
+    }
+}
+exports.default = Cable;

package/dist/cjs/src/cable/redisWsKey.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = redisWsKey;
+function redisWsKey(userId, redisKeyPrefix) {
+    return `${redisKeyPrefix}:${userId}:socket_ids`;
+}

package/dist/cjs/src/cable/ws.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidWsPathError = void 0;
+const dream_1 = require("@rvoh/dream");
+const redis_emitter_1 = require("@socket.io/redis-emitter");
+const luxon_1 = require("luxon");
+const EnvInternal_js_1 = require("../helpers/EnvInternal.js");
+const redisWsKey_js_1 = require("./redisWsKey.js");
+const index_js_1 = require("../psychic-application-websockets/index.js");
+class Ws {
+    allowedPaths;
+    io;
+    redisClient;
+    booted = false;
+    namespace;
+    redisKeyPrefix;
+    static async register(socket, id, redisKeyPrefix = 'user') {
+        const psychicWebsocketsApp = index_js_1.default.getOrFail();
+        const redisClient = psychicWebsocketsApp.websocketOptions.connection;
+        const interpretedId = id?.isDreamInstance ? id.primaryKeyValue : id;
+        const key = (0, redisWsKey_js_1.default)(interpretedId, redisKeyPrefix);
+        const socketIdsToKeep = await redisClient.lrange((0, redisWsKey_js_1.default)(interpretedId, redisKeyPrefix), -2, -1);
+        await redisClient
+            .multi()
+            .del(key)
+            .rpush(key, ...socketIdsToKeep, socket.id)
+            .expireat(key, 
+        // TODO: make this configurable in non-test environments
+        luxon_1.DateTime.now()
+            .plus(EnvInternal_js_1.default.isTest ? { seconds: 15 } : { day: 1 })
+            .toSeconds())
+            .exec();
+        socket.on('disconnect', async () => {
+            await redisClient.lrem(key, 1, socket.id);
+        });
+        const ws = new Ws(['/ops/connection-success']);
+        await ws.emit(interpretedId, '/ops/connection-success', {
+            message: 'Successfully connected to psychic websockets',
+        });
+    }
+    constructor(allowedPaths, { namespace = '/', redisKeyPrefix = 'user', } = {}) {
+        this.allowedPaths = allowedPaths;
+        this.namespace = namespace;
+        this.redisKeyPrefix = redisKeyPrefix;
+    }
+    boot() {
+        if (this.booted)
+            return;
+        const psychicWebsocketsApp = index_js_1.default.getOrFail();
+        this.redisClient = psychicWebsocketsApp.websocketOptions.connection;
+        this.io = new redis_emitter_1.Emitter(this.redisClient).of(this.namespace);
+        this.booted = true;
+    }
+    async emit(id, path, 
+    // eslint-disable-next-line
+    data = {}) {
+        if (this.allowedPaths.length && !this.allowedPaths.includes(path))
+            throw new InvalidWsPathError(path);
+        this.boot();
+        const socketIds = await this.findSocketIds(id?.isDreamInstance ? id.primaryKeyValue : id);
+        for (const socketId of socketIds) {
+            this.io.to(socketId).emit(path, data);
+        }
+    }
+    async findSocketIds(id) {
+        this.boot();
+        return (0, dream_1.uniq)(await this.redisClient.lrange(this.redisKey(id), 0, -1));
+    }
+    redisKey(userId) {
+        return (0, redisWsKey_js_1.default)(userId, this.redisKeyPrefix);
+    }
+}
+exports.default = Ws;
+class InvalidWsPathError extends Error {
+    invalidPath;
+    constructor(invalidPath) {
+        super();
+        this.invalidPath = invalidPath;
+    }
+    get message() {
+        return `
+      Invalid path passed to Ws: "${this.invalidPath}"
+    `;
+    }
+}
+exports.InvalidWsPathError = InvalidWsPathError;

package/dist/cjs/src/error/ws/MissingWsRedisConnection.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class MissingWsRedisConnection extends Error {
+    get message() {
+        return `
+No websocket redis connection was found, even though
+the application is configured to establish websockets.
+
+In conf/app.ts, either:
+
+  1.) disable websockets by omitting the call to psy.set('websockets', ...), OR
+  2.) provide a redis connection for your websockets, as shown below:
+
+export default async (psy: PsychicApplication) => {
+  ...
+
+  psy.set('websockets', {
+    connection: new Redis({
+      host: AppEnv.string('WS_REDIS_HOST'),
+      port: AppEnv.integer('WS_REDIS_PORT'),
+      username: AppEnv.string('WS_REDIS_USERNAME', { optional: true }),
+      password: AppEnv.string('WS_REDIS_PASSWORD', { optional: true }),
+      tls: AppEnv.isProduction ? {} : undefined,
+      maxRetriesPerRequest: null,
+    })
+  })
+}
+
+`;
+    }
+}
+exports.default = MissingWsRedisConnection;

package/dist/cjs/src/helpers/EnvInternal.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const dream_1 = require("@rvoh/dream");
+const EnvInternal = new dream_1.Env();
+exports.default = EnvInternal;

package/dist/cjs/src/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Ws = exports.Cable = exports.PsychicApplicationWebsockets = void 0;
+var index_js_1 = require("./psychic-application-websockets/index.js");
+Object.defineProperty(exports, "PsychicApplicationWebsockets", { enumerable: true, get: function () { return index_js_1.default; } });
+var index_js_2 = require("./cable/index.js");
+Object.defineProperty(exports, "Cable", { enumerable: true, get: function () { return index_js_2.default; } });
+var ws_js_1 = require("./cable/ws.js");
+Object.defineProperty(exports, "Ws", { enumerable: true, get: function () { return ws_js_1.default; } });

package/dist/cjs/src/psychic-application-websockets/cache.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cachePsychicApplicationWebsockets = cachePsychicApplicationWebsockets;
+exports.getCachedPsychicApplicationWebsockets = getCachedPsychicApplicationWebsockets;
+exports.getCachedPsychicApplicationWebsocketsOrFail = getCachedPsychicApplicationWebsocketsOrFail;
+let _psychicAppWebsockets = undefined;
+function cachePsychicApplicationWebsockets(psychicAppWebsockets) {
+    _psychicAppWebsockets = psychicAppWebsockets;
+}
+function getCachedPsychicApplicationWebsockets() {
+    return _psychicAppWebsockets;
+}
+function getCachedPsychicApplicationWebsocketsOrFail() {
+    if (!_psychicAppWebsockets)
+        throw new Error('must call `cachePsychicApplicationWebsockets` before loading cached psychic application websockets');
+    return _psychicAppWebsockets;
+}

package/dist/cjs/src/psychic-application-websockets/index.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("../cable/index.js");
+const cache_js_1 = require("./cache.js");
+class PsychicApplicationWebsockets {
+    static async init(psychicApp, cb) {
+        const psychicWsApp = new PsychicApplicationWebsockets(psychicApp);
+        await cb(psychicWsApp);
+        psychicApp.on('server:shutdown', async (psychicServer) => {
+            const cable = psychicServer.$attached.cable;
+            await cable?.stop();
+        });
+        psychicApp.override('server:start', async (psychicServer, { port, withFrontEndClient, frontEndPort }) => {
+            const cable = new index_js_1.default(psychicServer.expressApp, psychicWsApp);
+            await cable.start(port, {
+                withFrontEndClient,
+                frontEndPort,
+            });
+            psychicServer.attach('cable', cable);
+            return cable.httpServer;
+        });
+        (0, cache_js_1.cachePsychicApplicationWebsockets)(psychicWsApp);
+        return psychicWsApp;
+    }
+    /**
+     * Returns the cached psychic application if it has been set.
+     * If it has not been set, an exception is raised.
+     *
+     * The psychic application can be set by calling PsychicApplication#init
+     */
+    static getOrFail() {
+        return (0, cache_js_1.getCachedPsychicApplicationWebsocketsOrFail)();
+    }
+    psychicApp;
+    static log(...args) {
+        const psychicWebsocketsApp = this.getOrFail();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        return psychicWebsocketsApp.psychicApp.constructor.log(...args);
+    }
+    constructor(psychicApp) {
+        this.psychicApp = psychicApp;
+    }
+    _websocketOptions;
+    get websocketOptions() {
+        return this._websocketOptions;
+    }
+    _hooks = {
+        wsStart: [],
+        wsConnect: [],
+    };
+    get hooks() {
+        return this._hooks;
+    }
+    on(hookEventType, cb) {
+        switch (hookEventType) {
+            case 'ws:start':
+                this._hooks.wsStart.push(cb);
+                break;
+            case 'ws:connect':
+                this._hooks.wsConnect.push(cb);
+                break;
+            default:
+                throw new Error(`unrecognized event provided to PsychicApplicationWebsockets#on: ${hookEventType}`);
+        }
+    }
+    set(option, value) {
+        switch (option) {
+            case 'websockets':
+                this._websocketOptions = {
+                    ...value,
+                    subConnection: value?.connection?.duplicate(),
+                };
+                break;
+            default:
+                throw new Error(`Unhandled option type passed to PsychicApplicationWebsockets#set: ${option}`);
+        }
+    }
+}
+exports.default = PsychicApplicationWebsockets;

package/dist/esm/src/cable/index.js

@@ -0,0 +1,118 @@
+import { PsychicServer } from '@rvoh/psychic';
+import { createAdapter } from '@socket.io/redis-adapter';
+import * as colors from 'colorette';
+import * as socketio from 'socket.io';
+import MissingWsRedisConnection from '../error/ws/MissingWsRedisConnection.js';
+import EnvInternal from '../helpers/EnvInternal.js';
+import PsychicApplicationWebsockets from '../psychic-application-websockets/index.js';
+export default class Cable {
+    app;
+    io;
+    httpServer;
+    config;
+    redisConnections = [];
+    constructor(app, config) {
+        this.app = app;
+        this.config = config;
+    }
+    connect() {
+        if (this.io)
+            return;
+        // for socket.io, we have to circumvent the normal process for starting a
+        // psychic server so that we can bind socket.io to the http instance.
+        this.httpServer = PsychicServer.createPsychicHttpInstance(this.app, this.config.psychicApp.sslCredentials);
+        this.io = new socketio.Server(this.httpServer, { cors: this.config.psychicApp.corsOptions });
+    }
+    async start(port, { withFrontEndClient = false, frontEndPort = 3000, } = {}) {
+        this.connect();
+        for (const hook of this.config.hooks.wsStart) {
+            await hook(this.io);
+        }
+        this.io.on('connect', async (socket) => {
+            try {
+                for (const hook of this.config.hooks.wsConnect) {
+                    await hook(socket);
+                }
+            }
+            catch (error) {
+                if (EnvInternal.boolean('PSYCHIC_DANGEROUSLY_PERMIT_WS_EXCEPTIONS'))
+                    throw error;
+                else {
+                    ;
+                    this.config.psychicApp.constructor.logWithLevel('error', `
+            An exception was caught in your websocket thread.
+            To prevent your server from crashing, we are rescuing this error here for you.
+            If you would like us to raise this exception, make sure to set
+
+            PSYCHIC_DANGEROUSLY_PERMIT_WS_EXCEPTIONS=1
+
+            the error received is:
+
+            ${error.message}
+          `);
+                    console.trace();
+                }
+            }
+        });
+        this.bindToRedis();
+        const psychicAppWebsockets = PsychicApplicationWebsockets.getOrFail();
+        await this.listen({
+            port: parseInt((port || psychicAppWebsockets.psychicApp.port).toString()),
+            withFrontEndClient,
+            frontEndPort,
+        });
+    }
+    async stop() {
+        try {
+            await this.io?.close();
+        }
+        catch {
+            // noop
+        }
+        for (const connection of this.redisConnections) {
+            try {
+                connection.disconnect();
+            }
+            catch {
+                // noop
+            }
+        }
+    }
+    async listen({ port, withFrontEndClient, frontEndPort, }) {
+        return new Promise(accept => {
+            this.httpServer.listen(port, () => {
+                if (!EnvInternal.isTest) {
+                    const app = PsychicApplicationWebsockets.getOrFail().psychicApp;
+                    app.logger.info(PsychicServer.asciiLogo());
+                    app.logger.info('\n');
+                    app.logger.info(colors.cyan('socket server started                                      '));
+                    app.logger.info(colors.cyan(`psychic dev server started at port ${colors.bgBlueBright(colors.green(port))}`));
+                    if (withFrontEndClient)
+                        app.logger.info(`client server started at port ${colors.cyan(frontEndPort)}`);
+                    app.logger.info('\n');
+                }
+                accept(true);
+            });
+        });
+    }
+    bindToRedis() {
+        const pubClient = this.config.websocketOptions.connection;
+        const subClient = this.config.websocketOptions.subConnection;
+        if (!pubClient || !subClient)
+            throw new MissingWsRedisConnection();
+        this.redisConnections.push(pubClient);
+        this.redisConnections.push(subClient);
+        pubClient.on('error', error => {
+            PsychicApplicationWebsockets.log('PUB CLIENT ERROR', error);
+        });
+        subClient.on('error', error => {
+            PsychicApplicationWebsockets.log('sub CLIENT ERROR', error);
+        });
+        try {
+            this.io.adapter(createAdapter(pubClient, subClient));
+        }
+        catch (error) {
+            PsychicApplicationWebsockets.log('FAILED TO ADAPT', error);
+        }
+    }
+}

package/dist/esm/src/cable/redisWsKey.js

@@ -0,0 +1,3 @@
+export default function redisWsKey(userId, redisKeyPrefix) {
+    return `${redisKeyPrefix}:${userId}:socket_ids`;
+}

package/dist/esm/src/cable/ws.js

@@ -0,0 +1,81 @@
+import { uniq } from '@rvoh/dream';
+import { Emitter } from '@socket.io/redis-emitter';
+import { DateTime } from 'luxon';
+import EnvInternal from '../helpers/EnvInternal.js';
+import redisWsKey from './redisWsKey.js';
+import PsychicApplicationWebsockets from '../psychic-application-websockets/index.js';
+export default class Ws {
+    allowedPaths;
+    io;
+    redisClient;
+    booted = false;
+    namespace;
+    redisKeyPrefix;
+    static async register(socket, id, redisKeyPrefix = 'user') {
+        const psychicWebsocketsApp = PsychicApplicationWebsockets.getOrFail();
+        const redisClient = psychicWebsocketsApp.websocketOptions.connection;
+        const interpretedId = id?.isDreamInstance ? id.primaryKeyValue : id;
+        const key = redisWsKey(interpretedId, redisKeyPrefix);
+        const socketIdsToKeep = await redisClient.lrange(redisWsKey(interpretedId, redisKeyPrefix), -2, -1);
+        await redisClient
+            .multi()
+            .del(key)
+            .rpush(key, ...socketIdsToKeep, socket.id)
+            .expireat(key, 
+        // TODO: make this configurable in non-test environments
+        DateTime.now()
+            .plus(EnvInternal.isTest ? { seconds: 15 } : { day: 1 })
+            .toSeconds())
+            .exec();
+        socket.on('disconnect', async () => {
+            await redisClient.lrem(key, 1, socket.id);
+        });
+        const ws = new Ws(['/ops/connection-success']);
+        await ws.emit(interpretedId, '/ops/connection-success', {
+            message: 'Successfully connected to psychic websockets',
+        });
+    }
+    constructor(allowedPaths, { namespace = '/', redisKeyPrefix = 'user', } = {}) {
+        this.allowedPaths = allowedPaths;
+        this.namespace = namespace;
+        this.redisKeyPrefix = redisKeyPrefix;
+    }
+    boot() {
+        if (this.booted)
+            return;
+        const psychicWebsocketsApp = PsychicApplicationWebsockets.getOrFail();
+        this.redisClient = psychicWebsocketsApp.websocketOptions.connection;
+        this.io = new Emitter(this.redisClient).of(this.namespace);
+        this.booted = true;
+    }
+    async emit(id, path, 
+    // eslint-disable-next-line
+    data = {}) {
+        if (this.allowedPaths.length && !this.allowedPaths.includes(path))
+            throw new InvalidWsPathError(path);
+        this.boot();
+        const socketIds = await this.findSocketIds(id?.isDreamInstance ? id.primaryKeyValue : id);
+        for (const socketId of socketIds) {
+            this.io.to(socketId).emit(path, data);
+        }
+    }
+    async findSocketIds(id) {
+        this.boot();
+        return uniq(await this.redisClient.lrange(this.redisKey(id), 0, -1));
+    }
+    redisKey(userId) {
+        return redisWsKey(userId, this.redisKeyPrefix);
+    }
+}
+export class InvalidWsPathError extends Error {
+    invalidPath;
+    constructor(invalidPath) {
+        super();
+        this.invalidPath = invalidPath;
+    }
+    get message() {
+        return `
+      Invalid path passed to Ws: "${this.invalidPath}"
+    `;
+    }
+}

package/dist/esm/src/error/ws/MissingWsRedisConnection.js

@@ -0,0 +1,29 @@
+export default class MissingWsRedisConnection extends Error {
+    get message() {
+        return `
+No websocket redis connection was found, even though
+the application is configured to establish websockets.
+
+In conf/app.ts, either:
+
+  1.) disable websockets by omitting the call to psy.set('websockets', ...), OR
+  2.) provide a redis connection for your websockets, as shown below:
+
+export default async (psy: PsychicApplication) => {
+  ...
+
+  psy.set('websockets', {
+    connection: new Redis({
+      host: AppEnv.string('WS_REDIS_HOST'),
+      port: AppEnv.integer('WS_REDIS_PORT'),
+      username: AppEnv.string('WS_REDIS_USERNAME', { optional: true }),
+      password: AppEnv.string('WS_REDIS_PASSWORD', { optional: true }),
+      tls: AppEnv.isProduction ? {} : undefined,
+      maxRetriesPerRequest: null,
+    })
+  })
+}
+
+`;
+    }
+}

package/dist/esm/src/helpers/EnvInternal.js

@@ -0,0 +1,3 @@
+import { Env } from '@rvoh/dream';
+const EnvInternal = new Env();
+export default EnvInternal;

package/dist/esm/src/index.js

@@ -0,0 +1,3 @@
+export { default as PsychicApplicationWebsockets } from './psychic-application-websockets/index.js';
+export { default as Cable } from './cable/index.js';
+export { default as Ws } from './cable/ws.js';

package/dist/esm/src/psychic-application-websockets/cache.js

@@ -0,0 +1,12 @@
+let _psychicAppWebsockets = undefined;
+export function cachePsychicApplicationWebsockets(psychicAppWebsockets) {
+    _psychicAppWebsockets = psychicAppWebsockets;
+}
+export function getCachedPsychicApplicationWebsockets() {
+    return _psychicAppWebsockets;
+}
+export function getCachedPsychicApplicationWebsocketsOrFail() {
+    if (!_psychicAppWebsockets)
+        throw new Error('must call `cachePsychicApplicationWebsockets` before loading cached psychic application websockets');
+    return _psychicAppWebsockets;
+}

package/dist/esm/src/psychic-application-websockets/index.js

@@ -0,0 +1,76 @@
+import Cable from '../cable/index.js';
+import { cachePsychicApplicationWebsockets, getCachedPsychicApplicationWebsocketsOrFail } from './cache.js';
+export default class PsychicApplicationWebsockets {
+    static async init(psychicApp, cb) {
+        const psychicWsApp = new PsychicApplicationWebsockets(psychicApp);
+        await cb(psychicWsApp);
+        psychicApp.on('server:shutdown', async (psychicServer) => {
+            const cable = psychicServer.$attached.cable;
+            await cable?.stop();
+        });
+        psychicApp.override('server:start', async (psychicServer, { port, withFrontEndClient, frontEndPort }) => {
+            const cable = new Cable(psychicServer.expressApp, psychicWsApp);
+            await cable.start(port, {
+                withFrontEndClient,
+                frontEndPort,
+            });
+            psychicServer.attach('cable', cable);
+            return cable.httpServer;
+        });
+        cachePsychicApplicationWebsockets(psychicWsApp);
+        return psychicWsApp;
+    }
+    /**
+     * Returns the cached psychic application if it has been set.
+     * If it has not been set, an exception is raised.
+     *
+     * The psychic application can be set by calling PsychicApplication#init
+     */
+    static getOrFail() {
+        return getCachedPsychicApplicationWebsocketsOrFail();
+    }
+    psychicApp;
+    static log(...args) {
+        const psychicWebsocketsApp = this.getOrFail();
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        return psychicWebsocketsApp.psychicApp.constructor.log(...args);
+    }
+    constructor(psychicApp) {
+        this.psychicApp = psychicApp;
+    }
+    _websocketOptions;
+    get websocketOptions() {
+        return this._websocketOptions;
+    }
+    _hooks = {
+        wsStart: [],
+        wsConnect: [],
+    };
+    get hooks() {
+        return this._hooks;
+    }
+    on(hookEventType, cb) {
+        switch (hookEventType) {
+            case 'ws:start':
+                this._hooks.wsStart.push(cb);
+                break;
+            case 'ws:connect':
+                this._hooks.wsConnect.push(cb);
+                break;
+            default:
+                throw new Error(`unrecognized event provided to PsychicApplicationWebsockets#on: ${hookEventType}`);
+        }
+    }
+    set(option, value) {
+        switch (option) {
+            case 'websockets':
+                this._websocketOptions = {
+                    ...value,
+                    subConnection: value?.connection?.duplicate(),
+                };
+                break;
+            default:
+                throw new Error(`Unhandled option type passed to PsychicApplicationWebsockets#set: ${option}`);
+        }
+    }
+}

package/dist/types/src/cable/index.d.ts

@@ -0,0 +1,24 @@
+import { Application } from 'express';
+import * as http from 'http';
+import * as socketio from 'socket.io';
+import PsychicApplicationWebsockets from '../psychic-application-websockets/index.js';
+export default class Cable {
+    app: Application;
+    io: socketio.Server | undefined;
+    httpServer: http.Server;
+    private config;
+    private redisConnections;
+    constructor(app: Application, config: PsychicApplicationWebsockets);
+    connect(): void;
+    start(port?: number, { withFrontEndClient, frontEndPort, }?: {
+        withFrontEndClient?: boolean;
+        frontEndPort?: number;
+    }): Promise<void>;
+    stop(): Promise<void>;
+    listen({ port, withFrontEndClient, frontEndPort, }: {
+        port: number | string;
+        withFrontEndClient: boolean;
+        frontEndPort: number;
+    }): Promise<unknown>;
+    bindToRedis(): void;
+}

package/dist/types/src/cable/redisWsKey.d.ts

@@ -0,0 +1,2 @@
+import { IdType } from '@rvoh/dream';
+export default function redisWsKey(userId: IdType, redisKeyPrefix: string): string;

package/dist/types/src/cable/ws.d.ts

@@ -0,0 +1,25 @@
+import { Dream, IdType } from '@rvoh/dream';
+import { Emitter } from '@socket.io/redis-emitter';
+import { Socket } from 'socket.io';
+export default class Ws<AllowedPaths extends readonly string[]> {
+    allowedPaths: AllowedPaths & readonly string[];
+    io: Emitter;
+    private redisClient;
+    private booted;
+    private namespace;
+    private redisKeyPrefix;
+    static register(socket: Socket, id: IdType | Dream, redisKeyPrefix?: string): Promise<void>;
+    constructor(allowedPaths: AllowedPaths & readonly string[], { namespace, redisKeyPrefix, }?: {
+        namespace?: string;
+        redisKeyPrefix?: string;
+    });
+    boot(): void;
+    emit<T extends Ws<AllowedPaths>, const P extends AllowedPaths[number]>(this: T, id: IdType | Dream, path: P, data?: any): Promise<void>;
+    findSocketIds(id: IdType): Promise<string[]>;
+    private redisKey;
+}
+export declare class InvalidWsPathError extends Error {
+    private invalidPath;
+    constructor(invalidPath: string);
+    get message(): string;
+}

package/dist/types/src/error/ws/MissingWsRedisConnection.d.ts

@@ -0,0 +1,3 @@
+export default class MissingWsRedisConnection extends Error {
+    get message(): string;
+}

package/dist/types/src/helpers/EnvInternal.d.ts

@@ -0,0 +1,6 @@
+import { Env } from '@rvoh/dream';
+declare const EnvInternal: Env<{
+    string: "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT";
+    boolean: "DEBUG" | "PSYCHIC_CORE_DEVELOPMENT" | "PSYCHIC_DANGEROUSLY_PERMIT_WS_EXCEPTIONS";
+}, "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT", never, "PSYCHIC_CORE_DEVELOPMENT" | "DEBUG" | "PSYCHIC_DANGEROUSLY_PERMIT_WS_EXCEPTIONS">;
+export default EnvInternal;

package/dist/types/src/index.d.ts

@@ -0,0 +1,3 @@
+export { default as PsychicApplicationWebsockets } from './psychic-application-websockets/index.js';
+export { default as Cable } from './cable/index.js';
+export { default as Ws } from './cable/ws.js';

package/dist/types/src/psychic-application-websockets/cache.d.ts

@@ -0,0 +1,4 @@
+import PsychicApplicationWebsockets from './index.js';
+export declare function cachePsychicApplicationWebsockets(psychicAppWebsockets: PsychicApplicationWebsockets): void;
+export declare function getCachedPsychicApplicationWebsockets(): PsychicApplicationWebsockets | undefined;
+export declare function getCachedPsychicApplicationWebsocketsOrFail(): PsychicApplicationWebsockets;

package/dist/types/src/psychic-application-websockets/index.d.ts

@@ -0,0 +1,35 @@
+import { PsychicApplication } from '@rvoh/psychic';
+import { Cluster, Redis } from 'ioredis';
+import { Socket, Server as SocketServer } from 'socket.io';
+export default class PsychicApplicationWebsockets {
+    static init(psychicApp: PsychicApplication, cb: (app: PsychicApplicationWebsockets) => void | Promise<void>): Promise<PsychicApplicationWebsockets>;
+    /**
+     * Returns the cached psychic application if it has been set.
+     * If it has not been set, an exception is raised.
+     *
+     * The psychic application can be set by calling PsychicApplication#init
+     */
+    static getOrFail(): PsychicApplicationWebsockets;
+    psychicApp: PsychicApplication;
+    static log(...args: Parameters<typeof PsychicApplication.log>): void;
+    constructor(psychicApp: PsychicApplication);
+    private _websocketOptions;
+    get websocketOptions(): PsychicWebsocketOptions & {
+        subConnection?: RedisOrRedisClusterConnection;
+    };
+    private _hooks;
+    get hooks(): PsychicApplicationWebsocketsHooks;
+    on<T extends PsychicWebsocketsHookEventType>(hookEventType: T, cb: T extends 'ws:start' ? (server: SocketServer) => void | Promise<void> : T extends 'ws:connect' ? (socket: Socket) => void | Promise<void> : never): void;
+    set<Opt extends PsychicApplicationWebsocketsOption>(option: Opt, value: unknown): void;
+}
+interface PsychicWebsocketOptions {
+    connection: Redis;
+}
+export type PsychicApplicationWebsocketsOption = 'websockets';
+export type PsychicWebsocketsHookEventType = 'ws:start' | 'ws:connect';
+export interface PsychicApplicationWebsocketsHooks {
+    wsStart: ((server: SocketServer) => void | Promise<void>)[];
+    wsConnect: ((socket: Socket) => void | Promise<void>)[];
+}
+export type RedisOrRedisClusterConnection = Redis | Cluster;
+export {};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "type": "module",
+  "name": "@rvoh/psychic-websockets",
+  "description": "Websocket system for Psychic applications",
+  "version": "0.2.0",
+  "author": "RVOHealth",
+  "repository": "https://github.com/rvohealth/psychic-websockets.git",
+  "license": "MIT",
+  "main": "./dist/cjs/src/index.js",
+  "module": "./dist/esm/src/index.js",
+  "types": "./dist/types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/esm/src/index.js",
+      "require": "./dist/cjs/src/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "client": "yarn --cwd=./client start",
+    "psy": "yarn psyts",
+    "psyjs": "node ./dist/test-app/src/cli/index.js",
+    "psyts": "node --experimental-specifier-resolution=node --import ./bin/esm.js ./test-app/src/cli/index.ts",
+    "build": "echo \"building cjs...\" && rm -rf dist && npx tsc -p ./tsconfig.cjs.build.json && echo \"building esm...\" && npx tsc -p ./tsconfig.esm.build.json",
+    "uspec": "vitest --config ./spec/unit/vite.config.ts",
+    "fspec": "vitest run --config=./spec/features/vite.config.ts",
+    "format": "yarn run prettier . --write",
+    "lint": "yarn run eslint --no-warn-ignored \"src/**/*.ts\" && yarn run prettier . --check",
+    "dev": "NODE_ENV=development WORKER_COUNT=0 ts-node --transpile-only ./test-app/main.ts",
+    "prepack": "yarn build"
+  },
+  "peerDependencies": {
+    "@rvoh/dream": "*",
+    "@rvoh/psychic": "*",
+    "@socket.io/redis-adapter": "*",
+    "@socket.io/redis-emitter": "*",
+    "ioredis": "*",
+    "socket.io": "*",
+    "socket.io-adapter": "*"
+  },
+  "devDependencies": {
+    "@eslint/js": "=9.0.0",
+    "@rvoh/dream": "^0.29.1",
+    "@rvoh/dream-spec-helpers": "^0.1.0",
+    "@rvoh/psychic": "^0.24.0",
+    "@rvoh/psychic-spec-helpers": "^0.2.0",
+    "@socket.io/redis-adapter": "^8.3.0",
+    "@socket.io/redis-emitter": "^5.1.0",
+    "@types/express": "^4",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.5.1",
+    "@types/pg": "^8",
+    "@types/supertest": "^6.0.2",
+    "bullmq": "^5.12.12",
+    "eslint": "^9.9.1",
+    "express": "^4.21.2",
+    "ioredis": "^5.4.1",
+    "kysely": "^0.27.5",
+    "kysely-codegen": "^0.17.0",
+    "luxon": "^3.5.0",
+    "luxon-jest-matchers": "^0.1.14",
+    "pg": "^8.13.1",
+    "prettier": "^3.3.3",
+    "puppeteer": "^24.4.0",
+    "socket.io": "^4.8.1",
+    "socket.io-adapter": "^2.5.5",
+    "socket.io-client": "^4.8.1",
+    "supertest": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.7.0",
+    "typedoc": "^0.26.6",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "=7.18.0",
+    "vitest": "^3.0.8"
+  },
+  "packageManager": "yarn@4.4.1"
+}