@velajs/cloudflare 1.5.0 → 1.8.0

package/dist/storage/r2-storage.driver.d.ts

@@ -0,0 +1,19 @@
+import { type DownloadResult, type PresignedUrlResult, type PresignMethod, type StorageBody, type StorageDriver, type UploadOptions, type UploadResult } from '@velajs/vela/storage';
+/** Base path of the StorageController presign-proxy route. */
+export declare const STORAGE_ROUTE_BASE = "/storage";
+export interface R2StorageDriverConfig {
+    disk: string;
+    bucket: R2Bucket;
+    /** HMAC secret for presigned URLs (typically env.APP_SECRET). */
+    secret?: string;
+}
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */
+export declare class R2StorageDriver implements StorageDriver {
+    private readonly config;
+    constructor(config: R2StorageDriverConfig);
+    upload(body: StorageBody, path: string, options: UploadOptions): Promise<UploadResult>;
+    download(path: string): Promise<DownloadResult>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getPresignedUrl(path: string, method: PresignMethod, expiresIn: number): Promise<PresignedUrlResult>;
+}

package/dist/storage/r2-storage.driver.js

@@ -0,0 +1,61 @@
+import { signUrl } from "@velajs/vela/storage";
+/** Base path of the StorageController presign-proxy route. */ export const STORAGE_ROUTE_BASE = '/storage';
+/** {@link StorageDriver} over a Cloudflare R2 bucket. */ export class R2StorageDriver {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async upload(body, path, options) {
+        await this.config.bucket.put(path, body, {
+            httpMetadata: options.mimeType ? {
+                contentType: options.mimeType
+            } : undefined,
+            customMetadata: options.metadata
+        });
+        return {
+            path,
+            disk: this.config.disk,
+            size: options.size,
+            mimeType: options.mimeType ?? 'application/octet-stream',
+            uploadedAt: new Date()
+        };
+    }
+    async download(path) {
+        const obj = await this.config.bucket.get(path);
+        if (!obj) throw new Error(`Storage object not found at "${path}".`);
+        return {
+            toStream: ()=>obj.body,
+            toArrayBuffer: ()=>obj.arrayBuffer(),
+            toText: ()=>obj.text(),
+            contentType: obj.httpMetadata?.contentType ?? 'application/octet-stream',
+            size: obj.size,
+            metadata: obj.customMetadata
+        };
+    }
+    async delete(path) {
+        await this.config.bucket.delete(path);
+    }
+    async exists(path) {
+        return await this.config.bucket.head(path) !== null;
+    }
+    async getPresignedUrl(path, method, expiresIn) {
+        if (!this.config.secret) {
+            throw new Error('A signing secret is required for presigned URLs (set APP_SECRET).');
+        }
+        // Defend the direct-driver path too: a non-finite/non-positive expiry would
+        // make signUrl omit `expires`, yielding a never-expiring URL.
+        if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+            throw new Error(`Invalid presigned URL expiry: ${expiresIn}s (must be a positive number).`);
+        }
+        const routePath = `${STORAGE_ROUTE_BASE}/${this.config.disk}/${path}`;
+        const url = await signUrl(`${routePath}?method=${method}`, this.config.secret, {
+            expiresIn
+        });
+        return {
+            url,
+            method,
+            expiresIn,
+            expiresAt: new Date(Date.now() + expiresIn * 1000)
+        };
+    }
+}

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

@@ -0,0 +1,16 @@
+import { EnvService } from '../services/env.service';
+import { R2StorageDriver } from './r2-storage.driver';
+import type { DiskConfig, StorageModuleOptions } from './storage.types';
+/**
+ * Resolves R2 buckets by binding NAME (via {@link EnvService}) so multiple disks
+ * coexist without registering N R2Modules. Drivers are created per call — cheap,
+ * and avoids caching a per-request env value on this singleton.
+ */
+export declare class StorageManagerService {
+    private readonly options;
+    private readonly env;
+    constructor(options: StorageModuleOptions, env: EnvService);
+    hasDisk(disk: string): boolean;
+    getDiskConfig(disk: string): DiskConfig;
+    getDriver(disk: string): R2StorageDriver;
+}

package/dist/storage/storage-manager.service.js

