refactor(ts): RpcPeerRefBuilder -> RpcRefBuilder (TS side of the RpcRef rename)

TS refs stay plain strings - there's no RpcRoute counterpart. Also updates
the .NET-comparison comments to describe the RpcRef + RpcRoute model.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PLbC1QXTLkBj3G2CBgkXdC

Author: alexyakunin

.gitignore

@@ -16,6 +16,7 @@ _ReSharper*/
 *.sln.docstates
 *.userprefs
 **/Properties/launchSettings.json
+!samples/TodoApp/AspireHost/Properties/launchSettings.json
 
 # Build artifacts
 [Aa]rtifacts/

docs/PartR-CallRouting.md

@@ -52,6 +52,7 @@ Starting from v14.1, `RpcPeerRef` is replaced by the `RpcRef` + `RpcRoute` pair:
 | `RpcPeerRef` | `RpcRef` (stable; one instance per logical target) |
 | `RpcRouteState` | `RpcRoute` (one instance per route generation) |
 | `RpcPeerRef.RouteState` | `RpcRef.Route` (re-minted via `CreateRoute()` on change) |
+| `RpcPeerRefBuilder` (TS, `@actuallab/rpc`) | `RpcRefBuilder` (TS refs stay plain strings; no route concept) |
 | `RpcRouteStateExt` | Merged into `RpcRoute` (`IsChanged`, `RerouteIfChanged`, etc.) |
 | `RpcPeer.Ref.RouteState` | `RpcPeer.Route` (the generation the peer is bound to) |
 

samples/TodoApp/AspireHost/Properties/launchSettings.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    /*
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:17120;http://localhost:15185",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21151",
+        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22136"
+      }
+    },
+    */
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15185",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19070",
+        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20130",
+        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true",
+        "DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS": "true"
+      }
+    }
+  }
+}

samples/TodoApp/Host/Program.cs

@@ -332,6 +332,7 @@ void ConfigureApp()
 
     // Fusion endpoints
     app.MapRpcWebSocketServer();
-    app.MapFusionAuthEndpoints();
+    if (hostKind != HostKind.BackendServer)
+        app.MapFusionAuthEndpoints();
     app.MapFusionRenderModeEndpoints();
 }

ts/e2e/ts-dotnet-e2e.ts

