@velajs/cloudflare 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## 1.29.0
+
+### Minor Changes
+
+- 416650e: Cron triggers run core `@Cron()` jobs through `invokeScheduledJob`, the same primitive as the Node executor: the adapter runs every `@Cron` job whose expression is exactly the trigger string, in a fresh invocation scope, and the trigger settles after every matching job and its `EXECUTION_LIFETIME` work settle. Closing the application aborts the invocation signal of running jobs and waits for them.
+  
+  Add `CLOUDFLARE_SCHEDULED_EVENT`, a request-scoped token seeded into each job's invocation scope. Its `CloudflareScheduledEvent` value carries the trigger's `cron`, `scheduledTime` and a `noRetry()` already bound to the native controller. The token provides itself as request-scoped in every container, so a class that injects it is request-scoped wherever the module graph boots, including a `VelaWebSocketDurableObject`, `vela` CLI commands and `Test.createTestingModule()`, and is constructed per invocation instead of at bootstrap; resolving it outside a scheduled invocation throws. `ScheduledEvent` (the input of `scheduled()`) now also accepts the controller's optional `noRetry`.
+  
+  Signed `ScheduleModule` dispatch now works on Workers: the adapter's invocation transport re-enters the signed route, so its global guards run.
+  
+  The adapter reports schedule declarations a cron trigger cannot honor through the diagnostics policy: a `@Cron` without a dialect whose weekday field has digits or whose day fields are both restricted, `dialect: 'unix'`, `timeZone: 'local'`, `@Interval` jobs, which never run on Workers, and `@UseGuards`, `@UseInterceptors` or `@UseFilters` declared for a cron job. The default `'log'` mode warns once per declaration and never fails the first event; `'throw'` fails bootstrap. `vela deploy check` rejects the cron declarations and `@Interval` jobs before deployment (`ambiguous-cron-dialect`, `incompatible-cron-options`, `unsupported-interval`).
+  
+  The adapter provides `SCHEDULE_INVOCATION_SEED`: a cron job fired outside a trigger, such as by Studio's run-now, receives a synthetic `CLOUDFLARE_SCHEDULED_EVENT` whose `cron` is the job's expression, whose `scheduledTime` is the invocation's, and whose `noRetry()` does nothing.
+  
+  **Behavior change:** `@Scheduled` and `parseScheduledMetadata` are removed, along with the `ScheduledMetadata`, `ScheduledController`, `ScheduledContext` and `ScheduledHandler` types and the `cf:scheduled` and `cf:vela-cron` entrypoint kinds. Replace `@Scheduled(expr)` with `@Cron(expr, { dialect: 'cloudflare' })` from `@velajs/vela`. Cron jobs appear only as `schedule:cron` entrypoints.
+  
+  **Behavior change:** scheduled handlers receive only a `ScheduleInvocation` (`kind`, `expression` equal to the trigger string, `scheduledTime`, `signal`), identical to Node, instead of `(controller, env, ctx)`. Inject `ENV` for bindings, `CLOUDFLARE_SCHEDULED_EVENT` for `noRetry()`, and `EXECUTION_LIFETIME` for `waitUntil()`.
+  
+  **Behavior change:** scheduled jobs no longer run interceptors or filters declared with `@UseInterceptors` or `@UseFilters`, matching the Node executor. A job that declares `@UseGuards` on its class, method or module, whose guards the adapter used to run on each trigger, is now refused instead of running unguarded: the trigger fails, the job is never constructed, and the refusal is reported through the exception reporter (guards do not run for directly dispatched scheduled jobs — use `ScheduleModule.forRoot({ dispatch: { kind: 'signed', ... } })` or remove the guard). Other jobs on the same trigger still run. Queue consumers keep their guards, interceptors and filters. Use signed `ScheduleModule` dispatch to run a job through a route's request pipeline, or remove the guard.
+  
+  **Behavior change:** a `@Cron` job that declares `@UseGuards`, `@UseInterceptors` or `@UseFilters` on its class, method or module is reported through the diagnostics policy, because those components never run for scheduled jobs: the default `'log'` mode warns once and `'throw'` fails bootstrap. Move them to a signed `ScheduleModule` dispatch route.
+- a3e2b38: The Cloudflare runtime seeds the native environment as the framework `ENV`, in the Worker and in every `VelaWebSocketDurableObject`, and types it with the environment `wrangler types` generates: the package augments `VelaEnv` with `Cloudflare.Env`, so `@InjectEnv() env: VelaEnv`, `inject: [ENV]` factories and `registerAs` factories see your bindings, variables and secrets typed. Run `wrangler types` (for example with `--include-runtime=false` alongside `@cloudflare/workers-types`) so `Cloudflare.Env` declares them. The per-environment application cache and the environment identity assertion are unchanged.
+  
+  `createCloudflareWorker` and `createCloudflareApp` accept `adapters: RuntimeAdapter[]`, composed after the Cloudflare adapter for each application, so a Worker entry can stay `export default createCloudflareWorker(AppModule, { adapters: [...] })` without a hand-written per-environment cache.
+  
+  **Behavior change:** the `envToken` option is removed from `createCloudflareWorker`, `createCloudflareApp`, `cloudflareAdapter`, `VelaWebSocketDurableObject` and `buildDoRuntime`, with no alias. Delete the application's environment `InjectionToken` and inject `ENV` from `@velajs/vela` instead: `createCloudflareWorker(AppModule)`, `VelaWebSocketDurableObject(AppModule)`, `cloudflareAdapter({ env })`. `CloudflareApplication` and `CloudflareRoot` are no longer generic; their environment type is `VelaEnv`.
+  
+  **Behavior change:** the `@Env()` parameter decorator is removed. Inject the environment with `@InjectEnv()` in a constructor, or read a binding in a factory with `inject: [ENV]`.
+  
+  **Behavior change:** ENV now carries every binding, variable and secret of the Worker, so framework readers pick up values such as `URL_SIGNING_SECRET` (URL and invocation signing) and `VELA_STUDIO_TOKEN` (Studio) automatically once they are set as variables or secrets. Values come from outside the program: validate each value your code reads before relying on it.
+- 2ae8505: Add the `@velajs/cloudflare/queues` subpath with `cloudflareQueues()`, the Cloudflare Queues driver for `QueueModule`. Configure it once with `QueueModule.forRoot({ driver: cloudflareQueues() })` and register each queue where it is used with `QueueModule.registerQueue({ name: 'email', binding: 'EMAIL_QUEUE' })`. Each application gets its own driver, which reads the registered binding from that application's `ENV` when a job is added, checks that it has `send()`, and awaits the native send. `QueueClient.addBulk` uses `sendBatch`, split into calls of at most 100 messages and an estimated 256 KB; a job estimated over 128 KB is rejected before anything is sent, and a partial failure rejects with a `QueueBatchError` listing the accepted job ids.
+  
+  Native delivery needs no mapping: the Worker's `queue()` handler gives batches that no `@QueueConsumer` claims to `QueueModule`, which routes every job by its logical `queue`, so several registered queues can share one physical queue. Every job goes through the module's dispatch policy, so signed dispatch re-enters the signed route and runs its global guards. A message that is not a job envelope, belongs to an unregistered queue, or fails stays unacknowledged, so Cloudflare retries it and then dead-letters it. `registerQueue({ name, consumer })` pins the queue to that physical queue: its jobs are accepted only from it, and it carries only the queues pinned to it. Bootstrap rejects a physical queue claimed by both `@QueueConsumer` and a pinned registration. A raw `@QueueConsumer` owns its physical queue and must not carry jobs of queues registered with `QueueModule`, which `cloudflareQueues()` delivers: when it receives such job envelopes, which reach their `@Processor` only if the raw handler dispatches them itself, the adapter warns once per physical and logical queue unless diagnostics are silent; the raw consumer still receives and settles the batch.
+  
+  **Behavior change:** `cloudflareQueueDriver(bindings, { consumers, producerBindings })` and the `@velajs/cloudflare/queue` subpath are removed, together with the `CloudflareQueueBindings` and `CloudflareQueueDriverOptions` types. Replace `driver: cloudflareQueueDriver({ email: env.EMAIL_QUEUE }, { producerBindings: { email: 'EMAIL_QUEUE' } })` with `driver: cloudflareQueues()` plus `QueueModule.registerQueue({ name: 'email', binding: 'EMAIL_QUEUE' })`, and replace a `consumers: { 'email-production': 'email' }` mapping with `QueueModule.registerQueue({ name: 'email', consumer: 'email-production' })`, or with a plain `registerQueue({ name: 'email' })` when the physical queue needs no pin.
+  
+  **Behavior change:** `consumeQueueBatch` moves to `@velajs/cloudflare/queues`. It accepts every job envelope by default instead of requiring the job's queue to equal the batch's physical queue; its `queue` option is replaced by `queues`, the list of logical queues to accept.
+  
+  **Behavior change:** the driver publishes one `cf:queue:module` entrypoint per application with `{ consumers }` (the pinned physical queues) instead of one `{ queueName, logicalQueue }` entrypoint per mapping, and the `cf:queue:producer` entrypoint kind is removed: registered queues are published as `queue:registration` entrypoints by `QueueModule`.
+  
+  **Behavior change:** a failure on the native `QueueModule` path is reported once to the exception handler instead of once by its processor and again, with the whole batch rejection, by the adapter; a message that is not a job envelope or belongs to an unregistered queue is still reported once, individually.
+- 8a3016c: **Behavior change:** Workers and Durable Objects are built from static roots only. `createCloudflareWorker`, `createCloudflareApp` and `VelaWebSocketDurableObject` take a module class or a `DynamicModule` declared at module scope; `CloudflareRoot` is now `Type | DynamicModule`. The `{ create(env) }` and async `{ create: async (env) => ... }` roots are removed, with no alias, together with the per-(root, environment) resolution cache. Read bindings where each application is built instead: `Module.forRootAsync({ inject: [ENV], useFactory: (env) => ({ ... }) })`, `useFactory` providers that inject `ENV`, or `@InjectEnv()` constructors. These run for each application, so nothing built from one environment is shared with another, and constructing another application or Durable Object instance declares no new classes in the isolate. The per-environment application cache of `createCloudflareWorker` is unchanged.
+  
+  WebSocket upgrade routes authenticate with the gateway's `authenticator`, resolved once per application from the module that declares the gateway, and read an `(env) => origins` allowlist from the Worker's `ENV`. Authentication still completes before the Durable Object id is derived, and client-supplied `x-vela-*` headers are still stripped first. `UpgradeAuthenticator`, `WebSocketUpgradeIdentity` and `WebSocketUpgradeAuthenticationContext` are re-exported from the package root.
+  
+  `WsGatewayRoute` gains an optional `moduleId`: the module that declares the gateway, from which its authenticator resolves.
+- 864735d: **Behavior change:** a WebSocket Durable Object now refuses to start when its module registers the core `WebSocketModule` instead of `CloudflareWebSocketModule`. The core module's `WS_SERVER` broadcasts through its own sync driver, which never reaches the Durable Object's sockets, so `@WebSocketServer()` pushes were silently lost. Import `CloudflareWebSocketModule.forRoot()` in modules a `VelaWebSocketDurableObject` bootstraps.
+  
+  The Worker adapter now warns once per isolate when `LiveModule` runs the default `localLive()` driver in the Worker, whose invalidations never reach subscriptions held by the Durable Object. Pass `driver: () => durableObjectLive({ namespace, gatewayPath })`. The warning respects the `'silent'` diagnostics mode.
+
+### Patch Changes
+
+- a01273b: A queue batch that no consumer claims now rejects with guidance: the error names the physical queue, points to `@QueueConsumer(name)` or `QueueModule.forRoot({ driver: cloudflareQueues() })` with a `QueueModule.registerQueue()` for each queue the batch carries, and states that the unacknowledged batch is retried and then dead-lettered by Cloudflare.
+- e4f2008: A Durable Object WebSocket whose `handleConnection` hook broadcasts to its room, for example `server.emit('system', { text: 'joined' })`, is now admitted. The broadcast reached the still-pending socket and rejected it, so every such upgrade failed with "Unable to persist authorized WebSocket state". Broadcasts now skip a socket while its connection hook runs and deliver to the room's active sockets; a pending socket that is not being admitted is still closed with 1008. When a socket is rejected while its hook runs, the error now says so.
+- Updated dependencies [07d1713]
+- Updated dependencies [db18d3a]
+- Updated dependencies [07d1713]
+- Updated dependencies [4071cb7]
+- Updated dependencies [bacaacd]
+- Updated dependencies [a814199]
+- Updated dependencies [1838474]
+- Updated dependencies [8a3016c]
+- Updated dependencies [d803a49]
+- Updated dependencies [b235935]
+- Updated dependencies [08a81c8]
+- Updated dependencies [5b5b81d]
+- Updated dependencies [7daf4fc]
+- Updated dependencies [35e8e0d]
+- Updated dependencies [4420501]
+- Updated dependencies [ff44b6a]
+- Updated dependencies [6d4f0c0]
+- Updated dependencies [e3bda2a]
+- Updated dependencies [bd7e3c9]
+- Updated dependencies [2b74880]
+- Updated dependencies [5ba8635]
+- Updated dependencies [db0c834]
+- Updated dependencies [d6f6a65]
+- Updated dependencies [8a3016c]
+- Updated dependencies [d5a3ec8]
+- Updated dependencies [0f7e8e7]
+- Updated dependencies [41ec70d]
+- Updated dependencies [b265297]
+- Updated dependencies [bdfff47]
+- Updated dependencies [28c7d07]
+- Updated dependencies [8a3016c]
+- Updated dependencies [44efdde]
+  - @velajs/vela@1.29.0
+  - @velajs/feature-flags@1.29.0
+
 ## 1.28.0
 
 ### Minor Changes

