fix: add ready_chunks to worker bumps, bumps per tick metric

[MasterPtato]

No description provided.

[MasterPtato]

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

• fix(pegboard): cache none runner pool errors too #3899
• fix(engine-runner): handle shutdown close codes correctly #3896
• chore(gas): add overview and history docs #3879
• fix(otel): enrich http traces #3878
• fix(guard): clean up guard #3862
• fix: add ready_chunks to worker bumps, bumps per tick metric #3855 👈 (View in Graphite)
• fix(epoxy): add metrics #3847
• chore: clean up errors #3846
• fix(pb): have restart policy actors sleep after pending for too long #3837
• fix: set failure reason regardless of crash policy #3835
• feat: add metrics to pb, guard #3815
• fix: clear all pending signals after workflow complete #3798
• fix: remove pending actors metric, fix actor error tracker, engine runner error print #3797
• chore(engine): add support for epoxy debugging #3794
• 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.

[pkg-pr-new]

More templates

• actor-actions
• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• cross-actor-actions
• example-cursors
• example-cursors-raw-websocket
• custom-serverless
• example-sqlite
• example-elysia
• example-experimental-durable-streams-ai-agent
• hello-world
• example-hono
• hono-react
• example-kitchen-sink
• multi-region
• native-websockets
• next-js
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• scheduling
• state
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: fab1f2d

[claude]

PR Review: Add ready_chunks to worker bumps, bumps per tick metric

Summary

This PR introduces two improvements to the Gasoline worker's bump handling:

1. Uses ready_chunks(1024) to batch bump messages together
2. Adds a new metric WORKER_BUMPS_PER_TICK to track how many bump messages are processed per tick

Positive Observations

✅ Good performance optimization: Using ready_chunks is an excellent approach to coalesce multiple bump notifications into a single wake event. This prevents unnecessary tick processing when many bumps arrive in quick succession.

✅ Useful observability: The new histogram metric will provide valuable insights into bump batching behavior and help identify if the chunk size of 1024 is appropriate.

✅ Proper histogram buckets: The bucket distribution (1, 2, 3, 4, 8, 16, 32, 64, 128, 256, 512, 1024) is well-suited for tracking bump counts with good granularity at lower values.

✅ Follows project conventions: Code style matches the existing patterns, structured logging is used properly, and the metric is registered correctly.

Issues and Concerns

1. Logic Error: Metric only recorded on Some, not None (Minor)

In worker.rs:112-118, the metric is only observed when bumps are received (Some(bumps)). However, the tick still happens and processes workflows even when the subscription ends (None case), which immediately breaks the loop. This is likely fine, but worth noting that the metric won't capture the final state before shutdown.

2. Missing Logging (Minor)

The original code didn't log anything about bumps, and neither does the new code. Consider adding a debug log when a large batch is received to help with diagnostics.

3. Magic Number: 1024 chunk size (Minor)

The chunk size of 1024 is hardcoded without explanation. While this is likely fine for most cases, consider:

• Documenting why 1024 was chosen
• Whether this should be configurable
• What happens if the actual burst size exceeds 1024 (answer: it processes them in multiple ticks, which is fine)

4. Ready Chunks Behavior Clarification (Documentation)

The comment on line 77 states "multiple bumps in a row should be processed as 1 bump," which is accurate. However, it's worth understanding that ready_chunks(1024):

• Returns immediately with available items (up to 1024)
• Does NOT wait to fill the buffer
• This is the desired behavior for responsiveness

The comment is correct, but could be clearer about the immediate-return behavior.

Recommendations

Priority: Low

1. Consider adding a comment explaining the choice of 1024 as the chunk size
2. Optional: Add debug logging for large bump batches to help with diagnostics
3. Optional: Add a test case that verifies metric recording with bump batching

Code Quality Assessment

• Style: ✅ Follows project conventions
• Error Handling: ✅ Appropriate (continues on None by breaking)
• Performance: ✅ Improvement from baseline
• Observability: ✅ Good metric added
• Security: ✅ No concerns
• Test Coverage: ⚠️ No new tests, but this is observability code

Verdict

