diff --git a/docs/guide/queues.md b/docs/guide/queues.md index 77c73d887..0e358d522 100644 --- a/docs/guide/queues.md +++ b/docs/guide/queues.md @@ -94,6 +94,7 @@ interface Message { export const maxBatchSize = 50; export const maxBatchTimeout = 10; // seconds +export const maxConcurrency = 2; export const maxRetries = 5; export const retryDelay = 30; // seconds @@ -106,11 +107,16 @@ export default defineQueue(async (batch, env) => { - `maxBatchSize`: maximum number of messages per batch (default `10`) - `maxBatchTimeout`: maximum seconds to wait before delivering an incomplete batch (default `5`) +- `maxConcurrency`: maximum number of batches processed concurrently, from `1` to `250` (default: Cloudflare automatic scaling) - `maxRetries`: maximum number of retries before delivery is exhausted (default `3`) - `retryDelay`: seconds to wait between retries (default `0`) Export each option directly from the queue file as a whole number, such as `export const maxRetries = 5`. Computed values and re-exports aren't supported; repeat shared settings in each queue file. +Set `maxConcurrency` when your consumer calls a rate-limited API or another service that needs bounded parallel work. `maxBatchSize` limits messages in each batch; `maxConcurrency` limits how many batches run at once. It applies to both direct Cloudflare and Void-managed deployments. Omit it to let Cloudflare scale automatically; see [consumer concurrency](https://developers.cloudflare.com/queues/configuration/consumer-concurrency/). + +Void-managed deployments require platform version 1.9.2 or later. + Void-managed queues do not configure a dead-letter queue. Cloudflare permanently deletes messages that exhaust their retries without one; see [Cloudflare's dead-letter queue guide](https://developers.cloudflare.com/queues/configuration/dead-letter-queues/). diff --git a/packages/deploy-core/src/index.ts b/packages/deploy-core/src/index.ts index 6ed4ae84e..971c8245d 100644 --- a/packages/deploy-core/src/index.ts +++ b/packages/deploy-core/src/index.ts @@ -23,6 +23,7 @@ export type QueueMeta = { bindingName: string; maxBatchSize?: number; maxBatchTimeout?: number; + maxConcurrency?: number; maxRetries?: number; retryDelay?: number; }; diff --git a/packages/deploy-core/src/validate.ts b/packages/deploy-core/src/validate.ts index ff0f5f35c..e630d15a6 100644 --- a/packages/deploy-core/src/validate.ts +++ b/packages/deploy-core/src/validate.ts @@ -177,6 +177,15 @@ export function validateManifestShape(manifest: unknown): string | null { if (typeof queue.name !== 'string' || typeof queue.bindingName !== 'string') { return 'invalid manifest shape: queues entries must have string name and bindingName'; } + if ( + queue.maxConcurrency !== undefined && + (typeof queue.maxConcurrency !== 'number' || + !Number.isInteger(queue.maxConcurrency) || + queue.maxConcurrency < 1 || + queue.maxConcurrency > 250) + ) { + return 'invalid manifest shape: queues entry maxConcurrency must be an integer between 1 and 250'; + } for (const tuning of [ 'maxBatchSize', 'maxBatchTimeout', diff --git a/packages/deploy-core/test/unit/validate.test.ts b/packages/deploy-core/test/unit/validate.test.ts index 055a1030f..ae41d00b1 100644 --- a/packages/deploy-core/test/unit/validate.test.ts +++ b/packages/deploy-core/test/unit/validate.test.ts @@ -1,6 +1,33 @@ import { describe, expect, it } from 'vite-plus/test'; import { validateManifestShape, type DeployManifest } from '../../src/index.ts'; +describe('queue concurrency', () => { + it.each([undefined, 1, 2, 250])('accepts maxConcurrency = %s', (maxConcurrency) => { + expect( + validateManifestShape({ + version: 3, + bindings: {}, + queues: [{ name: 'jobs', bindingName: 'QUEUE_JOBS', maxConcurrency }], + }), + ).toBeNull(); + }); + + it.each([0, -1, 251, 1.5, Infinity, NaN, '2', null])( + 'rejects invalid maxConcurrency = %s', + (maxConcurrency) => { + expect( + validateManifestShape({ + version: 3, + bindings: {}, + queues: [{ name: 'jobs', bindingName: 'QUEUE_JOBS', maxConcurrency }], + }), + ).toBe( + 'invalid manifest shape: queues entry maxConcurrency must be an integer between 1 and 250', + ); + }, + ); +}); + describe('R2 location hints', () => { it('accepts custom Durable Objects alongside a location hint', () => { expect( diff --git a/packages/void/AGENTS.md b/packages/void/AGENTS.md index 496bc61c9..ac5c0bacc 100644 --- a/packages/void/AGENTS.md +++ b/packages/void/AGENTS.md @@ -109,6 +109,7 @@ generated entries must preserve the module-boundary rules below. - **Cloudflare queue names**: Only `void deploy --platform cloudflare` renames queues. Preflight (`cli/deploy-cloudflare-queues.ts`) reads the account and picks `-` (the Worker part in resource-name form, as for R2 and KV, untrimmed), or keeps the plain name that this Worker already consumes (Cloudflare's consumer list is the record: `void.lock.json` is shared by every Worker that deploys from the checkout). It stores the result in `desired.queueNames`, and the build gets it through `VOID_CLOUDFLARE_QUEUE_NAMES`. Bindings, the route table and the framework wrapper read the same map, and the resolver then matches names exactly, because a `-name` suffix can pick the wrong queue. Dev, previews, plain builds and the hosted platform keep plain names and the suffix fallback. - **Framework queue delivery**: Native queue handlers receive the original `MessageBatch`; only managed HTTP delivery serializes it. In deployed Workers the generated `/__void/queue` endpoint requires `__VOID_PROXY_TOKEN` (dev accepts only `x-void-dev-trigger`); it reconstructs `Date` timestamps and first-decision-wins ack/retry methods, and returns per-message decisions even if the consumer throws. Queue-only wrappers must also serve readiness. +- **Framework queue concurrency**: Queue provenance records which consumers had `max_concurrency` written from an export, including pre-existing consumer entries. Removing the export must remove that generated setting and persist the removal to `void.lock.json`; preserve concurrency settings Void never wrote. - **Shared cron expressions**: Each scheduled invocation runs every matching job once and awaits all results before surfacing failures. Native trigger configuration and managed scheduler delivery deduplicate expressions; keep this coordinated with worker dispatch to avoid multiplying jobs on managed delivery. diff --git a/packages/void/src/cli/client.ts b/packages/void/src/cli/client.ts index 9b9872765..3465a0943 100644 --- a/packages/void/src/cli/client.ts +++ b/packages/void/src/cli/client.ts @@ -35,8 +35,8 @@ function readCliVersion(): string | null { const VOID_CLI_VERSION = readCliVersion(); -/** The oldest Void platform release this CLI supports. */ -export const MIN_PLATFORM_VERSION = '1.9.0'; +/** The oldest Void platform release this CLI supports, including queue concurrency caps. */ +export const MIN_PLATFORM_VERSION = '1.9.2'; const RELEASE_VERSION = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/; diff --git a/packages/void/src/cli/deploy-cloudflare-preflight.ts b/packages/void/src/cli/deploy-cloudflare-preflight.ts index 7361ff98a..5a73c97bf 100644 --- a/packages/void/src/cli/deploy-cloudflare-preflight.ts +++ b/packages/void/src/cli/deploy-cloudflare-preflight.ts @@ -652,6 +652,7 @@ export async function preflightCloudflareWorker(input: { max_batch_timeout: queue.maxBatchTimeout, }), ...(queue.maxRetries != null && { max_retries: queue.maxRetries }), + ...(queue.maxConcurrency != null && { max_concurrency: queue.maxConcurrency }), ...(queue.retryDelay != null && { retry_delay: queue.retryDelay }), })), reconcileVoidOwned: true, diff --git a/packages/void/src/cli/deploy-helpers.ts b/packages/void/src/cli/deploy-helpers.ts index dd2270379..e3e8a0869 100644 --- a/packages/void/src/cli/deploy-helpers.ts +++ b/packages/void/src/cli/deploy-helpers.ts @@ -536,6 +536,7 @@ export function toManifestSchedulesAndQueues( bindingName: q.bindingName, ...(q.maxBatchSize != null && { maxBatchSize: q.maxBatchSize }), ...(q.maxBatchTimeout != null && { maxBatchTimeout: q.maxBatchTimeout }), + ...(q.maxConcurrency != null && { maxConcurrency: q.maxConcurrency }), ...(q.maxRetries != null && { maxRetries: q.maxRetries }), ...(q.retryDelay != null && { retryDelay: q.retryDelay }), })), diff --git a/packages/void/src/cli/gen.ts b/packages/void/src/cli/gen.ts index a3a34c230..efcc12843 100644 --- a/packages/void/src/cli/gen.ts +++ b/packages/void/src/cli/gen.ts @@ -677,6 +677,7 @@ type Message = {}; // export const maxBatchSize = 10; // export const maxBatchTimeout = 5; +// export const maxConcurrency = 2; export default defineQueue(async (batch, env) => { for (const message of batch.messages) { diff --git a/packages/void/src/cli/wrangler.ts b/packages/void/src/cli/wrangler.ts index 44376e973..1762c9d3d 100644 --- a/packages/void/src/cli/wrangler.ts +++ b/packages/void/src/cli/wrangler.ts @@ -859,6 +859,7 @@ export type WranglerQueueConsumer = { queue: string; max_batch_size?: number; max_batch_timeout?: number; + max_concurrency?: number; max_retries?: number; retry_delay?: number; }; @@ -915,6 +916,8 @@ export type ProvisionedWranglerPatch = { type ManagedQueueProvenance = { producerBindings: Array; consumerQueues: Array; + /** Consumers whose max_concurrency was set from a queue file export. */ + consumerConcurrencyQueues: Array; /** Void-owned consumers removed locally but not yet confirmed removed remotely. */ pendingConsumerRemovals: Array; }; @@ -923,6 +926,7 @@ function readManagedQueueProvenance(text: string): ManagedQueueProvenance { const none: ManagedQueueProvenance = { producerBindings: [], consumerQueues: [], + consumerConcurrencyQueues: [], pendingConsumerRemovals: [], }; const encoded = MANAGED_QUEUES_MARKER.exec(text)?.[1]; @@ -939,6 +943,7 @@ function readManagedQueueProvenance(text: string): ManagedQueueProvenance { return { producerBindings: strings(parsed.producerBindings), consumerQueues: strings(parsed.consumerQueues), + consumerConcurrencyQueues: strings(parsed.consumerConcurrencyQueues), pendingConsumerRemovals: strings(parsed.pendingConsumerRemovals), }; } catch { @@ -951,12 +956,14 @@ function writeManagedQueueProvenance(text: string, provenance: ManagedQueueProve const normalized: ManagedQueueProvenance = { producerBindings: [...new Set(provenance.producerBindings)].sort(), consumerQueues: [...new Set(provenance.consumerQueues)].sort(), + consumerConcurrencyQueues: [...new Set(provenance.consumerConcurrencyQueues)].sort(), pendingConsumerRemovals: [...new Set(provenance.pendingConsumerRemovals)].sort(), }; const existing = MANAGED_QUEUES_MARKER.exec(text); if ( normalized.producerBindings.length === 0 && normalized.consumerQueues.length === 0 && + normalized.consumerConcurrencyQueues.length === 0 && normalized.pendingConsumerRemovals.length === 0 ) { if (!existing) { @@ -1353,6 +1360,9 @@ export function writeProvisionedWranglerConfig( const managedQueueProvenance = readManagedQueueProvenance(text); const managedProducerBindings = new Set(managedQueueProvenance.producerBindings); const managedConsumerQueues = new Set(managedQueueProvenance.consumerQueues); + const managedConsumerConcurrencyQueues = new Set( + managedQueueProvenance.consumerConcurrencyQueues, + ); const pendingConsumerRemovals = new Set(managedQueueProvenance.pendingConsumerRemovals); const upsertQueueEntries = ( section: 'producers' | 'consumers', @@ -1425,6 +1435,16 @@ export function writeProvisionedWranglerConfig( ); } + if (reconcileManagedQueues && section === 'consumers' && typeof entry.queue === 'string') { + if (entry.max_concurrency !== undefined) { + managedConsumerConcurrencyQueues.add(entry.queue); + } else if (managedConsumerConcurrencyQueues.delete(entry.queue) && index >= 0) { + // Removing the export restores autoscaling without clearing a cap Void never wrote. + set(['queues', section, index, 'max_concurrency'], undefined); + delete currentList[index].max_concurrency; + } + } + if (index >= 0) { // Set only the supplied properties: replacing the element would drop comments and // user-tuned fields such as `dead_letter_queue`. @@ -1587,6 +1607,9 @@ export function writeProvisionedWranglerConfig( finalProducerBindings.has(binding), ), consumerQueues: [...managedConsumerQueues].filter((queue) => finalConsumerQueues.has(queue)), + consumerConcurrencyQueues: [...managedConsumerConcurrencyQueues].filter((queue) => + finalConsumerQueues.has(queue), + ), pendingConsumerRemovals: [...pendingConsumerRemovals], }); } diff --git a/packages/void/src/plugin-worker-bindings.ts b/packages/void/src/plugin-worker-bindings.ts index 587cc3f11..278e60d9c 100644 --- a/packages/void/src/plugin-worker-bindings.ts +++ b/packages/void/src/plugin-worker-bindings.ts @@ -286,6 +286,7 @@ export function mergeWorkerBindings( queue: cloudflareQueueName(q.name, cloudflareNames), ...(q.maxBatchSize != null && { max_batch_size: q.maxBatchSize }), ...(q.maxBatchTimeout != null && { max_batch_timeout: q.maxBatchTimeout }), + ...(q.maxConcurrency != null && { max_concurrency: q.maxConcurrency }), ...(q.maxRetries != null && { max_retries: q.maxRetries }), ...(q.retryDelay != null && { retry_delay: q.retryDelay }), })), diff --git a/packages/void/src/queues/scan.ts b/packages/void/src/queues/scan.ts index 02e31a8cc..cb67cd1e2 100644 --- a/packages/void/src/queues/scan.ts +++ b/packages/void/src/queues/scan.ts @@ -16,6 +16,8 @@ export type QueueDefinition = { maxBatchSize?: number; /** Optional max batch timeout (seconds) for consumer */ maxBatchTimeout?: number; + /** Optional maximum concurrent consumer invocations (1–250) */ + maxConcurrency?: number; /** Optional max retries before dead-lettering */ maxRetries?: number; /** Optional delay (seconds) between retries */ @@ -30,7 +32,13 @@ function deriveQueueBindingName(name: string): string { return 'QUEUE_' + name.toUpperCase().replace(/[^A-Z0-9]/g, '_'); } -const OPTION_NAMES = ['maxBatchSize', 'maxBatchTimeout', 'maxRetries', 'retryDelay'] as const; +const OPTION_NAMES = [ + 'maxBatchSize', + 'maxBatchTimeout', + 'maxConcurrency', + 'maxRetries', + 'retryDelay', +] as const; const OPTION_NAME_SET: ReadonlySet = new Set(OPTION_NAMES); /** Queue files already warned about `export *`; a dev server rescans queues on every change. */ @@ -83,9 +91,14 @@ export function scanQueuesSync(queuesDir: string): Array { return undefined; } const value = staticLiteral(initializer); - if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) { + if ( + typeof value !== 'number' || + !Number.isInteger(value) || + value < 0 || + (option === 'maxConcurrency' && (value < 1 || value > 250)) + ) { throw new Error( - `queue: ${option} in '${filePath}' must be a nonnegative integer literal.`, + `queue: ${option} in '${filePath}' must be ${option === 'maxConcurrency' ? 'an integer literal between 1 and 250' : 'a nonnegative integer literal'}.`, ); } return value; @@ -96,6 +109,7 @@ export function scanQueuesSync(queuesDir: string): Array { bindingName: deriveQueueBindingName(name), maxBatchSize: optionValue('maxBatchSize'), maxBatchTimeout: optionValue('maxBatchTimeout'), + maxConcurrency: optionValue('maxConcurrency'), maxRetries: optionValue('maxRetries'), retryDelay: optionValue('retryDelay'), }; diff --git a/packages/void/test/unit/client-platform-version.test.ts b/packages/void/test/unit/client-platform-version.test.ts index cc14a04ee..11f611bbf 100644 --- a/packages/void/test/unit/client-platform-version.test.ts +++ b/packages/void/test/unit/client-platform-version.test.ts @@ -73,7 +73,7 @@ describe('minimum platform version', () => { }, ); - it.each(['1.9.0', '1.9.1', '2.0.0', 'hosted'])( + it.each(['1.9.2', '1.9.3', '2.0.0', 'hosted'])( 'accepts a platform reporting %s', async (version) => { serve(version); @@ -83,7 +83,7 @@ describe('minimum platform version', () => { ); it('sends discovery without the account token', async () => { - serve('1.9.0'); + serve('1.9.2'); await client().listProjectChoices(); const [, init] = fetchMock.mock.calls[0] as [string, RequestInit]; expect(init.headers).not.toHaveProperty('Authorization'); @@ -109,16 +109,19 @@ describe('minimum platform version', () => { '1.8.0', '1.8.1', '1.9.0-1', + '1.9.0', + '1.9.1', + '1.9.2-1', ])('refuses a platform reporting %s', async (version) => { serve(version); await expect(client().listProjectChoices()).rejects.toThrow( - `The Void platform at ${origin} runs version ${version}, but this CLI requires 1.9.0 or later. Ask its administrator to upgrade the platform runtime with \`void platform upgrade\`.`, + `The Void platform at ${origin} runs version ${version}, but this CLI requires 1.9.2 or later. Ask its administrator to upgrade the platform runtime with \`void platform upgrade\`.`, ); expect(requestedPaths()).toEqual(['/.well-known/void-platform']); }); it('checks once per process and base URL, sharing a concurrent first check', async () => { - serve('1.9.0'); + serve('1.9.2'); await Promise.all([client().listProjectChoices(), client().listProjects()]); await client().listProjectChoices(); expect(requestedPaths().filter((path) => path === '/.well-known/void-platform')).toHaveLength( @@ -149,7 +152,7 @@ describe('minimum platform version', () => { ['a JSON 404', () => Response.json({ error: 'not found' }, { status: 404 })], ])('refuses a platform that answers discovery with %s', async (_label, answer) => { serve(answer); - const message = `The Void platform at ${origin} does not report its version, but this CLI requires 1.9.0 or later. Ask its administrator to upgrade the platform runtime with \`void platform upgrade\`.`; + const message = `The Void platform at ${origin} does not report its version, but this CLI requires 1.9.2 or later. Ask its administrator to upgrade the platform runtime with \`void platform upgrade\`.`; await expect(client().listProjectChoices()).rejects.toThrow(message); await expect(client().listProjects()).rejects.toThrow(message); expect(requestedPaths()).toEqual(['/.well-known/void-platform']); diff --git a/packages/void/test/unit/cloudflare-deploy.test.ts b/packages/void/test/unit/cloudflare-deploy.test.ts index f380cb506..c31c4a2e8 100644 --- a/packages/void/test/unit/cloudflare-deploy.test.ts +++ b/packages/void/test/unit/cloudflare-deploy.test.ts @@ -7744,6 +7744,7 @@ describe('runCloudflareDeploy — framework artifact guard', () => { 'queues/email.ts': [ 'export const maxBatchSize = 25;', 'export const maxBatchTimeout = 10;', + 'export const maxConcurrency = 2;', 'export const maxRetries = 4;', 'export const retryDelay = 30;', 'export default async function email() {}', @@ -7761,6 +7762,7 @@ describe('runCloudflareDeploy — framework artifact guard', () => { queue: 'skapp-email', max_batch_size: 25, max_batch_timeout: 10, + max_concurrency: 2, max_retries: 4, retry_delay: 30, }, @@ -7769,6 +7771,45 @@ describe('runCloudflareDeploy — framework artifact guard', () => { }); }); + it('clears removed framework concurrency from generated config and the lock before building', async () => { + const root = makeProject({ + 'package.json': JSON.stringify({ + name: 'skapp', + dependencies: { '@sveltejs/kit': '2.0.0' }, + }), + 'void.config.ts': `export default { cloudflare: { account_id: 'acc123', name: 'skapp' } };\n`, + 'queues/email.ts': 'export const maxConcurrency = 2; export default async () => {};', + }); + const { deps, exitCalls } = harness(); + await runCloudflareDeploy(root, { platform: 'cloudflare' }, silentCliLog, deps); + expect(exitCalls).toEqual([]); + const readLockedQueues = () => + JSON.parse(readFileSync(join(root, 'void.lock.json'), 'utf8')).resolved.queues; + expect(readLockedQueues().consumers).toEqual([{ queue: 'skapp-email', max_concurrency: 2 }]); + + writeFileSync(join(root, 'queues/email.ts'), 'export default async () => {};'); + const expectedQueues = { + producers: [{ queue: 'skapp-email', binding: 'QUEUE_EMAIL' }], + consumers: [{ queue: 'skapp-email' }], + }; + const runBuild = vi.fn(() => { + expect(parseRootWranglerConfig(materializeCloudflareConfig(root)).queues).toEqual( + expectedQueues, + ); + expect(readLockedQueues()).toEqual(expectedQueues); + }); + deps.runBuild = runBuild; + await runCloudflareDeploy(root, { platform: 'cloudflare' }, silentCliLog, deps); + expect(exitCalls).toEqual([]); + expect(runBuild).toHaveBeenCalledOnce(); + + rmSync(join(root, '.void-wrangler.jsonc')); + expect(parseRootWranglerConfig(materializeCloudflareConfig(root)).queues).toEqual( + expectedQueues, + ); + expect(readLockedQueues()).toEqual(expectedQueues); + }); + it('gives the framework wrapper the queue names it binds', async () => { const root = makeProject({ 'package.json': JSON.stringify({ diff --git a/packages/void/test/unit/deploy-project.test.ts b/packages/void/test/unit/deploy-project.test.ts index 028b263aa..60e120b66 100644 --- a/packages/void/test/unit/deploy-project.test.ts +++ b/packages/void/test/unit/deploy-project.test.ts @@ -560,7 +560,7 @@ describe('generateDeployWrapperIfNeeded', () => { }); describe('toManifestSchedulesAndQueues', () => { - it('keeps queue retry options, including zero', () => { + it('keeps queue consumer options, including zero retries and omitted concurrency', () => { const { queues } = toManifestSchedulesAndQueues( [], [ @@ -570,6 +570,7 @@ describe('toManifestSchedulesAndQueues', () => { bindingName: 'QUEUE_EMAILS', maxBatchSize: 50, maxBatchTimeout: 10, + maxConcurrency: 2, maxRetries: 0, retryDelay: 30, }, @@ -582,6 +583,7 @@ describe('toManifestSchedulesAndQueues', () => { bindingName: 'QUEUE_EMAILS', maxBatchSize: 50, maxBatchTimeout: 10, + maxConcurrency: 2, maxRetries: 0, retryDelay: 30, }, diff --git a/packages/void/test/unit/gen.test.ts b/packages/void/test/unit/gen.test.ts index 6f6da8a47..285a7914b 100644 --- a/packages/void/test/unit/gen.test.ts +++ b/packages/void/test/unit/gen.test.ts @@ -1268,6 +1268,7 @@ describe('gen queue', () => { expect(content).toContain('type Message = {};'); expect(content).toContain('// export const maxBatchSize = 10;'); expect(content).toContain('// export const maxBatchTimeout = 5;'); + expect(content).toContain('// export const maxConcurrency = 2;'); expect(content).toContain('export default defineQueue('); expect(content).toContain('batch.messages'); }); diff --git a/packages/void/test/unit/plugin-queue-bindings.test.ts b/packages/void/test/unit/plugin-queue-bindings.test.ts new file mode 100644 index 000000000..f3c9733d3 --- /dev/null +++ b/packages/void/test/unit/plugin-queue-bindings.test.ts @@ -0,0 +1,48 @@ +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { afterEach, describe, expect, it, vi } from 'vite-plus/test'; + +vi.mock('../../src/plugin-cloudflare.ts', () => import('../helpers/cloudflare-vite-plugin.ts')); + +const roots: Array = []; + +afterEach(() => { + vi.restoreAllMocks(); + for (const root of roots.splice(0)) { + rmSync(root, { recursive: true, force: true }); + } +}); + +describe('queue consumer config', () => { + it.each([undefined, 2])('emits only exported concurrency (maxConcurrency: %s)', async (value) => { + const root = mkdtempSync(join(tmpdir(), 'void-queue-config-')); + roots.push(root); + writeFileSync(join(root, 'package.json'), JSON.stringify({ type: 'module' })); + writeFileSync( + join(root, 'void.json'), + JSON.stringify({ worker: { compatibility_date: '2026-02-24' } }), + ); + mkdirSync(join(root, 'queues')); + writeFileSync( + join(root, 'queues/jobs.ts'), + `${value === undefined ? '' : `export const maxConcurrency = ${value};`} +export default async () => {};`, + ); + vi.spyOn(process, 'cwd').mockReturnValue(root); + const { voidPlugin } = await import('../../src/index.ts'); + const cloudflare = voidPlugin().find((plugin) => plugin.name === 'mock:cloudflare'); + if (!cloudflare) { + throw new Error('Expected mocked Cloudflare plugin.'); + } + const { config } = ( + cloudflare.api as { + pluginConfig: { config: (resolved: Record) => Record }; + } + ).pluginConfig; + expect(config({}).queues).toEqual({ + producers: [{ queue: 'jobs', binding: 'QUEUE_JOBS' }], + consumers: [{ queue: 'jobs', ...(value !== undefined && { max_concurrency: value }) }], + }); + }); +}); diff --git a/packages/void/test/unit/queue-scan.test.ts b/packages/void/test/unit/queue-scan.test.ts index 8527da1c0..f2434b4fb 100644 --- a/packages/void/test/unit/queue-scan.test.ts +++ b/packages/void/test/unit/queue-scan.test.ts @@ -24,6 +24,7 @@ describe('scanQueuesSync', () => { `import { defineQueue } from "void"; export const maxBatchSize = 50; export const maxBatchTimeout = 10; +export const maxConcurrency = 2; export const maxRetries = 3; export const retryDelay = 60; export default defineQueue(async (batch, env) => {});`, @@ -33,10 +34,43 @@ export default defineQueue(async (batch, env) => {});`, expect(queues).toHaveLength(1); expect(queues[0].maxBatchSize).toBe(50); expect(queues[0].maxBatchTimeout).toBe(10); + expect(queues[0].maxConcurrency).toBe(2); expect(queues[0].maxRetries).toBe(3); expect(queues[0].retryDelay).toBe(60); }); + it.each([1, 250])('accepts maxConcurrency = %i', (value) => { + writeFileSync(join(queuesDir, 'jobs.ts'), `export const maxConcurrency = ${value} as const;`); + expect(scanQueuesSync(queuesDir)).toMatchObject([{ maxConcurrency: value }]); + }); + + it.each(['0', '-1', '251', '1.5', 'Infinity', 'NaN', '"2"', 'null', '2 + 3'])( + 'rejects invalid maxConcurrency = %s', + (value) => { + writeFileSync(join(queuesDir, 'jobs.ts'), `export const maxConcurrency = ${value};`); + expect(() => scanQueuesSync(queuesDir)).toThrow( + "queue: maxConcurrency in 'jobs.ts' must be an integer literal between 1 and 250.", + ); + }, + ); + + it('rejects a re-exported maxConcurrency instead of deploying the default', () => { + writeFileSync(join(queuesDir, 'jobs.ts'), "export { maxConcurrency } from './_shared';"); + expect(() => scanQueuesSync(queuesDir)).toThrow( + 'must be declared in the queue file as `export const maxConcurrency = `', + ); + }); + + it('leaves concurrency unset when it is not exported', () => { + writeFileSync( + join(queuesDir, 'jobs.ts'), + `// export const maxConcurrency = 2; +const example = 'export const maxConcurrency = 3'; +export default async () => {};`, + ); + expect(scanQueuesSync(queuesDir)[0].maxConcurrency).toBeUndefined(); + }); + it('ignores options mentioned only in comments and strings', () => { writeFileSync( join(root, 'queues', 'basic.ts'), @@ -130,6 +164,7 @@ export default async () => {};`, `export * from './_helpers'; export const maxBatchSize = 1; export const maxBatchTimeout = 2; +export const maxConcurrency = 5; export const maxRetries = 3; export const retryDelay = 4; export default async () => {};`, diff --git a/packages/void/test/unit/wrangler.test.ts b/packages/void/test/unit/wrangler.test.ts index 8260fdfa3..b64099488 100644 --- a/packages/void/test/unit/wrangler.test.ts +++ b/packages/void/test/unit/wrangler.test.ts @@ -1087,6 +1087,37 @@ describe('writeProvisionedWranglerConfig', () => { }); }); + it.each([false, true])( + 'clears Void-written concurrency when omitted (preexisting consumer: %s)', + (preexisting) => { + setup( + 'wrangler.jsonc', + JSON.stringify({ + queues: { + consumers: preexisting + ? [{ queue: 'jobs', dead_letter_queue: 'jobs-dlq', max_concurrency: 8 }] + : [], + }, + }), + ); + const queues: NonNullable = { + consumers: [{ queue: 'jobs', max_concurrency: 2 }], + reconcileVoidOwned: true, + }; + writeProvisionedWranglerConfig(tmpDir, { queues }); + expect(parseRaw('wrangler.jsonc').queues).toMatchObject({ + consumers: [{ queue: 'jobs', max_concurrency: 2 }], + }); + + queues.consumers = [{ queue: 'jobs' }]; + expect(writeProvisionedWranglerConfig(tmpDir, { queues }).modified).toBe(true); + expect(parseRaw('wrangler.jsonc').queues).toEqual({ + consumers: [{ queue: 'jobs', ...(preexisting && { dead_letter_queue: 'jobs-dlq' }) }], + }); + expect(writeProvisionedWranglerConfig(tmpDir, { queues }).modified).toBe(false); + }, + ); + it('prunes only queue entries that Void explicitly recorded as managed', () => { setup('wrangler.jsonc', '{}'); writeProvisionedWranglerConfig(tmpDir, { @@ -1305,6 +1336,7 @@ describe('writeProvisionedWranglerConfig', () => { queues: { producers: [{ queue: 'jobs', binding: 'QUEUE_JOBS' }], consumers: [{ queue: 'jobs', max_batch_size: 25, max_retries: 5 }], + reconcileVoidOwned: true, }, }; diff --git a/platform/packages/api/src/deploy/publish-worker.ts b/platform/packages/api/src/deploy/publish-worker.ts index 7a9a4194b..d319f1a27 100644 --- a/platform/packages/api/src/deploy/publish-worker.ts +++ b/platform/packages/api/src/deploy/publish-worker.ts @@ -203,6 +203,7 @@ export async function publishWorkerDeployment(input: { max_wait_time_ms: q.maxBatchTimeout * 1000, }), ...(q.maxRetries != null && { max_retries: q.maxRetries }), + ...(q.maxConcurrency != null && { max_concurrency: q.maxConcurrency }), ...(q.retryDelay != null && { retry_delay: q.retryDelay }), }, ); diff --git a/platform/packages/api/src/deploy/recovery.ts b/platform/packages/api/src/deploy/recovery.ts index 6245db4b2..9e943f63c 100644 --- a/platform/packages/api/src/deploy/recovery.ts +++ b/platform/packages/api/src/deploy/recovery.ts @@ -365,6 +365,7 @@ export async function replayDeploymentCutover( ...(queue.maxBatchSize != null && { batch_size: queue.maxBatchSize }), ...(queue.maxBatchTimeout != null && { max_wait_time_ms: queue.maxBatchTimeout * 1000 }), ...(queue.maxRetries != null && { max_retries: queue.maxRetries }), + ...(queue.maxConcurrency != null && { max_concurrency: queue.maxConcurrency }), ...(queue.retryDelay != null && { retry_delay: queue.retryDelay }), }, ); diff --git a/platform/packages/api/src/provisioning/cloudflare-api.ts b/platform/packages/api/src/provisioning/cloudflare-api.ts index 8df08c73e..0dcb9c9a4 100644 --- a/platform/packages/api/src/provisioning/cloudflare-api.ts +++ b/platform/packages/api/src/provisioning/cloudflare-api.ts @@ -239,6 +239,7 @@ export async function createQueue( export type QueueConsumerSettings = Readonly<{ batch_size?: number; max_wait_time_ms?: number; + max_concurrency?: number; max_retries?: number; retry_delay?: number; }>; diff --git a/platform/packages/api/src/routes/projects.ts b/platform/packages/api/src/routes/projects.ts index 344e4f118..7156cb959 100644 --- a/platform/packages/api/src/routes/projects.ts +++ b/platform/packages/api/src/routes/projects.ts @@ -1478,6 +1478,9 @@ const app = new Hono() ...(targetQueue.maxRetries != null && { max_retries: targetQueue.maxRetries, }), + ...(targetQueue.maxConcurrency != null && { + max_concurrency: targetQueue.maxConcurrency, + }), ...(targetQueue.retryDelay != null && { retry_delay: targetQueue.retryDelay, }), diff --git a/platform/packages/api/test/integration/api-deploy.test.ts b/platform/packages/api/test/integration/api-deploy.test.ts index b31efaa02..0f8ec99b2 100644 --- a/platform/packages/api/test/integration/api-deploy.test.ts +++ b/platform/packages/api/test/integration/api-deploy.test.ts @@ -1992,43 +1992,53 @@ describe('POST /projects/:id/deploy', () => { ); }); - it('provisions queue and adds consumer on deploy with queues manifest', async () => { - const user = await createTestUser(env.db); - const project = await createTestProject(env.db, user.id, 'queue-app'); - const fetchMock = mockCfApi(); - - const res = await app.fetch( - await buildDeployRequest(env, project.id, user.jwt, { - manifest: { - version: 3, - bindings: {}, - queues: [{ name: 'emails', bindingName: 'QUEUE_EMAILS' }], - }, - }), - env, - ); - expect(res.status).toBe(200); - await res.text(); + it.each([undefined, 2])( + 'provisions queue and adds consumer (maxConcurrency: %s)', + async (maxConcurrency) => { + const user = await createTestUser(env.db); + const project = await createTestProject(env.db, user.id, 'queue-app'); + const fetchMock = mockCfApi(); - // Verify queue resource was created in DB with queue_id (UUID), not queue_name - const [resource] = await env.db - .select({ cf_id: resources.cf_id, binding_name: resources.binding_name }) - .from(resources) - .where(eq(resources.project_id, project.id)); - expect(resource).toBeDefined(); - expect(resource!.cf_id).toBe('a1b2c3d4-e5f6-7890-abcd-ef1234567890'); - expect(resource!.binding_name).toBe('emails'); + const res = await app.fetch( + await buildDeployRequest(env, project.id, user.jwt, { + manifest: { + version: 3, + bindings: {}, + queues: [{ name: 'emails', bindingName: 'QUEUE_EMAILS', maxConcurrency }], + }, + }), + env, + ); + expect(res.status).toBe(200); + await res.text(); - // Verify addQueueConsumer was called with queue_id (UUID), not queue_name - const consumerCall = fetchMock.mock.calls.find((call: Array) => { - const url = typeof call[0] === 'string' ? call[0] : String(call[0]); - return url.includes('/queues/') && url.includes('/consumers'); - }); - expect(consumerCall).toBeDefined(); - const consumerUrl = - typeof consumerCall![0] === 'string' ? consumerCall![0] : String(consumerCall![0]); - expect(consumerUrl).toContain('a1b2c3d4-e5f6-7890-abcd-ef1234567890'); - }); + // Verify queue resource was created in DB with queue_id (UUID), not queue_name + const [resource] = await env.db + .select({ cf_id: resources.cf_id, binding_name: resources.binding_name }) + .from(resources) + .where(eq(resources.project_id, project.id)); + expect(resource).toBeDefined(); + expect(resource!.cf_id).toBe('a1b2c3d4-e5f6-7890-abcd-ef1234567890'); + expect(resource!.binding_name).toBe('emails'); + + // Verify addQueueConsumer was called with queue_id (UUID), not queue_name + const consumerCall = fetchMock.mock.calls.find((call: Array) => { + const url = typeof call[0] === 'string' ? call[0] : String(call[0]); + return ( + url.includes('/queues/') && + url.includes('/consumers') && + (call[1] as RequestInit | undefined)?.method === 'POST' + ); + }); + expect(consumerCall).toBeDefined(); + const consumerUrl = + typeof consumerCall![0] === 'string' ? consumerCall![0] : String(consumerCall![0]); + expect(consumerUrl).toContain('a1b2c3d4-e5f6-7890-abcd-ef1234567890'); + expect(JSON.parse(String(consumerCall![1]?.body)).settings).toEqual( + maxConcurrency === undefined ? {} : { max_concurrency: maxConcurrency }, + ); + }, + ); it('includes queue producer binding in worker upload metadata', async () => { const user = await createTestUser(env.db); diff --git a/platform/packages/api/test/integration/api-projects.test.ts b/platform/packages/api/test/integration/api-projects.test.ts index 88d88f78b..011f1d0b1 100644 --- a/platform/packages/api/test/integration/api-projects.test.ts +++ b/platform/packages/api/test/integration/api-projects.test.ts @@ -2963,7 +2963,9 @@ describe('POST /projects/:id/rollback', () => { version: 4, type: 'void', bindings: {}, - queues: [{ name: 'emails', bindingName: 'QUEUE_EMAILS', maxBatchSize: 20 }], + queues: [ + { name: 'emails', bindingName: 'QUEUE_EMAILS', maxBatchSize: 20, maxConcurrency: 2 }, + ], }), ); await updateDeploymentStatus(env.db, target.id, 'live'); @@ -2975,7 +2977,9 @@ describe('POST /projects/:id/rollback', () => { version: 4, type: 'void', bindings: {}, - queues: [{ name: 'emails', bindingName: 'QUEUE_EMAILS', maxBatchSize: 5 }], + queues: [ + { name: 'emails', bindingName: 'QUEUE_EMAILS', maxBatchSize: 5, maxConcurrency: 1 }, + ], }), ); await updateDeploymentStatus(env.db, current.id, 'live'); @@ -2986,9 +2990,9 @@ describe('POST /projects/:id/rollback', () => { consumer_id: 'consumer-1', script: 'void-dispatch', type: 'worker', - settings: { batch_size: 5, max_retries: 2 }, + settings: { batch_size: 5, max_retries: 2, max_concurrency: 1 }, }; - const newConsumer = { ...oldConsumer, settings: { batch_size: 20 } }; + const newConsumer = { ...oldConsumer, settings: { batch_size: 20, max_concurrency: 2 } }; let listCalls = 0; const updateBodies: Array = []; mockCfApi({ @@ -3031,11 +3035,11 @@ describe('POST /projects/:id/rollback', () => { expect(res.status).toBe(500); expect((await db.getProject(env.db, project.id))?.active_deployment_id).toBe(current.id); expect(updateBodies).toHaveLength(2); - expect(updateBodies[0]).toMatchObject({ settings: { batch_size: 20 } }); + expect(updateBodies[0]).toMatchObject({ settings: { batch_size: 20, max_concurrency: 2 } }); expect(updateBodies[1]).toEqual({ script_name: 'void-dispatch', type: 'worker', - settings: { batch_size: 5, max_retries: 2 }, + settings: { batch_size: 5, max_retries: 2, max_concurrency: 1 }, }); }); diff --git a/platform/packages/api/test/integration/deployment-recovery.test.ts b/platform/packages/api/test/integration/deployment-recovery.test.ts index a1655e533..d8b3a4a4e 100644 --- a/platform/packages/api/test/integration/deployment-recovery.test.ts +++ b/platform/packages/api/test/integration/deployment-recovery.test.ts @@ -365,12 +365,12 @@ test('preserves retained historical deployment artifacts while terminalizing its }); test.each([ - { issued: 1, held: 0 }, - { issued: 1, held: 1 }, - { issued: 0, held: 0 }, + { issued: 1, held: 0, maxConcurrency: 2 }, + { issued: 1, held: 1, maxConcurrency: 1 }, + { issued: 0, held: 0, maxConcurrency: undefined }, ])( 'cutover replay to a Worker on generation $held while generation $issued is issued writes only its token', - async ({ issued, held }) => { + async ({ issued, held, maxConcurrency }) => { await env.db .update(projects) .set({ proxy_token_gen: issued }) @@ -384,7 +384,7 @@ test.each([ type: 'void', bindings: {}, schedules: [{ cron: '*/5 * * * *', filePath: 'crons/tick.ts' }], - queues: [{ name: 'emails', bindingName: 'QUEUE_EMAILS' }], + queues: [{ name: 'emails', bindingName: 'QUEUE_EMAILS', maxConcurrency }], }), }) .where(eq(deployments.id, deployment.id)); @@ -396,9 +396,14 @@ test.each([ binding_name: 'emails', }); const heldToken = await deriveProxyToken(env.JWT_SECRET, project.id, held); + const consumerBodies: Array = []; mockCfApi({ listWorkerBindings: () => cfSuccess([{ type: 'plain_text', name: '__VOID_PROXY_TOKEN', text: heldToken }]), + addQueueConsumer: (_url, init) => { + consumerBodies.push(JSON.parse(String(init?.body))); + return cfSuccess({ consumer_id: 'consumer-1' }); + }, }); const syncBodies: Array = []; const originalGet = env.CRON_SCHEDULER.get.bind(env.CRON_SCHEDULER); @@ -438,5 +443,12 @@ test.each([ // Exactly one token: the one the Worker holds. expect(Object.keys(sync).filter((key) => key.startsWith('proxyToken'))).toEqual(['proxyToken']); expect(sync.proxyToken).toBe(heldToken); + expect(consumerBodies).toEqual([ + { + script_name: 'void-dispatch', + type: 'worker', + settings: maxConcurrency === undefined ? {} : { max_concurrency: maxConcurrency }, + }, + ]); }, );