package/README.md

@@ -6,26 +6,27 @@ platform's native types.
 
 ## Native environment and application lifetime
 
-Define one typed token for your generated Workers environment. Inject that token
-wherever bindings or secrets are needed, including async provider factories.
+The Worker's native environment is the framework `ENV` from `@velajs/vela`.
+`createCloudflareWorker` seeds it for each environment before any provider is
+constructed, so the Worker entry only exports. Inject it wherever bindings or
+secrets are needed, including async provider factories (`inject: [ENV]`).
+
+Types come from Wrangler. Run `wrangler types --include-runtime=false` (runtime
+types stay with `@cloudflare/workers-types`) and include the generated
+`worker-configuration.d.ts` in your tsconfig. It declares `Cloudflare.Env` from
+the bindings and variables in your Wrangler file and the secret names in
+`.dev.vars`; this package extends `VelaEnv` with it, so `ENV`, `forRootAsync`
+factories and `registerAs` factories are typed without a hand-written interface.
+Regenerate it whenever the Wrangler file changes.
 
 ```ts
-import { Controller, Get, Inject, InjectionToken, Module } from '@velajs/vela';
+import { Controller, Get, InjectEnv, Module, type VelaEnv } from '@velajs/vela';
 import { createCloudflareWorker } from '@velajs/cloudflare';
 
-interface WorkerEnv {
-  CACHE: KVNamespace;
-  DB: D1Database;
-  FILES: R2Bucket;
-  JOBS: Queue<{ taskId: string }>;
-  SERVICE_NAME: string;
-  APP_SECRET: string;
-}
-export const ENV = new InjectionToken<WorkerEnv>('Worker environment');
-
 @Controller('/status')
 class StatusController {
-  constructor(@Inject(ENV) private readonly env: WorkerEnv) {}
+  // CACHE is a KVNamespace in worker-configuration.d.ts.
+  constructor(@InjectEnv() private readonly env: VelaEnv) {}
 
   @Get()
   async status() {
@@ -36,7 +37,7 @@ class StatusController {
 @Module({ controllers: [StatusController] })
 class AppModule {}
 
-export default createCloudflareWorker(AppModule, { envToken: ENV });
+export default createCloudflareWorker(AppModule);
 ```
 
 The worker exposes `fetch`, `queue`, and `scheduled`. Its first event builds an
