@velajs/vela 1.16.0 → 1.17.1

package/dist/websocket/ws-dispatcher.js

@@ -24,7 +24,7 @@ import { MetadataRegistry } from "../registry/metadata.registry.js";
 import { resolveWsArgs } from "./ws-argument-resolver.js";
 import { buildWsExecutionContext } from "./ws-execution-context.js";
 import { toErrorFrame, WsException } from "./ws-exception.js";
-import { WS_GATEWAY_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA } from "./websocket.tokens.js";
+import { RESERVED_WS_EVENT_PREFIX, WS_GATEWAY_METADATA, WS_RESERVED_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA } from "./websocket.tokens.js";
 function hasAfterInit(x) {
     return typeof x?.afterInit === 'function';
 }
@@ -43,6 +43,7 @@ export class WsDispatcher {
     server;
     routeManager;
     gateways = new Map();
+    reserved = new Map();
     constructor(container, discovery, server, routeManager){
         this.container = container;
         this.discovery = discovery;
@@ -55,6 +56,19 @@ export class WsDispatcher {
         ];
     }
     async onApplicationBootstrap() {
+        // Reserved-event handlers first: modules claiming a `$…` event
+        // (@ReservedWsEvent) receive those frames across every gateway path.
+        for (const found of this.discovery.providersWithMeta(WS_RESERVED_METADATA)){
+            if (!found.instance) continue;
+            const event = found.meta.event;
+            if (this.reserved.has(event)) {
+                const msg = `[vela] duplicate @ReservedWsEvent('${event}') ` + `(${found.metatype.name}); keeping the first.`;
+                if (this.container.getDiagnostics() === 'throw') throw new Error(msg);
+                console.warn(msg);
+                continue;
+            }
+            this.reserved.set(event, found.instance);
+        }
         for (const found of this.discovery.providersWithMeta(WS_GATEWAY_METADATA)){
             if (!found.instance) continue;
             const gatewayClass = found.metatype;
@@ -98,6 +112,15 @@ export class WsDispatcher {
         }
     }
     async handleClose(path, client, _code, _reason) {
+        // Reserved handlers drop per-connection state first (isolated per handler)
+        // so a throwing gateway handleDisconnect can't leak live subscriptions.
+        for (const handler of this.reserved.values()){
+            try {
+                await handler.handleSocketClose?.(path, client);
+            } catch (err) {
+                await this.handleError(path, client, err);
+            }
+        }
         const entry = this.gateways.get(path);
         if (entry && hasHandleDisconnect(entry.instance)) {
             await entry.instance.handleDisconnect(client);
@@ -120,6 +143,13 @@ export class WsDispatcher {
             });
             return;
         }
+        // Reserved namespace: `$…` frames route to @ReservedWsEvent handlers
+        // (after app-wide guards) and NEVER reach gateway handlers; an unclaimed
+        // reserved event is dropped like any unknown event.
+        if (message.event.startsWith(RESERVED_WS_EVENT_PREFIX)) {
+            await this.dispatchReserved(path, client, message);
+            return;
+        }
         const handler = entry.handlers.get(message.event);
         if (!handler) return; // unknown event — ignored (NestJS parity)
         const ctx = buildWsExecutionContext(client, message.data, entry.gatewayClass, handler.methodName, message.event);
@@ -162,6 +192,31 @@ export class WsDispatcher {
             await this.runFilters(client, message, error, filters, ctx);
         }
     }
+    /**
+   * Route a reserved (`$…`) frame to its claiming handler. App-wide (`APP_*` /
+   * `useGlobalGuards`) guards protect reserved frames exactly like gateway
+   * messages — guards-first, WS convention; handler/class-tier components are
+   * the claiming module's own concern (e.g. live resolvers run their scoped
+   * guards at subscribe).
+   */ async dispatchReserved(path, client, message) {
+        const handler = this.reserved.get(message.event);
+        if (!handler) return;
+        const ctx = buildWsExecutionContext(client, message.data, handler.constructor, 'handleReservedEvent', message.event);
+        const globals = this.routeManager?.getGlobalComponents();
+        const guards = instantiateMany(globals?.guards ?? [], this.container);
+        try {
+            for (const guard of guards){
+                if (!await guard.canActivate(ctx)) {
+                    const frame = toErrorFrame(new WsException('Forbidden'));
+                    this.trySend(client, frame.event, frame.data, message.id);
+                    return;
+                }
+            }
+            await handler.handleReservedEvent(path, client, message);
+        } catch (err) {
+            await this.handleError(path, client, err);
+        }
+    }
     reply(client, message, result) {
         if (result === undefined || result === null) return;
         if (isWsResponse(result)) {
@@ -216,6 +271,14 @@ export class WsDispatcher {
         const allParams = MetadataRegistry.getParameters(ctor);
         const handlers = new Map();
         for (const { event, methodName } of subs){
+            // The `$` namespace belongs to framework modules (@ReservedWsEvent) — an
+            // app gateway subscribing to it would never receive the frames anyway.
+            if (event.startsWith(RESERVED_WS_EVENT_PREFIX)) {
+                const msg = `[vela] @SubscribeMessage('${event}') on ${gatewayClass.name}: the ` + `'${RESERVED_WS_EVENT_PREFIX}' event prefix is reserved for framework modules — skipped.`;
+                if (this.container.getDiagnostics() === 'throw') throw new Error(msg);
+                console.warn(msg);
+                continue;
+            }
             const paramMeta = [
                 ...allParams.get(methodName) ?? []
             ].sort((a, b)=>a.index - b.index);

package/dist/websocket-node/index.d.ts

@@ -2,3 +2,5 @@ export { NodeWsClient } from './node-ws-client';
 export { registerWebSocketGateways } from './register-gateways';
 export { redis } from './redis-sync';
 export type { RedisPubSubClient, RedisSyncOptions } from './redis-sync';
+export { redisLive } from './redis-live';
+export type { RedisLiveOptions } from './redis-live';

package/dist/websocket-node/index.js

@@ -3,3 +3,4 @@
 export { NodeWsClient } from "./node-ws-client.js";
 export { registerWebSocketGateways } from "./register-gateways.js";
 export { redis } from "./redis-sync.js";
+export { redisLive } from "./redis-live.js";

package/dist/websocket-node/redis-live.d.ts

@@ -0,0 +1,24 @@
+import type { LiveDriver } from '../live/index';
+import type { RedisPubSubClient } from './redis-sync';
+export interface RedisLiveOptions {
+    /** Connection used to publish invalidations. */
+    pub: RedisPubSubClient;
+    /** Separate connection kept in subscriber mode. */
+    sub: RedisPubSubClient;
+    /** Channel prefix. Default `vela:live`. */
+    prefix?: string;
+}
+/**
+ * Cross-instance live-invalidation driver for node/bun via Redis pub/sub —
+ * the live sibling of the WebSocket `redis()` sync driver, carrying TAGS
+ * instead of frames. Local-first: `dispatch` applies to this instance's
+ * engine immediately (its log stamps the returned commit cursor), then fans
+ * the command out so every peer re-runs ITS local subscriptions.
+ *
+ * Guarantees (same honesty as `redis()`): at-most-once, no cross-publisher
+ * ordering, no replay. Each instance keeps its own per-process epoch, so a
+ * client reconnecting onto a different instance always receives a full
+ * snapshot — exactly the protocol's multi-instance-node rule. Real cursor
+ * resume needs a shared ordered log (the Cloudflare DO transport).
+ */
+export declare function redisLive(options: RedisLiveOptions): LiveDriver;

package/dist/websocket-node/redis-live.js

@@ -0,0 +1,57 @@
+const swallow = (op)=>{
+    void Promise.resolve(op).catch(()=>{});
+};
+/**
+ * Cross-instance live-invalidation driver for node/bun via Redis pub/sub —
+ * the live sibling of the WebSocket `redis()` sync driver, carrying TAGS
+ * instead of frames. Local-first: `dispatch` applies to this instance's
+ * engine immediately (its log stamps the returned commit cursor), then fans
+ * the command out so every peer re-runs ITS local subscriptions.
+ *
+ * Guarantees (same honesty as `redis()`): at-most-once, no cross-publisher
+ * ordering, no replay. Each instance keeps its own per-process epoch, so a
+ * client reconnecting onto a different instance always receives a full
+ * snapshot — exactly the protocol's multi-instance-node rule. Real cursor
+ * resume needs a shared ordered log (the Cloudflare DO transport).
+ */ export function redisLive(options) {
+    const prefix = options.prefix ?? 'vela:live';
+    const channel = `${prefix}:invalidate`;
+    const origin = crypto.randomUUID();
+    let sink;
+    let bound = false;
+    const onMessage = (ch, message)=>{
+        if (ch !== channel) return;
+        let cmd;
+        try {
+            cmd = JSON.parse(message);
+        } catch  {
+            return;
+        }
+        if (cmd.origin === origin) return; // our own publish — already applied locally
+        if (sink) swallow(sink.applyInvalidation(cmd));
+    };
+    return {
+        kind: 'redis',
+        bind (boundSink) {
+            sink = boundSink;
+            if (bound) return; // idempotent — never stack duplicate 'message' listeners
+            bound = true;
+            swallow(options.sub.subscribe(channel));
+            options.sub.on('message', onMessage);
+        },
+        async dispatch (cmd) {
+            swallow(options.pub.publish(channel, JSON.stringify({
+                ...cmd,
+                origin
+            })));
+            return sink?.applyInvalidation(cmd);
+        },
+        stop () {
+            if (!bound) return;
+            bound = false;
+            options.sub.off?.('message', onMessage);
+            options.sub.removeListener?.('message', onMessage);
+            swallow(options.sub.unsubscribe?.(channel));
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,6 +38,10 @@
       "types": "./dist/queue/index.d.ts",
       "import": "./dist/queue/index.js"
     },
+    "./live": {
+      "types": "./dist/live/index.d.ts",
+      "import": "./dist/live/index.js"
+    },
     "./storage": {
       "types": "./dist/storage/index.d.ts",
       "import": "./dist/storage/index.js"
@@ -84,6 +88,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@velajs/live-protocol": "^1.0.0",
     "hono": "^4.12.26"
   },
   "peerDependencies": {