feat: actor query in gateway

[NathanFlurry]

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-4553 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 11:43 am
frontend-cloud	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 8:58 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 8:58 am
website	😴 Sleeping (View Logs)	Web	Apr 5, 2026 at 6:33 am
ladle	❌ Build Failed (View Logs)	Web	Apr 5, 2026 at 6:22 am
mcp-hub	✅ Success (View Logs)	Web	Apr 4, 2026 at 6:22 pm

[NathanFlurry]

• chore: remove global epoxy contention #4554
• feat: native SQLite backend via napi-rs with KV channel protocol #4496
• feat: actor query in gateway #4553 👈 (View in Graphite)
• feat: add sleep and reschedule endpoints for actors #4556
• fix: optimize e2e actor path #4551
• feat(pb): actor v1 to v2 migration #4548
• feat(envoy-client): fully flesh out tunnel impl #4547
• feat: basic rivetkit impl #4544
• feat: basic envoy tunnel impl #4534
• chore: envoy client #4521 : 1 other dependent PR (#4531 )
• feat(pb): actors v3 #4463
• 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
• example-agent-os
• example-agent-os-e2e
• 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@4553

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/sqlite-vfs

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

@rivetkit/traces

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

@rivetkit/workflow-engine

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 53cca42

[claude]

PR Review: feat: actor query in gateway

This is a well-structured PR adding query-based actor routing to the gateway, allowing clients to route by actor name+namespace+key using matrix parameters rather than requiring a pre-resolved actor ID. The architecture is clean, the error handling is thorough, and test coverage is good.

Issues

Base64 encoding inconsistency (potential bug)

In actor_path.rs, the input parameter is decoded from URL-safe no-padding base64 (URL_SAFE_NO_PAD). In resolve_actor_query.rs, the raw bytes are re-encoded using standard base64 (STANDARD, with +/slash and padding) before being passed to the actor creation op. If downstream consumers expect URL-safe base64 consistent with what the client sent, inputs whose bytes map to + or slash would be encoded differently. Verify what encoding pegboard::ops::actor::create::Input.input expects and whether the TypeScript mirror in gateway.ts uses the same encoding.

Potential panic in production path -- actor_path.rs, build_actor_query_from_gateway_params

The validation above guards the runner_name expect() call, but expect panics in a hot request path. Prefer ok_or_else(|| errors::QueryMissingRunnerName.build())? to make the invariant explicit in the type system rather than relying on a panic that would crash the process if the guard is refactored away.

Security: CBOR parsing without size bounds -- actor_path.rs, validate_cbor

There is no maximum byte-length check before CBOR deserialization. A deeply-nested CBOR structure could exhaust stack space via recursive deserialization. The decoded bytes should be bounded (e.g., reject if len > 64 KB) before calling this function.

Unused error artifact -- guard.query_ambiguous_runner_configs.json

The artifact is defined but resolve_query_target_dc_label never raises it. It silently picks the first matching DC via .into_iter().next(). Either raise this error when more than one DC matches, or remove the artifact. A defined error that is never emitted will confuse anyone reading the error catalog.

Error mapping gap -- guard.query_no_runner_configs.json

This artifact exists, but the no-runner-config case raises pegboard::errors::Actor::NoRunnerConfigConfigured instead. Verify whether this maps to query_no_runner_configs on the wire. If not, clients receive an opaque pegboard error rather than the documented guard error.

Style: missing newline at end of artifact JSON files

All 13 new files under engine/artifacts/errors/ are missing the final newline.

Positive observations

• Comprehensive error types with matching artifact JSON files and formatted messages.
• Race condition handling: the optimistic create-then-retry pattern in resolve_query_get_or_create_actor_id correctly handles concurrent getOrCreate races.
• Test coverage in parse_actor_path.rs is thorough -- encoding edge cases, empty keys, unknown params, disallowed params. The cross-reference comment to the TypeScript equivalent is good practice.
• Clean refactor: moving ActorPathInfo into routing/actor_path.rs and splitting pegboard_gateway.rs into a module directory is a clear improvement.
• Cache key design: excluding the token from the query path cache key is correct and clearly documented.

Questions

1. Token priority: Token can come from either the token= matrix param or the x-rivet-token / sec-websocket-protocol header, with path taking precedence. Is this intentional and consistent with direct-path behavior?

2. Remote DC authorization: In resolve_query_get_or_create_actor_id, when the target DC differs from the local one, the call goes through request_remote_datacenter. Does this path carry the gateway token through for auth, or does it bypass the token check?

3. Key serialization stability: serialize_actor_key uses serde_json::to_string, producing e.g. ["a","b"]. Is this format documented and stable? A serialization change would silently make all existing keyed actors unreachable.

The base64 encoding inconsistency is the only potentially breaking item. The expect panic and CBOR size bound are the main items to address before merge.

[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:43 AM UTC: Graphite rebased this pull request as part of a merge.
• Apr 5, 11:43 AM UTC: @NathanFlurry merged this pull request with Graphite.