@@ -45,37 +46,57 @@ environment object share construction. Different environment objects receive
 separate applications, including separate providers, lifecycle state, and live
 drivers. A failed construction is evicted and the next event retries.
 
-When module configuration itself needs bindings, pass `{ create: (env) => AppModule }`
-instead of a static class. Dynamic module roots and asynchronous factories are also
-supported. The callback receives the native environment inferred
-from `envToken` and runs once per successful environment bootstrap. The same form
-works with `VelaWebSocketDurableObject` for authenticated live gateways. See the
+The root is static: a module class, or a `DynamicModule` such as
+`AppModule.forRoot(...)`, declared once at module scope. `createCloudflareWorker`,
+`createCloudflareApp` and `VelaWebSocketDurableObject` all take the same root.
+When module configuration needs bindings, read them where each application is
+built, from its own `ENV`:
+
+```ts
+import { ENV, Module } from '@velajs/vela';
+
+@Module({
+  imports: [
+    DatabaseModule.forRootAsync({
+      inject: [ENV],
+      useFactory: (env) => ({ database: env.DB }),
+    }),
+  ],
+})
+class AppModule {}
+```
+
+`forRootAsync` factories, `useFactory` providers, `@InjectEnv()` constructors and
+queue driver factories such as `cloudflareQueues()` run for each application, so
+nothing built from one environment is shared with another. Because the root never
+changes, building another application or Durable Object instance declares no new
+classes in the isolate. See the
 [complete API starter](../../apps/api-starter/README.md) for D1, Better Auth, CRUD,
 the generated Hono client, live updates, and Studio inspection in one application.
 
