Dynamic handler loading in @effect/rpc - recommended approach?

[schickling]

Context

I'm exploring whether it's possible to dynamically load more handlers into a running @effect/rpc server. My use case involves adding new RPC handlers at runtime without restarting the server.

Investigation Findings

After exploring the codebase, I found that dynamic handler loading is not currently supported out of the box. Here's what I discovered:

Current Architecture

1. RpcGroup maintains an immutable readonly requests: ReadonlyMap<string, R>
2. RpcServer.makeNoSerialization() captures the handler context once at initialization:

   // packages/rpc/src/RpcServer.ts:107
   const context = yield* Effect.context<Rpc.ToHandler<Rpcs> | Scope.Scope>()

3. Handler lookup directly accesses this captured context with no indirection layer:

   // packages/rpc/src/RpcServer.ts:230
   const entry = context.unsafeMap.get(rpc?.key) as Rpc.Handler<Rpcs["_tag"]>

Potential Approaches I've Identified

1. ResourceRef Pattern (from @effect/cluster)

I noticed that @effect/cluster uses a ResourceRef pattern in entityManager.ts that allows hot-swapping RPC servers:

// packages/cluster/src/internal/entityManager.ts:149-167
// the server is stored in a ref, so if there is a defect, we can
// swap the server without losing the active requests
const writeRef = yield* ResourceRef.from(
  scope,
  Effect.fnUntraced(function*(scope) {
    const handlers = yield* entity.protocol.toHandlersContext(buildHandlers).pipe(...)
    const server = yield* RpcServer.makeNoSerialization(entity.protocol, {...})
    // ...
  })
)

This seems like the most proven approach since it's already in production use.

2. Layer Reconstruction

Reconstruct the entire server with updated handler layers. Maintains type safety but requires connection draining.

3. Proxy Handler Pattern

Use a single dispatch handler that routes to dynamically registered implementations. Works with current design but loses RPC type safety.

Questions

1. Is the ResourceRef pattern the recommended approach for dynamic handler scenarios?
2. Are there any plans to add first-class support for dynamic handler registration in @effect/rpc?
3. Is there a simpler pattern I might be missing that would allow adding handlers to a running server?
4. For the ResourceRef approach, are there any gotchas or best practices beyond what's shown in the cluster package?

Any guidance would be greatly appreciated!

---

This discussion was created with assistance from Claude Code

[sunnypatell]

@schickling your analysis is spot on. RpcGroup is immutable and RpcServer.makeNoSerialization() captures handler context once, so there's no first-class dynamic handler registration.

the ResourceRef pattern you found is the recommended approach. specifically in entityManager.ts (lines 149-167):

const writeRef = yield* ResourceRef.from(
  scope,
  Effect.fnUntraced(function*(scope) {
    const handlers = yield* entity.protocol.toHandlersContext(buildHandlers).pipe(...)
    const server = yield* RpcServer.makeNoSerialization(entity.protocol, {...})
  })
)

ResourceRef.unsafeRebuild() swaps the entire RpcServer by closing the old scope, creating a new one, and rebuilding with the updated handler set. in-flight requests complete against the old server; new requests route to the new one via the latch mechanism.

re: your alternatives -- the proxy handler pattern (single dispatch to a Ref<Map>) is the quickest if you don't need type safety on dynamic handlers. layer reconstruction via RpcGroup.toLayer() works but requires connection draining.

i didn't find any open PRs or roadmap items for first-class dynamic handler support. given how RpcGroup's type-level request map works, runtime additions while preserving type safety would be a significant API change.