@velajs/cloudflare 1.6.0 → 1.9.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';
@@ -23,6 +23,10 @@ export { AIService } from './services/ai.service';
 export { VectorizeService } from './services/vectorize.service';
 export { HyperdriveService } from './services/hyperdrive.service';
 export { EnvService } from './services/env.service';
+export { FlagshipFlagDriver, flagshipFlagDriver } from './services/flagship-flag.driver';
+export type { FlagshipBinding, FlagshipFlagDriverOptions } from './services/flagship-flag.driver';
+export { KvFlagDriver, kvFlagDriver } from './services/kv-flag.driver';
+export type { KvFlagDriverOptions } from './services/kv-flag.driver';
 export { Env } from './decorators/env';
 export { Scheduled } from './decorators/scheduled';
 export { QueueConsumer } from './decorators/queue-consumer';

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";
@@ -24,6 +24,9 @@ export { AIService } from "./services/ai.service.js";
 export { VectorizeService } from "./services/vectorize.service.js";
 export { HyperdriveService } from "./services/hyperdrive.service.js";
 export { EnvService } from "./services/env.service.js";
+// Feature-flag drivers (implement @velajs/feature-flags' FeatureFlagDriver contract)
+export { FlagshipFlagDriver, flagshipFlagDriver } from "./services/flagship-flag.driver.js";
+export { KvFlagDriver, kvFlagDriver } from "./services/kv-flag.driver.js";
 // Decorators
 export { Env } from "./decorators/env.js";
 export { Scheduled } from "./decorators/scheduled.js";

package/dist/services/flagship-flag.driver.d.ts