-The cache uses weak object keys: it does not permanently retain replaced
-environments or secrets. Providers with request scope still rebuild per HTTP
-request or queue/cron dispatch. Do not retain request objects or authentication
-state in singleton providers.
+The application cache uses weak object keys, so the cache itself does not keep a
+replaced environment alive. Build secret-bearing values in `forRootAsync`
+factories that inject `ENV` rather than capturing them in module options.
+Providers with request scope still rebuild per HTTP request or queue/cron dispatch.
+Do not retain request objects or authentication state in singleton providers.
 
 For explicit construction inside a platform event:
 
 ```ts
 const app = await createCloudflareApp(AppModule, {
   env,
-  envToken: ENV,
   globalPrefix: '/api',
   middleware: (bindings) => [async (context, next) => {
     context.header('x-service', bindings.SERVICE_NAME);
     await next();
   }],
 });
-const bindings = app.get(ENV); // WorkerEnv, inferred from ENV
+const bindings = app.get(ENV); // VelaEnv
 return app.fetch(request, env, executionContext);
 ```
 
-`env` is registered before provider factories and lifecycle hooks. Referencing a
-binding inside `middleware(env)` is typed from that same token; request callbacks
+`env` is registered as `ENV` before provider factories and lifecycle hooks.
+Bindings inside `middleware(env)` are typed as `VelaEnv` too; request callbacks
 capture the native environment without retyping Hono's context. Referencing a
 binding is safe during construction; platform I/O must still happen inside a
 Workers event or Durable Object context. An explicitly built application rejects
@@ -83,29 +104,114 @@ requests or events carrying another environment object, including calls through
 the underlying Hono app. Internal `ctx.run` reentry retains the application's
 environment.
 
-`cloudflareAdapter({ env, envToken })` provides the same bootstrap and request
-contract when composing `VelaFactory.create` directly.
+`cloudflareAdapter({ env })` provides the same bootstrap and request contract
+when composing `VelaFactory.create` directly. `createCloudflareWorker` and
+`createCloudflareApp` accept `adapters: RuntimeAdapter[]`, composed after the
+Cloudflare adapter for each application, so the Worker entry needs no
+hand-written per-environment cache for them.
+
+Because `ENV` carries every binding, variable and secret, framework features
+read their secrets from it without extra wiring: a string `URL_SIGNING_SECRET`
+signs URLs and invocations when no explicit secret is configured, and Studio
+reads `VELA_STUDIO_TOKEN` and its `VELA_STUDIO_*_EDITABLE` flags. Set them with
+`wrangler secret put`. Values come from outside the program, so validate each
+value your own code reads before relying on it.
 
 ## Module-based queues, cron and RPC
 
-Import `QueueModule` and configure `cloudflareQueueDriver` consumer mappings to
-connect native batches directly to `@Processor`/`@Process` providers. Use
-`ScheduleModule.forRoot()` and `@Cron()` for native scheduled work. The
-[module guide](../../docs/module-workers.md) covers producer-only and consumer-only
-Workers, RPC modules, migration, and deployment checks. Native decorators remain
-available as escape hatches.
+`QueueModule` from `@velajs/vela/queue` is the Workers queue API. Configure the
+driver once in the root module and register each queue where it is used:
 
