feat(rivetkit): add `GET /actors/names` #3411

NathanFlurry · 2025-11-07T22:02:06Z

No description provided.

vercel · 2025-11-07T22:02:09Z

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

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Nov 9, 2025 5:46am

3 Skipped Deployments

Project	Deployment	Preview	Updated (UTC)
rivet-cloud	Ignored		Nov 9, 2025 5:46am
rivet-inspector	Ignored	Preview	Nov 9, 2025 5:46am
rivet-site	Ignored	Preview	Nov 9, 2025 5:46am

NathanFlurry · 2025-11-07T22:02:24Z

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

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-07T22:03:50Z

PR Review: Add `GET /actors/names` endpoint

Summary

This PR adds a new endpoint to retrieve actor names with metadata. The implementation is clean and follows existing patterns in the codebase.

Code Quality ✅

Positives:

Clean implementation following existing patterns in the codebase
Proper use of Zod schemas for type safety
Consistent with OpenAPI route definitions
Schema definitions properly structured with ActorNameSchema and ActorsListNamesResponseSchema

Issues & Concerns

1. Unused Query Parameter ⚠️

Location: rivetkit-typescript/packages/rivetkit/src/manager/router.ts:384-386

The endpoint defines a required namespace query parameter but never uses it:

query: z.object({
    namespace: z.string(),
}),

However, in the handler (line 392), the parameter is never extracted or used. The function simply calls buildActorNames(registryConfig) without any namespace filtering.

Recommendation:

If namespace filtering is intended for future use, document this with a TODO comment
If not needed, remove the parameter from the schema to avoid confusion
If it should be used, implement the filtering logic

2. Empty Metadata 🤔

Location: rivetkit-typescript/packages/rivetkit/src/registry/config.ts:38

The buildActorNames function currently returns empty metadata for all actors:

Object.keys(registryConfig.use).map((name) => [name, { metadata: {} }])

Questions:

Is this a placeholder for future metadata population?
Should metadata be extracted from the actor definitions?
If metadata is always empty, is the field necessary?

Recommendation:

Add a comment explaining the purpose of the metadata field
Consider if any useful metadata should be populated from actor definitions

3. Missing Documentation 📝

Recommendation:

Add JSDoc comments to explain what this endpoint returns and its use case
Document the expected metadata structure in ActorNameSchema

Example:

/**
 * Retrieves all registered actor names with their metadata.
 * Used by clients to discover available actor types in the registry.
 */
export const ActorsListNamesResponseSchema = z.object({
    names: z.record(z.string(), ActorNameSchema),
});

Test Coverage ⚠️

Issue: No tests included for the new endpoint.

Recommendation: Consider adding integration tests to verify:

Endpoint returns all registered actor names
Response schema is correct
Handles empty registry gracefully

Performance Considerations ✅

No performance concerns. The buildActorNames function is lightweight and only iterates over the actor registry keys.

Security Considerations ✅

No security concerns identified. The endpoint only exposes actor names (which are already public in the registry) and doesn't leak sensitive information.

Overall Assessment

This is a solid implementation that follows the existing codebase patterns. The main concerns are:

The unused namespace query parameter
Unclear purpose of the empty metadata field
Missing tests and documentation

Recommendation: Address the unused parameter issue before merging. The other items are nice-to-haves but not blockers.

🤖 Generated with Claude Code

pkg-pr-new · 2025-11-07T22:04:20Z

More templates

@rivetkit/actor

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

@rivetkit/cloudflare-workers

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

@rivetkit/core

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 819085b

claude · 2025-11-08T22:27:17Z

Code Review

I've reviewed PR #3411 and found several issues that need to be addressed:

Critical Issues

1. Unused Query Parameter (Bug)

Location: rivetkit-typescript/packages/rivetkit/src/manager/router.ts:391

The endpoint accepts a namespace query parameter but never uses it:

router.openapi(route, async (c) => {
    const names = buildActorNames(registryConfig);
    return c.json<ActorsListNamesResponse>({
        names,
    });
});

Expected behavior: The handler should either:

Use the namespace parameter to filter/scope the results
Remove the parameter from the schema if it's not needed

Current behavior: The parameter is validated but ignored, which could confuse API consumers who expect namespace-based filtering.

Recommendation: Either retrieve and use the namespace parameter with c.req.valid("query"), or remove it from the query schema if namespacing isn't needed for this endpoint.

2. Empty Metadata (Design Issue)

Location: rivetkit-typescript/packages/rivetkit/src/registry/config.ts:38

The buildActorNames function returns empty metadata objects for all actors:

