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

NathanFlurry · 2025-11-10T21:58:56Z

No description provided.

vercel · 2025-11-10T21:59:02Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 13, 2025 9:35pm

3 Skipped Deployments

Project	Deployment	Preview	Updated (UTC)
rivet-cloud	Ignored		Nov 13, 2025 9:35pm
rivet-inspector	Ignored	Preview	Nov 13, 2025 9:35pm
rivet-site	Ignored	Preview	Nov 13, 2025 9:35pm

NathanFlurry · 2025-11-10T21:59:27Z

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 · 2025-11-10T22:00:27Z

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 ✅

Clear Documentation: The JSDoc comment explaining why manual injection is necessary (multi-encoding support) is excellent and provides important context for future maintainers.
Code Reuse: Good use of shared constants like actorIdParam to avoid repetition across multiple endpoint definitions.
Schema Integration: Proper integration with existing Zod schemas (HttpActionRequestSchema, HttpActionResponseSchema) ensures consistency with the actual implementation.
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.

vercel · 2025-11-13T20:54:08Z

Deployment failed with the following error:

Too many requests - try again in 1 minute (more than 120, code: "api-deployments-flood-pro").

Learn More: https://vercel.com/docs/limits#rate-limits

claude · 2025-11-13T20:55:34Z

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 approach is pragmatic and well-documented.

✅ Strengths

Excellent Documentation: The JSDoc comment explaining why manual injection is necessary (multi-encoding support vs JSON-focused OpenAPI) provides critical context for future maintainers.
Code Reuse: Smart use of constants like actorIdParam and requestPath to avoid repetition across multiple endpoint definitions.
Schema Integration: Proper integration with existing Zod schemas ensures consistency with the actual implementation at src/schemas/client-protocol-zod/mod.ts.
Clean Separation: Extracting the injection logic into a separate injectActorRouter function keeps the code organized.
Comprehensive HTTP Method Coverage: All standard HTTP methods are properly included for the raw request endpoint.

⚠️ Issues & Recommendations

1. Missing Dependency (CRITICAL)

The code imports zod-to-json-schema but this package is not listed in package.json:

import { zodToJsonSchema } from "zod-to-json-schema";

Action Required: Add to rivetkit-typescript/packages/rivetkit/package.json:

"devDependencies": {
  "zod-to-json-schema": "^3.23.0",
  ...
}

This is likely causing build failures and must be fixed before merging.

2. Type Safety (Medium Priority)

The openApiDoc parameter uses any type (line 94):