-## Managed queue and cron work
+```ts
+import { Injectable, Module } from '@velajs/vela';
+import {
+  InjectQueue,
+  Process,
+  Processor,
+  QueueModule,
+  defineQueueJob,
+  type QueueClient,
+  type QueueJob,
+} from '@velajs/vela/queue';
+import { cloudflareQueues } from '@velajs/cloudflare/queues';
+import { z } from 'zod';
+
+const welcome = defineQueueJob('welcome', z.object({ userId: z.string() }));
+
+@Injectable()
+class Signup {
+  constructor(@InjectQueue('email') private readonly email: QueueClient) {}
+  invite(userId: string) {
+    return this.email.add(welcome, { userId });
+  }
+}
+
+@Processor('email')
+class EmailProcessor {
+  @Process(welcome)
+  send(job: QueueJob<{ userId: string }>) {}
+}
+
+@Module({
+  imports: [QueueModule.registerQueue({ name: 'email', binding: 'EMAIL_QUEUE' })],
+  providers: [Signup, EmailProcessor],
+})
+class EmailModule {}
+
+@Module({ imports: [QueueModule.forRoot({ driver: cloudflareQueues() }), EmailModule] })
+class AppModule {}
+```
+
+`binding` names a Wrangler `queues.producers[].binding`. The driver reads it
+from the application's `ENV` when a job is added and awaits the native send.
+`addBulk` uses `sendBatch`, split into calls of at most 100 messages and an
+estimated 256 KB, and rejects a job estimated over 128 KB before sending
+anything. A partial failure rejects with a `QueueBatchError` whose `accepted`
+lists the job ids already sent.
+
+The Worker's `queue()` handler gives each batch to the `@QueueConsumer` handlers
+of its physical queue. Batches no `@QueueConsumer` claims go to `QueueModule`,
+which routes every job by its logical queue, so several registered queues may
+share one physical queue. Each job runs through the module's dispatch policy,
+including signed dispatch and its global guards. A message is acknowledged
+after its processors succeed; a message that is not a job envelope, belongs to
+an unregistered queue, or fails stays unacknowledged, so Cloudflare retries it
+and then dead-letters it. `registerQueue({ name, consumer: 'email-production' })`
+pins the queue to that physical queue: its jobs are accepted only from it, and
+it carries only the queues pinned to it. A physical queue cannot be both a
+`@QueueConsumer` queue and a pinned consumer. A `@QueueConsumer` owns its
+physical queue and must not carry jobs of registered queues: those reach their
+`@Processor` only if the raw handler dispatches them itself, so the adapter
+warns once when it sees them. Registered queues are delivered by
+`cloudflareQueues()`. `dispatchQueueJob` is for tests and for transports other
+than Cloudflare Queues; it applies the module's dispatch policy, signed dispatch
+included.
+
+Use `ScheduleModule.forRoot()` and `@Cron()` for native scheduled work. The
+[queue guide](../../docs/queues.md) and [module guide](../../docs/module-workers.md)
+cover producer-only and consumer-only Workers, RPC modules and deployment
+checks. `@QueueConsumer` remains available for raw batches.
 
-Each matching queue/cron handler receives its original event and environment,
-plus a context whose `waitUntil(promise)` delegates to the platform and retains
-that handler's DI scope until the promise settles. Class/method guards,
-interceptors and filters resolve asynchronously from the handler's declaring
-module. The execution context exposes that same child via `getContainer()` and
-its owner via `getModuleId()`; `REQUEST_CONTEXT` remains HTTP-only.
+## Managed queue and cron work
 
-Inject `EXECUTION_LIFETIME` from `@velajs/vela` to schedule deferred callbacks
-with `lifetime.defer(work)` or register already-started work with
+Each matching `@QueueConsumer` handler receives its batch and environment, plus
+a context whose `waitUntil(promise)` delegates to the platform and retains that
+handler's DI scope until the promise settles. Class/method guards, interceptors
+and filters resolve asynchronously from the handler's declaring module. The
+execution context exposes that same child via `getContainer()` and its owner via
+`getModuleId()`; `REQUEST_CONTEXT` remains HTTP-only.
+
+A `@Cron` job receives only its `CronInvocation`, with no environment or
+context argument, and runs no guards, interceptors or filters: the adapter warns
+once (fails bootstrap in `diagnostics: 'throw'`) when a job declares
+`@UseGuards`, `@UseInterceptors` or `@UseFilters`, and a job that declares
+guards is refused on every trigger instead of running unguarded. Use signed
+`ScheduleModule` dispatch to run a job through a route's request pipeline, and
+inject `ENV`, `CLOUDFLARE_SCHEDULED_EVENT` and `EXECUTION_LIFETIME` for what the
+native handler arguments used to carry.
+
+In both, inject `EXECUTION_LIFETIME` from `@velajs/vela` to schedule deferred
+callbacks with `lifetime.defer(work)` or register already-started work with
 `lifetime.waitUntil(promise)`. The handler, managed work and asynchronous provider
 disposal finish before queue/cron dispatch returns. Unclaimed failures reject
 for the platform to observe; they are not silently converted into success. When