@@ -0,0 +1,56 @@
+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 { EnvService } from "../services/env.service.js";
+import { R2StorageDriver } from "./r2-storage.driver.js";
+import { STORAGE_OPTIONS } from "./storage.tokens.js";
+export class StorageManagerService {
+    options;
+    env;
+    constructor(options, env){
+        this.options = options;
+        this.env = env;
+    }
+    hasDisk(disk) {
+        return this.options.disks.some((d)=>d.disk === disk);
+    }
+    getDiskConfig(disk) {
+        const config = this.options.disks.find((d)=>d.disk === disk);
+        if (!config) throw new Error(`Storage disk "${disk}" is not configured.`);
+        return config;
+    }
+    getDriver(disk) {
+        const config = this.getDiskConfig(disk);
+        const bucket = this.env.get(config.binding);
+        if (!bucket) {
+            throw new Error(`R2 binding "${config.binding}" for disk "${disk}" was not found in env.`);
+        }
+        return new R2StorageDriver({
+            disk,
+            bucket,
+            secret: this.env.get('APP_SECRET')
+        });
+    }
+}
+StorageManagerService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(STORAGE_OPTIONS)),
+    _ts_param(1, Inject(EnvService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof StorageModuleOptions === "undefined" ? Object : StorageModuleOptions,
+        typeof EnvService === "undefined" ? Object : EnvService
+    ])
+], StorageManagerService);

package/dist/storage/storage.controller.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from 'hono';
+import { EnvService } from '../services/env.service';
+import { StorageManagerService } from './storage-manager.service';
+/**
+ * Presign-proxy: serves objects for HMAC-signed URLs produced by
+ * `StorageService.url()`. R2 has no native presign, so a signed URL points here;
+ * this route verifies the signature (+expiry) before streaming the object.
+ * The wildcard is the FULL object path (root already applied at sign time), so
+ * it is passed straight to the driver.
+ */
+export declare class StorageController {
+    private readonly manager;
+    private readonly env;
+    constructor(manager: StorageManagerService, env: EnvService);
+    download(c: Context): Promise<Response>;
+}

package/dist/storage/storage.controller.js

@@ -0,0 +1,88 @@
+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 { Controller, Get, Inject, Req } from "@velajs/vela";
+import { verifySignedUrl } from "@velajs/vela/storage";
+import { EnvService } from "../services/env.service.js";
+import { StorageManagerService } from "./storage-manager.service.js";
+export class StorageController {
+    manager;
+    env;
+    constructor(manager, env){
+        this.manager = manager;
+        this.env = env;
+    }
+    async download(c) {
+        const secret = this.env.get('APP_SECRET');
+        if (!secret) return new Response('Storage signing is not configured', {
+            status: 500
+        });
+        const disk = c.req.param('disk');
+        if (!disk || !this.manager.hasDisk(disk)) return new Response('Unknown disk', {
+            status: 404
+        });
+        if (!await verifySignedUrl(c.req.url, secret)) {
+            return new Response('Invalid or expired URL', {
+                status: 403
+            });
+        }
+        // Enforce the signed `method` scope: this proxy only serves reads, so a URL
+        // scoped to PUT/DELETE/HEAD must NOT be honored as a GET (it would over-grant
+        // read access relative to the token's intended scope). The param is part of
+        // the signed payload, so it is trustworthy once the signature verifies.
+        const url = new URL(c.req.url);
+        if ((url.searchParams.get('method') ?? 'GET') !== 'GET') {
+            return new Response('URL is not scoped for reads', {
+                status: 403
+            });
+        }
+        // The object key is everything after `/storage/:disk/` (Hono doesn't expose
+        // the `*` wildcard via param()). The key already includes the disk root.
+        const { pathname } = url;
+        const prefix = `/storage/${disk}/`;
+        const idx = pathname.indexOf(prefix);
+        const fullPath = idx >= 0 ? decodeURIComponent(pathname.slice(idx + prefix.length)) : '';
+        try {
+            const result = await this.manager.getDriver(disk).download(fullPath);
+            return new Response(result.toStream(), {
+                headers: {
+                    'content-type': result.contentType
+                }
+            });
+        } catch  {
+            return new Response('Not found', {
+                status: 404
+            });
+        }
+    }
+}
+_ts_decorate([
+    Get('/:disk/*'),
+    _ts_param(0, Req()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Context === "undefined" ? Object : Context
+    ]),
+    _ts_metadata("design:returntype", Promise)
+], StorageController.prototype, "download", null);
+StorageController = _ts_decorate([
+    Controller('storage'),
+    _ts_param(0, Inject(StorageManagerService)),
+    _ts_param(1, Inject(EnvService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof StorageManagerService === "undefined" ? Object : StorageManagerService,
+        typeof EnvService === "undefined" ? Object : EnvService
+    ])
+], StorageController);

package/dist/storage/storage.module.d.ts

@@ -0,0 +1,7 @@
+import type { StorageModuleOptions } from './storage.types';
+declare const ConfigurableModuleClass: import("@velajs/vela").ConfigurableModuleClassType<StorageModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class StorageModule extends ConfigurableModuleClass {
+}
+export {};

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;
+}