chore: update workflow queues api by NathanFlurry · Pull Request #4230 · rivet-dev/rivet

NathanFlurry · 2026-02-19T07:43:32Z

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes

railway-app · 2026-02-19T07:43:41Z

🚅 Deployed to the rivet-pr-4230 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Feb 19, 2026 at 7:56 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:45 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:44 am
mcp-hub	✅ Success (View Logs)	Web	Feb 19, 2026 at 7:44 am
ladle	❌ Build Failed (View Logs)	Web	Feb 19, 2026 at 7:44 am

NathanFlurry · 2026-02-19T07:43:51Z

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.
Learn more

chore(rivetkit): make execute generic #4231
chore: update workflow queues api #4230 👈 (View in Graphite)
chore: simplify queue api #4229 : 1 other dependent PR (#4200 )
refactor(rivetkit): add typed event and queue schemas for actors #4209 : 1 other dependent PR (#4224 )
main

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has enabled the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

claude · 2026-02-19T07:46:18Z

PR Review: chore: update workflow queues api

This PR replaces 7 separate listen*() methods with a unified ctx.queue.next(name, opts) API. The consolidation is a clear improvement to the interface — fewer methods, more composable options, and better type safety. Here are notes grouped by severity.

Potential Bugs / Correctness Issues

History format migration — The rename from __rivetWorkflowListenMessage to __rivetWorkflowQueueMessage in context.ts is a breaking change for any in-flight workflows persisted with the old marker. fromHistoryQueueMessage will not recognize old entries and will fall back to treating the raw value as the message body, returning completed: false. For a backend service this is a silent correctness failure on resume — workflows that had already received and should-have-completed a message will try to re-receive it. If there are any live workflows using the old API, a migration or version gate is needed before merging.

hasMessages semantic change in executeLiveWorkflow (index.ts):

// Before (checks length)
const hasMessages = result.waitingForMessages && result.waitingForMessages.length > 0;

// After (checks existence only)
const hasMessages = result.waitingForMessages \!== undefined;

An empty waitingForMessages = [] now sets hasMessages = true, which is intentional for the wildcard case (empty names = any message). However, this means driver.waitForMessages will be called with an empty array when a wildcard wait has a deadline. Confirm that both ActorWorkflowDriver.waitForNames and the live runtime's waitForMessage handle names = [] correctly — they appear to, but a comment explaining the invariant would help future readers.

Early return in completable fixture (workflow-fixtures.ts):

const [message] = await loopCtx.queue.next("queue-wait", { names: [WORKFLOW_QUEUE_NAME], completable: true });
if (\!message || \!message.complete) {
    return Loop.continue(undefined); // silently skips storing
}

When completable: true and no timeout is set, queue.next will block until a message arrives, so \!message should never be true here. The \!message.complete guard is similarly unreachable: if completable: true, the returned message always includes complete. The defensive guards are harmless but misleading — if either condition were reachable it would silently skip a received message rather than surfacing an error. Consider removing them or replacing with a throw if they're meant as sanity checks.

API Design Notes

Removal of workflowQueueName() — This was a public export. Any downstream code that called workflowQueueName(x) to route messages to a workflow's queue will now need to use the bare queue name directly. The change itself is correct (the prefix added indirection with no real benefit), but it should be clearly called out as a breaking change in the PR description and changelog.

completable as an opt-in flag — The new model is cleaner than the old one where listen() always returned a completable handle. One ergonomic consideration: if a caller passes completable: true but uses the TypeScript type as WorkflowQueueMessage (without the narrowed type), complete appears as optional. The overloads in ActorWorkflowContext.queue.next handle this, but make sure the base WorkflowQueue.next type in types.ts preserves the conditional return correctly through all call paths.

listenUntil → timeout semantic shift — The old listenUntil took an absolute timestamp; timeout is relative. The deadline is persisted to history on first execution so replay uses the recorded deadline, which is correct. A comment in the method noting this behavior ("deadline is recorded on first execution and replayed from history") would help readers who notice the relative-vs-absolute distinction.

Minor / Style

Inconsistent indentation in context.ts — Several blocks in checkDuplicateName and the surrounding methods have mixed indentation levels (some blocks have an extra level of indentation compared to the method body). This appears to be leftover from a rebase or partial refactor.

Indentation in messages.test.ts — Several test bodies gained an extra indentation level (e.g., the workflow function inside tests is indented one level too deep relative to the it block). This is cosmetic but makes diffs harder to read and inconsistent with neighboring tests.

#log removed from ActorWorkflowDriver — The helper was deleted without replacement. If any debug logging is needed in the driver in the future this will need to be re-added. Fine to remove if it was unused, just noting it.

queueSend asymmetry (context.ts):

if (\!this.messageDriver.receiveMessages) {
    this.storage.messages.push(message); // only for non-actor-backed drivers
}
await this.messageDriver.addMessage(message);

The logic is correct — actor-backed drivers bypass local storage — but a brief comment explaining why the push is conditional ("actor-backed drivers manage their own message storage") would clarify intent.

Test Coverage

The new tests for completable replay (replay should not block the next completable queue.next and replay should keep blocking if completable message was not completed) are a nice addition and cover an important correctness property. The existing suite is well-updated.

One gap: there is no test for the wildcard case (names omitted or []). Given the hasMessages change and the notifyMessage/waitForMessage logic changes to support wildcards, a test that sends a message to any name and receives it with a wildcard queue.next would provide confidence.

Overall this is a solid API cleanup. The main item to resolve before merging is the history format migration concern for in-flight workflows.

pkg-pr-new · 2026-02-19T07:46:32Z

More templates

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4230

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4230

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4230

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4230

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4230

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4230

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4230

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4230

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4230

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4230

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4230

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4230

commit: 480b364

chore: update workflow queues api

480b364

railway-app bot had a problem deploying to rivet-frontend / rivet-pr-4230 February 19, 2026 07:43 Failure

This was referenced Feb 19, 2026

chore: multiplayer cookbook #4200

Open

chore: multiplayer examples #4201

Closed

chore(repo): ignore openspec #4202

Closed

chore: multiplayer game examples #4203

Closed

NathanFlurry mentioned this pull request Feb 19, 2026

chore: simplify queue api #4229

Open

11 tasks

NathanFlurry marked this pull request as ready for review February 19, 2026 08:12

NathanFlurry mentioned this pull request Feb 19, 2026

chore(rivetkit): make execute generic #4231

Open

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: update workflow queues api#4230

chore: update workflow queues api#4230
NathanFlurry wants to merge 1 commit into02-18-chore_simplify_queue_apifrom
02-18-chore_update_workflow_queues_api

NathanFlurry commented Feb 19, 2026

Uh oh!

railway-app bot commented Feb 19, 2026 •

edited

Loading

Uh oh!

NathanFlurry commented Feb 19, 2026 •

edited

Loading

Uh oh!

claude bot commented Feb 19, 2026

Uh oh!

pkg-pr-new bot commented Feb 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

Conversation

NathanFlurry commented Feb 19, 2026

Description

Type of change

How Has This Been Tested?

Checklist:

Uh oh!

railway-app bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NathanFlurry commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

claude bot commented Feb 19, 2026

PR Review: chore: update workflow queues api

Potential Bugs / Correctness Issues

API Design Notes

Minor / Style

Test Coverage

Uh oh!

pkg-pr-new bot commented Feb 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

railway-app bot commented Feb 19, 2026 •

edited

Loading

NathanFlurry commented Feb 19, 2026 •

edited

Loading