nestjs-web-repl 2.0.0 → 2.1.0

package/README.md

@@ -7,19 +7,18 @@ so `get(SomeService)`, `resolve(...)`, `select(...)`, and friends all work exact
 they do in the local REPL — except reachable over HTTP, from anywhere, against a
 running server.
 
-> ## ⚠️ Security warning — read this before enabling anything
+> ## ⚠️ Security
 >
-> **These endpoints execute arbitrary code inside your running application.**
-> A command like `require('child_process').execSync('...')` runs with the full
-> privileges of your Node process. This library ships with **no authentication,
-> no authorization, and no rate limiting**. The `enabled` option is the *only*
-> built-in safety rail, and it is a blunt boolean — it does not check who is
-> asking.
+> These endpoints run arbitrary code inside your app, with the full privileges of
+> your Node process. That's the whole point — it's a debugging tool — and it's
+> also the risk: anyone who can reach an enabled endpoint can run anything your
+> app can.
 >
-> Do not expose these routes on a public-facing port. Do not enable this in
-> production unless you have put your own auth in front of it (see
-> [Securing it](#securing-it) below). Treat this exactly like you would treat
-> giving someone a shell on your server — because that is what it is.
+> The module ships no authentication of its own; `enabled` is an on/off switch,
+> not a lock. Control access yourself: gate `enabled` behind an environment
+> variable and put your own guard in front of the routes ([Securing it](#securing-it)).
+>
+> Guarded and on a trusted network, it's a safe way to inspect a running app.
 
 ## Install
 
@@ -218,62 +217,56 @@ are distinct from, and not to be confused with, the client-visible `system`
 *SSE event type* documented under [Endpoints](#endpoints), which only ever
 carries `{ping}`/`{done}`/`{error}`).
 
-### Redis adapter sketch
+### Redis (multi-instance)
+
+Behind a load balancer the default in-memory adapter is per-process: a command
+posted to one replica never reaches a session owned by another. Supply a Redis
+adapter so every replica shares one pub/sub bus. Import it from the
+`nestjs-web-repl/redis` subpath and hand it one connected client — the adapter
+creates its own dedicated subscriber connection (Redis requires one for subscribe
+mode) and closes only that connection on shutdown; your client stays yours.
+
+**ioredis:**
 
 ```ts
-import { Injectable, OnModuleDestroy } from '@nestjs/common';
 import Redis from 'ioredis';
-import type { WebReplAdapter } from 'nestjs-web-repl';
-
-@Injectable()
-export class RedisWebReplAdapter implements WebReplAdapter, OnModuleDestroy {
-  private readonly pub = new Redis(process.env.REDIS_URL);
-  private readonly sub = new Redis(process.env.REDIS_URL);
-
-  async publish(topic: string, message: string): Promise<void> {
-    await this.pub.publish(topic, message);
-  }
-
-  async subscribe(topic: string, handler: (message: string) => void): Promise<void> {
-    await this.sub.subscribe(topic);
-    this.sub.on('message', (channel, message) => {
-      if (channel === topic) handler(message);
-    });
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    await this.pub.quit();
-    await this.sub.quit();
-  }
-}
-```
+import { WebReplModule } from 'nestjs-web-repl';
+import { IoRedisWebReplAdapter } from 'nestjs-web-repl/redis';
 
-```ts
-// as a ready-made instance
 WebReplModule.register({
   enabled: process.env.REPL_ENABLED === 'true',
-  adapter: new RedisWebReplAdapter(),
-  instanceId: process.env.HOSTNAME, // shows up in `command` SSE events and
-                                     // internal webrepl:sys claim messages
+  adapter: new IoRedisWebReplAdapter(new Redis(process.env.REDIS_URL!)),
 });
+```
 
-// or let Nest construct it (and its dependencies) for you
-WebReplModule.register({
-  enabled: process.env.REPL_ENABLED === 'true',
-  adapter: { useClass: RedisWebReplAdapter, imports: [RedisModule] },
-});
+**node-redis:**
+
+```ts
+import { createClient } from 'redis';
+import { WebReplModule } from 'nestjs-web-repl';
+import { NodeRedisWebReplAdapter } from 'nestjs-web-repl/redis';
 
-// or build it with a factory
 WebReplModule.register({
   enabled: process.env.REPL_ENABLED === 'true',
   adapter: {
-    useFactory: (redis: RedisService) => new RedisWebReplAdapter(redis),
-    inject: [RedisService],
-    imports: [RedisModule],
+    useFactory: async () => {
+      const client = createClient({ url: process.env.REDIS_URL });
+      await client.connect();
+      return new NodeRedisWebReplAdapter(client);
+    },
   },
 });
 ```
 
+`ioredis` and `redis` are optional peer dependencies — install whichever you use.
+Both adapters wrap a small shared base; to target another broker, subclass
+`BaseRedisWebReplAdapter` or implement `WebReplAdapter` directly.
+
+The `adapter` extra also accepts a DI-configured provider — `{ useClass, imports? }`
+or `{ useFactory, inject?, imports? }` — so a custom adapter can pull its own
+dependencies (a shared client, a config service) from a Nest module. See the
+[extras table](#options-webreplmoduleoptions) below.
+
 ## Options (`WebReplModuleOptions`)
 
 | Option              | Type             | Default                    | Notes                                              |
@@ -390,10 +383,11 @@ We tell you this because the honest thing to do is let you judge the code on
 its merits rather than guess at its origins. If you are skeptical of AI-written
 code, here is what to actually look at:
 
-- **The tests.** 83 automated tests, including a two-instance end-to-end test
+- **The tests.** 100 automated tests, including a two-instance end-to-end test
   that proves cross-instance command routing and output fan-out, and an
   execution-proof test that resolves a real provider through the live REPL
-  context. `npm test`, `npm run build`, and `npx tsc --noEmit` are all green.
+  context. `npm test`, `npm run build`, and `npx tsc -p tsconfig.build.json
+  --noEmit` are all green.
 - **The commit history.** The real TDD trail is preserved — failing test,
   implementation, fixes — including several rounds where review caught genuine
   defects (the trickiest: `node:repl` completion detection on modern Node, and

package/dist/adapters/redis/base-redis-web-repl.adapter.d.ts

@@ -0,0 +1,20 @@
+import type { WebReplAdapter } from '../../interfaces/web-repl-adapter.interface';
+type Handler = (message: string) => void;
+/**
+ * Library-agnostic Redis pub/sub bridge. Subclasses wire the abstract hooks to a
+ * concrete client. Topics are opaque; the service owns the `webrepl:*` names.
+ */
+export declare abstract class BaseRedisWebReplAdapter implements WebReplAdapter {
+    private readonly handlers;
+    private readonly subscribed;
+    private readonly logger;
+    publish(topic: string, message: string): Promise<void>;
+    subscribe(topic: string, handler: Handler): Promise<void>;
+    /** Fan an inbound message out to every handler registered for the topic. */
+    protected dispatch(topic: string, message: string): void;
+    onModuleDestroy(): Promise<void>;
+    protected abstract doPublish(topic: string, message: string): Promise<void>;
+    protected abstract ensureSubscribed(topic: string): Promise<void>;
+    protected abstract teardown(): Promise<void>;
+}
+export {};

package/dist/adapters/redis/base-redis-web-repl.adapter.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseRedisWebReplAdapter = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * Library-agnostic Redis pub/sub bridge. Subclasses wire the abstract hooks to a
+ * concrete client. Topics are opaque; the service owns the `webrepl:*` names.
+ */
+class BaseRedisWebReplAdapter {
+    constructor() {
+        this.handlers = new Map();
+        this.subscribed = new Set();
+        this.logger = new common_1.Logger(this.constructor.name);
+    }
+    async publish(topic, message) {
+        await this.doPublish(topic, message);
+    }
+    async subscribe(topic, handler) {
+        let set = this.handlers.get(topic);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(topic, set);
+        }
+        set.add(handler);
+        if (!this.subscribed.has(topic)) {
+            await this.ensureSubscribed(topic);
+            this.subscribed.add(topic);
+        }
+    }
+    /** Fan an inbound message out to every handler registered for the topic. */
+    dispatch(topic, message) {
+        const set = this.handlers.get(topic);
+        if (!set)
+            return;
+        for (const handler of set) {
+            try {
+                handler(message);
+            }
+            catch (err) {
+                // A handler fault (e.g. malformed inbound JSON on a shared Redis
+                // channel) must not escape into the client's message emitter and crash
+                // the process, nor abort delivery to the remaining handlers.
+                this.logger.error(`web-repl adapter handler for "${topic}" threw: ${String(err)}`);
+            }
+        }
+    }
+    async onModuleDestroy() {
+        await this.teardown();
+        this.handlers.clear();
+        this.subscribed.clear();
+    }
+}
+exports.BaseRedisWebReplAdapter = BaseRedisWebReplAdapter;

package/dist/adapters/redis/index.d.ts

@@ -0,0 +1,5 @@
+export { BaseRedisWebReplAdapter } from './base-redis-web-repl.adapter';
+export { IoRedisWebReplAdapter } from './ioredis-web-repl.adapter';
+export type { IoRedisLike } from './ioredis-web-repl.adapter';
+export { NodeRedisWebReplAdapter } from './node-redis-web-repl.adapter';
+export type { NodeRedisLike } from './node-redis-web-repl.adapter';

package/dist/adapters/redis/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRedisWebReplAdapter = exports.IoRedisWebReplAdapter = exports.BaseRedisWebReplAdapter = void 0;
+var base_redis_web_repl_adapter_1 = require("./base-redis-web-repl.adapter");
+Object.defineProperty(exports, "BaseRedisWebReplAdapter", { enumerable: true, get: function () { return base_redis_web_repl_adapter_1.BaseRedisWebReplAdapter; } });
+var ioredis_web_repl_adapter_1 = require("./ioredis-web-repl.adapter");
+Object.defineProperty(exports, "IoRedisWebReplAdapter", { enumerable: true, get: function () { return ioredis_web_repl_adapter_1.IoRedisWebReplAdapter; } });
+var node_redis_web_repl_adapter_1 = require("./node-redis-web-repl.adapter");
+Object.defineProperty(exports, "NodeRedisWebReplAdapter", { enumerable: true, get: function () { return node_redis_web_repl_adapter_1.NodeRedisWebReplAdapter; } });

package/dist/adapters/redis/ioredis-web-repl.adapter.d.ts

@@ -0,0 +1,22 @@
+import { BaseRedisWebReplAdapter } from './base-redis-web-repl.adapter';
+/** Minimal structural surface of an ioredis client (no `ioredis` import). */
+export interface IoRedisLike {
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string): Promise<unknown>;
+    duplicate(): IoRedisLike;
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    quit(): Promise<unknown>;
+}
+/**
+ * Redis adapter backed by ioredis. Pass one connected client (the publisher);
+ * the adapter creates and owns a duplicated subscriber connection.
+ */
+export declare class IoRedisWebReplAdapter extends BaseRedisWebReplAdapter {
+    private readonly publisher;
+    private subscriber?;
+    constructor(publisher: IoRedisLike);
+    private ensureSubscriber;
+    protected doPublish(topic: string, message: string): Promise<void>;
+    protected ensureSubscribed(topic: string): Promise<void>;
+    protected teardown(): Promise<void>;
+}

package/dist/adapters/redis/ioredis-web-repl.adapter.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IoRedisWebReplAdapter = void 0;
+const base_redis_web_repl_adapter_1 = require("./base-redis-web-repl.adapter");
+/**
+ * Redis adapter backed by ioredis. Pass one connected client (the publisher);
+ * the adapter creates and owns a duplicated subscriber connection.
+ */
+class IoRedisWebReplAdapter extends base_redis_web_repl_adapter_1.BaseRedisWebReplAdapter {
+    constructor(publisher) {
+        super();
+        this.publisher = publisher;
+    }
+    ensureSubscriber() {
+        if (!this.subscriber) {
+            this.subscriber = this.publisher.duplicate();
+            this.subscriber.on('message', (channel, message) => this.dispatch(channel, message));
+        }
+        return this.subscriber;
+    }
+    async doPublish(topic, message) {
+        await this.publisher.publish(topic, message);
+    }
+    async ensureSubscribed(topic) {
+        await this.ensureSubscriber().subscribe(topic);
+    }
+    async teardown() {
+        if (this.subscriber) {
+            await this.subscriber.quit();
+            this.subscriber = undefined;
+        }
+    }
+}
+exports.IoRedisWebReplAdapter = IoRedisWebReplAdapter;

package/dist/adapters/redis/node-redis-web-repl.adapter.d.ts

@@ -0,0 +1,24 @@
+import { BaseRedisWebReplAdapter } from './base-redis-web-repl.adapter';
+/** Minimal structural surface of a node-redis v4 client (no `redis` import). */
+export interface NodeRedisLike {
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, listener: (message: string, channel: string) => void): Promise<void>;
+    duplicate(): NodeRedisLike;
+    connect(): Promise<unknown>;
+    quit(): Promise<unknown>;
+}
+/**
+ * Redis adapter backed by node-redis v4. Pass one connected client (the
+ * publisher); the adapter duplicates it, connects the copy (v4 duplicates start
+ * disconnected), and owns that subscriber connection.
+ */
+export declare class NodeRedisWebReplAdapter extends BaseRedisWebReplAdapter {
+    private readonly publisher;
+    private subscriber?;
+    private connecting?;
+    constructor(publisher: NodeRedisLike);
+    private ensureSubscriber;
+    protected doPublish(topic: string, message: string): Promise<void>;
+    protected ensureSubscribed(topic: string): Promise<void>;
+    protected teardown(): Promise<void>;
+}

package/dist/adapters/redis/node-redis-web-repl.adapter.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeRedisWebReplAdapter = void 0;
+const base_redis_web_repl_adapter_1 = require("./base-redis-web-repl.adapter");
+/**
+ * Redis adapter backed by node-redis v4. Pass one connected client (the
+ * publisher); the adapter duplicates it, connects the copy (v4 duplicates start
+ * disconnected), and owns that subscriber connection.
+ */
+class NodeRedisWebReplAdapter extends base_redis_web_repl_adapter_1.BaseRedisWebReplAdapter {
+    constructor(publisher) {
+        super();
+        this.publisher = publisher;
+    }
+    async ensureSubscriber() {
+        if (this.subscriber)
+            return this.subscriber;
+        if (!this.connecting) {
+            const sub = this.publisher.duplicate();
+            this.connecting = sub.connect().then(() => {
+                this.subscriber = sub;
+                return sub;
+            });
+        }
+        return this.connecting;
+    }
+    async doPublish(topic, message) {
+        await this.publisher.publish(topic, message);
+    }
+    async ensureSubscribed(topic) {
+        const sub = await this.ensureSubscriber();
+        await sub.subscribe(topic, (message) => this.dispatch(topic, message));
+    }
+    async teardown() {
+        if (this.subscriber) {
+            await this.subscriber.quit();
+            this.subscriber = undefined;
+            this.connecting = undefined;
+        }
+    }
+}
+exports.NodeRedisWebReplAdapter = NodeRedisWebReplAdapter;

package/dist/redis.d.ts

@@ -0,0 +1 @@
+export * from './adapters/redis';

package/dist/redis.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./adapters/redis"), exports);

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "nestjs-web-repl",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Expose a live NestJS REPL over the network (HTTP + SSE + Monaco UI).",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./redis": {
+      "types": "./dist/redis.d.ts",
+      "default": "./dist/redis.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "redis": [
+        "dist/redis.d.ts"
+      ]
+    }
+  },
   "bin": {
     "nestjs-web-repl": "dist/cli/index.js"
   },
@@ -35,7 +53,17 @@
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11",
     "@nestjs/core": "^10 || ^11",
-    "rxjs": "^7"
+    "rxjs": "^7",
+    "ioredis": "^5",
+    "redis": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@nestjs/common": "^11",
@@ -47,6 +75,7 @@
     "@swc/core": "^1.15.43",
     "@types/node": "^20",
     "@types/supertest": "^6",
+    "ioredis-mock": "^8.13.1",
     "reflect-metadata": "^0.2",
     "rxjs": "^7",
     "semantic-release": "^25.0.8",

package/skill/SKILL.md

@@ -89,13 +89,14 @@ Open `http://localhost:3000/repl/main/ui` in a browser for the interactive UI.
   `@UseGuards(...)`, and pass it as `controller:` to `register`/`registerAsync`.
   See "Securing it" in the package README.
 - **Multiple app instances** (load-balanced replicas): the default in-memory
-  adapter is per-process; supply a shared adapter via the `adapter` extra
-  (a ready instance, `{ useClass, imports }`, or `{ useFactory, inject, imports }`)
-  so a command and its output reach the owning instance. See "Adapter /
-  multi-instance" in the package README.
-- **Custom adapter:** implement the adapter interface (publish/subscribe over
-  the message topics) and pass it via the `adapter` extra. See "Adapter /
-  multi-instance" in the README.
+  adapter is per-process. For Redis, import a ready-made adapter from the
+  `nestjs-web-repl/redis` subpath — `IoRedisWebReplAdapter` (ioredis) or
+  `NodeRedisWebReplAdapter` (node-redis) — and pass it as the `adapter` extra in
+  the same `register` call:
+  `register({ enabled, adapter: new IoRedisWebReplAdapter(client) })`. Hand it
+  one connected client; it owns its own subscriber connection. For any other
+  broker, supply a custom adapter (a ready instance, `{ useClass, imports }`, or
+  `{ useFactory, inject, imports }`). See "Adapter / multi-instance" in the README.
 - **Options** (base path, TTLs, heartbeats) and **exported symbols:** see
   "Options" and "Exports" in the README.
 - **Runnable example gotcha:** run examples with `ts-node`, not `tsx` —