chore(rivetkit): add actor router to the openapi spec

[NathanFlurry]

No description provided.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 10, 2025 10:00pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Nov 10, 2025 10:00pm
rivet-inspector	Ignored	Preview		Nov 10, 2025 10:00pm
rivet-site	Ignored	Preview		Nov 10, 2025 10:00pm

[NathanFlurry]

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

• feat(site): add typedoc docs #3446
• chore(rivetkit): remove deprecated packages #3447
• chore(rivetkit): add support for conn params on onRequest and onWebSocket #3445
• feat(rivetkit): add asyncapi spec #3442
• chore(rivetkit): add actor router to the openapi spec #3441 👈 (View in Graphite)
• fix(rivetkit): skip sending RivetKit messages to conns that do not support it #3440
• fix(rivetkit): fix race condition with websocket open events #3439
• fix(rivetkit): standardize error metadata return type #3438
• fix(rivetkit): remove incorrect getEndpoint call in metadata handler #3433
• feat(rivetkit): add json protocol support #3432
• chore(rivetkit): add required zod validation for json encoding #3431
• chore(rivetkit): add listing actors by only name to manager api #3430
• refactor(rivetkit): extract WebSocket protocol parsing to shared utility #3429
• refactor(rivetkit): restructure connection lifecycle contexts #3428
• chore(rivetkit): add WebSocketContext and RequestContext #3427
• chore(rivetkit): add conn type #3426
• chore(rivetkit): add connection for raw http #3425
• chore(rivetkit): rename onFetch to onRequest #3424
• refactor(rivetkit): add state manager for conn with symbol-based access #3423
• fix(rivetkit): use loggerWithoutContext for websocket error when actor undefined #3412
• feat(rivetkit): add GET /actors/names #3411
• feat(api-public): expose actor kv api #3410
• chore(rivetkit): auto-generate inspector token for engine driver #3409
• chore(rivetkit): close websockets on out of sequence messages #3404
• fix(rivetkit): properly apply clientEndpoint from metadata lookup #3402
• fix(rivetkit): properly handle msgIndex for hibernatable websocket reconnection #3401
• chore(rivetkit): rename onstart/onstop to onwake/onsleep #3422
• chore(rivetkit): split ActorInstance logic in to multiple classes #3421
• chore(rivetkit): move conns to separate persisted kv keys #3420
• chore(rivetkit): remove deprecated conn tokens & sse support #3419
• 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]

PR Review: Add Actor Router to OpenAPI Spec

Summary

This PR adds actor router endpoints to the RivetKit OpenAPI specification by manually injecting route definitions into the generated OpenAPI document. The implementation is clean and well-documented.

Positive Aspects ✅

1. Clear Documentation: The JSDoc comment explaining why manual injection is necessary (multi-encoding support) is excellent and provides important context for future maintainers.

2. Code Reuse: Good use of shared constants like actorIdParam to avoid repetition across multiple endpoint definitions.

3. Schema Integration: Proper integration with existing Zod schemas (HttpActionRequestSchema, HttpActionResponseSchema) ensures consistency with the actual implementation.

4. Clean Separation: Extracting the injection logic into a separate injectActorRouter function keeps the main function focused.

Issues & Recommendations

1. Object Mutation Pattern (Medium)

The function mutates the openApiDoc object directly:

function injectActorRouter(openApiDoc: any) {
  if (!openApiDoc.paths) {
    openApiDoc.paths = {};
  }
  // ... mutations
}

Recommendation: Consider using a more explicit pattern or adding a return type to make the mutation intent clearer:

function injectActorRouter(openApiDoc: OpenAPIDocument): void {
  // ...
}

2. any Type Usage (Medium)

The parameter type is any, which bypasses TypeScript's type safety:

function injectActorRouter(openApiDoc: any)

Recommendation: Consider importing or defining a proper OpenAPI document type from @hono/zod-openapi or use a more specific type. This would catch type errors at compile time.

3. Missing Path Parameter Specification (Low)

The /gateway/{actorId}/request/{path} endpoint uses a {path} parameter that likely needs to be a wildcard/catch-all parameter. The current OpenAPI spec treats it as a regular path parameter, which may not accurately represent the actual routing behavior.

Question: Should this be documented differently to indicate that {path} can contain slashes (e.g., /gateway/{actorId}/request/{path*} or similar OpenAPI 3.x pattern)?

4. Object Reuse Across Methods (Low)

The same requestPath object is reused across all HTTP methods:

openApiDoc.paths["/gateway/{actorId}/request/{path}"] = {
  get: requestPath,
  post: requestPath,
  // ... all methods share the same object reference
};

While this works in JavaScript, it creates shared object references. If the OpenAPI library mutates these objects, it could cause unexpected behavior.

Recommendation: Create separate objects for each method or use a spread operator:

const createRequestPath = () => ({
  parameters: [...],
  responses: {...}
});

openApiDoc.paths["/gateway/{actorId}/request/{path}"] = {
  get: createRequestPath(),
  post: createRequestPath(),
  // ...
};

5. Missing Request Body for Non-GET Methods (Low)

The /gateway/{actorId}/request/{path} endpoint doesn't specify request body schemas for POST, PUT, PATCH methods. While this might be intentional (raw pass-through), it could be documented:

requestBody: {
  description: "Raw request body forwarded to the actor",
  content: {
    "*/*": {
      schema: { type: "string" }
    }
  }
}

6. Error Response Schemas Missing (Low)

The /gateway/{actorId}/health endpoint only defines a 200 response but might also return error responses. Consider adding 4xx/5xx responses for consistency with the action endpoint.

7. Test Coverage (Medium Priority)

No tests were added for the OpenAPI generation logic. Consider adding:

• Unit tests for injectActorRouter function
• Integration test that validates the generated OpenAPI JSON against a schema
• Test that ensures the injected routes don't conflict with existing routes

Security Considerations

No security issues identified. The code only generates documentation and doesn't affect runtime behavior.

Performance Considerations

No performance concerns. This is a build-time script that runs infrequently.

Minor: Code Style

The $schema deletion could be more type-safe:

// Current
delete (actionRequestSchema as any).$schema;

// Alternative (if type is known)
if ('$schema' in actionRequestSchema) {
  delete actionRequestSchema.$schema;
}

Overall Assessment

This is a solid PR that accomplishes its goal effectively. The main improvements would be around type safety and ensuring the OpenAPI spec accurately represents the actual API behavior. The approach of manual injection is well-justified and documented.

Recommendation: Approve with minor suggestions for future improvements.