feat(pb): actors v3

[MasterPtato]

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]

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

Service	Status	Web	Updated (UTC)
frontend-cloud	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:25 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:25 am
website	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:25 am
ladle	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:25 am
mcp-hub	✅ Success (View Logs)	Web	Mar 21, 2026 at 1:56 am

[MasterPtato]

• chore: envoy client #4521 : 2 dependent PRs (#4531 , #4534 )
• feat(pb): actors v3 #4463 👈 (View in Graphite)
• feat(ups): implement queue subs #4486
• feat(cache): add in flight deduping #4459
• fix(cache): clean up lib #4457
• fix(config): allow configuring topo dcs via map, fix pg ssl mode config #4456
• fix(api): dont 500 on cross dc response #4449
• chore: update byte units on frontend #4444
• fix: runner alloc idx logic, api auth for actor get #4443
• main

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

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/cloudflare-workers

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

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

@rivetkit/traces

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

@rivetkit/workflow-engine

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 9d9049a

[claude]

PR Review: feat(pb): actors v3

This is a large, ambitious draft PR introducing actor v3 infrastructure. Since it's a draft, I'm flagging issues to address before it's ready for merge.

---

Critical Issues (must fix before merge)

1. Package name mismatch in pegboard-envoy/Cargo.toml
The package is named pegboard-runner but lives in the pegboard-envoy directory. routing/envoy.rs references PegboardEnvoyWsCustomServe, but lib.rs defines PegboardRunnerWsCustomServe. Pick one name and be consistent — this will cause build/dependency resolution issues.

2. Literal TODO placeholders that won't compile
Several TODO tokens appear as literal struct field values that are not valid Rust:

• ctx.msg(Allocate { TODO }) in actor2/mod.rs
• EnvoyStartFailed { TODO: TODO } in the ActorError enum

These will fail to compile and need to be resolved before this can be tested.

3. Undefined type UpdateStateAndDbOutput
update_state_and_db in actor2/mod.rs declares Result<UpdateStateAndDbOutput> as its return type, but this struct is never defined in the diff. Either define it or change the return type.

4. Missing ActorError::EnvoyConnectionLost variant
is_envoy_failure() and error-building code reference ActorError::EnvoyConnectionLost, but it does not appear in the ActorError enum declaration. This will be a compile error.

5. Wrong struct name in runtime.rs
Envoy::new appears to return a LifecycleRunnerState { ... } literal, which looks like a stale copy-paste from the v1 runner. It should return an Envoy { ... } struct.

6. Mismatched input type: SendMessagesToEnvoyInput vs SendMessagesToRunnerInput
mod.rs calls runtime::SendMessagesToEnvoyInput, but runtime.rs defines SendMessagesToRunnerInput. Code also references input.runner_id which is not a field on that struct (only envoy_key and messages).

---

Dependency Issues

7. hyper pinned outside workspace in both new Cargo.toml files
Both pegboard-envoy/Cargo.toml and pegboard-gateway2/Cargo.toml pin hyper = "1.6" with a TODO comment about the workspace version mismatch. Fix the workspace dependency rather than bypassing it.

---

Code Quality

8. Commented-out dead code
shared_state.rs has wrapping_lt commented out at the bottom. Remove it or use it.

9. Metrics label change is a breaking change
pegboard/src/metrics.rs changes ACTOR_ALLOCATE_DURATION labels from ["status"] to ["kind", "result"]. This is a breaking change for existing dashboards/alerts monitoring this metric — worth calling out in the PR description.

10. Duplicated lost_timeout_ts computation
In the GoingAway signal handler in actor2/mod.rs, lost_timeout_ts is computed twice identically. Verify there isn't a scoping error here.

---

Design / Architecture Questions

11. Naming: envoy vs runner
The PR introduces pegboard-envoy and renames the protocol in v1.bare (ToServer/ToClient to ToRivet/ToEnvoy), but many internal struct and package names still say "runner". Settle on one canonical term before merging.

12. Epoxy key reservation failure modes
The new keys.rs Epoxy-based key reservation is a significant new cross-DC consensus path. A comment explaining what happens if the reservation is committed in Epoxy but the UDB reserve_actor_key activity fails afterward would help reviewers and future maintainers.

13. Unresolved TODO comments in production paths

• // TODO: Don't return actual error? appears multiple times in ws_to_tunnel_task.rs
• // TODO: Add queue and bg thread for processing kv ops suggests the KV path may have ordering/concurrency issues under load

These should be resolved or tracked as follow-up issues before merge.

---

Minor

• pegboard/src/workflows/actor/metrics.rs: the renamed function pegboard_actor2_metrics lives in the v1 actor module. If intentional, add a comment explaining why. If not, it likely belongs in actor2.
• The typo fix (an serverless to a serverless) in actor/runtime.rs is unrelated to the feature and could be a separate commit.

---

Overall this is a substantial architectural improvement with sleep/wake support, the envoy protocol rename, and Epoxy-based key reservation. The main blockers are compile errors from placeholder TODO tokens and naming inconsistencies. Happy to re-review once those are addressed.

[claude]

Design / Logic Issues

5. Double-counted eviction metrics
Both tunnel_to_ws_task and ws_to_tunnel_task subscribe to separate eviction subjects and each increments EVICTION_TOTAL. When a runner is evicted, both tasks fire concurrently, doubling the counter per eviction.

6. Silent JSON deserialization errors in conn.rs
Actor metadata falls back to an empty map on parse failure via unwrap_or_default(). This silently swallows invalid data. At minimum, log a warning when falling back.

