@zyno-io/ts-server-foundation 26.729.1927 → 26.731.113

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/dist/src/app/base.d.ts +2 -1
  2. package/dist/src/app/base.d.ts.map +1 -1
  3. package/dist/src/app/base.js +19 -4
  4. package/dist/src/app/base.js.map +1 -1
  5. package/dist/src/app/index.js +1 -1
  6. package/dist/src/di/container.js +1 -1
  7. package/dist/src/helpers/index.d.ts +1 -0
  8. package/dist/src/helpers/index.d.ts.map +1 -1
  9. package/dist/src/helpers/index.js +1 -0
  10. package/dist/src/helpers/index.js.map +1 -1
  11. package/dist/src/helpers/utils/timer.d.ts +3 -0
  12. package/dist/src/helpers/utils/timer.d.ts.map +1 -0
  13. package/dist/src/helpers/utils/timer.js +12 -0
  14. package/dist/src/helpers/utils/timer.js.map +1 -0
  15. package/dist/src/http/base.js +3 -3
  16. package/dist/src/http/base.js.map +1 -1
  17. package/dist/src/http/decorators.d.ts +12 -0
  18. package/dist/src/http/decorators.d.ts.map +1 -1
  19. package/dist/src/http/decorators.js +24 -1
  20. package/dist/src/http/decorators.js.map +1 -1
  21. package/dist/src/http/index.js +1 -1
  22. package/dist/src/http/response.js +1 -1
  23. package/dist/src/http/router.d.ts +16 -2
  24. package/dist/src/http/router.d.ts.map +1 -1
  25. package/dist/src/http/router.js +119 -28
  26. package/dist/src/http/router.js.map +1 -1
  27. package/dist/src/http/static-files.d.ts +4 -3
  28. package/dist/src/http/static-files.d.ts.map +1 -1
  29. package/dist/src/http/static-files.js +12 -4
  30. package/dist/src/http/static-files.js.map +1 -1
  31. package/dist/src/index.js +1 -1
  32. package/dist/src/services/index.js +1 -1
  33. package/dist/src/services/mesh-client/index.d.ts +3 -1
  34. package/dist/src/services/mesh-client/index.d.ts.map +1 -1
  35. package/dist/src/services/mesh-client/index.js +6 -2
  36. package/dist/src/services/mesh-client/index.js.map +1 -1
  37. package/dist/src/services/mesh-client/mesh-client-redis-registry.d.ts +53 -7
  38. package/dist/src/services/mesh-client/mesh-client-redis-registry.d.ts.map +1 -1
  39. package/dist/src/services/mesh-client/mesh-client-redis-registry.js +862 -61
  40. package/dist/src/services/mesh-client/mesh-client-redis-registry.js.map +1 -1
  41. package/dist/src/services/mesh-client/mesh-client-registry.d.ts +17 -6
  42. package/dist/src/services/mesh-client/mesh-client-registry.d.ts.map +1 -1
  43. package/dist/src/services/mesh-client/mesh-client-registry.js +43 -2
  44. package/dist/src/services/mesh-client/mesh-client-registry.js.map +1 -1
  45. package/dist/src/services/mesh-client/mesh-client-service.d.ts +115 -48
  46. package/dist/src/services/mesh-client/mesh-client-service.d.ts.map +1 -1
  47. package/dist/src/services/mesh-client/mesh-client-service.js +790 -101
  48. package/dist/src/services/mesh-client/mesh-client-service.js.map +1 -1
  49. package/dist/src/services/mesh-client/mesh-srpc-link-controller.d.ts +129 -17
  50. package/dist/src/services/mesh-client/mesh-srpc-link-controller.d.ts.map +1 -1
  51. package/dist/src/services/mesh-client/mesh-srpc-link-controller.js +1615 -126
  52. package/dist/src/services/mesh-client/mesh-srpc-link-controller.js.map +1 -1
  53. package/dist/src/services/mesh-client/mesh-srpc-remote-connection.d.ts +38 -6
  54. package/dist/src/services/mesh-client/mesh-srpc-remote-connection.d.ts.map +1 -1
  55. package/dist/src/services/mesh-client/mesh-srpc-remote-connection.js +192 -27
  56. package/dist/src/services/mesh-client/mesh-srpc-remote-connection.js.map +1 -1
  57. package/dist/src/services/mesh-client/mesh-srpc-server.d.ts +57 -8
  58. package/dist/src/services/mesh-client/mesh-srpc-server.d.ts.map +1 -1
  59. package/dist/src/services/mesh-client/mesh-srpc-server.js +479 -131
  60. package/dist/src/services/mesh-client/mesh-srpc-server.js.map +1 -1
  61. package/dist/src/services/mesh-client/types.d.ts +77 -6
  62. package/dist/src/services/mesh-client/types.d.ts.map +1 -1
  63. package/dist/src/services/mesh-client/types.js +1 -1
  64. package/dist/src/services/mesh-client/types.js.map +1 -1
  65. package/dist/src/services/mesh-link/auth.d.ts +36 -2
  66. package/dist/src/services/mesh-link/auth.d.ts.map +1 -1
  67. package/dist/src/services/mesh-link/auth.js +97 -21
  68. package/dist/src/services/mesh-link/auth.js.map +1 -1
  69. package/dist/src/services/mesh-link/index.d.ts +2 -2
  70. package/dist/src/services/mesh-link/index.d.ts.map +1 -1
  71. package/dist/src/services/mesh-link/index.js +5 -2
  72. package/dist/src/services/mesh-link/index.js.map +1 -1
  73. package/dist/src/services/mesh-link/peer.d.ts +26 -1
  74. package/dist/src/services/mesh-link/peer.d.ts.map +1 -1
  75. package/dist/src/services/mesh-link/peer.js +220 -26
  76. package/dist/src/services/mesh-link/peer.js.map +1 -1
  77. package/dist/src/services/mesh-link/protocol.d.ts +16 -3
  78. package/dist/src/services/mesh-link/protocol.d.ts.map +1 -1
  79. package/dist/src/services/mesh-link/protocol.js +8 -4
  80. package/dist/src/services/mesh-link/protocol.js.map +1 -1
  81. package/dist/src/services/mesh-link/runtime.d.ts +57 -4
  82. package/dist/src/services/mesh-link/runtime.d.ts.map +1 -1
  83. package/dist/src/services/mesh-link/runtime.js +557 -67
  84. package/dist/src/services/mesh-link/runtime.js.map +1 -1
  85. package/dist/src/services/mesh.d.ts +72 -28
  86. package/dist/src/services/mesh.d.ts.map +1 -1
  87. package/dist/src/services/mesh.js +587 -278
  88. package/dist/src/services/mesh.js.map +1 -1
  89. package/dist/src/srpc/SrpcByteStream.d.ts +21 -2
  90. package/dist/src/srpc/SrpcByteStream.d.ts.map +1 -1
  91. package/dist/src/srpc/SrpcByteStream.js +271 -61
  92. package/dist/src/srpc/SrpcByteStream.js.map +1 -1
  93. package/dist/src/srpc/SrpcClient.d.ts +57 -13
  94. package/dist/src/srpc/SrpcClient.d.ts.map +1 -1
  95. package/dist/src/srpc/SrpcClient.js +558 -120
  96. package/dist/src/srpc/SrpcClient.js.map +1 -1
  97. package/dist/src/srpc/SrpcServer.d.ts +59 -4
  98. package/dist/src/srpc/SrpcServer.d.ts.map +1 -1
  99. package/dist/src/srpc/SrpcServer.js +683 -80
  100. package/dist/src/srpc/SrpcServer.js.map +1 -1
  101. package/dist/src/srpc/index.js +1 -1
  102. package/dist/src/srpc/observer.js +1 -1
  103. package/dist/src/srpc/types.d.ts +37 -6
  104. package/dist/src/srpc/types.d.ts.map +1 -1
  105. package/dist/src/srpc/types.js +12 -1
  106. package/dist/src/srpc/types.js.map +1 -1
  107. package/docs/content/getting-started.md +22 -20
  108. package/docs/content/http.md +38 -1
  109. package/docs/content/mesh-client.md +175 -53
  110. package/docs/content/mesh-service.md +64 -229
  111. package/docs/content/srpc.md +33 -10
  112. package/package.json +7 -7
