@velajs/cloudflare 1.5.0 → 1.6.0

package/dist/storage/storage.module.js

@@ -0,0 +1,37 @@
+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 { ConfigurableModuleBuilder, Module } from "@velajs/vela";
+import { EnvModule } from "../modules/env.module.js";
+import { StorageController } from "./storage.controller.js";
+import { StorageManagerService } from "./storage-manager.service.js";
+import { StorageService } from "./storage.service.js";
+import { STORAGE_OPTIONS } from "./storage.tokens.js";
+const { ConfigurableModuleClass } = new ConfigurableModuleBuilder({
+    moduleName: 'Storage',
+    optionsInjectionToken: STORAGE_OPTIONS
+}).build();
+export class StorageModule extends ConfigurableModuleClass {
+}
+StorageModule = _ts_decorate([
+    Module({
+        imports: [
+            EnvModule.forRoot()
+        ],
+        providers: [
+            StorageManagerService,
+            StorageService
+        ],
+        controllers: [
+            StorageController
+        ],
+        exports: [
+            StorageService,
+            StorageManagerService,
+            STORAGE_OPTIONS
+        ]
+    })
+], StorageModule);

package/dist/storage/storage.service.d.ts

@@ -0,0 +1,20 @@
+import { type DownloadResult, type PresignedUrlResult, type PresignMethod, type StorageBody, type UploadOptions, type UploadResult } from '@velajs/vela/storage';
+import { StorageManagerService } from './storage-manager.service';
+import type { StorageModuleOptions } from './storage.types';
+/**
+ * Multi-disk storage facade. Applies each disk's (templated) root, resolves the
+ * driver, and validates presign expiry. Injectable anywhere via `StorageService`.
+ */
+export declare class StorageService {
+    private readonly options;
+    private readonly manager;
+    constructor(options: StorageModuleOptions, manager: StorageManagerService);
+    put(relativePath: string, body: StorageBody, options?: UploadOptions, disk?: string): Promise<UploadResult>;
+    get(relativePath: string, disk?: string): Promise<DownloadResult>;
+    delete(relativePath: string, disk?: string): Promise<void>;
+    exists(relativePath: string, disk?: string): Promise<boolean>;
+    url(relativePath: string, method?: PresignMethod, expiresIn?: number, disk?: string): Promise<PresignedUrlResult>;
+    private resolveDisk;
+    private fullPath;
+    private validateExpiry;
+}

package/dist/storage/storage.service.js

@@ -0,0 +1,78 @@
+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;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable } from "@velajs/vela";
+import { joinStoragePath } from "@velajs/vela/storage";
+import { StorageManagerService } from "./storage-manager.service.js";
+import { STORAGE_OPTIONS } from "./storage.tokens.js";
+const DEFAULT_PRESIGN = {
+    defaultExpiry: 3600,
+    maxExpiry: 86400
+};
+export class StorageService {
+    options;
+    manager;
+    constructor(options, manager){
+        this.options = options;
+        this.manager = manager;
+    }
+    put(relativePath, body, options = {}, disk) {
+        const name = this.resolveDisk(disk);
+        return this.manager.getDriver(name).upload(body, this.fullPath(relativePath, name), options);
+    }
+    get(relativePath, disk) {
+        const name = this.resolveDisk(disk);
+        return this.manager.getDriver(name).download(this.fullPath(relativePath, name));
+    }
+    delete(relativePath, disk) {
+        const name = this.resolveDisk(disk);
+        return this.manager.getDriver(name).delete(this.fullPath(relativePath, name));
+    }
+    exists(relativePath, disk) {
+        const name = this.resolveDisk(disk);
+        return this.manager.getDriver(name).exists(this.fullPath(relativePath, name));
+    }
+    url(relativePath, method = 'GET', expiresIn, disk) {
+        const name = this.resolveDisk(disk);
+        return this.manager.getDriver(name).getPresignedUrl(this.fullPath(relativePath, name), method, this.validateExpiry(expiresIn));
+    }
+    resolveDisk(disk) {
+        const name = disk ?? this.options.defaultDisk;
+        if (!this.manager.hasDisk(name)) throw new Error(`Storage disk "${name}" is not configured.`);
+        return name;
+    }
+    fullPath(relativePath, disk) {
+        return joinStoragePath(this.manager.getDiskConfig(disk).root, relativePath);
+    }
+    validateExpiry(expiresIn) {
+        const cfg = this.options.presignedUrl ?? DEFAULT_PRESIGN;
+        const value = expiresIn ?? cfg.defaultExpiry;
+        // `Number.isFinite` rejects NaN — otherwise `NaN < 1 || NaN > max` is false,
+        // NaN slips through, signUrl omits `expires`, and the URL never expires.
+        if (!Number.isFinite(value) || value < 1 || value > cfg.maxExpiry) {
+            throw new Error(`Presigned URL expiry ${value}s is out of range (1–${cfg.maxExpiry}s).`);
+        }
+        return value;
+    }
+}
+StorageService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(STORAGE_OPTIONS)),
+    _ts_param(1, Inject(StorageManagerService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof StorageModuleOptions === "undefined" ? Object : StorageModuleOptions,
+        typeof StorageManagerService === "undefined" ? Object : StorageManagerService
+    ])
+], StorageService);

