@velajs/cloudflare 1.5.0 → 1.6.0

package/dist/websocket/index.js

@@ -0,0 +1,13 @@
+// DO base class (imports `cloudflare:workers` — only runs in workerd).
+export { VelaWebSocketDurableObject } from "./websocket.durable-object.js";
+// Module + server-initiated emit helper
+export { CloudflareWebSocketModule } from "./cloudflare-websocket.module.js";
+export { broadcastToRoom } from "./broadcast.js";
+// Transport internals (advanced use / testing)
+export { CfWsClient } from "./cf-ws-client.js";
+export { CfRoomRegistry } from "./cf-room-registry.js";
+export { DoWebSocketHost } from "./do-websocket-host.js";
+export { WsServerHolder } from "./ws-server-holder.js";
+export { buildDoRuntime } from "./do-bootstrap.js";
+export { registerWebSocketRoutes, collectWsGatewayRoutes } from "./websocket-routing.js";
+export { roomTag, connTag, roomToDurableId } from "./room-id.js";

package/dist/websocket/room-id.d.ts

@@ -0,0 +1,6 @@
+/** Hibernation tag marking a socket's hub room (set at accept; immutable after). */
+export declare function roomTag(roomId: string): string;
+/** Hibernation tag addressing one connection directly. */
+export declare function connTag(connId: string): string;
+/** One Durable Object instance per room, addressed by name. */
+export declare function roomToDurableId(ns: DurableObjectNamespace, roomId: string): DurableObjectId;

package/dist/websocket/room-id.js

@@ -0,0 +1,12 @@
+// Canonical room ↔ Durable Object mappings. The SAME functions are used by the
+// Worker upgrade route (to pick the DO) and by every server-initiated emit — so
+// a connection and a later broadcast always resolve to the same DO instance.
+/** Hibernation tag marking a socket's hub room (set at accept; immutable after). */ export function roomTag(roomId) {
+    return `room:${roomId}`;
+}
+/** Hibernation tag addressing one connection directly. */ export function connTag(connId) {
+    return `conn:${connId}`;
+}
+/** One Durable Object instance per room, addressed by name. */ export function roomToDurableId(ns, roomId) {
+    return ns.idFromName(roomId);
+}

package/dist/websocket/websocket-routing.d.ts

@@ -0,0 +1,14 @@
+import type { Hono } from 'hono';
+export interface WsGatewayRoute {
+    path: string;
+    binding: string;
+}
+/** Read `@WebSocketGateway({ path, binding })` off a resolved instance (CF-hosted gateways only). */
+export declare function collectWsGatewayRoutes(instance: object): WsGatewayRoute[];
+/**
+ * Registers the upgrade routes on the Worker's Hono app. Each route validates
+ * the `Upgrade` header, resolves the room's Durable Object, and forwards the raw
+ * request — injecting spoof-safe `x-vela-*` headers the DO reads. The DO returns
+ * the `101` with the client socket.
+ */
+export declare function registerWebSocketRoutes(hono: Hono, routes: WsGatewayRoute[]): void;

package/dist/websocket/websocket-routing.js

@@ -0,0 +1,45 @@
+import { getMetadata } from "@velajs/vela";
+import { WS_GATEWAY_METADATA } from "@velajs/vela/websocket";
+import { roomToDurableId } from "./room-id.js";
+/** Read `@WebSocketGateway({ path, binding })` off a resolved instance (CF-hosted gateways only). */ export function collectWsGatewayRoutes(instance) {
+    const options = getMetadata(WS_GATEWAY_METADATA, instance.constructor);
+    if (!options?.path || !options?.binding) return [];
+    return [
+        {
+            path: options.path,
+            binding: options.binding
+        }
+    ];
+}
+/**
+ * Registers the upgrade routes on the Worker's Hono app. Each route validates
+ * the `Upgrade` header, resolves the room's Durable Object, and forwards the raw
+ * request — injecting spoof-safe `x-vela-*` headers the DO reads. The DO returns
+ * the `101` with the client socket.
+ */ export function registerWebSocketRoutes(hono, routes) {
+    for (const route of routes){
+        hono.get(route.path, async (c)=>{
+            if (c.req.header('upgrade')?.toLowerCase() !== 'websocket') {
+                return c.text('Expected WebSocket upgrade', 426);
+            }
+            const ns = c.env[route.binding];
+            if (!ns) {
+                return c.text(`Durable Object binding '${route.binding}' is not configured`, 500);
+            }
+            const roomId = c.req.param('id') ?? route.path;
+            const stub = ns.get(roomToDurableId(ns, roomId));
+            // Strip any client-supplied x-vela-* (anti-spoof), then set server values.
+            const headers = new Headers(c.req.raw.headers);
+            headers.delete('x-vela-room');
+            headers.delete('x-vela-path');
+            headers.delete('x-vela-user');
+            headers.set('x-vela-room', roomId);
+            headers.set('x-vela-path', route.path);
+            const userId = c.get('userId');
+            if (userId) headers.set('x-vela-user', String(userId));
+            return stub.fetch(new Request(c.req.raw, {
+                headers
+            }));
+        });
+    }
+}

package/dist/websocket/websocket.durable-object.d.ts

@@ -0,0 +1,15 @@
+import { DurableObject } from 'cloudflare:workers';
+import type { Type } from '@velajs/vela';
+/**
+ * Base class for the WebSocket Durable Object. The user exports a named subclass
+ * (matching their `wrangler.toml` `class_name`) built from their `AppModule`:
+ *
+ * ```ts
+ * export class ChatRoom extends VelaWebSocketDurableObject(AppModule) {}
+ * ```
+ *
+ * It owns the raw hibernation socket lifecycle (Hono's `upgradeWebSocket` cannot
+ * bridge DO hibernation) and forwards every event into the runtime-agnostic
+ * `WsDispatcher` via {@link DoWebSocketHost}.
+ */
+export declare function VelaWebSocketDurableObject(rootModule: Type): new (ctx: DurableObjectState, env: Record<string, unknown>) => DurableObject<Record<string, unknown>>;