@@ -122,7 +228,7 @@ Bindings retain their full native API and generic parameters. There are no
 binding-name wrappers to initialize or cast.
 
 ```ts
-import { defineProvider, InjectionToken, Module } from '@velajs/vela';
+import { defineProvider, ENV, InjectionToken, Module } from '@velajs/vela';
 
 const TASK_QUEUE = new InjectionToken<Queue<{ taskId: string }>>('task queue');
 
@@ -136,27 +242,29 @@ const TASK_QUEUE = new InjectionToken<Queue<{ taskId: string }>>('task queue');
 class JobsModule {}
 ```
 
-Every `useFactory` strategy declares its dependencies with `inject`, including
-`inject: []` for factories without dependencies. This also applies to
-`lazyProvider` and `forRootAsync` factory options.
+A `useFactory` strategy declares its dependencies with `inject`; a factory
+without parameters may omit it. This also applies to `lazyProvider` and
+`forRootAsync` factory options.
 
 Use native `env.DB`, `env.CACHE`, `env.FILES`, `env.JOBS`, `env.AI`,
-`env.VECTORIZE`, or `env.HYPERDRIVE` directly. `@Env()` remains available for HTTP
-handler parameters; typed token injection also works outside HTTP.
+`env.VECTORIZE`, or `env.HYPERDRIVE` directly. Inject `ENV` in constructors
+(`@InjectEnv()`) and factories (`inject: [ENV]`); it works the same in HTTP,
+queue, cron and Durable Object code.
 
 ## Queues and cron
 
 ```ts
-import { Inject, Injectable } from '@velajs/vela';
-import { QueueConsumer, Scheduled } from '@velajs/cloudflare';
+import { Cron, InjectEnv, Injectable, type CronInvocation, type VelaEnv } from '@velajs/vela';
+import { QueueConsumer } from '@velajs/cloudflare';
 
 @Injectable()
 class Jobs {
-  constructor(@Inject(ENV) private readonly env: WorkerEnv) {}
+  constructor(@InjectEnv() private readonly env: VelaEnv) {}
 
-  @Scheduled('0 * * * *')
-  async refresh() {
-    await this.env.CACHE.put('last-refresh', new Date().toISOString());
+  // Declare the same string under Wrangler `triggers.crons`.
+  @Cron('0 * * * *', { dialect: 'cloudflare' })
+  async refresh(tick: CronInvocation) {
+    await this.env.CACHE.put('last-refresh', new Date(tick.scheduledTime).toISOString());
   }
 
   @QueueConsumer('jobs')
@@ -168,17 +276,24 @@ class Jobs {
 }
 ```
 
-Core `@Cron()` also runs on Workers scheduled triggers. Consumers use fresh
-request scopes and their declared guards, interceptors, and filters. Unclaimed
-errors propagate to the platform for retry. Cold queue and cron events have the
-same native bindings and live invalidation capabilities as HTTP.
+A cron trigger runs every core `@Cron()` job whose expression is exactly the
+trigger string. Jobs receive only their `CronInvocation`, as on Node, in a fresh
+request scope and without guards, interceptors or filters; inject
+`CLOUDFLARE_SCHEDULED_EVENT` for the trigger's bound `noRetry()` and
+`EXECUTION_LIFETIME` for background work. A job run outside a trigger (Studio's
+run-now) receives a synthetic event whose `noRetry()` does nothing. Signed `ScheduleModule` dispatch runs
+the signed route with its global guards. Queue consumers use fresh request
+scopes and their declared guards, interceptors, and filters. Unclaimed errors
+propagate to the platform for retry. Cold queue and cron events have the same
+native bindings and live invalidation capabilities as HTTP. See
+[scheduling](../../docs/scheduling.md).
 
 ## WebSockets, live queries, and Durable Objects
 
 Use the native Durable Object entrypoint only in your Worker entry file:
 
 ```ts
-import { InjectionToken, Module } from '@velajs/vela';
+import { ENV, Module } from '@velajs/vela';
 import { LiveModule } from '@velajs/vela/live';
 import {
   CloudflareWebSocketModule,
@@ -188,14 +303,12 @@ import {
 } from '@velajs/cloudflare';
 import { VelaWebSocketDurableObject } from '@velajs/cloudflare/durable-objects';
 
-interface RoomEnv { ROOMS: DurableObjectNamespace<Room> }
-const ROOM_ENV = new InjectionToken<RoomEnv>('room environment');
-
 @Module({
   imports: [
     CloudflareWebSocketModule.forRoot(),
     LiveModule.forRootAsync({
-      inject: [ROOM_ENV],
+      // ROOMS is typed DurableObjectNamespace<Room> by `wrangler types`.
+      inject: [ENV],
       useFactory: (env) => ({
         driver: () => durableObjectLive({
           namespace: env.ROOMS,
@@ -210,12 +323,19 @@ const ROOM_ENV = new InjectionToken<RoomEnv>('room environment');
 })
 class RoomModule {}
 
-export class Room extends VelaWebSocketDurableObject(RoomModule, { envToken: ROOM_ENV }) {}
-export default createCloudflareWorker(RoomModule, { envToken: ROOM_ENV });
+export class Room extends VelaWebSocketDurableObject(RoomModule) {}
+export default createCloudflareWorker(RoomModule);
 ```
 
 Declare gateways with `@WebSocketGateway({ path, roomParam, binding, ... })` and