package/dist/storage/storage.tokens.d.ts

@@ -0,0 +1,3 @@
+import { InjectionToken } from '@velajs/vela';
+import type { StorageModuleOptions } from './storage.types';
+export declare const STORAGE_OPTIONS: InjectionToken<StorageModuleOptions>;

package/dist/storage/storage.tokens.js

@@ -0,0 +1,2 @@
+import { InjectionToken } from "@velajs/vela";
+export const STORAGE_OPTIONS = new InjectionToken('STORAGE_OPTIONS');

package/dist/storage/storage.types.d.ts

@@ -0,0 +1,17 @@
+/** A named storage disk backed by an R2 bucket binding. */
+export interface DiskConfig {
+    disk: string;
+    /** R2Bucket binding name from wrangler.toml. */
+    binding: string;
+    /** Optional root prefix; supports path-template tokens ({date}/{year}/…). */
+    root?: string;
+}
+export interface PresignedUrlConfig {
+    defaultExpiry: number;
+    maxExpiry: number;
+}
+export interface StorageModuleOptions {
+    disks: DiskConfig[];
+    defaultDisk: string;
+    presignedUrl?: PresignedUrlConfig;
+}

package/dist/storage/storage.types.js

@@ -0,0 +1 @@
+/** A named storage disk backed by an R2 bucket binding. */ export { };

package/dist/websocket/broadcast.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Push to a room from a Worker HTTP handler / cron / queue consumer (server-
+ * initiated emit). Resolves the room's Durable Object and calls its `broadcast`
+ * RPC method — the same canonical room→DO mapping the upgrade route uses, so it
+ * always reaches the DO holding those sockets.
+ *
+ * @example
+ * ```ts
+ * // In a controller — ns from DurableObjectService.namespace
+ * await broadcastToRoom(ns, `org:${id}`, 'order.created', order);
+ * ```
+ */
+export declare function broadcastToRoom(ns: DurableObjectNamespace, room: string, event: string, data?: unknown, options?: {
+    exceptIds?: string[];
+}): Promise<void>;

package/dist/websocket/broadcast.js

@@ -0,0 +1,26 @@
+import { roomToDurableId } from "./room-id.js";
+/**
+ * Push to a room from a Worker HTTP handler / cron / queue consumer (server-
+ * initiated emit). Resolves the room's Durable Object and calls its `broadcast`
+ * RPC method — the same canonical room→DO mapping the upgrade route uses, so it
+ * always reaches the DO holding those sockets.
+ *
+ * @example
+ * ```ts
+ * // In a controller — ns from DurableObjectService.namespace
+ * await broadcastToRoom(ns, `org:${id}`, 'order.created', order);
+ * ```
+ */ export async function broadcastToRoom(ns, room, event, data, options) {
+    const cmd = {
+        rooms: [
+            room
+        ],
+        exceptIds: options?.exceptIds,
+        frame: JSON.stringify({
+            event,
+            data
+        })
+    };
+    const stub = ns.get(roomToDurableId(ns, room));
+    await stub.broadcast(cmd);
+}

