chore(core): add metadata endpoint & client endpoint redirects

[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	Oct 12, 2025 9:50pm

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Metadata Endpoint & Client Endpoint Redirects

Todo List

• Read project guidelines from CLAUDE.md
• Analyze core changes in router and registry components
• Review client-side changes and configuration updates
• Examine API endpoint additions and manager driver changes
• Check example updates for consistency
• Review error handling modifications
• Assess security and performance implications
• Provide comprehensive feedback and recommendations

---

Overview

This PR adds a metadata endpoint system with client endpoint redirection capabilities. The main feature allows serverless runners to redirect clients to the appropriate main endpoint, enabling cleaner routing and improved serverless functionality.

✅ Positive Aspects

1. Well-Structured Implementation

• Clean separation of concerns with metadata handling in router/registry
• Proper TypeScript interfaces (MetadataResponse) with good documentation
• Consistent API patterns following existing codebase conventions

2. Good Error Handling

• Proper error propagation in metadata checks (packages/rivetkit/src/remote-manager-driver/mod.ts:102-108)
• Non-blocking metadata failures with appropriate logging
• Graceful fallbacks when metadata endpoint is unavailable

3. Performance Optimizations

• Smart caching for metadata checks to prevent racing requests (packages/rivetkit/src/remote-manager-driver/mod.ts:51-80)
• Async metadata checks that don't block other operations
• Optional health checks to reduce startup overhead

⚠️ Areas for Improvement

1. Security Concerns

Medium Risk: Unvalidated Endpoint Redirection

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:87-93
• Issue: The client automatically updates its endpoint based on clientEndpoint from metadata response without validation
• Risk: Potential redirect attacks if metadata endpoint is compromised
• Recommendation: Add URL validation to ensure redirects stay within trusted domains

// Add validation before updating endpoint
if (metadataData.clientEndpoint) {
    // Validate the endpoint is trusted
    if (isValidRedirectEndpoint(metadataData.clientEndpoint, config.endpoint)) {
        this.#config.endpoint = metadataData.clientEndpoint;
    } else {
        logger().warn({ msg: "rejected untrusted redirect endpoint", endpoint: metadataData.clientEndpoint });
    }
}

2. Type Safety Issues

Location: packages/rivetkit/src/common/router.ts:81-82

// TODO: Remove any
return c.body(output as any, { status: statusCode });

• The any cast should be addressed to maintain type safety
• Consider using proper Hono response types

3. Error Handling Gaps

Missing Error Codes

• Location: packages/rivetkit/src/actor/errors.ts - 11 lines were removed
• The removal of error codes without replacement could break error handling
• Recommendation: Verify all removed error codes are truly unused

4. Potential Race Conditions

Metadata Cache Management

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:52
• The global cache map could lead to memory leaks if endpoints change frequently
• Recommendation: Add cache TTL or size limits

5. Configuration Validation

Serverless Auto-Configuration

• Location: packages/rivetkit/src/registry/mod.ts:221-298
• The auto-configuration function has extensive validation but could benefit from stronger type checking
• Consider using Zod schemas for runtime validation of the serverless config object

🔧 Code Quality Improvements

1. Documentation

• MetadataResponse interface is well-documented ✅
• Consider adding JSDoc comments for the new getMetadata function
• The configureServerlessRunner function could use better inline documentation

2. Logging Consistency

• Good use of structured logging throughout ✅
• All log messages follow lowercase convention as per CLAUDE.md ✅

3. Error Messages

• Error messages provide helpful context and links to documentation ✅
• Consistent error structure across the codebase ✅

🚀 Performance Considerations

Positive:

• Metadata checks are cached and non-blocking
• Proper use of Promises for async operations
• Smart lazy initialization of connections

Recommendations:

• Consider adding metrics for metadata endpoint response times
• Add timeout configuration for metadata checks

🧪 Test Coverage

Missing Test Coverage:

• No visible tests for the new metadata endpoint functionality
• Serverless auto-configuration logic needs test coverage
• Client endpoint redirection behavior should be tested

Recommendations:

1. Add unit tests for handleMetadataRequest
2. Add integration tests for the endpoint redirection flow
3. Test error scenarios (unreachable metadata endpoint, invalid responses)
4. Test the serverless auto-configuration with various input scenarios

📋 Minor Issues

1. Imports: Example file changes look minimal and appropriate
2. OpenAPI Script: Good addition of router handling for API documentation
3. Manager Router: Clean integration of metadata endpoint ✅

🎯 Overall Assessment

This is a solid implementation that adds valuable functionality for serverless deployment scenarios. The code follows project conventions well and implements the feature cleanly. The main concerns are around security validation and test coverage.

Recommendation: Approve with suggested security improvements

The security concern around unvalidated redirects should be addressed before merging, but otherwise this is a well-implemented feature that enhances the framework's serverless capabilities.

[NathanFlurry]

• chore(core): add metadata endpoint & client endpoint redirects #1373 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

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]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Metadata Endpoint & Client Endpoint Redirects