@@ -13,7 +13,7 @@ import WebSocket from 'ws';
 import {
     RpcClientPeer,
     RpcError,
-    RpcPeerRefBuilder,
+    RpcRefBuilder,
     RpcType,
     defineRpcService,
     type RpcConnectionState,
@@ -155,7 +155,7 @@ async function run(): Promise<void> {
     const hub = new FusionHub();
     // Bake the serialization format into the URL via ?f=... so the peer ctor
     // picks it up. Pass `mustStart=false` — we need to set webSocketFactory first.
-    const peer = new RpcClientPeer(hub, RpcPeerRefBuilder.forClient(serverUrl, rpcFormat), false);
+    const peer = new RpcClientPeer(hub, RpcRefBuilder.forClient(serverUrl, rpcFormat), false);
 
     // wsFactory: create ws WebSocket (Node.js)
     peer.webSocketFactory = (url: string) => new WebSocket(url) as unknown as WebSocketLike;

ts/packages/rpc/src/index.ts

@@ -88,7 +88,7 @@ export type {
 } from './rpc-peer.js';
 export { RpcHub } from './rpc-hub.js';
 export type { RpcPeerFactory } from './rpc-hub.js';
-export { RpcPeerRefBuilder } from './rpc-peer-ref-builder.js';
+export { RpcRefBuilder } from './rpc-ref-builder.js';
 export { RpcServiceHost } from './rpc-service-host.js';
 export type { RpcServiceImpl, RpcDispatchContext } from './rpc-service-host.js';
 export { createRpcClient } from './rpc-client.js';

ts/packages/rpc/src/rpc-hub.ts

@@ -3,7 +3,7 @@
 //     DI-resolved configuration (RpcRegistryOptions, PeerOptions, InboundCallOptions,
 //     OutboundCallOptions, DiagnosticsOptions), SerializationFormats, Middlewares,
 //     ClientPeerReconnectDelayer, Limits, SystemClock.
-//     Manages peers via ConcurrentDictionary<RpcPeerRef, RpcPeer> with GetPeer()
+//     Manages peers via ConcurrentDictionary<RpcRoute, RpcPeer> with GetPeer()
 //     that lazily creates + starts peers.  Also has GetClient<T>() / GetServer<T>()
 //     that look up services in ServiceRegistry.
 //
@@ -15,14 +15,15 @@
 //     addService() / addClient() calls.
 //   - GetClient<T>() / GetServer<T>() — .NET resolves typed client/server proxies
 //     via the ServiceRegistry + DI.  TS uses addClient<T>(peer, def).
-//   - RpcPeerRef-keyed peer dictionary — .NET peers are keyed by RpcPeerRef (rich
-//     value object encoding route, version, serialization format).  TS uses string
-//     refs (URL for clients, "server://{uuid}" for servers).
+//   - RpcRoute-keyed peer dictionary — .NET peers are keyed by RpcRoute (one
+//     route generation of a stable RpcRef, which encodes client/server, versions,
+//     serialization format).  TS uses string refs (URL for clients,
+//     "server://{uuid}" for servers).
 //   - Lazy peer creation + Start() — .NET's GetPeer auto-creates and starts a
 //     peer's reconnection loop.  TS requires explicit addPeer() + run().
 //   - DisposeAsync — .NET disposes all peers on hub shutdown.  TS has close().
-//   - Route change detection (RouteState.WhenChanged → Dispose peer) — .NET
-//     watches for load-balancer route changes and auto-disposes stale peers.
+//   - Route change detection (RpcRoute.WhenChanged → Dispose peer) — .NET
+//     watches for topology changes and auto-disposes stale-route peers.
 //     TS has no routing layer.
 //   - Middlewares (IRpcMiddleware[]) — ordered middleware pipeline for inbound
 //     calls.  TS dispatches directly to service implementations.
@@ -52,7 +53,7 @@ import { RpcSystemCalls } from './rpc-message.js';
 const { warnLog } = getLogs('RpcHub');
 
 /** Factory signature shared by all peer lookup/creation methods. Serialization
- *  format is encoded in the URL via `?f=...` (see {@link RpcPeerRefBuilder}),
+ *  format is encoded in the URL via `?f=...` (see {@link RpcRefBuilder}),
  *  so the factory doesn't need an extra parameter for it. `getClientPeer` /
  *  `getServerPeer` cast the result, so the factory returns RpcPeer. */
 export type RpcPeerFactory = (hub: RpcHub, ref: string) => RpcPeer;

ts/packages/rpc/src/rpc-peer.ts

@@ -56,9 +56,10 @@
 //   - ProcessMessage() — creates RpcInboundContext per message, dispatches via
 //     MethodDef.InboundCallInvoker.  TS dispatches via _handleMessage →
 //     handleSystemCall or RpcServiceHost.dispatch.
-//   - RpcPeerRef / routing — .NET peers are keyed by RpcPeerRef (which encodes
-//     client/server, route state, versions, serialization format).  TS peers are
-//     keyed by string ref (URL for clients, "server://{uuid}" for servers).
+//   - RpcRef / RpcRoute / routing — .NET peers are bound to an RpcRoute (one route
+//     generation of a stable RpcRef, which encodes client/server, versions,
+//     serialization format).  TS peers are keyed by string ref (URL for clients,
+//     "server://{uuid}" for servers).
 //   - StopMode / ComputeAutoStopMode — controls behavior of inbound calls when
 //     peer stops (cancel vs keep-incomplete).  TS has no stop mode.
 //   - ConnectionKind detector (Remote/Loopback/Local/None) — .NET detects if peer
@@ -792,7 +793,7 @@ export class RpcClientPeer extends RpcPeer {
      * @param url Full WebSocket URL — the serialization format is taken from
      *            the `f=` query parameter (e.g. `wss://host/rpc/ws?f=msgpack6`);
      *            falls back to the resolver's default when absent. Use
-     *            {@link RpcPeerRefBuilder.forClient} to compose URLs with a format.
+     *            {@link RpcRefBuilder.forClient} to compose URLs with a format.
      * @param mustStart Kick off the reconnect loop automatically at the end of
      *            construction (default `true`). Pass `false` if you need to
      *            tweak `reconnectDelayer`, `handshakeTimeoutMs`, or similar

…packages/rpc/src/rpc-peer-ref-builder.ts ts/packages/rpc/src/rpc-ref-builder.tsts/packages/rpc/src/rpc-peer-ref-builder.ts renamed to ts/packages/rpc/src/rpc-ref-builder.ts ts/packages/rpc/src/rpc-peer-ref-builder.ts renamed to ts/packages/rpc/src/rpc-ref-builder.ts

@@ -5,10 +5,10 @@
 // `RpcServerPeer`'s ref is `server://{id}`.
 //
 // Typical use:
-//     rpcHub.defaultPeerUrl = RpcPeerRefBuilder.forClient('wss://host/rpc/ws', 'msgpack6');
-//     const serverRef = RpcPeerRefBuilder.forServer(crypto.randomUUID());
+//     rpcHub.defaultPeerUrl = RpcRefBuilder.forClient('wss://host/rpc/ws', 'msgpack6');
+//     const serverRef = RpcRefBuilder.forServer(crypto.randomUUID());
 
-export class RpcPeerRefBuilder {
+export class RpcRefBuilder {
     /** Build a client peer ref from a WebSocket URL, optionally baking in the
      *  serialization format as a `f=` query parameter.
      *  @param url Base WebSocket URL, e.g. `wss://host/rpc/ws`.

ts/packages/rpc/tests/rpc-reconnection.test.ts

@@ -187,18 +187,18 @@ describe('RPC Reconnection', () => {
         const r1 = await calc.add(1, 2);
         expect(r1).toBe(3);
 
-        const peerRef = conn.clientPeer.ref;
+        const rpcRef = conn.clientPeer.ref;
         const peerIdBefore = conn.clientPeer.id;
         expect(conn.clientPeer.connection).toBeDefined();
-        expect(clientHub.peers.get(peerRef)).toBe(conn.clientPeer);
+        expect(clientHub.peers.get(rpcRef)).toBe(conn.clientPeer);
 
         // Call the public disconnect() — closes WS without disposing peer.
         conn.clientPeer.disconnect();
         await delay(5);
 
         // Connection is cleared, peer instance survives with same identity.
         expect(conn.clientPeer.connection).toBeUndefined();
-        expect(clientHub.peers.get(peerRef)).toBe(conn.clientPeer);
+        expect(clientHub.peers.get(rpcRef)).toBe(conn.clientPeer);
         expect(conn.clientPeer.id).toBe(peerIdBefore);
 
         // Re-attach a fresh connection — the same peer instance is reused.