feat(rivetkit): add asyncapi 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 11:33pm

3 Skipped Deployments

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

[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 👈 (View in Graphite)
• chore(rivetkit): add actor router to the openapi spec #3441
• 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]

Pull Request Review: AsyncAPI Spec Generation

This PR adds AsyncAPI specification generation for RivetKit's WebSocket protocol. Overall, this is a solid addition that improves API documentation. Here are my findings:

✅ Strengths

1. Good Structure: The AsyncAPI spec correctly follows v3.0.0 format with proper channels, operations, and message definitions
2. Comprehensive Coverage: All WebSocket message types are documented (Init, Error, ActionResponse, Event, ActionRequest, SubscriptionRequest)
3. Consistent Pattern: Follows the same pattern as the existing dump-openapi.ts script
4. Good Examples: Includes helpful payload examples for each message type
5. Type Safety: Leverages existing Zod schemas for consistency with runtime validation

🐛 Issues Found

1. Missing await in file write operation (Bug)

Location: scripts/dump-asyncapi.ts:323

fs.writeFile(outputPath, JSON.stringify(asyncApiSpec, null, 2));

This should be:

await fs.writeFile(outputPath, JSON.stringify(asyncApiSpec, null, 2));

Impact: The script may exit before the file is written, causing intermittent failures or incomplete writes.

2. Unused helper function

Location: scripts/dump-asyncapi.ts:44-54

The extractSchemas function is defined but never used. Consider removing it to keep the code clean.

3. Inconsistent metadata handling

Location: rivetkit-asyncapi/asyncapi.json:112,370

The metadata field in the Error schema is defined as an empty object {} without a type constraint. Looking at the Zod schema, it uses z.unknown().optional(), but the generated JSON schema shows:

"metadata": {}

This should be more explicit:

"metadata": {
  "type": ["object", "null"]
}

or simply omit it from required fields since it's optional.

4. Type inconsistency for id field

Location: Multiple locations in asyncapi.json

The id field is typed as integer with format: int64, but the example shows a string "123". The examples should use actual integers:

"id": 123

💡 Suggestions

1. Add error handling: Wrap the file write in a try-catch block to handle potential filesystem errors
2. Add validation: Consider validating the generated AsyncAPI spec against the official AsyncAPI schema
3. Document generation: Add a comment explaining when/how this script should be run (e.g., as part of CI, before releases, etc.)
4. Test coverage: Consider adding a test that validates the generated spec is valid AsyncAPI

📝 Code Quality

• TypeScript usage: Good use of TypeScript, though liberal use of any types in helper functions could be improved
• Comments: The code has helpful comments explaining non-obvious transformations
• Readability: Code is well-structured and easy to follow

🔒 Security

No security concerns identified.

⚡ Performance

No performance concerns for a build-time script.

🧪 Test Coverage

No tests were added for this functionality. Consider adding:

• A test that runs the script and validates the output
• A test that ensures the generated spec is valid AsyncAPI v3.0.0

📊 Summary

Approval Status: ⚠️ Approve with changes

The PR is functionally sound but has a critical bug (missing await) that must be fixed. The other issues are minor but should be addressed for code quality.

Required Changes:

1. Add await to the fs.writeFile call

Recommended Changes:

1. Remove unused extractSchemas function
2. Fix example values to match types (use integers, not strings for id)
3. Add error handling around file write

---

Generated with Claude Code

[pkg-pr-new]

More templates

• example-ai-agent
• example-background-jobs
• example-better-auth-external-db
• example-bots
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-counter
• example-counter-serverless
• example-crdt
• example-cursors
• example-cursors-raw-websocket
• example-database
• example-deno
• example-sqlite
• example-elysia
• example-express
• example-freestyle
• example-game
• example-hono
• example-hono-bun
• example-hono-react
• example-kitchen-sink
• example-next-js
• example-rate
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-sync
• example-tenant
• example-trpc
• example-workflows

@rivetkit/actor

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

@rivetkit/cloudflare-workers

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

@rivetkit/core

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 7a874a5

[claude]

Pull Request Review: AsyncAPI Specification Generation