export function buildActorNames(
    registryConfig: RegistryConfig,
): Record<string, { metadata: Record<string, any> }> {
    return Object.fromEntries(
        Object.keys(registryConfig.use).map((name) => [name, { metadata: {} }]),
    );
}

Questions:

Is this a placeholder for future functionality?
Should the metadata be populated from the actor definitions in registryConfig.use?
What is the intended purpose of this metadata field?

Recommendation: If metadata is meant to be populated, extract it from the actor definitions. If it's a placeholder, add a TODO comment explaining future plans.

Code Quality

3. Schema Definition

The ActorNameSchema definition looks reasonable:

export const ActorNameSchema = z.object({
    metadata: z.record(z.string(), z.unknown()),
});

However, given that metadata is always empty in the current implementation, consider documenting what this metadata will eventually contain.

4. Response Schema Structure

The response schema is well-structured:

export const ActorsListNamesResponseSchema = z.object({
    names: z.record(z.string(), ActorNameSchema),
});

This provides a good foundation for the API shape.

Testing

Missing test coverage: There are no tests included for this new endpoint.

Recommendation: Add tests covering:

Successful retrieval of actor names
Proper handling of the namespace parameter (once the bug is fixed)
Response schema validation
Edge cases (empty actor registry, etc.)

Summary

Must fix before merge:

Either implement namespace parameter usage or remove it from the schema
Clarify the purpose of empty metadata and either populate it or document why it's empty

Should address:

Add test coverage for the new endpoint
Document the intended use case for the metadata field

The overall structure and approach are sound, but the unused parameter is a blocking issue that needs resolution before this can be merged.

claude · 2025-11-08T22:29:27Z

Code Review

Thank you for the contribution! I've reviewed the PR and have the following feedback:

Issues Found

1. Unused Query Parameter - Warning

The namespace query parameter is defined but never used in the endpoint implementation:

query: z.object({
    namespace: z.string(),
}),

However, in the route handler:

router.openapi(route, async (c) => {
    const names = buildActorNames(registryConfig);  // namespace not used
    return c.json<ActorsListNamesResponse>({
        names,
    });
});

Recommendation: Either:

Remove the namespace parameter if it's not needed
Implement namespace filtering if it's intended functionality
Add validation to extract and use it: const { namespace } = c.req.valid("query");

2. Empty Metadata - Info

The buildActorNames function in registry/config.ts:34 always returns empty metadata objects:

return Object.fromEntries(
    Object.keys(registryConfig.use).map((name) => [name, { metadata: {} }]),
);

Question: Is this intentional? If the metadata will be populated later, consider adding a TODO comment. If not, the schema could be simplified.

Positive Aspects

Consistent API Design - Follows the existing pattern used in other endpoints
Type Safety - Proper use of Zod schemas for request/response validation
OpenAPI Integration - Correctly uses createRoute and buildOpenApiResponses
Code Reuse - Appropriately reuses the buildActorNames utility function

Minor Observations

No Tests - Consider adding tests for this endpoint (though I understand this may be added separately)
Documentation - The endpoint purpose is clear from the code, but API documentation would help consumers understand when to use /actors/names vs /metadata (which also returns actor names)

Test Coverage Recommendation

If you'd like to add tests, consider testing:

Successful response with actor names
Response schema validation
Namespace parameter handling (once clarified)

Summary

The implementation is clean and follows project conventions well. The main concern is the unused namespace parameter which should either be implemented or removed before merging.

Priority: Address the unused namespace parameter before merging.

claude · 2025-11-09T05:47:12Z

PR Review: Add `GET /actors/names` endpoint

Thank you for adding this endpoint! I've reviewed the changes and found several issues that need to be addressed before merging.

Critical Issues

1. Missing Pagination Support

The Rust implementation in engine/packages/api-types/src/actors/list_names.rs shows this endpoint supports pagination with limit and cursor query parameters, and returns a pagination field in the response:

pub struct ListNamesQuery {
    pub namespace: String,
    pub limit: Option<usize>,
    pub cursor: Option<String>,
}

pub struct ListNamesResponse {
    pub names: HashMap<String, ActorName>,
    pub pagination: Pagination,
}

However, the TypeScript implementation is missing these:

In manager-api/actors.ts:

Missing limit and cursor in the query schema
Missing pagination field in ActorsListNamesResponseSchema

In manager/router.ts:

The route doesn't accept limit or cursor parameters
The response doesn't include pagination metadata

2. Namespace Parameter Ignored

The endpoint accepts a namespace query parameter (line 380 in router.ts) but never uses it. The buildActorNames function is called with just registryConfig and doesn't filter by namespace. This is inconsistent with how other actor endpoints work and could be a security issue if actors from different namespaces shouldn't be visible to each other.