-configure origins and upgrade authentication for your application. Upgrade
+configure origins and upgrade authentication for your application.
+`authenticator` names an `UpgradeAuthenticator` class that the Worker resolves
+once per application from the module declaring the gateway, and
+`allowedOrigins` may read the environment: `(env) => [env.APP_ORIGIN]`.
+`BetterAuthUpgradeAuthenticator` (`@velajs/better-auth`) and
+`CloudflareAccessUpgradeAuthenticator` (`@velajs/cloudflare-access/vela`) are
+ready-made authenticators. A gateway without an authenticator refuses every
+upgrade. Authentication finishes before the Durable Object id is derived. Upgrade
 routing consumes the core trusted request identity, checks conflicts with the
 upgrade credential, and forwards issuer, subject, tenant, and expiry to the DO.
 Client-supplied internal identity headers are stripped before authorization.

package/dist/durable-objects.d.ts

@@ -1,24 +1,25 @@
-import { l as VelaDoPitrRpc, p as CloudflareRoot, t as VelaNonceDurableObject } from "./nonce.durable-object-DffHMRnU.js";
-import { InjectionToken } from "@velajs/vela";
+import "./vela-env-DFvyoNT3.js";
+import { l as VelaDoPitrRpc, p as CloudflareRoot, t as VelaNonceDurableObject } from "./nonce.durable-object-Df4CZi-0.js";
+import { VelaEnv } from "@velajs/vela";
 import { BroadcastCommand } from "@velajs/vela/websocket";
 import { CommitStamp, InvalidationCommand, LiveInspection } from "@velajs/vela/live";
 import { DurableObject } from "cloudflare:workers";
 //#region src/websocket/websocket.durable-object.d.ts
 /**
  * Base class for the WebSocket Durable Object. The user exports a named subclass
- * (matching their `wrangler.toml` `class_name`) built from their `AppModule`:
+ * (matching their `wrangler.toml` `class_name`) built from their `AppModule`, or
+ * from a `DynamicModule` declared at module scope:
  *
  * ```ts
- * export class ChatRoom extends VelaWebSocketDurableObject(AppModule, { envToken: ENV }) {}
+ * export class ChatRoom extends VelaWebSocketDurableObject(AppModule) {}
  * ```
  *
  * It owns the raw hibernation socket lifecycle (Hono's `upgradeWebSocket` cannot
  * bridge DO hibernation) and forwards every event into the runtime-agnostic
- * `WsDispatcher` via {@link DoWebSocketHost}.
+ * `WsDispatcher` via {@link DoWebSocketHost}. The DO's `env` is the
+ * application's ENV, as in the Worker.
  */