package/dist/websocket/cf-room-registry.d.ts

@@ -0,0 +1,23 @@
+import type { BroadcastCommand, RoomRegistry, WsClient } from '@velajs/vela/websocket';
+import type { DoStateLike, WsLike } from './do-state';
+/**
+ * Core `RoomRegistry` backed by a Durable Object's hibernatable sockets. Room
+ * membership lives in tags (hub room, set at accept) + the attachment (dynamic
+ * `join()`), never in DO instance fields — so it survives hibernation with zero
+ * rehydration.
+ */
+export declare class CfRoomRegistry implements RoomRegistry {
+    private readonly ctx;
+    constructor(ctx: DoStateLike);
+    register(_client: WsClient): void;
+    leaveAll(_client: WsClient): void;
+    join(client: WsClient, room: string): void | Promise<void>;
+    leave(client: WsClient, room: string): void | Promise<void>;
+    localIdsInRoom(room: string): string[];
+    deliverLocal(cmd: BroadcastCommand): void;
+    private collectRooms;
+    private socketsForRoom;
+    private attachmentOf;
+    /** Reconstruct a `WsClient` for a raw socket (e.g. inside gateway lifecycle scans). */
+    clientFor(ws: WsLike): WsClient;
+}

package/dist/websocket/cf-room-registry.js

@@ -0,0 +1,65 @@
+import { CfWsClient } from "./cf-ws-client.js";
+/**
+ * Core `RoomRegistry` backed by a Durable Object's hibernatable sockets. Room
+ * membership lives in tags (hub room, set at accept) + the attachment (dynamic
+ * `join()`), never in DO instance fields — so it survives hibernation with zero
+ * rehydration.
+ */ export class CfRoomRegistry {
+    ctx;
+    constructor(ctx){
+        this.ctx = ctx;
+    }
+    // CF sockets are registered with the DO by `acceptWebSocket`; nothing to track.
+    register(_client) {}
+    leaveAll(_client) {}
+    join(client, room) {
+        return client.join(room);
+    }
+    leave(client, room) {
+        return client.leave(room);
+    }
+    localIdsInRoom(room) {
+        return this.socketsForRoom(room).map((ws)=>this.attachmentOf(ws).connId);
+    }
+    deliverLocal(cmd) {
+        const excludeIds = new Set(cmd.exceptIds ?? []);
+        const excludeRooms = cmd.exceptRooms ?? [];
+        // Empty `rooms` => GLOBAL (every socket in this DO). Otherwise the union of
+        // targeted rooms, deduped per connection.
+        const targets = cmd.rooms.length === 0 ? this.ctx.getWebSockets() : this.collectRooms(cmd.rooms);
+        const seen = new Set();
+        for (const ws of targets){
+            const att = this.attachmentOf(ws);
+            if (seen.has(att.connId)) continue;
+            seen.add(att.connId);
+            if (excludeIds.has(att.connId)) continue;
+            if (excludeRooms.some((r)=>att.rooms.includes(r))) continue;
+            ws.send(cmd.frame);
+        }
+    }
+    collectRooms(rooms) {
+        const set = new Set();
+        for (const room of rooms)for (const ws of this.socketsForRoom(room))set.add(ws);
+        return [
+            ...set
+        ];
+    }
+    socketsForRoom(room) {
+        // Membership is the attachment's `rooms`, NOT the hibernation tag: tags are
+        // immutable after acceptWebSocket, so a socket that left its hub room still
+        // carries the tag. Since one DO ≈ one room, scanning all sockets in the DO
+        // and filtering by attachment is both correct and cheap.
+        return this.ctx.getWebSockets().filter((ws)=>this.attachmentOf(ws).rooms.includes(room));
+    }
+    attachmentOf(ws) {
+        return ws.deserializeAttachment() ?? {
+            connId: '',
+            path: '',
+            rooms: [],
+            data: {}
+        };
+    }
+    /** Reconstruct a `WsClient` for a raw socket (e.g. inside gateway lifecycle scans). */ clientFor(ws) {
+        return new CfWsClient(this.ctx, ws);
+    }
+}

