Uh oh!
There was an error while loading. Please reload this page.
Add env vars to help test Vercel Queue max 24 hour message TTL - #653
Merged
TooTallNate merged 4 commits intoDec 19, 2025
Conversation
|
Contributor
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
🧪 E2E Test Results❌ Some tests failed Summary
❌ Failed Tests💻 Local Development (27 failed)fastify-stable (26 failed):
nitro-stable (1 failed):
🌍 Community Worlds (11 failed)mongodb (1 failed):
redis (1 failed):
starter (8 failed):
turso (1 failed):
Details by Category✅ ▲ Vercel Production
❌ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
❌ 🌍 Community Worlds
❌ Some E2E test jobs failed:
Check the workflow run for details. |
TooTallNate
commented
Dec 18, 2025
MemberAuthor
Warning This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
This stack of pull requests is managed by Graphite. Learn more about stacking. |
Comment on lines
+23
to
+31
| const VERCEL_QUEUE_MAX_VISIBILITY = Number( | ||
| process.env.VERCEL_QUEUE_MAX_VISIBILITY ?? 39600 // 11 hours in seconds | ||
| ); | ||
| const VERCEL_QUEUE_MESSAGE_LIFETIME = Number( | ||
| process.env.VERCEL_QUEUE_MESSAGE_LIFETIME ?? 86400 // 24 hours in seconds | ||
| ); | ||
| const MESSAGE_LIFETIME_BUFFER = Number( | ||
| process.env.VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER ?? 3600 // 1 hour buffer before lifetime expires | ||
| ); |
Contributor
There was a problem hiding this comment.
Environment variables are converted to numbers without validation, which could result in NaN values if invalid values are provided, breaking queue timing logic.
View Details
📝 Patch Details
diff --git a/packages/world-vercel/src/queue.ts b/packages/world-vercel/src/queue.ts
index 8b6f791..31377c0 100644
--- a/packages/world-vercel/src/queue.ts+++ b/packages/world-vercel/src/queue.ts@@ -20,14 +20,34 @@ const MessageWrapper = z.object({
});
// Queue timing constants - can be overridden via environment variables for testing
-const VERCEL_QUEUE_MAX_VISIBILITY = Number(- process.env.VERCEL_QUEUE_MAX_VISIBILITY ?? 39600 // 11 hours in seconds+const parseEnvNumber = (+ value: string | undefined,+ defaultValue: number+): number => {+ if (value === undefined) {+ return defaultValue;+ }+ const parsed = Number(value);+ if (Number.isNaN(parsed)) {+ console.warn(+ `Invalid number in environment variable: "${value}". Using default: ${defaultValue}`+ );+ return defaultValue;+ }+ return parsed;+};++const VERCEL_QUEUE_MAX_VISIBILITY = parseEnvNumber(+ process.env.VERCEL_QUEUE_MAX_VISIBILITY,+ 39600 // 11 hours in seconds
);
-const VERCEL_QUEUE_MESSAGE_LIFETIME = Number(- process.env.VERCEL_QUEUE_MESSAGE_LIFETIME ?? 86400 // 24 hours in seconds+const VERCEL_QUEUE_MESSAGE_LIFETIME = parseEnvNumber(+ process.env.VERCEL_QUEUE_MESSAGE_LIFETIME,+ 86400 // 24 hours in seconds
);
-const MESSAGE_LIFETIME_BUFFER = Number(- process.env.VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER ?? 3600 // 1 hour buffer before lifetime expires+const MESSAGE_LIFETIME_BUFFER = parseEnvNumber(+ process.env.VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER,+ 3600 // 1 hour buffer before lifetime expires
);
export function createQueue(config?: APIConfig): Queue {
Analysis
Invalid environment variables cause NaN in queue timing constants, breaking message re-enqueue logic
What fails: Queue message re-enqueue logic in createQueueHandler() silently fails when environment variables VERCEL_QUEUE_MAX_VISIBILITY, VERCEL_QUEUE_MESSAGE_LIFETIME, or VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER are set to non-numeric values.
How to reproduce:
VERCEL_QUEUE_MAX_VISIBILITY="invalid" \
VERCEL_QUEUE_MESSAGE_LIFETIME="not-a-number" \
VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER="abc" \
node app.jsResult: Constants become NaN. When a message approaches its 24-hour lifetime:
- Line 102-105:
Math.min(result.timeoutSeconds, VERCEL_QUEUE_MAX_VISIBILITY)returnsNaN(since any operation with NaN returns NaN) - Line 112-113: The condition
messageAgeAtNextProcessing > VERCEL_QUEUE_MESSAGE_LIFETIME - MESSAGE_LIFETIME_BUFFERevaluates tofalse(any comparison with NaN returns false), so messages never get re-enqueued even when approaching the lifetime limit
Expected behavior: Invalid environment variables should fall back to safe defaults with a warning. Messages should be re-enqueued when approaching the 24-hour lifetime limit.
Fix: Added parseEnvNumber() helper that validates parsed numbers with Number.isNaN() and falls back to defaults, warning when invalid values are provided.
TooTallNate
marked this pull request as ready for review
December 19, 2025 18:51
TooTallNate
merged commit Dec 19, 2025
7bbba1c
into
12-18-handle_vercel_queue_24_hour_message_ttl_by_re-enqueueing_message
68 of 71 checks passed
Uh oh!
There was an error while loading. Please reload this page.
TooTallNate
deleted the
12-18-add_env_vars_to_help_test_vercel_queue_max_24_hour_message_ttl
branch
December 19, 2025 18:51
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors the Vercel Queue message lifetime tracking by replacing the custom messageQueuedAt field with the built-in meta.createdAt timestamp provided by the Vercel Queue library. It also introduces environment variable overrides for testing the 24-hour message TTL behavior.
Key Changes:
- Simplified message lifetime tracking by using Vercel's native
meta.createdAtinstead of manually tracking message queue timestamps - Added environment variable configuration (
VERCEL_QUEUE_MESSAGE_LIFETIMEandVERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER) to allow testing different TTL scenarios - Improved logging for message lifetime limit handling and timeout clamping
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| packages/world-vercel/src/queue.ts | Removed custom messageQueuedAt tracking; added env var configuration for testing; simplified message lifetime calculation using meta.createdAt; improved logging for debugging |
| packages/world-vercel/src/queue.test.ts | Updated tests to use meta.createdAt in mock objects; removed backwards compatibility test; updated test descriptions to reflect new behavior |
Comments suppressed due to low confidence (1)
packages/world-vercel/src/queue.test.ts:196
- Consider adding tests that verify the environment variable overrides work correctly. Since the PR title mentions "Add env vars to help test Vercel Queue max 24 hour message TTL", it would be valuable to have at least one test that demonstrates setting
VERCEL_QUEUE_MESSAGE_LIFETIMEandVERCEL_QUEUE_MESSAGE_LIFETIME_BUFFERenvironment variables and verifies the behavior changes accordingly.
describe('createQueue', () => {
beforeEach(() => {
vi.clearAllMocks();
});
afterEach(() => {
vi.clearAllMocks();
});
describe('queue()', () => {
it('should send message with payload and queueName', async () => {
mockSend.mockResolvedValue({ messageId: 'msg-123' });
const queue = createQueue();
await queue.queue('__wkf_workflow_test', { runId: 'run-123' });
expect(mockSend).toHaveBeenCalledTimes(1);
const sentPayload = mockSend.mock.calls[0][1];
expect(sentPayload.payload).toEqual({ runId: 'run-123' });
expect(sentPayload.queueName).toBe('__wkf_workflow_test');
});
});
describe('createQueueHandler()', () => {
// Helper to simulate handleCallback behavior
function setupHandler(handlerResult: { timeoutSeconds: number } | void) {
const capturedHandlers: Record<
string,
{ default: (body: unknown, meta: unknown) => Promise<unknown> }
> = {};
mockHandleCallback.mockImplementation((handlers) => {
Object.assign(capturedHandlers, handlers);
return async (req: Request) => new Response('ok');
});
const queue = createQueue();
queue.createQueueHandler('__wkf_workflow_', async () => handlerResult);
// Get the handler that was registered
const handlerKey = Object.keys(capturedHandlers)[0];
return capturedHandlers[handlerKey].default;
}
it('should pass through timeoutSeconds when message is fresh', async () => {
const handler = setupHandler({ timeoutSeconds: 50000 });
const result = await handler(
{
payload: { runId: 'run-123' },
queueName: '__wkf_workflow_test',
},
{ messageId: 'msg-123', deliveryCount: 1, createdAt: new Date() }
);
// Should pass through unchanged since message is fresh
expect(result).toEqual({ timeoutSeconds: 50000 });
expect(mockSend).not.toHaveBeenCalled(); // No re-enqueue
});
it('should clamp timeoutSeconds when message has limited lifetime remaining', async () => {
const handler = setupHandler({ timeoutSeconds: 7200 }); // 2 hours
// Message that was created 22 hours ago
// maxAllowedTimeout = 86400 - 3600 - 79200 = 3600s (1 hour)
const oldMessageTime = new Date(Date.now() - 22 * 60 * 60 * 1000);
const result = await handler(
{
payload: { runId: 'run-123' },
queueName: '__wkf_workflow_test',
},
{ messageId: 'msg-123', deliveryCount: 1, createdAt: oldMessageTime }
);
// Should clamp to maxAllowedTimeout (~3600s)
expect(result).toBeDefined();
expect((result as { timeoutSeconds: number }).timeoutSeconds).toBeCloseTo(
3600,
0
);
expect(mockSend).not.toHaveBeenCalled(); // No re-enqueue, just clamping
});
it('should re-enqueue when message has no lifetime remaining', async () => {
mockSend.mockResolvedValue({ messageId: 'new-msg-123' });
const handler = setupHandler({ timeoutSeconds: 3600 }); // 1 hour
// Message that was created 23 hours ago (at the buffer limit)
// maxAllowedTimeout = 86400 - 3600 - 82800 = 0s
const oldMessageTime = new Date(Date.now() - 23 * 60 * 60 * 1000);
const result = await handler(
{
payload: { runId: 'run-123' },
queueName: '__wkf_workflow_test',
},
{ messageId: 'msg-123', deliveryCount: 1, createdAt: oldMessageTime }
);
// Should return undefined (acknowledge old message)
expect(result).toBeUndefined();
// Should have re-enqueued
expect(mockSend).toHaveBeenCalledTimes(1);
const sentPayload = mockSend.mock.calls[0][1];
expect(sentPayload.payload).toEqual({ runId: 'run-123' });
expect(sentPayload.queueName).toBe('__wkf_workflow_test');
});
it('should not re-enqueue when message has enough lifetime remaining', async () => {
const handler = setupHandler({ timeoutSeconds: 7200 }); // 2 hours
// Message that was created 10 hours ago (plenty of time remaining)
const messageTime = new Date(Date.now() - 10 * 60 * 60 * 1000);
const result = await handler(
{
payload: { runId: 'run-123' },
queueName: '__wkf_workflow_test',
},
{ messageId: 'msg-123', deliveryCount: 1, createdAt: messageTime }
);
// Should return the timeout (not re-enqueue)
expect(result).toEqual({ timeoutSeconds: 7200 });
expect(mockSend).not.toHaveBeenCalled();
});
it('should pass through result when no timeoutSeconds', async () => {
const handler = setupHandler(undefined);
const result = await handler(
{
payload: { runId: 'run-123' },
queueName: '__wkf_workflow_test',
},
{ messageId: 'msg-123', deliveryCount: 1, createdAt: new Date() }
);
expect(result).toBeUndefined();
expect(mockSend).not.toHaveBeenCalled();
});
it('should handle step payloads correctly', async () => {
mockSend.mockResolvedValue({ messageId: 'new-msg-123' });
const handler = setupHandler({ timeoutSeconds: 3600 }); // 1 hour
// Old message approaching expiry
const oldMessageTime = new Date(Date.now() - 23 * 60 * 60 * 1000);
const stepPayload = {
workflowName: 'test-workflow',
workflowRunId: 'run-123',
workflowStartedAt: Date.now(),
stepId: 'step-456',
};
await handler(
{
payload: stepPayload,
queueName: '__wkf_step_myStep',
},
{ messageId: 'msg-123', deliveryCount: 1, createdAt: oldMessageTime }
);
expect(mockSend).toHaveBeenCalledTimes(1);
const sentPayload = mockSend.mock.calls[0][1];
expect(sentPayload.payload).toEqual(stepPayload);
});
});
});
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+17
to
+21
| const VERCEL_QUEUE_MESSAGE_LIFETIME = Number( | ||
| process.env.VERCEL_QUEUE_MESSAGE_LIFETIME ?? 86400 // 24 hours in seconds | ||
| ); | ||
| const MESSAGE_LIFETIME_BUFFER = Number( | ||
| process.env.VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER ?? 3600 // 1 hour buffer before lifetime expires |
There was a problem hiding this comment.
Using Number() to convert environment variables can produce NaN if the environment variables contain invalid numeric values. This would cause the message lifetime calculations to fail silently. Consider adding validation to ensure the environment variables are valid numbers, or use parseInt() with explicit radix and validate the result.
Suggested change
| constVERCEL_QUEUE_MESSAGE_LIFETIME=Number( | |
| process.env.VERCEL_QUEUE_MESSAGE_LIFETIME??86400// 24 hours in seconds | |
| ); | |
| constMESSAGE_LIFETIME_BUFFER=Number( | |
| process.env.VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER??3600// 1 hour buffer before lifetime expires | |
| functiongetNumericEnv(name: string,defaultValue: number): number{ | |
| constraw=process.env[name]; | |
| if(raw==null||raw===''){ | |
| returndefaultValue; | |
| } | |
| constparsed=parseInt(raw,10); | |
| if(Number.isNaN(parsed)){ | |
| console.warn( | |
| `Invalid numeric value for environment variable ${name}: "${raw}". Using default value ${defaultValue}.` | |
| ); | |
| returndefaultValue; | |
| } | |
| returnparsed; | |
| } | |
| constVERCEL_QUEUE_MESSAGE_LIFETIME=getNumericEnv( | |
| 'VERCEL_QUEUE_MESSAGE_LIFETIME', | |
| 86400// 24 hours in seconds | |
| ); | |
| constMESSAGE_LIFETIME_BUFFER=getNumericEnv( | |
| 'VERCEL_QUEUE_MESSAGE_LIFETIME_BUFFER', | |
| 3600// 1 hour buffer before lifetime expires |
Comment on lines
+76
to
+79
| const maxAllowedTimeout = | ||
| VERCEL_QUEUE_MESSAGE_LIFETIME - | ||
| MESSAGE_LIFETIME_BUFFER - | ||
| messageAge; |
There was a problem hiding this comment.
The maxAllowedTimeout calculation can result in negative values, which are then checked with <= 0. However, when maxAllowedTimeout is negative, using it in calculations or logging could be confusing. Consider clamping maxAllowedTimeout to a minimum of 0 using Math.max(0, ...) to make the logic clearer, even though the conditional already handles negative values.
Suggested change
| constmaxAllowedTimeout= | |
| VERCEL_QUEUE_MESSAGE_LIFETIME- | |
| MESSAGE_LIFETIME_BUFFER- | |
| messageAge; | |
| constmaxAllowedTimeout=Math.max( | |
| 0, | |
| VERCEL_QUEUE_MESSAGE_LIFETIME- | |
| MESSAGE_LIFETIME_BUFFER- | |
| messageAge | |
| ); |
Comment on lines
+72
to
+73
| // Calculate how old this message is using the queue's createdAt timestamp | ||
| const messageAge = (now - meta.createdAt.getTime()) / 1000; // Convert to seconds |
There was a problem hiding this comment.
The code assumes meta.createdAt is always available and is a valid Date object. If the Vercel Queue library doesn't guarantee this field is always present, or if it could be null/undefined, the code will throw an error when calling .getTime(). Consider adding validation or a fallback to handle cases where meta.createdAt might be missing, or verify that the Vercel Queue library guarantees this field is always present.
Suggested change
| // Calculate how old this message is using the queue's createdAt timestamp | |
| constmessageAge=(now-meta.createdAt.getTime())/1000;// Convert to seconds | |
| constcreatedAt=meta?.createdAt; | |
| if(!(createdAtinstanceofDate)){ | |
| console.warn( | |
| '[Workflows] meta.createdAt is missing or not a Date; skipping message lifetime calculations.' | |
| ); | |
| returnresult; | |
| } | |
| // Calculate how old this message is using the queue's createdAt timestamp | |
| constmessageAge=(now-createdAt.getTime())/1000;// Convert to seconds |
TooTallNate added a commit
that referenced
this pull request
Dec 19, 2025
* Add env vars to help test Vercel Queue max 24 hour message TTL * . * . * .
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
For testing. May or may not end up merging.