Great work adding AsyncAPI specification support to RivetKit! This PR adds comprehensive documentation for the WebSocket protocol. Here's my review:

✅ Strengths

1. Well-structured AsyncAPI spec - Properly follows AsyncAPI 3.0.0 specification with clear channels, operations, and message definitions
2. Comprehensive examples - Good coverage of all message types with realistic examples
3. Proper build integration - AsyncAPI generation is correctly integrated into the turbo build pipeline
4. Schema reuse - Leverages existing Zod schemas from the codebase, ensuring consistency

🐛 Potential Issues

1. Missing Error Handling in Script (rivetkit-typescript/packages/rivetkit/scripts/dump-asyncapi.ts:323)

fs.writeFile(outputPath, JSON.stringify(asyncApiSpec, null, 2));

Issue: The fs.writeFile promise is not awaited, and there's no error handling. If the write fails, the script will silently succeed.

Recommendation:

try {
    await fs.writeFile(outputPath, JSON.stringify(asyncApiSpec, null, 2));
    console.log("Dumped AsyncAPI spec to", outputPath);
} catch (error) {
    console.error("Failed to write AsyncAPI spec:", error);
    process.exit(1);
}

2. Unused Helper Function (rivetkit-typescript/packages/rivetkit/scripts/dump-asyncapi.ts:44-54)

function extractSchemas(jsonSchema: any): Record<string, any> {
    // ... implementation
}

Issue: The extractSchemas helper function is defined but never used in the code.

Recommendation: Remove unused code to improve maintainability.

3. Empty "metadata" Schema (rivetkit-asyncapi/asyncapi.json:112, 370)

"metadata": {},

Issue: The metadata field in the Error schema has an empty object as its type, which means it accepts anything. This could be more specific.

Question: Should this have a more specific schema, or is this intentionally flexible? Consider adding a comment or description explaining that metadata can be any JSON value.

4. Empty "output" and "args" Schemas

"output": {},  // Line 143, 386
"args": {}     // Line 165, 268, 398, 414

Issue: Similar to metadata, these fields accept any JSON value without type constraints.

Recommendation: If this is intentional (polymorphic data), consider:

• Adding descriptions explaining that these are intentionally flexible
• Using "type": "object" with "additionalProperties": true to make intent clearer
• Or defining a more specific schema if the structure is known

🎯 Code Quality & Best Practices

1. TypeScript Usage: Good use of TypeScript types, though the extensive use of any in helper functions could be improved with proper typing
2. Code Organization: The script is well-organized with clear helper functions and logical flow
3. Naming Conventions: Consistent and descriptive naming throughout

🔒 Security Considerations

No security concerns identified. The script:

• Only reads from Zod schemas (source of truth)
• Writes to a predetermined output path
• Doesn't accept external input

⚡ Performance Considerations

No performance concerns. The script:

• Runs as part of the build process
• Generates a static JSON file
• Has minimal computational complexity

📋 Test Coverage

Concern: No tests are included for the AsyncAPI generation script.

Recommendations:

1. Add a test that validates the generated AsyncAPI spec against the AsyncAPI 3.0.0 schema
2. Add tests to verify all Zod schemas are properly converted
3. Consider snapshot testing for the generated JSON output

🔧 Build Configuration (turbo.json:12-17)

The build configuration looks correct:

• Proper dependency on build:schema
• Correct input files specified
• Integrated into the main build pipeline

📦 Dependency Management

New dependency: zod-to-json-schema@^3.24.6

This is a well-maintained package and appropriate for this use case. No concerns.

📝 Suggestions for Future Improvements

1. Consider adding YAML output in addition to JSON (AsyncAPI specs are commonly written in YAML)
2. Add validation to ensure the generated spec is valid AsyncAPI 3.0.0
3. Consider generating API documentation from the AsyncAPI spec automatically
4. Add the generated file to .gitignore if it should be generated on build (though checking it in is also valid for version tracking)

Summary

This is a solid implementation that adds valuable documentation for the WebSocket protocol. The main issues are minor code quality improvements around error handling and unused code. I recommend addressing the error handling issue before merging.

Recommendation: Approve with minor changes suggested above.