package/dist/websocket/websocket.durable-object.js

@@ -0,0 +1,72 @@
+import { DurableObject } from "cloudflare:workers";
+import { buildDoRuntime } from "./do-bootstrap.js";
+import { DoWebSocketHost } from "./do-websocket-host.js";
+const PING = '{"event":"ping"}';
+const PONG = '{"event":"pong"}';
+/**
+ * Base class for the WebSocket Durable Object. The user exports a named subclass
+ * (matching their `wrangler.toml` `class_name`) built from their `AppModule`:
+ *
+ * ```ts
+ * export class ChatRoom extends VelaWebSocketDurableObject(AppModule) {}
+ * ```
+ *
+ * It owns the raw hibernation socket lifecycle (Hono's `upgradeWebSocket` cannot
+ * bridge DO hibernation) and forwards every event into the runtime-agnostic
+ * `WsDispatcher` via {@link DoWebSocketHost}.
+ */ export function VelaWebSocketDurableObject(rootModule) {
+    return class VelaWsDurableObject extends DurableObject {
+        host;
+        ready;
+        constructor(ctx, env){
+            super(ctx, env);
+            // Application-level ping/pong answered WITHOUT waking a hibernated DO.
+            try {
+                ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair(PING, PONG));
+            } catch  {
+            // Older runtimes without auto-response — fine, protocol pings still work.
+            }
+            this.ready = ctx.blockConcurrencyWhile(async ()=>{
+                const runtime = await buildDoRuntime(rootModule, ctx, env);
+                this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry);
+            });
+        }
+        async fetch(request) {
+            await this.ready;
+            if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+                return new Response('Expected WebSocket upgrade', {
+                    status: 426
+                });
+            }
+            const { 0: client, 1: server } = new WebSocketPair();
+            const url = new URL(request.url);
+            // Headers are primary (carry auth + multi-gateway routing); fall back to the
+            // DO's own name (set via idFromName(room)) and the single gateway path so a
+            // plain `stub.fetch(request)` forward still works.
+            const roomId = request.headers.get('x-vela-room') ?? this.ctx.id.name ?? url.pathname;
+            const path = request.headers.get('x-vela-path') ?? this.host.defaultPath() ?? url.pathname;
+            const userId = request.headers.get('x-vela-user') || undefined;
+            this.host.accept(server, path, roomId, userId);
+            return new Response(null, {
+                status: 101,
+                webSocket: client
+            });
+        }
+        async webSocketMessage(ws, message) {
+            await this.ready;
+            await this.host.onMessage(ws, message);
+        }
+        async webSocketClose(ws, code, reason) {
+            await this.ready;
+            await this.host.onClose(ws, code, reason);
+        }
+        async webSocketError(ws, error) {
+            await this.ready;
+            await this.host.onError(ws, error);
+        }
+        /** DO RPC — server-initiated broadcast forwarded from a Worker (see `broadcastToRoom`). */ async broadcast(cmd) {
+            await this.ready;
+            this.host.broadcast(cmd);
+        }
+    };
+}

package/dist/websocket/ws-server-holder.d.ts

@@ -0,0 +1,16 @@
+import type { BroadcastOperator, WsServer } from '@velajs/vela/websocket';
+/**
+ * Late-bound `WsServer`. Provided as `WS_SERVER` (one per DI container, i.e. per
+ * Durable Object instance), then pointed at the ctx-backed server once the DO
+ * builds. Gateways inject it via `@WebSocketServer()`; it throws if used before
+ * a runtime binds it (e.g. from the stateless Worker isolate).
+ */
+export declare class WsServerHolder implements WsServer {
+    private target?;
+    setTarget(server: WsServer): void;
+    private get resolved();
+    emit(event: string, data?: unknown): void | Promise<void>;
+    to(room: string): BroadcastOperator;
+    in(room: string): BroadcastOperator;
+    except(room: string): BroadcastOperator;
+}

package/dist/websocket/ws-server-holder.js

@@ -0,0 +1,34 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+import { Injectable } from "@velajs/vela";
+export class WsServerHolder {
+    target;
+    setTarget(server) {
+        this.target = server;
+    }
+    get resolved() {
+        if (!this.target) {
+            throw new Error('WebSocket server is only available inside a WebSocket Durable Object. To ' + 'push from a Worker HTTP handler, use broadcastToRoom(namespace, room, ...).');
+        }
+        return this.target;
+    }
+    emit(event, data) {
+        return this.resolved.emit(event, data);
+    }
+    to(room) {
+        return this.resolved.to(room);
+    }
+    in(room) {
+        return this.resolved.in(room);
+    }
+    except(room) {
+        return this.resolved.except(room);
+    }
+}
+WsServerHolder = _ts_decorate([
+    Injectable()
+], WsServerHolder);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,13 +17,6 @@
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepare": "swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
-    "prepublishOnly": "pnpm run typecheck && pnpm test"
-  },
   "sideEffects": false,
   "keywords": [
     "vela",
@@ -52,24 +45,22 @@
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/vela": ">=1.8.5",
+    "@velajs/vela": ">=1.10.0",
     "hono": ">=4"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260624.1",
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.43",
-    "@velajs/vela": "^1.8.5",
+    "@velajs/vela": "^1.10.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.9"
   },
-  "packageManager": "pnpm@10.20.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@swc/core",
-      "esbuild"
-    ]
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}