LGTM with minor suggestions - This is a solid improvement that adds both performance optimization and observability. The issues noted are minor and mostly documentation-related. The code is ready to merge as-is, though the suggestions above would make it even better.

---

Review generated by Claude Code

[claude]

Code Review Summary

This PR adds batching support to worker bump message processing and introduces a new metric to track bumps per tick. Overall, this is a well-implemented optimization with appropriate observability.

---

✅ Strengths

1. Performance Optimization

• Using ready_chunks(1024) is an excellent optimization that batches multiple consecutive bump messages into a single processing tick
• This prevents unnecessary duplicate work when multiple workflows wake simultaneously
• The batch size of 1024 is reasonable and avoids unbounded memory growth

2. Good Observability

• The new WORKER_BUMPS_PER_TICK histogram metric provides valuable insights into bump batching effectiveness
• Custom bucket distribution (1, 2, 3, 4, 8, 16, 32, 64, 128, 256, 512, 1024) is well-designed for tracking typical and edge-case batch sizes
• Metric placement correctly captures the actual bump count before processing

3. Code Quality

• Import of metrics module is properly added at worker.rs:19
• Pattern matching is clean and idiomatic
• Maintains existing error handling behavior (returns WorkflowError::SubscriptionUnsubscribed on stream end)

---

🔍 Observations & Suggestions

1. Comment Accuracy (Minor)

The comment at worker.rs:77 states: "We use ready_chunks because multiple bumps in a row should be processed as 1 bump"

This is slightly misleading. ready_chunks collects multiple bumps into a batch but does not inherently "process them as 1 bump." The actual deduplication happens because the worker tick() function runs once per batch regardless of batch size.

Suggested improvement:

// Use ready_chunks to batch multiple consecutive bump messages together.
// This reduces unnecessary work since each tick processes all pending workflows
// regardless of how many bumps triggered it.

2. Metric Naming Consistency

The metric is named WORKER_BUMPS_PER_TICK but measures bumps per batch (which may or may not result in a tick). This is a minor semantic difference worth noting:

• If bump_sub fires, a tick happens
• If tick_interval fires naturally, no bumps are recorded but a tick still happens

Consider whether this metric should be called WORKER_BUMPS_PER_BATCH for precision, or if the current name adequately represents the intent. (Not a blocker, just worth considering for clarity.)

3. Error Case

The None case for bump_sub.next() correctly breaks with an error. This maintains the existing behavior, which is good. However, no metric is recorded when the subscription unexpectedly closes. Consider whether this edge case deserves a counter metric for monitoring health (e.g., gasoline_worker_subscription_errors).

4. Test Coverage

There are no apparent tests for:

• Bump batching behavior
• The new metric being properly recorded

While this is not critical for a performance optimization, consider adding integration tests that:

• Dispatch multiple workflows rapidly
• Verify the metric shows batch sizes > 1
• Ensure batching does not introduce race conditions

---

🔒 Security Considerations

✅ No security concerns identified

• No new attack surface introduced
• Batch size (1024) is bounded, preventing DoS via memory exhaustion
• No credential handling or external input processing

---

⚡ Performance Considerations

✅ This PR improves performance

• Reduces redundant tick() calls when multiple bumps arrive simultaneously
• Histogram metric has negligible overhead
• ready_chunks(1024) is efficient and does not introduce polling overhead

---

🐛 Potential Issues

✅ No critical bugs identified

Minor edge case to be aware of:

• If exactly 1024 bumps arrive, and another bump arrives immediately after, ready_chunks will emit the first batch immediately. This is correct behavior but means the metric could show multiple batches in quick succession during sustained high load.

---

📋 Recommendations

Required: None

This PR is production-ready as-is.

Nice-to-have:

1. Clarify the comment explaining ready_chunks usage (see suggestion above)
2. Consider renaming metric to WORKER_BUMPS_PER_BATCH if semantic precision matters
3. Add integration test to validate batching behavior under load

---

Final Verdict

✅ APPROVE — This is a clean, focused optimization with proper observability. The changes follow repository conventions (CLAUDE.md), maintain error handling behavior, and improve performance without introducing bugs or security issues.

Great work on this optimization! 🚀