-export declare function VelaWebSocketDurableObject<T extends object>(rootModule: CloudflareRoot<NoInfer<T>>, options: {
-  envToken: InjectionToken<T>;
-}): new (ctx: DurableObjectState, env: T) => DurableObject<T> & VelaDoPitrRpc & {
+export declare function VelaWebSocketDurableObject(rootModule: CloudflareRoot): new (ctx: DurableObjectState, env: VelaEnv) => DurableObject<VelaEnv> & VelaDoPitrRpc & {
   broadcast(cmd: BroadcastCommand): Promise<void>;
   invalidate(cmd: InvalidationCommand): Promise<CommitStamp | undefined>;
   inspectLive(): Promise<LiveInspection>;

package/dist/durable-objects.js

@@ -1,4 +1,4 @@
-import { S as connTag, _ as readDoPitrBookmark, d as rejectedAttachment, f as socketAttachment, h as armDoPitr, l as CfWsClient, n as isValidExpiry, o as initDoLive, p as WsServerHolder, s as initializeDoLiveResources, t as isCanonicalBoundedText, w as roomTag, x as registerCloudflareEnvironment, y as resolveCloudflareRoot } from "./nonce-validation-CeVihShV.js";
+import { S as connTag, a as armDoPitr, f as initDoLive, g as CfWsClient, n as isValidExpiry, p as initializeDoLiveResources, r as WsServerHolder, s as readDoPitrBookmark, t as isCanonicalBoundedText, v as rejectedAttachment, w as roomTag, x as registerCloudflareEnvironment, y as socketAttachment } from "./nonce-validation-Dy8z05A9.js";
 import { VelaApplication, bootstrap } from "@velajs/vela";
 import { WS_SERVER, WebSocketSendGate, WsDispatcher, WsMessageQueue, WsServerImpl, assertBroadcastCommandFits, local, readWsEntrypointMeta } from "@velajs/vela/websocket";
 import { DurableObject } from "cloudflare:workers";
@@ -12,6 +12,7 @@ import { DurableObject } from "cloudflare:workers";
 var CfRoomRegistry = class {
 	ctx;
 	#sendGates = /* @__PURE__ */ new WeakMap();
+	#admitting = /* @__PURE__ */ new WeakSet();
 	#sendPolicyForPath;
 	setSendPolicyResolver(resolve) {
 		this.#sendPolicyForPath = resolve;
@@ -28,6 +29,19 @@ var CfRoomRegistry = class {
 	setFrameLimitResolver(resolver) {
 		this.frameLimitForPath = resolver;
 	}
+	/**
+	* Run `admit` (the connection hook) with `ws` marked as being admitted, so a
+	* broadcast issued meanwhile (for example `server.emit()` announcing the new
+	* connection) skips the still-pending socket instead of rejecting it.
+	*/
+	async admitting(ws, admit) {
+		this.#admitting.add(ws);
+		try {
+			return await admit();
+		} finally {
+			this.#admitting.delete(ws);
+		}
+	}
 	register(_client) {}
 	leaveAll(_client) {}
 	join(client, room) {
@@ -47,6 +61,7 @@ var CfRoomRegistry = class {
 		const selected = [];
 		for (const ws of targets) {
 			const att = this.reconcileFrameLimit(ws, this.attachmentOf(ws));
+			if (att.state === "pending" && this.#admitting.has(ws)) continue;
 			if (att.state !== "active" || att.expiresAtMs !== void 0 && (!Number.isSafeInteger(att.expiresAtMs) || att.expiresAtMs <= Date.now())) {
 				try {
 					att.state = "rejected";
@@ -191,8 +206,8 @@ var DoWebSocketHost = class {
 		}
 		const client = this.registry.clientFor(ws);
 		try {
-			await this.dispatcher.handleOpen(path, client);
-			if (!this.transition(ws, "active", "pending")) throw new Error("Unable to persist authorized WebSocket state");
+			await this.registry.admitting(ws, () => this.dispatcher.handleOpen(path, client));
+			if (!this.transition(ws, "active", "pending")) throw new Error(socketAttachment(ws)?.state === "rejected" ? "WebSocket was rejected while OnGatewayConnection was running: a frame arrived before the connection hook completed, or the connection closed or failed" : "Unable to persist authorized WebSocket state");
 			return true;
 		} catch (err) {
 			await this.dispatcher.handleError(path, client, err).catch(() => {});
@@ -284,16 +299,13 @@ var DoWebSocketHost = class {
 /**
 * 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
+* WITHOUT building the Hono app/routes the DO never serves. The DO's `env` is
+* seeded as the global ENV before providers construct, and the ctx-backed server
 * is bound before bootstrap lifecycle so gateway `afterInit`/handlers see it.
 */
 async function buildDoRuntime(rootModule, ctx, options) {
 	const { container, routeManager, loader } = await bootstrap(rootModule, { configureContainer: (container) => {
-		registerCloudflareEnvironment(container, {
-			token: options.envToken,
-			env: options.env
-		});
+		registerCloudflareEnvironment(container, options.env);
 	} });
 	const registry = new CfRoomRegistry(ctx);
 	const driver = local();
@@ -301,7 +313,8 @@ async function buildDoRuntime(rootModule, ctx, options) {
 	const server = new WsServerImpl(driver);
 	if (container.has(WS_SERVER)) {
 		const holder = await container.resolveAsync(WS_SERVER);
-		if (holder instanceof WsServerHolder) holder.setTarget(server);
+		if (!(holder instanceof WsServerHolder)) throw new Error("[vela] The WebSocket Durable Object found a WS_SERVER from the core WebSocketModule, which cannot reach Durable Object sockets. On Cloudflare, import CloudflareWebSocketModule.forRoot() instead of WebSocketModule.forRoot().");
+		holder.setTarget(server);
 	}
 	const app = new VelaApplication(container, routeManager);
 	app.setInstances(await loader.resolveAllInstances());
@@ -337,17 +350,19 @@ function isIdentityField(value) {
 }
 /**
 * Base class for the WebSocket Durable Object. The user exports a named subclass
-* (matching their `wrangler.toml` `class_name`) built from their `AppModule`:
+* (matching their `wrangler.toml` `class_name`) built from their `AppModule`, or
+* from a `DynamicModule` declared at module scope:
 *
 * ```ts
-* export class ChatRoom extends VelaWebSocketDurableObject(AppModule, { envToken: ENV }) {}
+* export class ChatRoom extends VelaWebSocketDurableObject(AppModule) {}
 * ```
 *
 * It owns the raw hibernation socket lifecycle (Hono's `upgradeWebSocket` cannot
 * bridge DO hibernation) and forwards every event into the runtime-agnostic
-* `WsDispatcher` via {@link DoWebSocketHost}.
+* `WsDispatcher` via {@link DoWebSocketHost}. The DO's `env` is the
+* application's ENV, as in the Worker.
 */
-function VelaWebSocketDurableObject(rootModule, options) {
+function VelaWebSocketDurableObject(rootModule) {
 	return class VelaWsDurableObject extends DurableObject {
 		host;
 		liveEngine;
@@ -358,10 +373,7 @@ function VelaWebSocketDurableObject(rootModule, options) {
 				ctx.setWebSocketAutoResponse(new WebSocketRequestResponsePair(PING, PONG));
 			} catch {}
 			this.ready = ctx.blockConcurrencyWhile(async () => {
-				const runtime = await buildDoRuntime(await resolveCloudflareRoot(rootModule, env), ctx, {
-					...options,
-					env
-				});
+				const runtime = await buildDoRuntime(rootModule, ctx, { env });
 				this.host = new DoWebSocketHost(ctx, runtime.dispatcher, runtime.registry, runtime.gatewayPaths);
 				this.liveEngine = runtime.live;
 			});