Location: rivetkit-typescript/packages/rivetkit/src/manager/router.ts:388

// namespace query param is parsed but never used
const names = buildActorNames(registryConfig);

3. Incorrect Implementation Logic

Looking at the Rust implementation in engine/packages/api-public/src/actors/list_names.rs:40-76, this endpoint should:

Validate the namespace exists
Fanout to all datacenters to get actor names
Deduplicate and sort results
Apply pagination

The TypeScript implementation just returns static actor type names from the registry config, which doesn't match the expected behavior. It should return the actual actor instances (by name) that exist in the namespace, not the actor type definitions.

Code Quality Issues

4. Inconsistent Schema Definition

The ActorNameSchema only contains metadata:

export const ActorNameSchema = z.object({
    metadata: z.record(z.string(), z.unknown()),
});

This matches the Rust ActorName struct, but it's unclear what the metadata should contain or how it's populated since buildActorNames just returns empty metadata objects.

Location: rivetkit-typescript/packages/rivetkit/src/manager-api/actors.ts:18-20

Recommendations

Add pagination support:
- Add limit and cursor to the query schema
- Add pagination field to the response schema
- Implement pagination logic in the route handler
Use the namespace parameter:
- Pass namespace to whatever data source provides the actor names
- Add validation to ensure the namespace exists
- Return appropriate error if namespace not found
Fix the implementation:
- This should return actual actor instances in the namespace, not static type definitions
- Consider whether this endpoint needs to interact with the driver to get actual actor data
Add tests:
- Given the complexity of pagination and multi-datacenter behavior, tests would be valuable
- See engine/packages/engine/tests/actors_list_names.rs for examples of what should be tested

Questions for Clarification

Is the manager router implementation supposed to mirror the engine's API exactly, or is it a simplified version for local development?
If it's meant to be simplified, should the pagination support still be included for API consistency?
Should buildActorNames be updated to accept a namespace parameter, or should this endpoint get the data differently?

Related Files

Rust implementation: engine/packages/api-public/src/actors/list_names.rs
Type definitions: engine/packages/api-types/src/actors/list_names.rs
Rust types: engine/packages/types/src/actors.rs:44-47
Tests: engine/packages/engine/tests/actors_list_names.rs

Once these issues are addressed, particularly the pagination support and namespace handling, this will be ready to merge. Let me know if you need any clarification on the feedback!

claude · 2025-11-09T05:48:23Z

PR Review: Add `GET /actors/names` endpoint

Thank you for the contribution! I've reviewed the changes and have the following feedback:

Critical Issues

1. Unused namespace query parameter (router.ts:381)

The endpoint defines a required namespace query parameter but never uses it in the handler:

// Query parameter is defined...
query: z.object({
    namespace: z.string(),
}),

// ...but not extracted or used in the handler
router.openapi(route, async (c) => {
    const names = buildActorNames(registryConfig);
    return c.json<ActorsListNamesResponse>({
        names,
    });
});

Recommendation: Either:

Remove the namespace parameter if it's not needed for the current implementation
Extract and use it: const { namespace } = c.req.valid("query"); and pass it to filter or scope the results
If it's for future use, document this with a TODO comment

Code Quality Observations

2. Metadata field is always empty (registry/config.ts:38)

The buildActorNames function always returns empty metadata objects:

Object.keys(registryConfig.use).map((name) => [name, { metadata: {} }])

Questions:

Is this placeholder implementation intentional?
Should metadata be populated from the actor definitions?
Consider adding a comment if this is intended for future enhancement

3. Missing test coverage

I couldn't find any tests for the new endpoint.

Recommendation: Add tests covering:

Successful retrieval of actor names
Response structure validation
The namespace parameter behavior (once clarified)

Minor Observations

4. API consistency

The new endpoint follows the existing pattern well (similar to GET /actors). The schema definitions and OpenAPI integration look correct.

5. TypeScript types

The Zod schemas and TypeScript type exports are properly defined:

ActorNameSchema ✓
ActorsListNamesResponseSchema ✓
Type exports ✓

Summary

The implementation is mostly solid and follows the project's patterns. The main blocker is clarifying the purpose of the unused namespace parameter. Once that's addressed and tests are added, this should be good to merge.

Please let me know if you need clarification on any of these points!

This was referenced Nov 7, 2025

fix(rivetkit): properly handle msgIndex for hibernatable websocket reconnection #3401

Open

fix(rivetkit): properly apply clientEndpoint from metadata lookup #3402

Open

chore(rivetkit): close websockets on out of sequence messages #3404

Open

This was referenced Nov 7, 2025