@@ -0,0 +1,57 @@
+import type { FeatureFlagDriver, FlagContext } from '@velajs/feature-flags';
+/**
+ * The subset of a Cloudflare **Flagship** binding this driver evaluates against
+ * — the four typed value methods. The binding itself returns the supplied
+ * `defaultValue` on evaluation errors; transport-level failures reject and are
+ * left to propagate (never-throw is the service layer's job, not the driver's).
+ *
+ * @see https://developers.cloudflare.com/flagship/binding/
+ */
+export interface FlagshipBinding {
+    getBooleanValue(key: string, defaultValue: boolean, context?: FlagContext): Promise<boolean>;
+    getStringValue(key: string, defaultValue: string, context?: FlagContext): Promise<string>;
+    getNumberValue(key: string, defaultValue: number, context?: FlagContext): Promise<number>;
+    getObjectValue<T extends object>(key: string, defaultValue: T, context?: FlagContext): Promise<T>;
+}
+export interface FlagshipFlagDriverOptions {
+    /** Driver name used for `use(name)` / default-driver selection. Default `"flagship"`. */
+    name?: string;
+}
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */
+export declare class FlagshipFlagDriver implements FeatureFlagDriver {
+    readonly name: string;
+    private readonly resolve;
+    constructor(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions);
+    getBoolean(key: string, fallback: boolean, ctx?: FlagContext): Promise<boolean>;
+    getString(key: string, fallback: string, ctx?: FlagContext): Promise<string>;
+    getNumber(key: string, fallback: number, ctx?: FlagContext): Promise<number>;
+    getObject<T extends object>(key: string, fallback: T, ctx?: FlagContext): Promise<T>;
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */
+export declare function flagshipFlagDriver(binding: FlagshipBinding | (() => FlagshipBinding), options?: FlagshipFlagDriverOptions): FlagshipFlagDriver;

package/dist/services/flagship-flag.driver.js

@@ -0,0 +1,49 @@
+/**
+ * {@link FeatureFlagDriver} backed by a Cloudflare Flagship binding.
+ *
+ * A thin, honest wrapper: each contract method maps 1:1 onto the binding's
+ * corresponding value method, forwarding the caller's `fallback` (the binding's
+ * `defaultValue`) and evaluation context. The binding resolves the fallback on
+ * evaluation errors; anything the binding *rejects* with (e.g. a `remote: true`
+ * dev-proxy tunnel dropping) propagates — `@velajs/feature-flags`'s service owns
+ * the never-throw guarantee.
+ *
+ * The binding only exists per request in a Worker, so pass a lazy accessor when
+ * wiring from a bootstrap factory (mirroring how {@link EnvService} reads are
+ * deferred); a resolved binding may be passed directly in tests.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [EnvService],
+ *   useFactory: (env: EnvService) => ({
+ *     drivers: [flagshipFlagDriver(() => env.get<FlagshipBinding>('FLAGS')!)],
+ *   }),
+ * });
+ * ```
+ *
+ * Evaluation ergonomics (the 1:1 binding-method mapping) are ported from the
+ * Stratal feature-flags service (MIT, © Temitayo Fadojutimi), reshaped as a
+ * bare driver.
+ */ export class FlagshipFlagDriver {
+    name;
+    resolve;
+    constructor(binding, options = {}){
+        this.resolve = typeof binding === 'function' ? binding : ()=>binding;
+        this.name = options.name ?? 'flagship';
+    }
+    getBoolean(key, fallback, ctx) {
+        return this.resolve().getBooleanValue(key, fallback, ctx);
+    }
+    getString(key, fallback, ctx) {
+        return this.resolve().getStringValue(key, fallback, ctx);
+    }
+    getNumber(key, fallback, ctx) {
+        return this.resolve().getNumberValue(key, fallback, ctx);
+    }
+    getObject(key, fallback, ctx) {
+        return this.resolve().getObjectValue(key, fallback, ctx);
+    }
+}
+/** Convenience factory for {@link FlagshipFlagDriver}. */ export function flagshipFlagDriver(binding, options) {
+    return new FlagshipFlagDriver(binding, options);
+}

package/dist/services/kv-flag.driver.d.ts

@@ -0,0 +1,48 @@
+import type { FeatureFlagDriver, FlagContext } from '@velajs/feature-flags';
+import { KVService } from './kv.service';
+export interface KvFlagDriverOptions {
+    /** Driver name used for `use(name)` / default-driver selection. Default `"kv"`. */
+    name?: string;
+    /** Prefix prepended to every flag key before the KV read. Default `""` (none). */
+    prefix?: string;
+}
+/**
+ * Cloudflare KV-backed {@link FeatureFlagDriver}. Flags are stored as JSON
+ * values under an optional key prefix and read with `get(key, 'json')`. Reads
+ * are type-checked against the requested type: a missing key or a value of the
+ * wrong JSON type returns the caller's `fallback`. KV has no targeting, so the
+ * evaluation context is ignored.
+ *
+ * The driver stays honest — it does **not** swallow errors. A KV failure (or a
+ * `SyntaxError` from a malformed stored value) propagates; the never-throw
+ * guarantee lives in `@velajs/feature-flags`'s service layer.
+ *
+ * Placed like {@link KVCacheStore}: construct it in a wiring factory over a
+ * resolved {@link KVService}.
+ *
+ * ```ts
+ * FeatureFlagsModule.forRootAsync({
+ *   inject: [KVService],
+ *   useFactory: (kv: KVService) => ({ drivers: [new KvFlagDriver(kv, { prefix: 'flag:' })] }),
+ * });
+ * ```
+ */
+export declare class KvFlagDriver implements FeatureFlagDriver {
+    private readonly kv;
+    readonly name: string;
+    private readonly prefix;
+    constructor(kv: KVService, options?: KvFlagDriverOptions);
+    private get ns();
+    getBoolean(key: string, fallback: boolean, _ctx?: FlagContext): Promise<boolean>;
+    getString(key: string, fallback: string, _ctx?: FlagContext): Promise<string>;
+    getNumber(key: string, fallback: number, _ctx?: FlagContext): Promise<number>;
+    getObject<T extends object>(key: string, fallback: T, _ctx?: FlagContext): Promise<T>;
+    /**
+     * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+     * when `matches` accepts its type; otherwise the caller's fallback. A missing
+     * key reads as `null` → fallback. Read/parse errors are left to propagate.
+     */
+    private read;
+}
+/** Convenience factory for {@link KvFlagDriver}. */
+export declare function kvFlagDriver(kv: KVService, options?: KvFlagDriverOptions): KvFlagDriver;

package/dist/services/kv-flag.driver.js

@@ -0,0 +1,62 @@
+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 { KVService } from "./kv.service.js";
+export class KvFlagDriver {
+    kv;
+    name;
+    prefix;
+    constructor(kv, options = {}){
+        this.kv = kv;
+        this.name = options.name ?? 'kv';
+        this.prefix = options.prefix ?? '';
+    }
+    get ns() {
+        return this.kv.namespace;
+    }
+    getBoolean(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'boolean');
+    }
+    getString(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'string');
+    }
+    getNumber(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'number');
+    }
+    getObject(key, fallback, _ctx) {
+        return this.read(key, fallback, (v)=>typeof v === 'object' && v !== null);
+    }
+    /**
+   * Reads and JSON-parses the (prefixed) key, returning the parsed value only
+   * when `matches` accepts its type; otherwise the caller's fallback. A missing
+   * key reads as `null` → fallback. Read/parse errors are left to propagate.
+   */ async read(key, fallback, matches) {
+        const value = await this.ns.get(this.prefix + key, 'json');
+        if (value === null || value === undefined) return fallback;
+        return matches(value) ? value : fallback;
+    }
+}
+KvFlagDriver = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(KVService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof KVService === "undefined" ? Object : KVService,
+        typeof KvFlagDriverOptions === "undefined" ? Object : KvFlagDriverOptions
+    ])
+], KvFlagDriver);
+/** Convenience factory for {@link KvFlagDriver}. */ export function kvFlagDriver(kv, options) {
+    return new KvFlagDriver(kv, options);
+}

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.9.0",
   "description": "Cloudflare Workers integration for Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,14 +45,21 @@
   },
   "peerDependencies": {
     "@cloudflare/workers-types": ">=4",
-    "@velajs/vela": ">=1.10.0",
+    "@velajs/feature-flags": "^0.1.0",
+    "@velajs/vela": ">=1.11.0",
     "hono": ">=4"
   },
+  "peerDependenciesMeta": {
+    "@velajs/feature-flags": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260624.1",
     "@swc/cli": "^0.8.1",
     "@swc/core": "^1.15.43",
-    "@velajs/vela": "^1.10.0",
+    "@velajs/feature-flags": "^0.1.0",
+    "@velajs/vela": "^1.12.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",