function injectActorRouter(openApiDoc: any) {

Recommendation: Use a proper type from @hono/zod-openapi or define an interface. This would catch type errors at compile time.

3. Path Parameter Semantics (Low Priority)

The {path} parameter in /gateway/{actorId}/request/{path} appears to be a catch-all that can contain multiple path segments (e.g., /foo/bar/baz). OpenAPI 3.0 doesn't have native support for wildcard path parameters.

Recommendation: Add a note in the parameter description clarifying that {path} can contain slashes and multiple segments.

4. Missing operationId Fields (Low Priority)

OpenAPI best practice includes operationId for each endpoint to improve client SDK generation:

{
  get: {
    operationId: "getActorHealth",
    parameters: [actorIdParam],
    // ...
  }
}

5. Object Reference Sharing (Low Priority)

The same requestPath object is reused across all HTTP methods, creating shared object references. While this works, if the OpenAPI library mutates these objects, it could cause unexpected behavior.

Recommendation: Either create separate objects for each method or document that this is safe.

6. Missing Request Body Schemas (Low Priority)

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

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

🧪 Test Coverage

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

Unit tests for the injectActorRouter function
Integration test validating the generated OpenAPI JSON against the OpenAPI 3.0 schema
Test ensuring injected routes don't conflict with manager router routes

🔒 Security & Performance

Security: No security concerns identified. This is documentation-only code.
Performance: No performance concerns. This is a build-time script.

Overall Assessment

This is a solid, pragmatic PR that accomplishes its goal effectively. The manual injection approach is well-justified and properly documented. The main blocker is the missing zod-to-json-schema dependency which must be added before merging.

Recommendation: ✅ Approve pending dependency fix

Once the dependency is added, this is ready to merge. The other suggestions are optional improvements that can be addressed in follow-up PRs if desired.

claude · 2025-11-13T21:06:03Z

Code Review

This PR adds actor router endpoints to the OpenAPI specification. Overall, the approach is sound, but there are several important considerations:

✅ Strengths

Clear Documentation: The comment explaining why manual injection is used (multi-encoding support vs JSON-focused OpenAPI) is excellent
Good Code Organization: The injectActorRouter function is well-structured and easy to understand
Schema Reuse: Correctly leverages existing Zod schemas (HttpActionRequestSchema, HttpActionResponseSchema) via zod-to-json-schema
Comprehensive HTTP Methods: The /gateway/{actorId}/request/{path} endpoint properly covers all standard HTTP methods

⚠️ Issues & Concerns

1. Missing Dependency (CRITICAL)

The code imports zod-to-json-schema on line 3, but this package is not listed in package.json (neither in dependencies nor devDependencies). This will cause a runtime error when the script runs.

Fix: Add to rivetkit-typescript/packages/rivetkit/package.json:

"devDependencies": {
  "zod-to-json-schema": "^3.23.5"
}

2. Route Path Mismatch

The OpenAPI spec defines routes as:

/gateway/{actorId}/health
/gateway/{actorId}/action/{action}
/gateway/{actorId}/request/{path}

But the actual router (src/actor/router.ts) defines:

/health (line 80)
/action/:action (line 134)
/request/* (line 146)

There's no /gateway prefix in the actual implementation. This means the OpenAPI spec documents routes that don't exist as-written. Either:

The OpenAPI paths should remove /gateway/{actorId} prefix, OR
There's a gateway/proxy layer that adds this prefix (should be documented)

3. Missing `/actors/names` Implementation

The OpenAPI spec includes a /actors/names endpoint with a namespace query parameter, but I don't see this route in the actor router implementation. This appears to be carried over from the manager router. If this endpoint doesn't belong in the actor router context, it should be removed from the injected paths.

4. Loose Type Safety

function injectActorRouter(openApiDoc: any) {

Using any reduces type safety. Consider using a proper OpenAPI document type from @hono/zod-openapi or at minimum:

interface OpenAPIDocument {
  paths?: Record<string, any>;
}

5. Schema Mutation

delete (actionRequestSchema as any).$schema;

Mutating the schema object could cause issues if it's reused elsewhere. Consider spreading to create a new object:

const { $schema, ...actionRequestSchema } = zodToJsonSchema(...);

6. Missing Request Body for Other HTTP Methods

The /gateway/{actorId}/request/{path} endpoint supports POST, PUT, and PATCH, but the OpenAPI spec doesn't include requestBody schemas for these methods. While it may proxy arbitrary content, documenting expected content types would improve the spec.

7. Incomplete Error Responses

The /gateway/{actorId}/health endpoint only documents a 200 response. Consider documenting error cases (404 if actor not found, 500 for internal errors) for consistency with the other endpoints.

8. No Tests

There are no tests validating that the generated OpenAPI spec matches the actual routes. Consider adding:

A test that runs the dump script and validates the output structure
Integration tests that verify documented endpoints actually work
A CI check that fails if routes and OpenAPI spec drift

🔍 Security Considerations

Path Traversal: The {path} parameter in /request/{path} could be vulnerable to path traversal attacks if not properly validated in the handler
Action Validation: The spec doesn't document which actions are valid, making it unclear what constitutes a "400 Invalid action" vs valid usage

📊 Testing Recommendations

Run pnpm dump-openapi in CI to ensure the spec stays in sync
Add schema validation tests
Consider using the generated OpenAPI spec for request/response validation in tests

💡 Suggestions

Add a comment at the top of openapi.json indicating it's auto-generated and linking to the script
Consider adding operationIds to each endpoint for better code generation support
Add example request/response bodies for better API documentation

Verdict: The implementation approach is good, but the missing dependency will break the build and the route path mismatch needs clarification. Please address the critical issues before merging.

graphite-app · 2025-11-13T21:34:13Z

Merge activity

Nov 13, 9:34 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Nov 13, 9:37 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Nov 13, 9:43 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Nov 13, 10:04 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.

claude · 2025-11-13T21:35:45Z

PR Review: Add Actor Router to OpenAPI Spec

Thank you for this contribution! This PR adds actor router endpoints to the OpenAPI specification. Here's my detailed review:

Code Quality & Best Practices ✅

Strengths:

Well-documented code with clear comments explaining why manual injection is necessary
Good separation of concerns with the injectActorRouter function
Proper use of TypeScript type safety with as const for parameter definitions
Consistent code style following the existing patterns
Clear variable naming and function structure

Areas for Improvement:

Missing Dependency ⚠️
The import import { zodToJsonSchema } from "zod-to-json-schema" at line 3 uses a package that is not listed in package.json dependencies. This will cause the script to fail when run.

Fix needed: Add "zod-to-json-schema": "^3.x.x" to the dependencies in rivetkit-typescript/packages/rivetkit/package.json
Type Safety 🔧
The openApiDoc parameter in injectActorRouter is typed as any (line 94). Consider using a more specific type from the OpenAPI library being used.

Suggestion:
```
import type { OpenAPIObject } from '@hono/zod-openapi';

function injectActorRouter(openApiDoc: OpenAPIObject) {
  // ...
}
```

Object Reuse Pattern 💡
The requestPath object is reused across all HTTP methods for /gateway/{actorId}/request/{path} (lines 182-210). While this works, it creates shared references that could be mutated. Consider using a function to generate fresh objects:

const createRequestPath = () => ({
  parameters: [
    actorIdParam,
    {
      name: "path",
      in: "path" as const,
      required: true,
      schema: { type: "string" },
      description: "The HTTP path to forward to the actor",
    },
  ],
  responses: {
    200: {
      description: "Response from actor's raw HTTP handler",
    },
  },
});

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

Potential Bugs 🐛

Missing Dependency (Critical)
As mentioned above, zod-to-json-schema is not installed. This will cause runtime failures.
Path Parameter Specification ⚠️
The /gateway/{actorId}/request/{path} endpoint uses a {path} parameter, but this might not work as expected with OpenAPI when the path contains slashes. The actual implementation uses /request/* (a wildcard). Consider documenting this limitation or adjusting the spec to use x-path or noting it only represents a single path segment.

Performance Considerations ⚡

The schema conversions happen during script execution, which is fine for a build-time tool
No performance concerns for the dump script itself
The generated JSON is properly formatted with JSON.stringify(..., null, 2)

Security Concerns 🔒

No security issues identified
The script runs in a build context, not runtime
No user input is processed
No sensitive data exposure risks

Test Coverage 🧪

Missing:

No tests for the injectActorRouter function
No validation that the generated OpenAPI spec is valid

Recommendations:

Add a test that validates the generated OpenAPI document against the OpenAPI 3.0 schema
Add a test that verifies all actor router paths are present in the output
Consider adding a test that compares the generated schemas with expected outputs

Example test structure:

describe('dump-openapi', () => {
  it('should generate valid OpenAPI 3.0 spec', async () => {
    const spec = await generateOpenAPISpec();
    // Validate against OpenAPI schema
  });
  
  it('should include actor router paths', async () => {
    const spec = await generateOpenAPISpec();
    expect(spec.paths).toHaveProperty('/gateway/{actorId}/health');
    expect(spec.paths).toHaveProperty('/gateway/{actorId}/action/{action}');
    expect(spec.paths).toHaveProperty('/gateway/{actorId}/request/{path}');
  });
});

Documentation 📚

Good:

Inline comments explain the rationale for manual injection
Clear JSDoc comment on injectActorRouter

Could be enhanced:

Consider adding a comment about the path wildcard limitation mentioned above
Document expected return types in the responses more specifically

Additional Notes

The generated OpenAPI spec in openapi.json looks correct
The approach of manual injection is reasonable given the multi-encoding constraint
The PR aligns with the monorepo structure and conventions

Summary

This is a solid PR that adds important API documentation. The main blocker is the missing zod-to-json-schema dependency which needs to be added before this can be merged. The suggested improvements around type safety and object reuse are optional but would improve code quality.

Recommendation: Request changes to add the missing dependency, then approve with optional suggestions for future improvements.

🤖 Generated with Claude Code

NathanFlurry mentioned this pull request Nov 10, 2025

fix(rivetkit): fix race condition with websocket open events #3439

Closed

This was referenced Nov 10, 2025

fix(rivetkit): skip sending RivetKit messages to conns that do not support it #3440

Merged

feat(rivetkit): add asyncapi spec #3442

Merged

vercel bot deployed to Preview – rivetkit-serverless November 10, 2025 22:00 View deployment

NathanFlurry changed the base branch from graphite-base/3441 to 11-10-fix_rivetkit_skip_sending_rivetkit_messages_to_conns_that_do_not_support_it November 13, 2025 03:35

NathanFlurry mentioned this pull request Nov 13, 2025

chore(rivetkit): fix type checks #3462

Merged

NathanFlurry changed the base branch from 11-10-fix_rivetkit_skip_sending_rivetkit_messages_to_conns_that_do_not_support_it to graphite-base/3441 November 13, 2025 17:13

NathanFlurry changed the base branch from graphite-base/3441 to 11-10-fix_rivetkit_skip_sending_rivetkit_messages_to_conns_that_do_not_support_it November 13, 2025 17:20

This was referenced Nov 13, 2025

feat(gas): implement smart pulling for horizontally scaled workers #3417

Merged

fix(guard): handle websocket tasks during shutdown #3448

Merged

fix: improve sigterm handling for the entire runtime #3443

Merged

NathanFlurry mentioned this pull request Nov 13, 2025

feat(gateway): websocket hibernation #3400

Merged

This was referenced Nov 13, 2025

fix(pb): dont immediately reallocate actors on runner stopping #3413

Merged

fix(guard): dont send open msg for hibernating ws, hibernating ws keepalive #3449

Merged

NathanFlurry mentioned this pull request Nov 13, 2025

chore(gas): rename wake sub to bump sub #3408

Merged

jog1t mentioned this pull request Nov 13, 2025

refactor: performance improvements for inspector #3452

Draft

MasterPtato approved these changes Nov 13, 2025

View reviewed changes

NathanFlurry force-pushed the 11-10-chore_rivetkit_add_actor_router_to_the_openapi_spec branch from 1a8edc2 to 898bc9a Compare November 13, 2025 20:53

NathanFlurry force-pushed the 11-10-fix_rivetkit_skip_sending_rivetkit_messages_to_conns_that_do_not_support_it branch from ca5b3f0 to 51a32d6 Compare November 13, 2025 20:53

NathanFlurry mentioned this pull request Nov 13, 2025

chore(rivetkit): implement new hibernating ws protocol #3464

Open

NathanFlurry force-pushed the 11-10-fix_rivetkit_skip_sending_rivetkit_messages_to_conns_that_do_not_support_it branch from 51a32d6 to ab1c83d Compare November 13, 2025 21:32

Base automatically changed from 11-10-fix_rivetkit_skip_sending_rivetkit_messages_to_conns_that_do_not_support_it to main November 13, 2025 21:33

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

82cbd70

NathanFlurry force-pushed the 11-10-chore_rivetkit_add_actor_router_to_the_openapi_spec branch from 898bc9a to 82cbd70 Compare November 13, 2025 21:33

vercel bot deployed to Preview – rivetkit-serverless November 13, 2025 21:35 View deployment

NathanFlurry mentioned this pull request Nov 13, 2025

feat(cloudflare-workers): add createInlineClient #3466

Open

NathanFlurry merged commit 5c6f479 into main Nov 13, 2025
11 of 14 checks passed

NathanFlurry deleted the 11-10-chore_rivetkit_add_actor_router_to_the_openapi_spec branch November 13, 2025 22:10

NicholasKissel mentioned this pull request Nov 15, 2025

chre: v4 website changes #3472

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

NathanFlurry commented Nov 10, 2025

Uh oh!

vercel bot commented Nov 10, 2025 •

edited

Loading

Uh oh!

NathanFlurry commented Nov 10, 2025 •

edited

Loading

Uh oh!

claude bot commented Nov 10, 2025

Uh oh!

vercel bot commented Nov 13, 2025

Uh oh!

claude bot commented Nov 13, 2025

Uh oh!

claude bot commented Nov 13, 2025

Uh oh!

graphite-app bot commented Nov 13, 2025 •

edited

Loading

Uh oh!

claude bot commented Nov 13, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

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

Uh oh!

Conversation

NathanFlurry commented Nov 10, 2025

Uh oh!

vercel bot commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NathanFlurry commented Nov 10, 2025 • 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 Nov 10, 2025

PR Review: Add Actor Router to OpenAPI Spec

Summary

Positive Aspects ✅

Issues & Recommendations

1. Object Mutation Pattern (Medium)

2. any Type Usage (Medium)

3. Missing Path Parameter Specification (Low)

4. Object Reuse Across Methods (Low)

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

6. Error Response Schemas Missing (Low)

7. Test Coverage (Medium Priority)

Security Considerations

Performance Considerations

Minor: Code Style

Overall Assessment

Uh oh!

vercel bot commented Nov 13, 2025

Uh oh!

claude bot commented Nov 13, 2025

PR Review: Add Actor Router to OpenAPI Spec

Summary

✅ Strengths

⚠️ Issues & Recommendations

1. Missing Dependency (CRITICAL)

2. Type Safety (Medium Priority)

3. Path Parameter Semantics (Low Priority)

4. Missing operationId Fields (Low Priority)

5. Object Reference Sharing (Low Priority)

6. Missing Request Body Schemas (Low Priority)

🧪 Test Coverage

🔒 Security & Performance

Overall Assessment

Uh oh!

claude bot commented Nov 13, 2025

Code Review

✅ Strengths

⚠️ Issues & Concerns

1. Missing Dependency (CRITICAL)

2. Route Path Mismatch

3. Missing /actors/names Implementation

4. Loose Type Safety

5. Schema Mutation

6. Missing Request Body for Other HTTP Methods

7. Incomplete Error Responses

8. No Tests

🔍 Security Considerations

📊 Testing Recommendations

💡 Suggestions

Uh oh!

graphite-app bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

claude bot commented Nov 13, 2025

PR Review: Add Actor Router to OpenAPI Spec

Code Quality & Best Practices ✅

Potential Bugs 🐛

Performance Considerations ⚡

Security Concerns 🔒

Test Coverage 🧪

Documentation 📚

Additional Notes

Summary

Uh oh!

Uh oh!

Reviewers

vercel bot commented Nov 10, 2025 •

edited

Loading

NathanFlurry commented Nov 10, 2025 •

edited

Loading

2. `any` Type Usage (Medium)

3. Missing `/actors/names` Implementation

graphite-app bot commented Nov 13, 2025 •

edited

Loading