Todo List

• Read project guidelines from CLAUDE.md
• Analyze core changes in router and registry components
• Review client-side changes and configuration updates
• Examine API endpoint additions and manager driver changes
• Check example updates for consistency
• Review error handling modifications
• Assess security and performance implications
• Provide comprehensive feedback and recommendations

---

Overview

This PR adds a metadata endpoint system with client endpoint redirection capabilities. The main feature allows serverless runners to redirect clients to the appropriate main endpoint, enabling cleaner routing and improved serverless functionality.

✅ Positive Aspects

1. Well-Structured Implementation

• Clean separation of concerns with metadata handling in packages/rivetkit/src/common/router.ts:108-122
• Proper TypeScript interfaces (MetadataResponse) with excellent JSDoc documentation at lines 87-106
• Consistent API patterns following existing codebase conventions
• Smart caching implementation prevents racing requests in packages/rivetkit/src/remote-manager-driver/mod.ts:51-80

2. Good Error Handling

• Proper error propagation in metadata checks (packages/rivetkit/src/remote-manager-driver/mod.ts:102-108)
• Non-blocking metadata failures with appropriate logging
• Graceful fallbacks when metadata endpoint is unavailable

3. Performance Optimizations

• Async metadata checks that don't block other operations
• Global cache for metadata checks to prevent duplicate requests
• Automatic endpoint updates without requiring restart

4. Code Quality

• Follows project conventions per CLAUDE.md ✅
• Uses structured logging correctly with lowercase messages ✅
• Proper use of logger() calls without storing as variable ✅
• No unnecessary type casts or any usage (except TODO items)

⚠️ Areas for Improvement

1. Security Concerns - Medium Priority

Unvalidated Endpoint Redirection

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:87-93
• Issue: Client automatically updates endpoint based on clientEndpoint from metadata response without validation
• Risk: Potential redirect attacks if metadata endpoint is compromised

Recommendation: Add URL validation:

if (metadataData.clientEndpoint) {
    // Validate the endpoint is trusted
    if (isValidRedirectEndpoint(metadataData.clientEndpoint, config.endpoint)) {
        this.#config.endpoint = metadataData.clientEndpoint;
        logger().info({ 
            msg: "updated client endpoint from metadata", 
            endpoint: metadataData.clientEndpoint 
        });
    } else {
        logger().warn({ 
            msg: "rejected untrusted redirect endpoint", 
            endpoint: metadataData.clientEndpoint 
        });
    }
}

2. Type Safety Issues

Location: packages/rivetkit/src/common/router.ts:81-82

// TODO: Remove any
return c.body(output as any, { status: statusCode });

• The any cast should be addressed to maintain type safety
• This violates the CLAUDE.md guideline: "Don't try to fix type issues by casting to unknown or any"

3. Memory Management

Global Cache Concerns

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:52
• Issue: Global metadataCheckCache map could lead to memory leaks if endpoints change frequently
• Recommendation: Add cache TTL or size limits

4. Error Handling Gaps

Removed Error Serialization Method

• The removal of serializeForHttp() method from ActorError class needs verification
• Location: Changes in packages/rivetkit/src/actor/errors.ts (11 lines removed)
• Ensure all usage of this method has been properly replaced

🔧 Technical Implementation Review

1. Metadata Endpoint Implementation

• Interface: Well-documented MetadataResponse with clear field purposes
• Handler: handleMetadataRequest properly constructs response
• Integration: Clean integration in both serverless and normal router modes

2. Client-Side Changes

• Minimal impact on existing client functionality
• Automatic endpoint switching is transparent to users
• Example updates are appropriate and minimal

3. Caching Strategy

• Smart use of Promise-based caching to prevent race conditions
• Cache key based on endpoint ensures proper isolation
• Metadata checks only run when health checks are enabled

🚀 Performance Considerations

Positive:

• Metadata checks are cached and non-blocking ✅
• Proper use of Promises for async operations ✅
• Smart lazy initialization of connections ✅

Recommendations:

• Consider adding configurable timeout for metadata requests
• Add metrics collection for metadata endpoint response times

🧪 Test Coverage Gaps

Missing Test Coverage:

• No visible tests for the new metadata endpoint functionality
• Serverless auto-configuration logic needs test coverage
• Client endpoint redirection behavior should be tested
• Error scenarios (unreachable metadata endpoint, invalid responses)

Recommended Tests:

1. Unit tests for handleMetadataRequest
2. Integration tests for endpoint redirection flow
3. Tests for caching behavior
4. Tests for serverless configuration scenarios

📋 Minor Issues

Code Style

• All code follows CLAUDE.md guidelines ✅
• Proper import organization ✅
• Consistent naming conventions ✅

Documentation

• MetadataResponse interface has excellent JSDoc ✅
• Consider adding JSDoc for getMetadata function
• In-line comments are helpful and appropriate ✅

🎯 Overall Assessment

This is a well-implemented feature that adds valuable serverless functionality to RivetKit. The code is clean, follows project conventions, and implements a useful capability for endpoint redirection.

Grade: B+

Blocking Issues (Must Fix):

1. Security: Add validation for client endpoint redirects before merging

Non-Blocking Recommendations:

1. Add test coverage for the new functionality
2. Resolve the any type cast in router.ts
3. Consider memory management for metadata cache
4. Add timeout configuration for metadata requests

🔒 Security Summary

The main security concern is the unvalidated endpoint redirection which could be exploited if the metadata endpoint is compromised. This should be addressed with proper URL validation before merging.

Recommendation: Approve with security fix required

The implementation is solid and adds valuable functionality, but the redirect validation should be implemented to prevent potential security issues.

---

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Metadata Endpoint & Client Endpoint Redirects

Todo List

• Read project guidelines from CLAUDE.md
• Analyze core changes in router and registry components
• Review client-side changes and configuration updates
• Examine API endpoint additions and manager driver changes
• Check example updates for consistency
• Review error handling modifications
• Assess security and performance implications
• Provide comprehensive feedback and recommendations

---

Overview

This PR adds a metadata endpoint system with client endpoint redirection capabilities. The main feature allows serverless runners to redirect clients to the appropriate main endpoint, enabling cleaner routing and improved serverless functionality.

✅ Positive Aspects

1. Well-Structured Implementation

• Clean separation of concerns with metadata handling in packages/rivetkit/src/common/router.ts:108-122
• Proper TypeScript interfaces (MetadataResponse) with excellent JSDoc documentation at lines 87-106
• Consistent API patterns following existing codebase conventions
• Smart caching implementation prevents racing requests in packages/rivetkit/src/remote-manager-driver/mod.ts:51-80

2. Good Error Handling

• Proper error propagation in metadata checks (packages/rivetkit/src/remote-manager-driver/mod.ts:102-108)
• Non-blocking metadata failures with appropriate logging
• Graceful fallbacks when metadata endpoint is unavailable

3. Performance Optimizations

• Async metadata checks that don't block other operations
• Global cache for metadata checks to prevent duplicate requests
• Automatic endpoint updates without requiring restart

4. Code Quality

• Follows project conventions per CLAUDE.md ✅
• Uses structured logging correctly with lowercase messages ✅
• Proper use of logger() calls without storing as variable ✅
• No unnecessary type casts or any usage (except TODO items)

⚠️ Areas for Improvement

1. Security Concerns - Medium Priority

Unvalidated Endpoint Redirection

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:87-93
• Issue: Client automatically updates endpoint based on clientEndpoint from metadata response without validation
• Risk: Potential redirect attacks if metadata endpoint is compromised

Recommendation: Add URL validation:

if (metadataData.clientEndpoint) {
    // Validate the endpoint is trusted
    if (isValidRedirectEndpoint(metadataData.clientEndpoint, config.endpoint)) {
        this.#config.endpoint = metadataData.clientEndpoint;
        logger().info({ 
            msg: "updated client endpoint from metadata", 
            endpoint: metadataData.clientEndpoint 
        });
    } else {
        logger().warn({ 
            msg: "rejected untrusted redirect endpoint", 
            endpoint: metadataData.clientEndpoint 
        });
    }
}

2. Type Safety Issues

Location: packages/rivetkit/src/common/router.ts:81-82

// TODO: Remove any
return c.body(output as any, { status: statusCode });

• The any cast should be addressed to maintain type safety
• This violates the CLAUDE.md guideline: "Don't try to fix type issues by casting to unknown or any"

3. Memory Management