package/dist/websocket/cf-ws-client.d.ts

@@ -0,0 +1,28 @@
+import type { WsClient } from '@velajs/vela/websocket';
+import type { DoStateLike, WsLike } from './do-state';
+/**
+ * Core `WsClient` over a native Cloudflare `WebSocket` inside a Durable Object.
+ * Per-connection state lives in the hibernation attachment (survives eviction),
+ * so a fresh `CfWsClient` is reconstructed per message with no in-memory state.
+ */
+export declare class CfWsClient<TData extends Record<string, unknown> = Record<string, unknown>> implements WsClient<TData> {
+    private readonly ctx;
+    private readonly ws;
+    private readonly attachment;
+    constructor(ctx: DoStateLike, ws: WsLike);
+    get id(): string;
+    /** The gateway route path this socket connected on (used to route messages). */
+    get path(): string;
+    get rooms(): ReadonlySet<string>;
+    get data(): TData;
+    set data(value: TData);
+    get raw(): unknown;
+    send(event: string, data?: unknown, id?: string): void;
+    sendRaw(payload: string): void;
+    join(room: string): void;
+    leave(room: string): void;
+    /** Persist `data`/room mutations to the hibernation attachment. */
+    commit(): void;
+    close(code?: number, reason?: string): void;
+    private persist;
+}

package/dist/websocket/cf-ws-client.js

@@ -0,0 +1,83 @@
+const MAX_ATTACHMENT_BYTES = 16_384; // Cloudflare hibernation attachment limit (16 KiB).
+const encoder = new TextEncoder();
+const EMPTY = {
+    connId: '',
+    path: '',
+    rooms: [],
+    data: {}
+};
+/**
+ * Core `WsClient` over a native Cloudflare `WebSocket` inside a Durable Object.
+ * Per-connection state lives in the hibernation attachment (survives eviction),
+ * so a fresh `CfWsClient` is reconstructed per message with no in-memory state.
+ */ export class CfWsClient {
+    ctx;
+    ws;
+    attachment;
+    constructor(ctx, ws){
+        this.ctx = ctx;
+        this.ws = ws;
+        const raw = ws.deserializeAttachment();
+        this.attachment = raw ?? {
+            ...EMPTY,
+            data: {}
+        };
+    }
+    get id() {
+        return this.attachment.connId;
+    }
+    /** The gateway route path this socket connected on (used to route messages). */ get path() {
+        return this.attachment.path;
+    }
+    get rooms() {
+        return new Set(this.attachment.rooms);
+    }
+    get data() {
+        return this.attachment.data;
+    }
+    set data(value) {
+        this.attachment.data = value;
+    }
+    get raw() {
+        return this.ws;
+    }
+    send(event, data, id) {
+        this.ws.send(JSON.stringify(id !== undefined ? {
+            id,
+            event,
+            data
+        } : {
+            event,
+            data
+        }));
+    }
+    sendRaw(payload) {
+        this.ws.send(payload);
+    }
+    join(room) {
+        if (!this.attachment.rooms.includes(room)) {
+            this.attachment.rooms.push(room);
+            this.persist();
+        }
+    }
+    leave(room) {
+        const next = this.attachment.rooms.filter((r)=>r !== room);
+        if (next.length !== this.attachment.rooms.length) {
+            this.attachment.rooms = next;
+            this.persist();
+        }
+    }
+    /** Persist `data`/room mutations to the hibernation attachment. */ commit() {
+        this.persist();
+    }
+    close(code, reason) {
+        this.ws.close(code, reason);
+    }
+    persist() {
+        const serialized = JSON.stringify(this.attachment);
+        if (encoder.encode(serialized).length > MAX_ATTACHMENT_BYTES) {
+            throw new Error(`WebSocket attachment exceeds the 16 KiB Cloudflare limit. Store large ` + `per-connection state in Durable Object storage keyed by connId instead.`);
+        }
+        this.ws.serializeAttachment(this.attachment);
+    }
+}

