Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/guide/queues.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -106,11 +107,16 @@ export default defineQueue<Message>(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/).
Expand Down
1 change: 1 addition & 0 deletions packages/deploy-core/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ export type QueueMeta = {
bindingName: string;
maxBatchSize?: number;
maxBatchTimeout?: number;
maxConcurrency?: number;
maxRetries?: number;
retryDelay?: number;
};
Expand Down
9 changes: 9 additions & 0 deletions packages/deploy-core/src/validate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
27 changes: 27 additions & 0 deletions packages/deploy-core/test/unit/validate.test.ts
Original file line number Diff line number Diff line change
@@ -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(
Expand Down
1 change: 1 addition & 0 deletions packages/void/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<worker>-<name>` (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.

Expand Down
4 changes: 2 additions & 2 deletions packages/void/src/cli/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.-]+)?$/;

Expand Down
1 change: 1 addition & 0 deletions packages/void/src/cli/deploy-cloudflare-preflight.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions packages/void/src/cli/deploy-helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }),
})),
Expand Down
1 change: 1 addition & 0 deletions packages/void/src/cli/gen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -677,6 +677,7 @@ type Message = {};

// export const maxBatchSize = 10;
// export const maxBatchTimeout = 5;
// export const maxConcurrency = 2;

export default defineQueue<Message>(async (batch, env) => {
for (const message of batch.messages) {
Expand Down
23 changes: 23 additions & 0 deletions packages/void/src/cli/wrangler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};
Expand Down Expand Up @@ -915,6 +916,8 @@ export type ProvisionedWranglerPatch = {
type ManagedQueueProvenance = {
producerBindings: Array<string>;
consumerQueues: Array<string>;
/** Consumers whose max_concurrency was set from a queue file export. */
consumerConcurrencyQueues: Array<string>;
/** Void-owned consumers removed locally but not yet confirmed removed remotely. */
pendingConsumerRemovals: Array<string>;
};
Expand All @@ -923,6 +926,7 @@ function readManagedQueueProvenance(text: string): ManagedQueueProvenance {
const none: ManagedQueueProvenance = {
producerBindings: [],
consumerQueues: [],
consumerConcurrencyQueues: [],
pendingConsumerRemovals: [],
};
const encoded = MANAGED_QUEUES_MARKER.exec(text)?.[1];
Expand All @@ -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 {
Expand All @@ -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) {
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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],
});
}
Expand Down
1 change: 1 addition & 0 deletions packages/void/src/plugin-worker-bindings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 }),
})),
Expand Down
20 changes: 17 additions & 3 deletions packages/void/src/queues/scan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 */
Expand All @@ -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<string> = new Set(OPTION_NAMES);

/** Queue files already warned about `export *`; a dev server rescans queues on every change. */
Expand Down Expand Up @@ -83,9 +91,14 @@ export function scanQueuesSync(queuesDir: string): Array<QueueDefinition> {
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;
Expand All @@ -96,6 +109,7 @@ export function scanQueuesSync(queuesDir: string): Array<QueueDefinition> {
bindingName: deriveQueueBindingName(name),
maxBatchSize: optionValue('maxBatchSize'),
maxBatchTimeout: optionValue('maxBatchTimeout'),
maxConcurrency: optionValue('maxConcurrency'),
maxRetries: optionValue('maxRetries'),
retryDelay: optionValue('retryDelay'),
};
Expand Down
13 changes: 8 additions & 5 deletions packages/void/test/unit/client-platform-version.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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');
Expand All @@ -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(
Expand Down Expand Up @@ -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']);
Expand Down
41 changes: 41 additions & 0 deletions packages/void/test/unit/cloudflare-deploy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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() {}',
Expand All @@ -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,
},
Expand All @@ -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({
Expand Down
Loading