chore(rivetkit): auto-generate inspector token for engine driver #3409

Open

feat(api-public): expose actor kv api #3410

Open

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

NathanFlurry mentioned this pull request Nov 7, 2025

fix(rivetkit): use loggerWithoutContext for websocket error when actor undefined #3412

Open

NathanFlurry force-pushed the 11-07-feat_rivetkit_add_get__actors_names_ branch from 44ab040 to c5ed5d6 Compare November 8, 2025 22:25

NathanFlurry force-pushed the 11-07-feat_api-public_expose_actor_kv_api branch from 4f3a2a9 to 42bf4e8 Compare November 8, 2025 22:25

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

feat(rivetkit): add GET /actors/names

819085b

NathanFlurry force-pushed the 11-07-feat_rivetkit_add_get__actors_names_ branch from c5ed5d6 to 819085b Compare November 9, 2025 05:44

NathanFlurry force-pushed the 11-07-feat_api-public_expose_actor_kv_api branch from 42bf4e8 to da963b1 Compare November 9, 2025 05:44

vercel bot deployed to Preview – rivetkit-serverless November 9, 2025 05:46 View deployment

This was referenced Nov 9, 2025

refactor(rivetkit): add state manager for conn with symbol-based access #3423

Open

chore(rivetkit): rename onFetch to onRequest #3424

Open

chore(rivetkit): add connection for raw http #3425

Open

chore(rivetkit): add conn type #3426

Open

NathanFlurry changed the base branch from 11-07-feat_api-public_expose_actor_kv_api to graphite-base/3411 November 10, 2025 21:07

This was referenced Nov 10, 2025

fix(rivetkit): standardize error metadata return type #3438

Merged

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

Open

NathanFlurry changed the base branch from graphite-base/3411 to 11-07-feat_api-public_expose_actor_kv_api November 10, 2025 21:14

This was referenced Nov 10, 2025

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

Open

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

Open

feat(rivetkit): add asyncapi spec #3442

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(rivetkit): add `GET /actors/names` #3411

feat(rivetkit): add `GET /actors/names` #3411

NathanFlurry commented Nov 7, 2025

Uh oh!

vercel bot commented Nov 7, 2025 •

edited

Loading

Uh oh!

NathanFlurry commented Nov 7, 2025 •

edited

Loading

Uh oh!

claude bot commented Nov 7, 2025

Uh oh!

pkg-pr-new bot commented Nov 7, 2025 •

edited

Loading

Uh oh!

claude bot commented Nov 8, 2025

Uh oh!

claude bot commented Nov 8, 2025

Uh oh!

claude bot commented Nov 9, 2025

Uh oh!

claude bot commented Nov 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(rivetkit): add GET /actors/names #3411

Are you sure you want to change the base?

feat(rivetkit): add GET /actors/names #3411

Conversation

NathanFlurry commented Nov 7, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

PR Review: Add GET /actors/names endpoint

Summary

Code Quality ✅

Issues & Concerns

1. Unused Query Parameter ⚠️

2. Empty Metadata 🤔

3. Missing Documentation 📝

Test Coverage ⚠️

Performance Considerations ✅

Security Considerations ✅

Overall Assessment

Uh oh!

pkg-pr-new bot commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Nov 8, 2025

Code Review

Critical Issues

1. Unused Query Parameter (Bug)

2. Empty Metadata (Design Issue)

Code Quality

3. Schema Definition

4. Response Schema Structure

Testing

Summary

Uh oh!

claude bot commented Nov 8, 2025

Code Review

Issues Found

1. Unused Query Parameter - Warning

2. Empty Metadata - Info

Positive Aspects

Minor Observations

Test Coverage Recommendation

Summary

Uh oh!

claude bot commented Nov 9, 2025

PR Review: Add GET /actors/names endpoint

Critical Issues

1. Missing Pagination Support

2. Namespace Parameter Ignored

3. Incorrect Implementation Logic

Code Quality Issues

4. Inconsistent Schema Definition

Recommendations

Questions for Clarification

Related Files

Uh oh!

claude bot commented Nov 9, 2025

PR Review: Add GET /actors/names endpoint

Critical Issues

Code Quality Observations

Minor Observations

Summary

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(rivetkit): add `GET /actors/names` #3411

feat(rivetkit): add `GET /actors/names` #3411

vercel bot commented Nov 7, 2025 •

edited

Loading

NathanFlurry commented Nov 7, 2025 •

edited

Loading

PR Review: Add `GET /actors/names` endpoint

pkg-pr-new bot commented Nov 7, 2025 •

edited

Loading

PR Review: Add `GET /actors/names` endpoint

PR Review: Add `GET /actors/names` endpoint