package/dist/websocket/cloudflare-websocket.module.d.ts

@@ -0,0 +1,11 @@
+import type { DynamicModule } from '@velajs/vela';
+/**
+ * Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
+ * your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
+ * `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
+ * ctx-backed server per instance. `useClass` ensures a fresh holder per DI
+ * container so colocated DO instances never share a server.
+ */
+export declare class CloudflareWebSocketModule {
+    static forRoot(): DynamicModule;
+}

package/dist/websocket/cloudflare-websocket.module.js

@@ -0,0 +1,27 @@
+import { WsDispatcher, WS_SERVER } from "@velajs/vela/websocket";
+import { WsServerHolder } from "./ws-server-holder.js";
+/**
+ * Cloudflare counterpart to the core `WebSocketModule.forRoot()`. Import this in
+ * your `AppModule` instead: it provides the gateway dispatcher plus a late-bound
+ * `WS_SERVER` (`WsServerHolder`) that the WebSocket Durable Object wires to a
+ * ctx-backed server per instance. `useClass` ensures a fresh holder per DI
+ * container so colocated DO instances never share a server.
+ */ export class CloudflareWebSocketModule {
+    static forRoot() {
+        const providers = [
+            {
+                provide: WS_SERVER,
+                useClass: WsServerHolder
+            },
+            WsDispatcher
+        ];
+        return {
+            module: CloudflareWebSocketModule,
+            providers,
+            exports: [
+                WS_SERVER,
+                WsDispatcher
+            ]
+        };
+    }
+}

package/dist/websocket/do-bootstrap.d.ts

@@ -0,0 +1,19 @@
+import type { Type } from '@velajs/vela';
+import { WsDispatcher } from '@velajs/vela/websocket';
+import type { WsServer } from '@velajs/vela/websocket';
+import { CfRoomRegistry } from './cf-room-registry';
+import type { DoStateLike } from './do-state';
+export interface DoRuntime {
+    dispatcher: WsDispatcher;
+    registry: CfRoomRegistry;
+    server: WsServer;
+    close(signal?: string): Promise<void>;
+}
+/**
+ * Slim DI bootstrap for the Durable Object isolate: wires the container and runs
+ * `OnModuleInit`/`OnApplicationBootstrap` (so `WsDispatcher` discovers gateways)
+ * WITHOUT building the Hono app/routes the DO never serves. Cloudflare binding
+ * refs are initialized straight from the DO's `env`, and the ctx-backed server
+ * is bound before bootstrap lifecycle so gateway `afterInit`/handlers see it.
+ */
+export declare function buildDoRuntime(rootModule: Type, ctx: DoStateLike, env: Record<string, unknown>): Promise<DoRuntime>;

package/dist/websocket/do-bootstrap.js