@@ -1,6 +1,6 @@
1
1
  # Mesh Client Tracking
2
2
 
3
- Track clients connected across multiple backend nodes and invoke operations on any client regardless of which node it's connected to. Built on top of [MeshService](./mesh-service.md).
3
+ Track clients connected across multiple backend nodes and invoke operations on any client regardless of which node it's connected to. Redis provides membership and registry coordination; `MeshSrpcServer` sends point-to-point client operations over authenticated mesh WebSockets.
4
4
 
5
5
  Three layers, each building on the previous:
6
6
 
@@ -25,52 +25,59 @@ interface ClientMeta {
25
25
  const backend = new MeshClientRedisRegistry<ClientMeta>('my-app');
26
26
  const registry = new MeshClientRegistry<ClientMeta>(mesh.instanceId, backend);
27
27
 
28
- await registry.register('client-123', { userId: 'user-1', role: 'admin' });
28
+ await registry.register('client-123', { userId: 'user-1', role: 'admin' }, true, 'connection-123');
29
29
 
30
30
  const client = await registry.getClient('client-123');
31
- // { clientId: 'client-123', nodeId: 1, connectedAt: 1710000000000, metadata: { userId: 'user-1', role: 'admin' } }
31
+ // { clientId: 'client-123', nodeId: 1, connectionId: 'connection-123', connectedAt: 1710000000000, metadata: { userId: 'user-1', role: 'admin' } }
32
32
 
33
33
  const all = await registry.listClients();
34
34
  const local = await registry.listClientsForNode(mesh.instanceId);
35
35
 
36
36
  // Update metadata (ownership-safe: only updates if this node owns the registration)
37
- const updated = await registry.updateMetadata('client-123', {
38
- userId: 'user-1',
39
- role: 'superadmin'
40
- });
37
+ const updated = await registry.updateMetadata(
38
+ 'client-123',
39
+ {
40
+ userId: 'user-1',
41
+ role: 'superadmin'
42
+ },
43
+ 'connection-123'
44
+ );
41
45
 
42
46
  // Ownership-safe: only removes if this node owns the registration
43
- const removed = await registry.unregister('client-123'); // true if removed, false if client moved
47
+ const removed = await registry.unregister('client-123', 'connection-123'); // true if removed, false if client moved
44
48
  ```
45
49
 
46
50
  The `MeshClientRegistryBackend` interface is pluggable — implement your own for database-backed tracking:
47
51
 
48
52
  ```typescript
49
- import type { MeshClientRegistryBackend, RegisteredClient, RegisterResult } from '@zyno-io/ts-server-foundation';
53
+ import type { MeshClientRecord, MeshClientRegistryBackend, RegisteredClient, RegisterResult } from '@zyno-io/ts-server-foundation';
50
54
 
51
55
  class DatabaseClientRegistry<TMeta> implements MeshClientRegistryBackend<TMeta> {
52
- async register(clientId: string, nodeId: number, metadata: TMeta, allowSupersede = true): Promise<RegisterResult> {
56
+ async register(clientId: string, nodeId: number, metadata: TMeta, allowSupersede: boolean, connectionId: string): Promise<RegisterResult> {
53
57
  // Atomically create an active registration, return a conflict when another
54
58
  // node owns it and supersession is disabled, or report the superseded node.
55
59
  throw new Error('Implement active registration');
56
60
  }
57
- async reserve(clientId: string, nodeId: number, metadata: TMeta, allowSupersede = true): Promise<RegisterResult> {
61
+ async reserve(clientId: string, nodeId: number, metadata: TMeta, allowSupersede: boolean, connectionId: string): Promise<RegisterResult> {
58
62
  // Pending reservations must remain hidden from lookup/list operations.
59
63
  throw new Error('Implement pending reservation');
60
64
  }
61
- async activate(clientId: string, nodeId: number, metadata: TMeta): Promise<boolean> {
65
+ async activate(clientId: string, nodeId: number, metadata: TMeta, connectionId: string): Promise<boolean> {
62
66
  // Promote this node's pending reservation to active without changing ownership.
63
67
  throw new Error('Implement reservation activation');
64
68
  }
65
- async unregister(clientId: string, nodeId: number): Promise<boolean> {
69
+ async unregister(clientId: string, nodeId: number, connectionId: string): Promise<boolean> {
66
70
  throw new Error('Implement ownership-safe removal');
67
71
  }
68
- async updateMetadata(clientId: string, nodeId: number, metadata: TMeta): Promise<boolean> {
72
+ async updateMetadata(clientId: string, nodeId: number, metadata: TMeta, connectionId: string): Promise<boolean> {
69
73
  throw new Error('Implement ownership-safe metadata update');
70
74
  }
71
75
  async getClient(clientId: string): Promise<RegisteredClient<TMeta> | undefined> {
72
76
  throw new Error('Implement active lookup');
73
77
  }
78
+ async getClientIncludingPending(clientId: string): Promise<MeshClientRecord<TMeta> | undefined> {
79
+ throw new Error('Implement exact active/pending lookup');
80
+ }
74
81
  async listClients(): Promise<RegisteredClient<TMeta>[]> {
75
82
  throw new Error('Implement active listing');
76
83
  }
@@ -83,6 +90,35 @@ class DatabaseClientRegistry<TMeta> implements MeshClientRegistryBackend<TMeta>
83
90
  }
84
91
  ```
85
92
 
93
+ Backends that support supersession must implement `claim`, `commitClaim`,
94
+ `abortClaim`, `getClientIncludingPending`, `removeClaimPrevious`, and
95
+ `removeClaimResult` methods.
96
+ `MeshClientService` treats these as one capability set and uses them to make
97
+ supersession a two-phase handoff: the old, exact `connectionId` remains
98
+ authoritative while the replacement is private; it is synchronously
99
+ disconnected and must acknowledge the fence before the replacement is
100
+ committed. Commit compares the exact raw preimage. If that same stable
101
+ generation changes state while its physical fence is in flight, the claimant
102
+ removes only that captured generation and retries once; a different reconnect
103
+ is never removed or overwritten. The committed raw record retains only the
104
+ opaque claim marker needed to reconcile a lost commit response or remove that
105
+ exact result. Claim creation also carries a caller-stable operation ID bound to
106
+ the complete requested node, process, connection, state, and metadata payload:
107
+ only an identical retry is idempotent, while a different operation or payload
108
+ conflicts. An ambiguous creation is retried with that same identity and
109
+ byte-identical request until the claim deadline. Lost exact-generation kick
110
+ responses are likewise retried against the same target; acknowledgement or a
111
+ raw read proving that exact generation absent completes the fence. Commit
112
+ reconciliation retries the same claim ID and exact raw read within a bounded
113
+ loop. If claim creation, commit, or exact cleanup cannot be proven, the service
114
+ fences and stops its entire mesh ownership generation rather than reporting
115
+ definite non-delivery while the claimed record could remain. Every registration
116
+ record must include a `connectionId`, and custom backends must implement all six
117
+ claim methods to support safe cross-node takeovers.
118
+ Missing any capability fails closed, because active-only lookup cannot
119
+ distinguish absence from a hidden pending owner and same-node conflict
120
+ semantics do not protect a reconnect without the exact generation.
121
+
86
122
  ### API
87
123
 
88
124
  #### `new MeshClientRegistry<TMeta>(nodeId: number, backend: MeshClientRegistryBackend<TMeta>)`
@@ -91,7 +127,7 @@ Creates a registry bound to a specific mesh node ID.
91
127
 
92
128
  #### `register(clientId, metadata, allowSupersede?)` → `Promise<RegisterResult>`
93
129
 
94
- Register an active client on this node. A `connectedAt` timestamp (epoch ms) is automatically recorded. The result is `{ status: 'ok', supersededNodeId }` when registration succeeds or `{ status: 'conflict', ownerNodeId }` when another node owns the client and supersession is disabled. `ownerNodeId` can be `null` if the owner disappears during the conflict/readback race. The built-in Redis backend allows supersession by default.
130
+ Register an active client on this node. A `connectedAt` timestamp (epoch ms) is automatically recorded. The result is `{ status: 'ok', supersededNodeId }` when registration succeeds or `{ status: 'conflict', ownerNodeId }` when another node owns the client. Direct registry registration never steals an active remote owner because it cannot obtain the required revocation acknowledgement; use `MeshClientService` (or the optional claim APIs) for a fenced takeover. `ownerNodeId` can be `null` if the owner disappears during the conflict/readback race.
95
131
 
96
132
  #### `reserve(clientId, metadata, allowSupersede?)` → `Promise<RegisterResult>`
97
133
 
@@ -117,10 +153,16 @@ Look up a client by ID across all nodes. The returned `RegisteredClient` include
117
153
 
118
154
  List all registered clients across all nodes.
119
155
 
156
+ #### `listClientsPage(cursor?)` → `Promise<{ clients, cursor? }>`
157
+
158
+ Incrementally scan registered clients without materializing the complete Redis hash in one command. Pass the opaque returned `cursor` to the next call; an absent cursor means the scan is complete. Scan pages can repeat an entry while the registry changes, so long-running consumers should deduplicate by `clientId`.
159
+
120
160
  #### `listClientsForNode(nodeId?)` → `Promise<RegisteredClient<TMeta>[]>`
121
161
 
122
162
  List clients for a specific node. Defaults to this registry's node.
123
163
 
164
+ `listClientsForNodePage(nodeId?, cursor?)` provides the corresponding incremental per-node scan.
165
+
124
166
  #### `cleanupNode(nodeId?)` → `Promise<RegisteredClient<TMeta>[]>`
125
167
 
126
168
  Remove all clients for a node, returning the orphaned clients (with metadata). Only removes clients still owned by that node — clients that reconnected elsewhere are left intact.
@@ -129,7 +171,7 @@ Remove all clients for a node, returning the orphaned clients (with metadata). O
129
171
 
130
172
  ## MeshClientService
131
173
 
132
- Combines MeshClientRegistry with MeshService for transparent cross-node client invocation. You provide a `clientInvokeFn` for delivery to a client connected to this node; it is called for both local invocations and requests forwarded from another node.
174
+ Combines `MeshClientRegistry` with local client delivery. On its own, `MeshClientService` only invokes clients connected to the current node. `MeshSrpcServer` installs the authenticated direct mesh-link transport required for cross-node invocation, metadata updates, disconnects, and exact ownership fencing; those operations do not use Redis pub/sub RPC. A standalone service fails a remote operation rather than falling back to Redis RPC.
133
175
 
134
176
  ```typescript
135
177
  import { MeshClientService } from '@zyno-io/ts-server-foundation';
@@ -142,19 +184,19 @@ interface MyBroadcasts {
142
184
  const clientService = new MeshClientService<ClientMeta, MyBroadcasts>({
143
185
  key: 'my-app',
144
186
  clientInvokeFn: async (clientId, type, data, timeoutMs) => {
145
- // Deliver to a client connected to this node, whether the caller is local or remote.
187
+ // Deliver to a client connected to this node.
146
188
  return localDelivery(clientId, type, data);
147
189
  }
148
190
  });
149
191
 
150
192
  await clientService.start();
151
193
 
152
- await clientService.registerClient('client-123', { userId: 'user-1', role: 'admin' });
194
+ await clientService.registerClient('client-123', { userId: 'user-1', role: 'admin' }, true, 'connection-123');
153
195
 
154
196
  // Update metadata after registration (ownership-safe)
155
197
  await clientService.updateClientMetadata('client-123', { userId: 'user-1', role: 'superadmin' });
156
198
 
157
- // Invoke on any client — routes through mesh if on a different node
199
+ // Invoke a client connected to this node
158
200
  const result = await clientService.invoke('client-123', 'notify', { text: 'hello' });
159
201
 
160
202
  // Broadcast to all nodes
@@ -177,6 +219,7 @@ await clientService.stop();
177
219
  | `key` | `string` | Mesh key (internally namespaced as `_mc:{key}`) |
178
220
  | `meshOptions` | `MeshServiceOptions` | Optional tuning for the internal mesh node |
179
221
  | `registryBackend` | `MeshClientRegistryBackend` | Optional custom backend (defaults to `MeshClientRedisRegistry`) |
222
+ | `registryOptions` | `MeshClientRedisRegistryOptions` | Optional limits for the built-in Redis registry; ignored when a custom backend is supplied |
180
223
  | `clientInvokeFn` | `(clientId, type, data, timeoutMs?) => Promise<unknown>` | Delivers local clients for both local and forwarded invocations |
181
224
  | `clientUpdateMetaFn` | `(clientId, metadata) => boolean` | Optional owning-node hook that applies a cross-node metadata update to the live local client. |
182
225
 
@@ -189,20 +232,21 @@ await clientService.stop();
189
232
 
190
233
  #### Methods
191
234
 
192
- | Method | Description |
193
- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
194
- | `start()` | Start the internal mesh and initialize the registry |
195
- | `stop()` | Clean up own clients, stop the mesh |
196
- | `registerClient(clientId, metadata, allowSupersede?)` → `Promise<boolean>` | Register on this node; false means a non-superseded ownership conflict |
197
- | `reserveClient(clientId, metadata, allowSupersede?)` → `Promise<boolean>` | Reserve ownership without exposing the client until activation |
198
- | `activateClient(clientId, metadata)` → `Promise<boolean>` | Promote this node's reservation to active |
199
- | `unregisterClient(clientId)` → `Promise<boolean>` | Unregister (returns false if client moved elsewhere) |
200
- | `updateClientMetadata(clientId, metadata)` → `Promise<boolean>` | Update metadata (returns false if client moved) |
201
- | `invoke(clientId, type, data, timeoutMs?)` | Invoke on any client, routes automatically |
202
- | `registerBroadcastHandler(type, handler)` | Register a handler for a broadcast type |
203
- | `broadcast(type, data, options?)` | Broadcast to all nodes in the mesh |
204
-
205
- Before `start()`, registration and reservation are accepted as no-op compatibility calls, activation/update/unregister return `false`, and `invoke()` throws `ClientNotFoundError`. Callers that need discoverable state must await `start()` first. Local invocation calls `clientInvokeFn` directly. Remote invocation forwards to the owning node and preserves `ClientDisconnectedError`; other delivery failures become `ClientInvocationError`. Remote metadata updates run `clientUpdateMetaFn` on the owner and persist the accepted metadata in the registry.
235
+ | Method | Description |
236
+ | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
237
+ | `start()` | Start the internal mesh and initialize the registry |
238
+ | `stop()` | Clean up own clients, stop the mesh |
239
+ | `registerClient(clientId, metadata, allowSupersede, connectionId)` → `Promise<boolean>` | Register this exact connection on this node; false means a non-superseded ownership conflict |
240
+ | `reserveClient(clientId, metadata, allowSupersede, connectionId)` → `Promise<boolean>` | Reserve exact ownership without exposing the client until activation |
241
+ | `activateClient(clientId, metadata, connectionId)` → `Promise<boolean>` | Promote this node's exact reservation to active |
242
+ | `unregisterClient(clientId, connectionId)` → `Promise<boolean>` | Unregister only that exact connection generation |
243
+ | `updateClientMetadata(clientId, metadata)` → `Promise<boolean>` | Update metadata (returns false if client moved) |
244
+ | `invoke(clientId, type, data, timeoutMs?)` | Invoke on any client, routes automatically |
245
+ | `registerBroadcastHandler(type, handler)` | Register a handler for a broadcast type |
246
+ | `broadcast(type, data, options?)` | Broadcast to all nodes in the mesh |
247
+ | `onLeaseLost(handler)` | Fence local delivery after the mesh lease is lost |
248
+
249
+ Before `start()`, registration and reservation are accepted as no-op calls, activation/update/unregister return `false`, and `invoke()` throws `ClientNotFoundError`. Callers that need discoverable state must await `start()` first. `start()`/`stop()` are serialized and `clientRegistry` remains the same facade throughout the service lifetime. Local invocation calls `clientInvokeFn` directly. With `MeshSrpcServer`, remote invocation, metadata updates, disconnects, and ownership fences go to the owning stream over its pinned, authenticated mesh WebSocket. A node that does not advertise a direct link fails closed; there is no Redis RPC fallback. A supplied timeout is an end-to-end deadline: routing time is deducted before delivery. Remote metadata updates run `clientUpdateMetaFn` on the owner and persist the accepted metadata in the registry. On lease loss, the service blocks new delivery before running its `onLeaseLost` handlers; `MeshSrpcServer` uses this to close local streams and mesh links.
206
250
 
207
251
  ---
208
252
 
@@ -210,6 +254,8 @@ Before `start()`, registration and reservation are accepted as no-op compatibili
210
254
 
211
255
  Extends `SrpcServer` with mesh client tracking. Single class — no need to create an SrpcServer separately.
212
256
 
257
+ Cross-node client operations require `meshLink.secret` or `MESH_LINK_SECRET`. Without either, `meshStart()` still starts membership, the registry, and broadcasts, but client operations are local-only. Remote operations fail closed; Redis is never used as an RPC fallback.
258
+
213
259
  ```typescript
214
260
  import { MeshSrpcServer } from '@zyno-io/ts-server-foundation';
215
261
  import { ClientMessage, ServerMessage } from './generated/proto';
@@ -222,7 +268,10 @@ const server = new MeshSrpcServer({
222
268
  wsPath: '/srpc',
223
269
 
224
270
  // Mesh options
225
- meshKey: 'my-app'
271
+ meshKey: 'my-app',
272
+ // Required for cross-node client operations. It may instead come from
273
+ // the MESH_LINK_SECRET application configuration.
274
+ meshLink: { secret: process.env.MESH_LINK_SECRET! }
226
275
  });
227
276
 
228
277
  // Register SRPC handlers as usual
@@ -243,7 +292,7 @@ server.onClientDisconnected((clientId, metadata) => {
243
292
  });
244
293
 
245
294
  server.onNodeClientsOrphaned((nodeId, clients) => {
246
- // Fires on the leader when a dead node is cleaned up
295
+ // One healthy node claims each durable cleanup chunk
247
296
  // Only includes clients that didn't reconnect elsewhere
248
297
  console.log(`Node ${nodeId} died, ${clients.length} orphaned clients`);
249
298
  for (const client of clients) {
@@ -285,12 +334,14 @@ new MeshSrpcServer(options: ISrpcServerOptions & MeshSrpcServerOptions)
285
334
 
286
335
  `MeshSrpcServerOptions`:
287
336
 
288
- | Option | Type | Description |
289
- | ----------------- | --------------------------- | ---------------------------------------------- |
290
- | `meshKey` | `string` | Mesh key |
291
- | `meshOptions` | `MeshServiceOptions` | Optional mesh tuning |
292
- | `registryBackend` | `MeshClientRegistryBackend` | Optional custom backend |
293
- | `extractMetadata` | `(stream) => TRegistryMeta` | Optional metadata extraction from SRPC streams |
337
+ | Option | Type | Description |
338
+ | ----------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
339
+ | `meshKey` | `string` | Mesh key |
340
+ | `meshOptions` | `MeshServiceOptions` | Optional mesh tuning |
341
+ | `registryBackend` | `MeshClientRegistryBackend` | Optional custom backend |
342
+ | `registryOptions` | `MeshClientRedisRegistryOptions` | Optional limits for the built-in Redis backend |
343
+ | `extractMetadata` | `(stream) => TRegistryMeta` | Optional metadata extraction from SRPC streams |
344
+ | `meshLink` | `object` | Direct WebSocket configuration; `secret` (or `MESH_LINK_SECRET`) enables cross-node client operations |
294
345
 
295
346
  #### Properties
296
347
 
@@ -311,23 +362,94 @@ new MeshSrpcServer(options: ISrpcServerOptions & MeshSrpcServerOptions)
311
362
  | `broadcast(type, data, options?)` | Broadcast to all nodes in the mesh |
312
363
  | `onClientConnected(handler)` | Fires on the node the client connected to |
313
364
  | `onClientDisconnected(handler)` | Fires on the node the client disconnected from |
314
- | `onNodeClientsOrphaned(handler)` | Fires on the **leader node** when a dead node's clients are cleaned up |
365
+ | `onNodeClientsOrphaned(handler)` | Fires on one durable single-claimer when a dead node's client chunk is cleaned up |
315
366
 
316
367
  Plus all `SrpcServer` methods: `registerMessageHandler`, `registerConnectionHandler`, `registerDisconnectHandler`, `setClientAuthorizer`, etc.
317
368
 
318
- `MeshSrpcServer` reserves client ownership before SRPC activation, so pending connections never appear in active registry lookups. After activation, top-level assignments and deletions on `stream.meta` are batched in a microtask and synchronized to the registry. Nested mutations are not observable through the proxy; replace the top-level value or call `updateClientMetadata()`. Explicit metadata updates currently merge supplied keys into the live `stream.meta` object while replacing the registry metadata value, so callers that need deletion parity should delete top-level stream keys directly. Calls for a remote client route through the mesh to the owning SRPC stream. Connected/disconnected callbacks are serialized per client, and a stale disconnect from a same-node replacement does not unregister the replacement or publish an offline callback.
319
-
320
- ## Current Limits
321
-
322
- - The built-in Redis registry applies a 24-hour safety TTL to its client hash and per-node sets. Registry writes refresh those keys, but mesh heartbeats currently do not; registrations in a completely quiet mesh can therefore expire while clients remain connected.
369
+ `MeshSrpcServer` reserves client ownership before SRPC activation, so pending connections never appear in active registry lookups. After activation, top-level assignments and deletions on `stream.meta` are batched in a microtask and synchronized to the registry. Nested mutations are not observable through the proxy; replace the top-level value or call `updateClientMetadata()`. Explicit metadata updates currently merge supplied keys into the live `stream.meta` object while replacing the registry metadata value, so callers that need deletion parity should delete top-level stream keys directly. Calls for a remote client route through the pinned, authenticated mesh WebSocket to the owning SRPC stream. Connected/disconnected callbacks are serialized per client. Exact disconnect unregisters are retained and retried while the lease is safe; absence or a different generation completes the obligation without deleting a reconnect. Offline callbacks run once only after that obligation is confirmed. Persistent ambiguity fences the service so leader cleanup can remove any ghost owner.
370
+
371
+ ## Resource limits and orphan delivery
372
+
373
+ The built-in Redis registry defaults to 1,024 UTF-8 bytes per client ID, 64 KiB of JSON metadata, 10,000 clients per node, 256-entry listing and cleanup batches, 4,096 authentication principals, and 256 live nonces per principal. Configure these through `registryOptions`. Core `SrpcServer` also defaults to 128 pending handshakes, 10,000 live streams, 1,024 client-ID bytes, 64 KiB merged client metadata, and 256 local replay principals.
374
+
375
+ Registry listing uses incremental Redis scans. Dead-node cleanup removes fenced records in bounded batches and persists active clients in bounded durable orphan chunks; pending reservations do not produce offline callbacks. Each mesh heartbeat refreshes the registry safety TTL for the node's client set and shared client hash, so a healthy quiet node retains its registrations.
376
+
377
+ Durable orphan callbacks are single-claimer, not leader-affine. The cleanup leader creates the obligation, but any healthy service instance may atomically claim and deliver a chunk. A failed callback NACKs the chunk for redelivery; a lost claim becomes available after its server-time lease expires. Callbacks must therefore be idempotent.
378
+
379
+ The built-in durable orphan queue has global `registryOptions.maxOrphanItems`
380
+ and `maxOrphanBytes` caps (defaults: 4,096 items and 64 MiB), atomically
381
+ accounted in Redis. Admission reserves the maximum claim-token growth, so the
382
+ stored/accounted total stays within the byte cap while an item is claimed or
383
+ NACKed. Legacy unaccounted queues fail closed until a bounded sweep or consumer
384
+ fully drains them. A full queue rejects admission so the source cleanup is
385
+ retried rather than losing a callback. The non-durable fallback is similarly
386
+ bounded with `maxPendingOrphanItems` and `maxPendingOrphanBytes`. A service
387
+ stop or mesh-lease loss fences the drain: it makes no new claims, releases its
388
+ exact active claim for redelivery, and never ACKs after the boundary.
389
+
390
+ Fallback orphan snapshots require the backend's
391
+ `cleanupNodeForFallback(nodeId, maxItems, maxBytes)` capability. That operation
392
+ must compute the exact active-only snapshot, treat any non-empty snapshot as
393
+ one item regardless of its client count, reject before mutation when that item
394
+ or its serialized bytes exceed the supplied remaining bounds, and otherwise
395
+ remove all node records and return that exact snapshot atomically. An empty
396
+ snapshot consumes no item or bytes and is not enqueued. Fallback cleanup
397
+ admission is serialized across nodes so concurrent cleanups cannot both spend
398
+ the same remaining capacity. Expiry frees an obligation even while its callback
399
+ is blocked; a late callback completion is fenced to its exact obligation and
400
+ cannot delete a replacement or change its accounting. Legacy/custom backends
401
+ without the atomic capability fail closed before calling `cleanupNode`.
402
+ Callback mutation cannot alter the retained serialized snapshot or its byte
403
+ accounting.
404
+
405
+ Custom backends are considered durable only when
406
+ `cleanupNodeAndEnqueueOrphaned`, `claimOrphaned`, `ackOrphaned`, and
407
+ `nackOrphaned` are implemented together. A partial implementation uses the
408
+ bounded local fallback only when `cleanupNodeForFallback` is also available;
409
+ otherwise cleanup fails closed. The service never splits destructive cleanup
410
+ from a later durable enqueue across two backend calls.
411
+
412
+ Mesh-link endpoint pins are capped by `maxEndpointPins` (default: twice
413
+ `maxPeers`). Resolver-created pins are globally expiry-pruned and fail closed
414
+ at capacity. Explicit owner references remain valid past their TTL until the
415
+ last live connection, reservation, or terminal-cleanup obligation releases
416
+ them.
417
+
418
+ Direct v2 handle capabilities distinguish unused sender-ID reservations from
419
+ live byte-stream senders. Allocating a sender emits an authenticated activation
420
+ for the exact ID and renews its handle; unused reservations do not keep an idle
421
+ capability alive. Owner disconnect or idle-capability expiry sends an exact
422
+ capability revocation through the bounded terminal retry/ACK path. The remote
423
+ requester then marks only that handle stale, destroys its streams, detaches
424
+ their disconnect handlers, and releases the cache/pin reference. If revocation
425
+ cannot be acknowledged within the bounded retry window, the exact pinned peer
426
+ is closed as the fallback fence.
427
+
428
+ Sender announcements made during a direct remote invocation are provisional
429
+ until the invocation result is encoded and returned. Any handler, encoding,
430
+ send, or timeout failure sends terminal destroy operations for every announced
431
+ sender. A bounded exact-invocation tombstone rejects late announcements with
432
+ the same terminal destroy so client sender state and disconnect listeners do
433
+ not leak after the request has already failed.
434
+
435
+ Invocation timeouts are end-to-end deadlines, including registry lookup and cold direct-link connection. Heartbeats report accepted delivery but do not extend the deadline. Once delivery may have occurred, a timeout or link loss can be reported as an indeterminate-delivery error; use application idempotency before retrying non-idempotent work.
436
+
437
+ Forwarded mesh-client calls and authenticated direct mesh-link invoke frames
438
+ carry a relative residual and may retain the caller's absolute epoch. Every
439
+ forwarding hop decrements the relative value. The owner
440
+ captures a receiver-local expiry from that authenticated residual and never
441
+ rejects or expands it by comparing a foreign host's absolute epoch to its own
442
+ wall clock. Routing and authentication work on the owner continues to consume
443
+ the receiver-local budget.
323
444
 
324
445
  ---
325
446
 
326
447
  ## Error Classes
327
448
 
328
- | Error | When |
329
- | ------------------------- | --------------------------------------------------------------------- |
330
- | `ClientNotFoundError` | `invoke()` called with a clientId not in the registry |
331
- | `ClientDisconnectedError` | Client was in the registry but no longer connected on the target node |
332
- | `ClientInvocationError` | Remote delivery failed (wraps the original error message) |
333
- | `MeshRequestTimeoutError` | The remote node didn't respond to the mesh forwarding request |
449
+ | Error | When |
450
+ | -------------------------------- | --------------------------------------------------------------------- |
451
+ | `ClientNotFoundError` | `invoke()` called with a clientId not in the registry |
452
+ | `ClientDisconnectedError` | Client was in the registry but no longer connected on the target node |
453
+ | `ClientInvocationError` | Remote delivery failed (wraps the original error message) |
454
+ | `SrpcError` | The client handler returned an explicit typed sRPC error |
455
+ | `SrpcIndeterminateDeliveryError` | A direct mesh-link delivery may have reached the remote owner |