@velajs/cloudflare 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.7.0 (2026-07-04)
+
+- `cloudflareAdapter()` exported (createCloudflareApp composes vela RuntimeAdapter); `@QueueConsumer`/`@Scheduled` declare open entrypoint kinds; queue/scheduled dispatch runs per-event in a request scope through PipelineRunner (consumer-scoped guards/interceptors/filters; request-scoped deps rebuild per batch); DO WebSocket reads `app.entrypoints`. Requires `@velajs/vela >=1.11.0`.
+
+
 ## 1.6.0 (2026-07-01)
 
 ### Added

package/dist/cloudflare-application.d.ts

@@ -41,8 +41,6 @@ export type MountOpenApiOptions = Parameters<VelaApplication['mountOpenApi']>[0]
  */
 export declare class CloudflareApplication {
     private app;
-    private scheduledHandlers;
-    private queueConsumers;
     private wsGatewayRoutes;
     constructor(app: VelaApplication);
     get fetch(): Hono['fetch'];
@@ -81,13 +79,20 @@ export declare class CloudflareApplication {
      * ```
      */
     mountOpenApi(options: MountOpenApiOptions): this;
-    /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */
+    /**
+     * @internal — scans instances for `@WebSocketGateway({ path, binding })`
+     * upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+     * come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+     * kinds) at dispatch time.
+     */
     scanInstances(instances: unknown[]): void;
     /** @internal — upgrade routes discovered from `@WebSocketGateway({ path, binding })`. */
     getWsGatewayRoutes(): WsGatewayRoute[];
     /**
      * Handle Cloudflare scheduled (cron) events.
-     * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.
+     * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
+     * handlers read from `app.entrypoints`; each handler runs inside a fresh
+     * request-scoped child (request-scoped providers rebuild per tick).
      */
     scheduled(event: {
         cron: string;
@@ -95,9 +100,20 @@ export declare class CloudflareApplication {
     }, env: CloudflareEnv, ctx: {
         waitUntil: (promise: Promise<unknown>) => void;
     }): Promise<void>;
+    /**
+     * Run one entrypoint handler inside a fresh request scope, through the
+     * shared guard → interceptor pipeline (components declared with
+     * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+     * method). HTTP-global components deliberately do NOT apply — an HTTP auth
+     * guard has no business rejecting a queue batch. Unclaimed errors rethrow
+     * so the platform's retry semantics stay intact.
+     */
+    private dispatchEntrypoint;
     /**
      * Handle Cloudflare Queue consumer events.
-     * Matches the batch queue name to `@QueueConsumer()` handlers.
+     * Matches the batch queue name to `@QueueConsumer()` handlers read from
+     * `app.entrypoints`; each batch is processed inside a fresh request-scoped
+     * child (request-scoped providers rebuild per batch — no boot-time captives).
      */
     queue(batch: {
         queue: string;

package/dist/cloudflare-application.js

@@ -1,7 +1,14 @@
-import { CRON_METADATA, getMetadata } from "@velajs/vela";
-import { getScheduledMetadata } from "./decorators/scheduled.js";
-import { getQueueConsumerMetadata } from "./decorators/queue-consumer.js";
+import { CRON_METADATA, PipelineRunner, buildEntrypointExecutionContext, registerEntrypointKind, runInEntrypointScope, shouldFilterCatch } from "@velajs/vela";
+import { ComponentManager } from "@velajs/vela/internal";
 import { collectWsGatewayRoutes } from "./websocket/websocket-routing.js";
+// vela's own @Cron jobs run via the same Workers cron trigger — declare an
+// entrypoint kind over vela's metadata key (the open-kind system makes
+// cross-package declarations first-class).
+registerEntrypointKind({
+    kind: 'cf:vela-cron',
+    metaKey: CRON_METADATA,
+    level: 'method'
+});
 function invoke(instance, methodName, args) {
     const method = instance[methodName];
     if (typeof method !== 'function') {
@@ -39,8 +46,6 @@ function invoke(instance, methodName, args) {
  * ```
  */ export class CloudflareApplication {
     app;
-    scheduledHandlers = [];
-    queueConsumers = [];
     wsGatewayRoutes = [];
     constructor(app){
         this.app = app;
@@ -88,32 +93,14 @@ function invoke(instance, methodName, args) {
         this.app.mountOpenApi(options);
         return this;
     }
-    /** @internal — scans instances for @Scheduled, @Cron, and @QueueConsumer metadata */ scanInstances(instances) {
+    /**
+   * @internal — scans instances for `@WebSocketGateway({ path, binding })`
+   * upgrade routes. Queue/scheduled handlers are NOT scanned anymore: they
+   * come from `app.entrypoints` (`cf:queue` / `cf:scheduled` / `cf:vela-cron`
+   * kinds) at dispatch time.
+   */ scanInstances(instances) {
         for (const instance of instances){
             if (!instance || typeof instance !== 'object') continue;
-            for (const meta of getScheduledMetadata(instance)){
-                this.scheduledHandlers.push({
-                    instance,
-                    methodName: meta.methodName,
-                    cron: meta.cron
-                });
-            }
-            // vela's @Cron jobs run via the same Workers cron trigger.
-            const cronMeta = getMetadata(CRON_METADATA, instance.constructor) ?? [];
-            for (const meta of cronMeta){
-                this.scheduledHandlers.push({
-                    instance,
-                    methodName: meta.methodName,
-                    cron: meta.expression
-                });
-            }
-            for (const meta of getQueueConsumerMetadata(instance)){
-                this.queueConsumers.push({
-                    instance,
-                    methodName: meta.methodName,
-                    queueName: meta.queueName
-                });
-            }
             this.wsGatewayRoutes.push(...collectWsGatewayRoutes(instance));
         }
     }
@@ -122,21 +109,72 @@ function invoke(instance, methodName, args) {
     }
     /**
    * Handle Cloudflare scheduled (cron) events.
-   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()` handlers.
+   * Matches the event's cron expression to `@Scheduled()` and vela `@Cron()`
+   * handlers read from `app.entrypoints`; each handler runs inside a fresh
+   * request-scoped child (request-scoped providers rebuild per tick).
    */ async scheduled(event, env, ctx) {
-        const matching = this.scheduledHandlers.filter((h)=>h.cron === event.cron);
-        await Promise.all(matching.map((h)=>invoke(h.instance, h.methodName, [
+        const handlers = [
+            ...this.app.entrypoints.ofKind('cf:scheduled').map((ep)=>({
+                    ep,
+                    cron: ep.meta.cron
+                })),
+            ...this.app.entrypoints.ofKind('cf:vela-cron').map((ep)=>({
+                    ep,
+                    cron: ep.meta.expression
+                }))
+        ].filter((h)=>h.cron === event.cron);
+        await Promise.all(handlers.map(({ ep })=>this.dispatchEntrypoint(ep, [
                 event,
                 env,
                 ctx
             ])));
     }
     /**
+   * Run one entrypoint handler inside a fresh request scope, through the
+   * shared guard → interceptor pipeline (components declared with
+   * `@UseGuards`/`@UseInterceptors`/`@UseFilters` on the consumer class or
+   * method). HTTP-global components deliberately do NOT apply — an HTTP auth
+   * guard has no business rejecting a queue batch. Unclaimed errors rethrow
+   * so the platform's retry semantics stay intact.
+   */ async dispatchEntrypoint(ep, args) {
+        const targetClass = ep.token;
+        const methodName = String(ep.methodName);
+        const context = buildEntrypointExecutionContext(ep.kind, targetClass, methodName, args[0]);
+        await runInEntrypointScope(this.app.getContainer(), async (scope)=>{
+            const instance = scope.resolve(ep.token);
+            const guards = ComponentManager.resolveGuards(ComponentManager.getScopedComponents('guard', targetClass, methodName), scope);
+            const interceptors = ComponentManager.resolveInterceptors(ComponentManager.getScopedComponents('interceptor', targetClass, methodName), scope);
+            // Closest-first, mirroring the HTTP/WS dispatchers.
+            const filters = ComponentManager.resolveFilters([
+                ...ComponentManager.getScopedComponents('filter', targetClass, methodName)
+            ].reverse(), scope);
+            try {
+                await PipelineRunner.run({
+                    context,
+                    guards,
+                    interceptors,
+                    resolveArgs: async ()=>args,
+                    invoke: async (resolved)=>invoke(instance, methodName, resolved)
+                });
+            } catch (error) {
+                for (const filter of filters){
+                    if (shouldFilterCatch(filter, error)) {
+                        await filter.catch(error, context);
+                        return;
+                    }
+                }
+                throw error;
+            }
+        });
+    }
+    /**
    * Handle Cloudflare Queue consumer events.
-   * Matches the batch queue name to `@QueueConsumer()` handlers.
+   * Matches the batch queue name to `@QueueConsumer()` handlers read from
+   * `app.entrypoints`; each batch is processed inside a fresh request-scoped
+   * child (request-scoped providers rebuild per batch — no boot-time captives).
    */ async queue(batch, env, ctx) {
-        const matching = this.queueConsumers.filter((h)=>h.queueName === batch.queue);
-        await Promise.all(matching.map((h)=>invoke(h.instance, h.methodName, [
+        const handlers = this.app.entrypoints.ofKind('cf:queue').filter((ep)=>ep.meta.queueName === batch.queue);
+        await Promise.all(handlers.map((ep)=>this.dispatchEntrypoint(ep, [
                 batch,
                 env,
                 ctx

package/dist/cloudflare-factory.d.ts

@@ -1,5 +1,5 @@
 import type { MiddlewareHandler } from 'hono';
-import type { Type } from '@velajs/vela';
+import type { RuntimeAdapter, Type } from '@velajs/vela';
 import { CloudflareApplication } from './cloudflare-application';
 /**
  * Options for {@link createCloudflareApp}.
@@ -71,4 +71,18 @@ export interface CreateCloudflareAppOptions {
  * });
  * ```
  */
+/**
+ * The Cloudflare platform binding as a vela {@link RuntimeAdapter}: a one-time
+ * request middleware captures `c.env` on the first request and initializes
+ * every `BindingRef`/`EnvRef` (collected at `onBootstrap`, before any request
+ * can arrive). Adapter `requestMiddleware` is prepended to the global chain by
+ * `VelaFactory.create`, so user middleware can safely read binding refs.
+ *
+ * Exposed so consumers composing `VelaFactory.create` themselves can opt in:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, { adapters: [cloudflareAdapter()] });
+ * ```
+ */
+export declare function cloudflareAdapter(): RuntimeAdapter;
 export declare function createCloudflareApp(rootModule: Type, options?: CreateCloudflareAppOptions): Promise<CloudflareApplication>;

package/dist/cloudflare-factory.js

@@ -48,31 +48,50 @@ function collectBindingRefs(container) {
  *   ],
  * });
  * ```
- */ export async function createCloudflareApp(rootModule, options = {}) {
+ */ /**
+ * The Cloudflare platform binding as a vela {@link RuntimeAdapter}: a one-time
+ * request middleware captures `c.env` on the first request and initializes
+ * every `BindingRef`/`EnvRef` (collected at `onBootstrap`, before any request
+ * can arrive). Adapter `requestMiddleware` is prepended to the global chain by
+ * `VelaFactory.create`, so user middleware can safely read binding refs.
+ *
+ * Exposed so consumers composing `VelaFactory.create` themselves can opt in:
+ *
+ * ```ts
+ * const app = await VelaFactory.create(AppModule, { adapters: [cloudflareAdapter()] });
+ * ```
+ */ export function cloudflareAdapter() {
     let initialized = false;
-    let refs;
-    const bindingInit = async (c, next)=>{
-        if (!initialized) {
-            initialized = true;
-            const env = c.env ?? {};
-            for (const ref of refs){
-                // EnvRef holds the whole env; every other ref holds one binding.
-                if (ref instanceof EnvRef) ref._initialize(env);
-                else ref._initialize(env[ref.bindingName]);
+    let refs = [];
+    return {
+        name: 'cloudflare',
+        requestMiddleware: [
+            async (c, next)=>{
+                if (!initialized) {
+                    initialized = true;
+                    const env = c.env ?? {};
+                    for (const ref of refs){
+                        // EnvRef holds the whole env; every other ref holds one binding.
+                        if (ref instanceof EnvRef) ref._initialize(env);
+                        else ref._initialize(env[ref.bindingName]);
+                    }
+                }
+                await next();
             }
+        ],
+        onBootstrap: ({ container })=>{
+            refs = collectBindingRefs(container);
         }
-        await next();
     };
-    // IMPORTANT: keep the binding-init middleware FIRST so user middleware
-    // can safely read binding refs / `c.env` derivatives on the first request.
+}
+export async function createCloudflareApp(rootModule, options = {}) {
     const velaApp = await VelaFactory.create(rootModule, {
         globalPrefix: options.globalPrefix,
-        middleware: [
-            bindingInit,
-            ...options.middleware ?? []
+        middleware: options.middleware,
+        adapters: [
+            cloudflareAdapter()
         ]
     });
-    refs = collectBindingRefs(velaApp.getContainer());
     const cfApp = new CloudflareApplication(velaApp);
     cfApp.scanInstances(velaApp.getInstances());
     // Register WebSocket upgrade routes for any @WebSocketGateway({ path, binding }).

package/dist/decorators/queue-consumer.js

@@ -1,5 +1,13 @@
-import { defineMetadata, getMetadata } from "@velajs/vela";
+import { defineMetadata, getMetadata, registerEntrypointKind } from "@velajs/vela";
 const QUEUE_CONSUMER_METADATA_KEY = 'cloudflare:queue-consumer';
+// Open entrypoint kind: any adapter can enumerate queue consumers via
+// `app.entrypoints.ofKind('cf:queue')` — declared here, next to the decorator,
+// with zero vela-core involvement.
+registerEntrypointKind({
+    kind: 'cf:queue',
+    metaKey: QUEUE_CONSUMER_METADATA_KEY,
+    level: 'method'
+});
 /**
  * Marks a method as a queue consumer handler.
  *

package/dist/decorators/scheduled.js

@@ -1,5 +1,12 @@
-import { defineMetadata, getMetadata } from "@velajs/vela";
+import { defineMetadata, getMetadata, registerEntrypointKind } from "@velajs/vela";
 const SCHEDULED_METADATA_KEY = 'cloudflare:scheduled';
+// Open entrypoint kind: adapters enumerate cron handlers via
+// `app.entrypoints.ofKind('cf:scheduled')` — declared next to the decorator.
+registerEntrypointKind({
+    kind: 'cf:scheduled',
+    metaKey: SCHEDULED_METADATA_KEY,
+    level: 'method'
+});
 /**
  * Marks a method as a scheduled (cron) handler.
  *

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createCloudflareApp } from './cloudflare-factory';
+export { cloudflareAdapter, createCloudflareApp } from './cloudflare-factory';
 export type { CreateCloudflareAppOptions } from './cloudflare-factory';
 export { CloudflareApplication } from './cloudflare-application';
 export type { MountOpenApiOptions } from './cloudflare-application';

package/dist/index.js

@@ -1,5 +1,5 @@
 // Factory & Application
-export { createCloudflareApp } from "./cloudflare-factory.js";
+export { cloudflareAdapter, createCloudflareApp } from "./cloudflare-factory.js";
 export { CloudflareApplication } from "./cloudflare-application.js";
 // Modules
 export { KVModule } from "./modules/kv.module.js";

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

@@ -7,6 +7,8 @@ export interface DoRuntime {
     dispatcher: WsDispatcher;
     registry: CfRoomRegistry;
     server: WsServer;
+    /** Gateway paths from `app.entrypoints.ofKind('websocket')` (discovery order). */
+    gatewayPaths: string[];
     close(signal?: string): Promise<void>;
 }
 /**

package/dist/websocket/do-bootstrap.js

@@ -34,10 +34,17 @@ import { WsServerHolder } from "./ws-server-holder.js";
     app.setInstances(await loader.resolveAllInstances());
     await app.callOnModuleInit();
     await app.callOnApplicationBootstrap();
+    // The entrypoint registry is the transport contract: one 'websocket' entry
+    // per discovered gateway ({ meta: { path, dispatcher } }). Built by
+    // callOnApplicationBootstrap(), so this slim no-routes path has it too.
+    const wsEntrypoints = app.entrypoints.ofKind('websocket');
     return {
-        dispatcher: app.get(WsDispatcher),
+        // Zero gateways still yields a live dispatcher (module imported, nothing
+        // decorated) — fall back to resolving it directly.
+        dispatcher: wsEntrypoints[0]?.meta.dispatcher ?? app.get(WsDispatcher),
         registry,
         server,
+        gatewayPaths: wsEntrypoints.map((ep)=>ep.meta.path),
         close: (signal)=>app.close(signal)
     };
 }

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

@@ -10,7 +10,8 @@ export declare class DoWebSocketHost {
     private readonly ctx;
     private readonly dispatcher;
     private readonly registry;
-    constructor(ctx: DoStateLike, dispatcher: WsDispatcher, registry: CfRoomRegistry);
+    private readonly gatewayPaths;
+    constructor(ctx: DoStateLike, dispatcher: WsDispatcher, registry: CfRoomRegistry, gatewayPaths?: readonly string[]);
     /** The single registered gateway's path — a fallback when the Worker didn't forward `x-vela-path`. */
     defaultPath(): string | undefined;
     /**

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

@@ -8,13 +8,15 @@ import { connTag, roomTag } from "./room-id.js";
     ctx;
     dispatcher;
     registry;
-    constructor(ctx, dispatcher, registry){
+    gatewayPaths;
+    constructor(ctx, dispatcher, registry, gatewayPaths = []){
         this.ctx = ctx;
         this.dispatcher = dispatcher;
         this.registry = registry;
+        this.gatewayPaths = gatewayPaths;
     }
     /** The single registered gateway's path — a fallback when the Worker didn't forward `x-vela-path`. */ defaultPath() {
-        return this.dispatcher.gatewayPaths[0];
+        return this.gatewayPaths[0];
     }
     /**
    * Accept a hibernatable socket: tag it with its hub room + connection id,

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

@@ -28,7 +28,7 @@ const PONG = '{"event":"pong"}';
             }
             this.ready = ctx.blockConcurrencyWhile(async ()=>{
                 const runtime = await buildDoRuntime(rootModule, ctx, env);
-                this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry);
+                this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry, runtime.gatewayPaths);
             });
         }
         async fetch(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/cloudflare",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,14 +45,14 @@
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/vela": ">=1.10.0",
+    "@velajs/vela": ">=1.11.0",
     "hono": ">=4"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260624.1",
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.43",
-    "@velajs/vela": "^1.10.0",
+    "@velajs/vela": "^1.12.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",