@@ -0,0 +1,43 @@
+import { bootstrap, VelaApplication } from "@velajs/vela";
+import { local, WsDispatcher, WsServerImpl, WS_SERVER } from "@velajs/vela/websocket";
+import { BindingRef } from "../binding-ref.js";
+import { EnvRef } from "../env-ref.js";
+import { CfRoomRegistry } from "./cf-room-registry.js";
+import { WsServerHolder } from "./ws-server-holder.js";
+/**
+ * Slim DI bootstrap for the Durable Object isolate: wires the container and runs
+ * `OnModuleInit`/`OnApplicationBootstrap` (so `WsDispatcher` discovers gateways)
+ * WITHOUT building the Hono app/routes the DO never serves. Cloudflare binding
+ * refs are initialized straight from the DO's `env`, and the ctx-backed server
+ * is bound before bootstrap lifecycle so gateway `afterInit`/handlers see it.
+ */ export async function buildDoRuntime(rootModule, ctx, env) {
+    const { container, routeManager, loader } = await bootstrap(rootModule);
+    // Init binding refs from env directly (no request middleware inside a DO).
+    // Enumerate per-instance useValue providers across ALL module buckets — two
+    // same-type binding modules share one token but live in distinct buckets, so
+    // resolving the token would return only the first and leave the rest uninitialized.
+    for (const value of container.getUseValues()){
+        if (value instanceof EnvRef) value._initialize(env);
+        else if (value instanceof BindingRef) value._initialize(env[value.bindingName]);
+    }
+    const registry = new CfRoomRegistry(ctx);
+    const driver = local();
+    driver.bind(registry);
+    const server = new WsServerImpl(driver);
+    try {
+        const holder = container.resolve(WS_SERVER);
+        if (holder instanceof WsServerHolder) holder.setTarget(server);
+    } catch  {
+    // CloudflareWebSocketModule not imported — gateways won't have a server.
+    }
+    const app = new VelaApplication(container, routeManager);
+    app.setInstances(await loader.resolveAllInstances());
+    await app.callOnModuleInit();
+    await app.callOnApplicationBootstrap();
+    return {
+        dispatcher: app.get(WsDispatcher),
+        registry,
+        server,
+        close: (signal)=>app.close(signal)
+    };
+}

package/dist/websocket/do-state.d.ts