Global Cache Concerns

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:52
• Issue: Global metadataCheckCache map could lead to memory leaks if endpoints change frequently
• Recommendation: Add cache TTL or size limits

4. Error Handling Gaps

Removed Error Serialization Method

• The removal of serializeForHttp() method from ActorError class needs verification
• Location: Changes in packages/rivetkit/src/actor/errors.ts (11 lines removed)
• Ensure all usage of this method has been properly replaced

🔧 Technical Implementation Review

1. Metadata Endpoint Implementation

• Interface: Well-documented MetadataResponse with clear field purposes
• Handler: handleMetadataRequest properly constructs response
• Integration: Clean integration in both serverless and normal router modes

2. Client-Side Changes

• Minimal impact on existing client functionality
• Automatic endpoint switching is transparent to users
• Example updates are appropriate and minimal

3. Caching Strategy

• Smart use of Promise-based caching to prevent race conditions
• Cache key based on endpoint ensures proper isolation
• Metadata checks only run when health checks are enabled

🚀 Performance Considerations

Positive:

• Metadata checks are cached and non-blocking ✅
• Proper use of Promises for async operations ✅
• Smart lazy initialization of connections ✅

Recommendations:

• Consider adding configurable timeout for metadata requests
• Add metrics collection for metadata endpoint response times

🧪 Test Coverage Gaps

Missing Test Coverage:

• No visible tests for the new metadata endpoint functionality
• Serverless auto-configuration logic needs test coverage
• Client endpoint redirection behavior should be tested
• Error scenarios (unreachable metadata endpoint, invalid responses)

Recommended Tests:

1. Unit tests for handleMetadataRequest
2. Integration tests for endpoint redirection flow
3. Tests for caching behavior
4. Tests for serverless configuration scenarios

📋 Minor Issues

Code Style

• All code follows CLAUDE.md guidelines ✅
• Proper import organization ✅
• Consistent naming conventions ✅

Documentation

• MetadataResponse interface has excellent JSDoc ✅
• Consider adding JSDoc for getMetadata function
• In-line comments are helpful and appropriate ✅

🎯 Overall Assessment

This is a well-implemented feature that adds valuable serverless functionality to RivetKit. The code is clean, follows project conventions, and implements a useful capability for endpoint redirection.

Grade: B+

Blocking Issues (Must Fix):

1. Security: Add validation for client endpoint redirects before merging

Non-Blocking Recommendations:

1. Add test coverage for the new functionality
2. Resolve the any type cast in router.ts
3. Consider memory management for metadata cache
4. Add timeout configuration for metadata requests

🔒 Security Summary

The main security concern is the unvalidated endpoint redirection which could be exploited if the metadata endpoint is compromised. This should be addressed with proper URL validation before merging.

Recommendation: Approve with security fix required

The implementation is solid and adds valuable functionality, but the redirect validation should be implemented to prevent potential security issues.

---

Claude finished @NathanFlurry's task — View job

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review: Metadata Endpoint & Client Endpoint Redirects

Todo List

• Read project guidelines from CLAUDE.md
• Analyze core changes in router and registry components
• Review client-side changes and configuration updates
• Examine API endpoint additions and manager driver changes
• Check example updates for consistency
• Review error handling modifications
• Assess security and performance implications
• Provide comprehensive feedback and recommendations

---

Overview

This PR adds a metadata endpoint system with client endpoint redirection capabilities. The main feature allows serverless runners to redirect clients to the appropriate main endpoint, enabling cleaner routing and improved serverless functionality.

✅ Positive Aspects

1. Well-Structured Implementation

• Clean separation of concerns with metadata handling in packages/rivetkit/src/common/router.ts:108-122
• Proper TypeScript interfaces (MetadataResponse) with excellent JSDoc documentation at lines 87-106
• Consistent API patterns following existing codebase conventions
• Smart caching implementation prevents racing requests in packages/rivetkit/src/remote-manager-driver/mod.ts:51-80

2. Good Error Handling

• Proper error propagation in metadata checks (packages/rivetkit/src/remote-manager-driver/mod.ts:102-108)
• Non-blocking metadata failures with appropriate logging
• Graceful fallbacks when metadata endpoint is unavailable

3. Performance Optimizations

• Async metadata checks that don't block other operations
• Global cache for metadata checks to prevent duplicate requests
• Automatic endpoint updates without requiring restart

4. Code Quality

• Follows project conventions per CLAUDE.md ✅
• Uses structured logging correctly with lowercase messages ✅
• Proper use of logger() calls without storing as variable ✅
• No unnecessary type casts or any usage (except TODO items)

