@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.
- package/dist/src/app/base.d.ts +2 -1
- package/dist/src/app/base.d.ts.map +1 -1
- package/dist/src/app/base.js +19 -4
- package/dist/src/app/base.js.map +1 -1
- package/dist/src/app/index.js +1 -1
- package/dist/src/di/container.js +1 -1
- package/dist/src/helpers/index.d.ts +1 -0
- package/dist/src/helpers/index.d.ts.map +1 -1
- package/dist/src/helpers/index.js +1 -0
- package/dist/src/helpers/index.js.map +1 -1
- package/dist/src/helpers/utils/timer.d.ts +3 -0
- package/dist/src/helpers/utils/timer.d.ts.map +1 -0
- package/dist/src/helpers/utils/timer.js +12 -0
- package/dist/src/helpers/utils/timer.js.map +1 -0
- package/dist/src/http/base.js +3 -3
- package/dist/src/http/base.js.map +1 -1
- package/dist/src/http/decorators.d.ts +12 -0
- package/dist/src/http/decorators.d.ts.map +1 -1
- package/dist/src/http/decorators.js +24 -1
- package/dist/src/http/decorators.js.map +1 -1
- package/dist/src/http/index.js +1 -1
- package/dist/src/http/response.js +1 -1
- package/dist/src/http/router.d.ts +16 -2
- package/dist/src/http/router.d.ts.map +1 -1
- package/dist/src/http/router.js +119 -28
- package/dist/src/http/router.js.map +1 -1
- package/dist/src/http/static-files.d.ts +4 -3
- package/dist/src/http/static-files.d.ts.map +1 -1
- package/dist/src/http/static-files.js +12 -4
- package/dist/src/http/static-files.js.map +1 -1
- package/dist/src/index.js +1 -1
- package/dist/src/services/index.js +1 -1
- package/dist/src/services/mesh-client/index.d.ts +3 -1
- package/dist/src/services/mesh-client/index.d.ts.map +1 -1
- package/dist/src/services/mesh-client/index.js +6 -2
- package/dist/src/services/mesh-client/index.js.map +1 -1
- package/dist/src/services/mesh-client/mesh-client-redis-registry.d.ts +53 -7
- package/dist/src/services/mesh-client/mesh-client-redis-registry.d.ts.map +1 -1
- package/dist/src/services/mesh-client/mesh-client-redis-registry.js +862 -61
- package/dist/src/services/mesh-client/mesh-client-redis-registry.js.map +1 -1
- package/dist/src/services/mesh-client/mesh-client-registry.d.ts +17 -6
- package/dist/src/services/mesh-client/mesh-client-registry.d.ts.map +1 -1
- package/dist/src/services/mesh-client/mesh-client-registry.js +43 -2
- package/dist/src/services/mesh-client/mesh-client-registry.js.map +1 -1
- package/dist/src/services/mesh-client/mesh-client-service.d.ts +115 -48
- package/dist/src/services/mesh-client/mesh-client-service.d.ts.map +1 -1
- package/dist/src/services/mesh-client/mesh-client-service.js +790 -101
- package/dist/src/services/mesh-client/mesh-client-service.js.map +1 -1
- package/dist/src/services/mesh-client/mesh-srpc-link-controller.d.ts +129 -17
- package/dist/src/services/mesh-client/mesh-srpc-link-controller.d.ts.map +1 -1
- package/dist/src/services/mesh-client/mesh-srpc-link-controller.js +1615 -126
- package/dist/src/services/mesh-client/mesh-srpc-link-controller.js.map +1 -1
- package/dist/src/services/mesh-client/mesh-srpc-remote-connection.d.ts +38 -6
- package/dist/src/services/mesh-client/mesh-srpc-remote-connection.d.ts.map +1 -1
- package/dist/src/services/mesh-client/mesh-srpc-remote-connection.js +192 -27
- package/dist/src/services/mesh-client/mesh-srpc-remote-connection.js.map +1 -1
- package/dist/src/services/mesh-client/mesh-srpc-server.d.ts +57 -8
- package/dist/src/services/mesh-client/mesh-srpc-server.d.ts.map +1 -1
- package/dist/src/services/mesh-client/mesh-srpc-server.js +479 -131
- package/dist/src/services/mesh-client/mesh-srpc-server.js.map +1 -1
- package/dist/src/services/mesh-client/types.d.ts +77 -6
- package/dist/src/services/mesh-client/types.d.ts.map +1 -1
- package/dist/src/services/mesh-client/types.js +1 -1
- package/dist/src/services/mesh-client/types.js.map +1 -1
- package/dist/src/services/mesh-link/auth.d.ts +36 -2
- package/dist/src/services/mesh-link/auth.d.ts.map +1 -1
- package/dist/src/services/mesh-link/auth.js +97 -21
- package/dist/src/services/mesh-link/auth.js.map +1 -1
- package/dist/src/services/mesh-link/index.d.ts +2 -2
- package/dist/src/services/mesh-link/index.d.ts.map +1 -1
- package/dist/src/services/mesh-link/index.js +5 -2
- package/dist/src/services/mesh-link/index.js.map +1 -1
- package/dist/src/services/mesh-link/peer.d.ts +26 -1
- package/dist/src/services/mesh-link/peer.d.ts.map +1 -1
- package/dist/src/services/mesh-link/peer.js +220 -26
- package/dist/src/services/mesh-link/peer.js.map +1 -1
- package/dist/src/services/mesh-link/protocol.d.ts +16 -3
- package/dist/src/services/mesh-link/protocol.d.ts.map +1 -1
- package/dist/src/services/mesh-link/protocol.js +8 -4
- package/dist/src/services/mesh-link/protocol.js.map +1 -1
- package/dist/src/services/mesh-link/runtime.d.ts +57 -4
- package/dist/src/services/mesh-link/runtime.d.ts.map +1 -1
- package/dist/src/services/mesh-link/runtime.js +557 -67
- package/dist/src/services/mesh-link/runtime.js.map +1 -1
- package/dist/src/services/mesh.d.ts +72 -28
- package/dist/src/services/mesh.d.ts.map +1 -1
- package/dist/src/services/mesh.js +587 -278
- package/dist/src/services/mesh.js.map +1 -1
- package/dist/src/srpc/SrpcByteStream.d.ts +21 -2
- package/dist/src/srpc/SrpcByteStream.d.ts.map +1 -1
- package/dist/src/srpc/SrpcByteStream.js +271 -61
- package/dist/src/srpc/SrpcByteStream.js.map +1 -1
- package/dist/src/srpc/SrpcClient.d.ts +57 -13
- package/dist/src/srpc/SrpcClient.d.ts.map +1 -1
- package/dist/src/srpc/SrpcClient.js +558 -120
- package/dist/src/srpc/SrpcClient.js.map +1 -1
- package/dist/src/srpc/SrpcServer.d.ts +59 -4
- package/dist/src/srpc/SrpcServer.d.ts.map +1 -1
- package/dist/src/srpc/SrpcServer.js +683 -80
- package/dist/src/srpc/SrpcServer.js.map +1 -1
- package/dist/src/srpc/index.js +1 -1
- package/dist/src/srpc/observer.js +1 -1
- package/dist/src/srpc/types.d.ts +37 -6
- package/dist/src/srpc/types.d.ts.map +1 -1
- package/dist/src/srpc/types.js +12 -1
- package/dist/src/srpc/types.js.map +1 -1
- package/docs/content/getting-started.md +22 -20
- package/docs/content/http.md +38 -1
- package/docs/content/mesh-client.md +175 -53
- package/docs/content/mesh-service.md +64 -229
- package/docs/content/srpc.md +33 -10
- 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.
|
|
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(
|
|
38
|
-
|
|
39
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
193
|
-
|
|
|
194
|
-
| `start()`
|
|
195
|
-
| `stop()`
|
|
196
|
-
| `registerClient(clientId, metadata, allowSupersede
|
|
197
|
-
| `reserveClient(clientId, metadata, allowSupersede
|
|
198
|
-
| `activateClient(clientId, metadata)` → `Promise<boolean>`
|
|
199
|
-
| `unregisterClient(clientId)` → `Promise<boolean>`
|
|
200
|
-
| `updateClientMetadata(clientId, metadata)` → `Promise<boolean>`
|
|
201
|
-
| `invoke(clientId, type, data, timeoutMs?)`
|
|
202
|
-
| `registerBroadcastHandler(type, handler)`
|
|
203
|
-
| `broadcast(type, data, options?)`
|
|
204
|
-
|
|
205
|
-
|
|
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
|
-
//
|
|
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
|
|
289
|
-
| ----------------- |
|
|
290
|
-
| `meshKey` | `string`
|
|
291
|
-
| `meshOptions` | `MeshServiceOptions`
|
|
292
|
-
| `registryBackend` | `MeshClientRegistryBackend`
|
|
293
|
-
| `
|
|
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
|
|
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
|
|
319
|
-
|
|
320
|
-
##
|
|
321
|
-
|
|
322
|
-
|
|
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
|
|
329
|
-
|
|
|
330
|
-
| `ClientNotFoundError`
|
|
331
|
-
| `ClientDisconnectedError`
|
|
332
|
-
| `ClientInvocationError`
|
|
333
|
-
| `
|
|
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 |
|