7. Wrong field mapping in Mk1 KV metadata
In the ws_to_tunnel_task.rs Mk1 handler, create_ts: x.update_ts looks like the wrong field is being mapped. It should likely be x.create_ts.

8. Unverified abort safety in demuxer GC
In actor_event_demuxer.rs, a TODO: Verify aborting is safe here precedes channel.handle.abort(). Aborting mid-dispatch could silently drop in-flight events. Confirm safety or use a graceful shutdown channel like shutdown() uses.

[claude]

Code Quality

9. Significant KV code duplication
handle_message_mk1 and handle_message_mk2 in ws_to_tunnel_task.rs share nearly identical KV operation handling (~400 lines), repeated for each operation type. Consider extracting a shared dispatcher that converts protocol versions once and delegates to common logic.

10. Unimplemented module
engine/packages/pegboard/src/workflows/actor2/allocator.rs is an empty file. Either add a placeholder comment or remove it until it has content.

11. TODOs indicating known gaps
The queue/bg-thread TODO means KV ops run inline in the WebSocket message loop, which could block message handling under load. The do-not-return-actual-error TODO means internal error details are exposed directly to runners in KV responses.

Minor / Style

12. Workflow rename is a breaking change
In engine/packages/pegboard/src/workflows/actor/metrics.rs, renaming from pegboard_actor_metrics to pegboard_actor2_metrics affects in-flight executions. Confirm this is intentional and that any migration path has been handled.

[claude]

Actors V3 Review

This is a substantial draft PR (~12k lines) introducing an envoy architecture for Actor V2 alongside the existing V1 system. Since it's a draft, some issues below are likely already on your radar, but I've flagged everything worth tracking before merge.

---

Summary of architectural changes

• pegboard-envoy: New server-side package that accepts WebSocket connections from the envoy process, demultiplexes actor events, handles KV ops, and bidirectionally proxies to/from the gateway via UPS.
• pegboard-gateway2: New gateway package that handles Actor V2 HTTP/WebSocket requests from clients, routing them through the envoy tunnel via the envoy protocol.
• guard routing: Extended to dispatch Actor V1 vs. V2 based on the version field, and adds a new path-based route /envoys/connect for envoy WebSocket connections.

---

Issues to address before merge

Unresolved workspace dependency pinning

Both pegboard-envoy/Cargo.toml and pegboard-gateway2/Cargo.toml pin hyper and hyper-util directly. The inline comments indicate this was a workaround rather than a resolution. These should use hyper.workspace = true to avoid silent version divergence.

Silent JSON deserialization failure in `conn.rs`

Malformed actor metadata silently becomes an empty map via unwrap_or_default(). A tracing::warn! on the error path would make this diagnosable in production.

Task abort safety unverified (`actor_event_demuxer.rs:82`)

The TODO comment "Verify aborting is safe here" above channel.handle.abort() needs to be resolved before merge. If the spawned channel_handler task holds a lock or a partially-written database transaction, aborting via JoinHandle::abort could leave state inconsistent.

KV ops block the WebSocket receive loop (`ws_to_tunnel_task.rs`)

Every KV operation (get/put/list/delete) blocks the envoy receive loop for a full database round-trip, serializing all actor KV requests through a single connection. The TODO ("Add queue and bg thread for processing kv ops") should be tracked as a follow-up issue even if not blocking the initial rollout.

Wake retry count changed for V1 (`pegboard_gateway.rs:390`)

The V1 actor path now retries 8 times instead of 16. If this is intentional alignment with V2, a comment explaining the rationale would help; if accidental, it should be reverted.

Separately, the added return Err(pegboard::errors::Actor::NotFound.build()) for the V1 missing-workflow case looks like a genuine bug fix in the existing code worth calling out explicitly.

---

Minor feedback

lib.rs (pegboard-envoy): handle_request returns 200 OK for plain HTTP — This endpoint is WebSocket-only. Returning 405 Method Not Allowed would be more correct for clients that hit it over plain HTTP.

conn.rs: duplicate imports — The two futures_util imports (StreamExt and TryStreamExt) can be merged into one line.

pegboard_gateway.rs: 8 subscriptions created before actor version is known — Both V1 and V2 subscriptions are established via tokio::try_join! before the actor version is fetched. Only one set is ever used. Fetching the version first and subscribing to only the relevant set would halve the subscription overhead per request.

routing/envoy.rs: trailing-slash path check — path_without_query.trim_end_matches('/') compared to /envoys/connect is cleaner than comparing to two separate literals.

routing/mod.rs: routing order change — The gateway route now runs before the runner route for header-based targets. Confirm this is intentional and won't shadow runner-targeted requests.

---

What looks good

• The eviction-before-subscribe ordering in lib.rs (publishing to evict existing connections, then skipping the first self-eviction message) correctly avoids the reconnect race condition.
• Abort propagation across the three tasks (tunnel-to-ws, ws-to-tunnel, ping) using watch::channel is clean and readable.
• SharedState using scc::HashMap for in-flight requests is a sound approach for concurrent access without a global mutex.
• CORS preflight handling at the gateway level with allow_credentials: true echoing the actual origin is correct.
• Metrics are well-instrumented across both new packages.

---

This is a draft, so the above TODOs may already be tracked. Happy to re-review once the draft is ready.

[NathanFlurry]

Merge activity

• Apr 5, 11:11 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 5, 11:25 AM UTC: Graphite rebased this pull request as part of a merge.
• Apr 5, 11:25 AM UTC: @NathanFlurry merged this pull request with Graphite.