⚠️ Areas for Improvement

1. Security Concerns - Medium Priority

Unvalidated Endpoint Redirection

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:87-93
• Issue: Client automatically updates endpoint based on clientEndpoint from metadata response without validation
• Risk: Potential redirect attacks if metadata endpoint is compromised

Recommendation: Add URL validation:

if (metadataData.clientEndpoint) {
    // Validate the endpoint is trusted
    if (isValidRedirectEndpoint(metadataData.clientEndpoint, config.endpoint)) {
        this.#config.endpoint = metadataData.clientEndpoint;
        logger().info({ 
            msg: "updated client endpoint from metadata", 
            endpoint: metadataData.clientEndpoint 
        });
    } else {
        logger().warn({ 
            msg: "rejected untrusted redirect endpoint", 
            endpoint: metadataData.clientEndpoint 
        });
    }
}

2. Type Safety Issues

Location: packages/rivetkit/src/common/router.ts:81-82

// TODO: Remove any
return c.body(output as any, { status: statusCode });

• The any cast should be addressed to maintain type safety
• This violates the CLAUDE.md guideline: "Don't try to fix type issues by casting to unknown or any"

3. Memory Management

Global Cache Concerns

• Location: packages/rivetkit/src/remote-manager-driver/mod.ts:52
• Issue: Global metadataCheckCache map could lead to memory leaks if endpoints change frequently
• Recommendation: Add cache TTL or size limits

4. Error Handling Gaps

Removed Error Serialization Method

• The removal of serializeForHttp() method from ActorError class needs verification
• Location: Changes in packages/rivetkit/src/actor/errors.ts (11 lines removed)
• Ensure all usage of this method has been properly replaced

🔧 Technical Implementation Review

1. Metadata Endpoint Implementation

• Interface: Well-documented MetadataResponse with clear field purposes
• Handler: handleMetadataRequest properly constructs response
• Integration: Clean integration in both serverless and normal router modes

2. Client-Side Changes

• Minimal impact on existing client functionality
• Automatic endpoint switching is transparent to users
• Example updates are appropriate and minimal

3. Caching Strategy

• Smart use of Promise-based caching to prevent race conditions
• Cache key based on endpoint ensures proper isolation
• Metadata checks only run when health checks are enabled

🚀 Performance Considerations

Positive:

• Metadata checks are cached and non-blocking ✅
• Proper use of Promises for async operations ✅
• Smart lazy initialization of connections ✅

Recommendations:

• Consider adding configurable timeout for metadata requests
• Add metrics collection for metadata endpoint response times

🧪 Test Coverage Gaps

Missing Test Coverage:

• No visible tests for the new metadata endpoint functionality
• Serverless auto-configuration logic needs test coverage
• Client endpoint redirection behavior should be tested
• Error scenarios (unreachable metadata endpoint, invalid responses)

Recommended Tests:

1. Unit tests for handleMetadataRequest
2. Integration tests for endpoint redirection flow
3. Tests for caching behavior
4. Tests for serverless configuration scenarios

📋 Minor Issues

Code Style

• All code follows CLAUDE.md guidelines ✅
• Proper import organization ✅
• Consistent naming conventions ✅

Documentation

• MetadataResponse interface has excellent JSDoc ✅
• Consider adding JSDoc for getMetadata function
• In-line comments are helpful and appropriate ✅

🎯 Overall Assessment

This is a well-implemented feature that adds valuable serverless functionality to RivetKit. The code is clean, follows project conventions, and implements a useful capability for endpoint redirection.

Grade: B+

Blocking Issues (Must Fix):

1. Security: Add validation for client endpoint redirects before merging

Non-Blocking Recommendations:

1. Add test coverage for the new functionality
2. Resolve the any type cast in router.ts
3. Consider memory management for metadata cache
4. Add timeout configuration for metadata requests

🔒 Security Summary

The main security concern is the unvalidated endpoint redirection which could be exploited if the metadata endpoint is compromised. This should be addressed with proper URL validation before merging.

Recommendation: Approve with security fix required

The implementation is solid and adds valuable functionality, but the redirect validation should be implemented to prevent potential security issues.

---

Claude finished @NathanFlurry's task — View job

[graphite-app]

Merge activity

• Oct 13, 6:23 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Oct 13, 6:24 AM UTC: CI is running for this pull request on a draft pull request (#1376) due to your merge queue CI optimization settings.
• Oct 13, 6:25 AM UTC: Merged by the Graphite merge queue via draft PR: #1376.