@@ -0,0 +1,25 @@
+export interface WsLike {
+    send(message: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    serializeAttachment(value: unknown): void;
+    deserializeAttachment(): unknown;
+}
+export interface DoStateLike {
+    readonly id: {
+        toString(): string;
+        readonly name?: string | null;
+    };
+    acceptWebSocket(ws: WsLike, tags?: string[]): void;
+    getWebSockets(tag?: string): WsLike[];
+    setWebSocketAutoResponse?(pair: unknown): void;
+}
+/** Per-connection metadata persisted in the hibernation attachment (≤ 16 KiB). */
+export interface WsAttachment {
+    connId: string;
+    userId?: string;
+    /** The gateway route path this socket belongs to — used to route messages. */
+    path: string;
+    /** Dynamically-joined room names (the hub room is also a hibernation tag). */
+    rooms: string[];
+    data: Record<string, unknown>;
+}

package/dist/websocket/do-state.js

@@ -0,0 +1,4 @@
+// Minimal structural views of the Durable Object runtime, so the transport
+// logic is unit-testable in Node with fakes. Real `DurableObjectState` and
+// `WebSocket` (from @cloudflare/workers-types) satisfy these structurally.
+/** Per-connection metadata persisted in the hibernation attachment (≤ 16 KiB). */ export { };

package/dist/websocket/do-websocket-host.d.ts

@@ -0,0 +1,27 @@
+import type { BroadcastCommand, WsDispatcher } from '@velajs/vela/websocket';
+import type { CfRoomRegistry } from './cf-room-registry';
+import type { DoStateLike, WsLike } from './do-state';
+/**
+ * The socket lifecycle inside a WebSocket Durable Object, decoupled from the
+ * `cloudflare:workers` base class so it is unit-testable with fakes. The thin
+ * `VelaWebSocketDurableObject` shell forwards its hibernation callbacks here.
+ */
+export declare class DoWebSocketHost {
+    private readonly ctx;
+    private readonly dispatcher;
+    private readonly registry;
+    constructor(ctx: DoStateLike, dispatcher: WsDispatcher, registry: CfRoomRegistry);
+    /** The single registered gateway's path — a fallback when the Worker didn't forward `x-vela-path`. */
+    defaultPath(): string | undefined;
+    /**
+     * Accept a hibernatable socket: tag it with its hub room + connection id,
+     * persist the attachment, then fire `OnGatewayConnection` WITHOUT blocking the
+     * 101 response (the caller returns it immediately).
+     */
+    accept(ws: WsLike, path: string, roomId: string, userId?: string): void;
+    onMessage(ws: WsLike, message: string | ArrayBuffer): Promise<void>;
+    onClose(ws: WsLike, code: number, reason: string): Promise<void>;
+    onError(ws: WsLike, err: unknown): Promise<void>;
+    /** Deliver a broadcast command to this DO's local sockets (RPC entry point). */
+    broadcast(cmd: BroadcastCommand): void;
+}

package/dist/websocket/do-websocket-host.js

@@ -0,0 +1,67 @@
+import { CfWsClient } from "./cf-ws-client.js";
+import { connTag, roomTag } from "./room-id.js";
+/**
+ * The socket lifecycle inside a WebSocket Durable Object, decoupled from the
+ * `cloudflare:workers` base class so it is unit-testable with fakes. The thin
+ * `VelaWebSocketDurableObject` shell forwards its hibernation callbacks here.
+ */ export class DoWebSocketHost {
+    ctx;
+    dispatcher;
+    registry;
+    constructor(ctx, dispatcher, registry){
+        this.ctx = ctx;
+        this.dispatcher = dispatcher;
+        this.registry = registry;
+    }
+    /** The single registered gateway's path — a fallback when the Worker didn't forward `x-vela-path`. */ defaultPath() {
+        return this.dispatcher.gatewayPaths[0];
+    }
+    /**
+   * Accept a hibernatable socket: tag it with its hub room + connection id,
+   * persist the attachment, then fire `OnGatewayConnection` WITHOUT blocking the
+   * 101 response (the caller returns it immediately).
+   */ accept(ws, path, roomId, userId) {
+        const connId = crypto.randomUUID();
+        this.ctx.acceptWebSocket(ws, [
+            roomTag(roomId),
+            connTag(connId)
+        ]);
+        const attachment = {
+            connId,
+            userId,
+            path,
+            rooms: [
+                roomId
+            ],
+            data: userId ? {
+                userId
+            } : {}
+        };
+        ws.serializeAttachment(attachment);
+        void Promise.resolve(this.dispatcher.handleOpen(path, new CfWsClient(this.ctx, ws))).catch((err)=>console.warn('[vela] websocket handleConnection failed:', err));
+    }
+    async onMessage(ws, message) {
+        const client = new CfWsClient(this.ctx, ws);
+        await this.dispatcher.dispatchMessage(client.path, client, message);
+    }
+    async onClose(ws, code, reason) {
+        const client = new CfWsClient(this.ctx, ws);
+        await this.dispatcher.handleClose(client.path, client, code, reason);
+        // Complete the closing handshake. Only 1000 and 3000-4999 are valid for
+        // close(); reserved/abnormal codes (1005/1006/1015, etc.) throw a RangeError,
+        // so fall back to a codeless close on those.
+        try {
+            if (code === 1000 || code >= 3000 && code <= 4999) ws.close(code, reason);
+            else ws.close();
+        } catch  {
+        // socket already closed
+        }
+    }
+    async onError(ws, err) {
+        const client = new CfWsClient(this.ctx, ws);
+        await this.dispatcher.handleError(client.path, client, err);
+    }
+    /** Deliver a broadcast command to this DO's local sockets (RPC entry point). */ broadcast(cmd) {
+        this.registry.deliverLocal(cmd);
+    }
+}

package/dist/websocket/index.d.ts

@@ -0,0 +1,13 @@
+export { VelaWebSocketDurableObject } from './websocket.durable-object';
+export { CloudflareWebSocketModule } from './cloudflare-websocket.module';
+export { broadcastToRoom } from './broadcast';
+export { CfWsClient } from './cf-ws-client';
+export { CfRoomRegistry } from './cf-room-registry';
+export { DoWebSocketHost } from './do-websocket-host';
+export { WsServerHolder } from './ws-server-holder';
+export { buildDoRuntime } from './do-bootstrap';
+export type { DoRuntime } from './do-bootstrap';
+export { registerWebSocketRoutes, collectWsGatewayRoutes } from './websocket-routing';
+export type { WsGatewayRoute } from './websocket-routing';
+export { roomTag, connTag, roomToDurableId } from './room-id';
+export type { DoStateLike, WsLike, WsAttachment } from './do-state';