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