@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,255 +1,90 @@
|
|
|
1
1
|
# MeshService
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`MeshService` provides Redis-backed membership, leader-driven cleanup, and
|
|
4
|
+
best-effort broadcast fan-out for a group of service instances. It is not an
|
|
5
|
+
RPC transport.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Cross-service requests, responses, client forwarding, and byte streams use
|
|
8
|
+
the authenticated mesh WebSocket link exposed by `MeshSrpcServer`. Redis is
|
|
9
|
+
limited to mesh membership, the client registry, cleanup obligations, and
|
|
10
|
+
optional broadcasts. Protect those Redis key prefixes with your Redis ACL or
|
|
11
|
+
network policy.
|
|
6
12
|
|
|
7
|
-
|
|
13
|
+
## Broadcasts
|
|
8
14
|
|
|
9
|
-
|
|
10
|
-
|
|
15
|
+
Declare the messages that may be broadcast, register handlers before starting
|
|
16
|
+
the mesh, then publish when needed:
|
|
11
17
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
invalidateCache: { request: { keys: string[] }; response: { cleared: number } };
|
|
15
|
-
};
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
### Create and start a node
|
|
19
|
-
|
|
20
|
-
```typescript
|
|
21
|
-
const mesh = new MeshService<MyMessages>('my-app');
|
|
22
|
-
|
|
23
|
-
mesh.registerHandler('getStatus', async data => {
|
|
24
|
-
return { status: 'ok', uptime: process.uptime() };
|
|
25
|
-
});
|
|
26
|
-
|
|
27
|
-
mesh.registerHandler('invalidateCache', async data => {
|
|
28
|
-
const cleared = await cache.delete(data.keys);
|
|
29
|
-
return { cleared };
|
|
30
|
-
});
|
|
31
|
-
|
|
32
|
-
await mesh.start();
|
|
33
|
-
console.log(`Node started with instance ID: ${mesh.instanceId}`);
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
### Invoke a handler on another node
|
|
18
|
+
```ts
|
|
19
|
+
import { MeshService, type MeshBroadcastMap } from '@zyno-io/ts-server-foundation';
|
|
37
20
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
const result = await mesh.invoke(targetInstanceId, 'getStatus', { verbose: true });
|
|
41
|
-
console.log(result.status); // fully typed
|
|
42
|
-
|
|
43
|
-
// Calling your own instance ID routes directly to the local handler (no pub/sub)
|
|
44
|
-
const local = await mesh.invoke(mesh.instanceId, 'getStatus', { verbose: false });
|
|
45
|
-
|
|
46
|
-
// Per-request timeout (overrides the service-level default)
|
|
47
|
-
const fast = await mesh.invoke(targetInstanceId, 'getStatus', { verbose: false }, 2000);
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### List nodes in the mesh
|
|
51
|
-
|
|
52
|
-
```typescript
|
|
53
|
-
const nodes = await mesh.getNodes();
|
|
54
|
-
for (const node of nodes) {
|
|
55
|
-
console.log(`${node.instanceId} @ ${node.hostname}${node.self ? ' (self)' : ''}`);
|
|
21
|
+
interface Broadcasts extends MeshBroadcastMap {
|
|
22
|
+
cacheInvalidated: { key: string };
|
|
56
23
|
}
|
|
57
|
-
// 1 @ web-server-01
|
|
58
|
-
// 2 @ web-server-02 (self)
|
|
59
|
-
// 3 @ web-server-03
|
|
60
|
-
```
|
|
61
24
|
|
|
62
|
-
|
|
25
|
+
const mesh = new MeshService<Broadcasts>('my-app');
|
|
63
26
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
});
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
### Broadcast to all nodes
|
|
72
|
-
|
|
73
|
-
Fire-and-forget messages to every node in the mesh. Unlike `invoke`, broadcasts have no response.
|
|
74
|
-
|
|
75
|
-
```typescript
|
|
76
|
-
import { MeshService, MeshBroadcastMap } from '@zyno-io/ts-server-foundation';
|
|
77
|
-
|
|
78
|
-
type MyBroadcasts = {
|
|
79
|
-
configUpdated: { keys: string[] };
|
|
80
|
-
userLoggedOut: { userId: string };
|
|
81
|
-
};
|
|
82
|
-
|
|
83
|
-
const mesh = new MeshService<MyMessages, MyBroadcasts>('my-app');
|
|
84
|
-
|
|
85
|
-
// Register handlers for broadcast types
|
|
86
|
-
mesh.registerBroadcastHandler('configUpdated', (data, senderInstanceId) => {
|
|
87
|
-
console.log(`Config update from node ${senderInstanceId}:`, data.keys);
|
|
88
|
-
reloadConfig(data.keys);
|
|
27
|
+
mesh.registerBroadcastHandler('cacheInvalidated', async ({ key }, senderInstanceId, { signal }) => {
|
|
28
|
+
if (signal.aborted) return;
|
|
29
|
+
await invalidateLocalCache(key);
|
|
30
|
+
console.log(`received from mesh node ${senderInstanceId}`);
|
|
89
31
|
});
|
|
90
32
|
|
|
91
33
|
await mesh.start();
|
|
92
|
-
|
|
93
|
-
// Broadcast to all nodes (including self)
|
|
94
|
-
await mesh.broadcast('configUpdated', { keys: ['feature-flags'] });
|
|
95
|
-
|
|
96
|
-
// Skip self-delivery
|
|
97
|
-
await mesh.broadcast('userLoggedOut', { userId: '123' }, { skipSelf: true });
|
|
34
|
+
await mesh.broadcast('cacheInvalidated', { key: 'users:42' });
|
|
98
35
|
```
|
|
99
36
|
|
|
100
|
-
|
|
37
|
+
Broadcast data is JSON-encoded once, before local delivery and Redis publish.
|
|
38
|
+
That means local and remote receivers observe the same representation (for
|
|
39
|
+
example, `Date` becomes an ISO string and `NaN` becomes `null`). Use
|
|
40
|
+
`{ skipSelf: true }` to publish only to other instances.
|
|
101
41
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
42
|
+
`broadcast()` rejects with `MeshBroadcastIndeterminateDeliveryError` if Redis
|
|
43
|
+
publish fails after local delivery has become possible. Broadcasts are
|
|
44
|
+
best-effort; handlers must tolerate duplicates and missed messages.
|
|
105
45
|
|
|
106
|
-
##
|
|
46
|
+
## Membership and cleanup
|
|
107
47
|
|
|
108
|
-
|
|
48
|
+
`start()` assigns an instance ID, records heartbeat and metadata in Redis, and
|
|
49
|
+
subscribes to the broadcast channel. `getNodes()` and `getNode()` return only
|
|
50
|
+
instances whose heartbeat is live. Node metadata is updated atomically with
|
|
51
|
+
the liveness check through `updateNodeMetadata()`.
|
|
109
52
|
|
|
110
|
-
|
|
53
|
+
One leader drains expired membership records. Register
|
|
54
|
+
`setNodeCleanedUpCallback()` for cleanup work associated with a vanished node.
|
|
55
|
+
The callback obligation remains in Redis until it succeeds, so a later leader
|
|
56
|
+
can retry it.
|
|
111
57
|
|
|
112
|
-
|
|
113
|
-
|
|
58
|
+
Mesh membership is a lease. `assertLeaseSafe()` synchronously fences work once
|
|
59
|
+
the latest provable lease expires; `setLeaseLostCallback()` lets dependants
|
|
60
|
+
close local resources immediately when that happens.
|
|
114
61
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
| Option | Type | Default | Description |
|
|
118
|
-
| --------------------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
119
|
-
| `heartbeatIntervalMs` | `number` | `5000` | How often this node refreshes its heartbeat in the registry. |
|
|
120
|
-
| `nodeTtlMs` | `number` | `15000` | How long a node can go without a heartbeat before the leader removes it. |
|
|
121
|
-
| `requestTimeoutMs` | `number` | `10000` | Default timeout for remote invocations. Reset on each heartbeat from the handler, so long-running handlers won't time out. |
|
|
122
|
-
| `leaderOptions` | `LeaderServiceOptions` | — | Options passed to the internal `LeaderService` used for cleanup leader election. |
|
|
62
|
+
## API
|
|
123
63
|
|
|
124
|
-
###
|
|
64
|
+
### `new MeshService<B extends MeshBroadcastMap = {}>(key, options?)`
|
|
125
65
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
| `
|
|
66
|
+
| Option | Default | Meaning |
|
|
67
|
+
| ----------------------- | ---------: | ------------------------------------------------------------------- |
|
|
68
|
+
| `heartbeatIntervalMs` | `5000` | Membership renewal interval. |
|
|
69
|
+
| `nodeTtlMs` | `15000` | Membership lease duration. Must be at least the heartbeat interval. |
|
|
70
|
+
| `leaderOptions` | — | Options for the cleanup leader election. |
|
|
71
|
+
| `nodeMetadata` | `{}` | Initial metadata advertised with this node. |
|
|
72
|
+
| `maxMessageBytes` | `1048576` | Maximum JSON-encoded broadcast size. |
|
|
73
|
+
| `maxActiveHandlers` | `4096` | Maximum concurrent broadcast handlers. |
|
|
74
|
+
| `maxActiveHandlerBytes` | `67108864` | Maximum bytes retained by active broadcast handlers. |
|
|
75
|
+
| `cleanupBatchSize` | `100` | Maximum cleanup records handled in one Lua pass. |
|
|
129
76
|
|
|
130
77
|
### Methods
|
|
131
78
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
- If the handler throws, rejects with `MeshHandlerError` containing the error message.
|
|
145
|
-
|
|
146
|
-
#### `registerBroadcastHandler<K>(type: K, handler: (data: B[K], senderInstanceId: number) => void | Promise<void>): void`
|
|
147
|
-
|
|
148
|
-
Register a handler for a broadcast message type. Broadcast handlers receive the message data and the sender's instance ID. Errors thrown in handlers are logged but do not propagate.
|
|
149
|
-
|
|
150
|
-
#### `broadcast<K>(type: K, data: B[K], options?: MeshBroadcastOptions): Promise<void>`
|
|
151
|
-
|
|
152
|
-
Send a fire-and-forget message to all nodes in the mesh (including self, unless `skipSelf: true`).
|
|
153
|
-
|
|
154
|
-
| Option | Type | Default | Description |
|
|
155
|
-
| ---------- | --------- | ------- | ----------------------------------- |
|
|
156
|
-
| `skipSelf` | `boolean` | `false` | Don't deliver the broadcast to self |
|
|
157
|
-
|
|
158
|
-
#### `getNodes(): Promise<MeshNode[]>`
|
|
159
|
-
|
|
160
|
-
Returns all live nodes in the mesh. Each `MeshNode` contains:
|
|
161
|
-
|
|
162
|
-
```typescript
|
|
163
|
-
interface MeshNode {
|
|
164
|
-
instanceId: number; // The node's unique integer ID
|
|
165
|
-
hostname: string; // The OS hostname of the machine running the node
|
|
166
|
-
self: boolean; // true if this is the calling node
|
|
167
|
-
}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
The method returns the current heartbeat registry members. Gracefully stopped nodes remove themselves immediately; expired nodes can remain visible until the leader's cleanup pass removes them.
|
|
171
|
-
|
|
172
|
-
#### `setNodeCleanedUpCallback(cb: (instanceId: number) => void | Promise<void>): void`
|
|
173
|
-
|
|
174
|
-
Register a callback invoked when the leader detects and removes an expired node. Only fires on the current leader instance. Errors in the callback are logged but don't affect cleanup of other nodes.
|
|
175
|
-
|
|
176
|
-
#### `start(): Promise<void>`
|
|
177
|
-
|
|
178
|
-
Join the mesh. Acquires a unique instance ID, subscribes to its pub/sub channel and broadcast channel, registers in the heartbeat set, and starts leader election. Throws if already running.
|
|
179
|
-
|
|
180
|
-
#### `stop(): Promise<void>`
|
|
181
|
-
|
|
182
|
-
Leave the mesh. Stops heartbeats, rejects all pending outbound requests with `Error('MeshService stopped')`, unsubscribes from pub/sub, and removes itself from the heartbeat registry. Safe to call before `start()` or multiple times.
|
|
183
|
-
|
|
184
|
-
## Error Classes
|
|
185
|
-
|
|
186
|
-
### `MeshRequestTimeoutError`
|
|
187
|
-
|
|
188
|
-
The target node did not respond within the timeout period. This can happen if the target has crashed, is unreachable, or the Redis pub/sub connection is disrupted.
|
|
189
|
-
|
|
190
|
-
### `MeshHandlerError`
|
|
191
|
-
|
|
192
|
-
The target node's handler threw an error. The `message` property contains the original error message from the remote handler.
|
|
193
|
-
|
|
194
|
-
### `MeshNoHandlerError`
|
|
195
|
-
|
|
196
|
-
No handler is registered for the requested message type -- either locally (direct invocation) or on the remote node.
|
|
197
|
-
|
|
198
|
-
## Architecture
|
|
199
|
-
|
|
200
|
-
### Node Registry
|
|
201
|
-
|
|
202
|
-
Nodes are tracked in a Redis sorted set (`{prefix}:mesh:{key}:heartbeats`) where the score is the last heartbeat timestamp (from Redis server time, avoiding clock skew) and the member is the instance ID. Node metadata (hostname) is stored in a Redis hash (`{prefix}:mesh:{key}:nodes`).
|
|
203
|
-
|
|
204
|
-
Unique instance IDs are assigned via `INCR` on `{prefix}:mesh:{key}:next_id`. Both the heartbeat entry and the nodes hash entry are removed on graceful stop or leader-driven cleanup of expired nodes.
|
|
205
|
-
|
|
206
|
-
### Messaging
|
|
207
|
-
|
|
208
|
-
Each node subscribes to its own pub/sub channel: `{prefix}:mesh:{key}:node:{instanceId}`.
|
|
209
|
-
|
|
210
|
-
Three message types flow over these channels:
|
|
211
|
-
|
|
212
|
-
| Type | Direction | Purpose |
|
|
213
|
-
| ------------- | ----------------- | -------------------------------------------------------- |
|
|
214
|
-
| **Request** | Caller -> Handler | `{ requestId, senderInstanceId, type, data, timeoutMs }` |
|
|
215
|
-
| **Response** | Handler -> Caller | `{ requestId, reply: true, data?, error? }` |
|
|
216
|
-
| **Heartbeat** | Handler -> Caller | `{ requestId, heartbeat: true }` |
|
|
217
|
-
|
|
218
|
-
### Broadcast
|
|
219
|
-
|
|
220
|
-
All nodes also subscribe to a shared broadcast channel: `{prefix}:mesh:{key}:broadcast`. Broadcasts are fire-and-forget — the sender publishes once and all subscribers receive the message. No response is collected.
|
|
221
|
-
|
|
222
|
-
Channel routing: the subscriber's `message` handler inspects the channel name to distinguish broadcast messages from point-to-point messages on the instance channel.
|
|
223
|
-
|
|
224
|
-
### Request Heartbeats
|
|
225
|
-
|
|
226
|
-
While a handler is executing, the handling node sends periodic heartbeat messages back to the caller (every `requestTimeoutMs * 0.75`). The caller resets its timeout timer on each heartbeat. This allows short absolute timeouts while supporting arbitrarily long handler execution.
|
|
227
|
-
|
|
228
|
-
The handler uses the **caller's** `requestTimeoutMs` (sent in the request message) for its heartbeat interval, so mixed-timeout configurations work correctly.
|
|
229
|
-
|
|
230
|
-
### Leader Election
|
|
231
|
-
|
|
232
|
-
Each mesh uses an internal `LeaderService` (key: `mesh:{key}`) for leader election. The leader is responsible for:
|
|
233
|
-
|
|
234
|
-
1. Running the cleanup Lua script on each heartbeat cycle
|
|
235
|
-
2. Removing expired nodes from the sorted set
|
|
236
|
-
3. Invoking the `nodeCleanedUpCallback` for each removed node
|
|
237
|
-
|
|
238
|
-
Only one node (the leader) performs cleanup at any time.
|
|
239
|
-
|
|
240
|
-
### Local Invocation
|
|
241
|
-
|
|
242
|
-
When `invoke` is called with the node's own instance ID, the handler is called directly as a function call -- no serialization, no pub/sub, no timeout. Errors propagate as-is.
|
|
243
|
-
|
|
244
|
-
## Configuration
|
|
245
|
-
|
|
246
|
-
The Redis connection is configured via environment variables with the `MESH_REDIS_` prefix (falls back to `REDIS_`):
|
|
247
|
-
|
|
248
|
-
| Variable | Description |
|
|
249
|
-
| -------------------------- | ------------------------------------------------------------ |
|
|
250
|
-
| `MESH_REDIS_HOST` | Redis host |
|
|
251
|
-
| `MESH_REDIS_PORT` | Redis port |
|
|
252
|
-
| `MESH_REDIS_PREFIX` | Key prefix (falls back to `REDIS_PREFIX`, then package name) |
|
|
253
|
-
| `MESH_REDIS_SENTINEL_HOST` | Sentinel host (optional) |
|
|
254
|
-
| `MESH_REDIS_SENTINEL_PORT` | Sentinel port (optional) |
|
|
255
|
-
| `MESH_REDIS_SENTINEL_NAME` | Sentinel master name (optional) |
|
|
79
|
+
- `start()` / `stop()` — join or leave membership.
|
|
80
|
+
- `getNodes()` / `getNode(instanceId)` — read live nodes.
|
|
81
|
+
- `updateNodeMetadata(metadata)` — atomically update metadata for a live node.
|
|
82
|
+
- `registerBroadcastHandler(type, handler)` — register a local broadcast
|
|
83
|
+
receiver. The handler receives `(data, senderInstanceId, { signal })`.
|
|
84
|
+
- `broadcast(type, data, { skipSelf? })` — fan out an optional Redis broadcast.
|
|
85
|
+
- `setNodeCleanedUpCallback(callback)` — handle expired node cleanup.
|
|
86
|
+
- `setLeaseLostCallback(callback)` / `assertLeaseSafe()` — react to membership
|
|
87
|
+
fencing.
|
|
88
|
+
|
|
89
|
+
For request/response calls, create a `MeshSrpcServer` and use its mesh-link
|
|
90
|
+
transport instead of `MeshService`.
|
package/docs/content/srpc.md
CHANGED
|
@@ -158,8 +158,7 @@ import { SrpcClient, SrpcConflictError } from '@zyno-io/ts-server-foundation';
|
|
|
158
158
|
import { ClientMessage, ServerMessage } from './generated/proto/service';
|
|
159
159
|
|
|
160
160
|
const client = new SrpcClient(logger, 'wss://api.example.com/srpc', ClientMessage, ServerMessage, 'worker-1', { role: 'worker' }, 'shared-secret', {
|
|
161
|
-
enableReconnect: true
|
|
162
|
-
protocolVersion: 2
|
|
161
|
+
enableReconnect: true
|
|
163
162
|
});
|
|
164
163
|
|
|
165
164
|
client.registerConnectionHandler(() => {
|
|
@@ -191,18 +190,16 @@ Client options:
|
|
|
191
190
|
| Option | Default | Description |
|
|
192
191
|
| ----------------- | ------- | ---------------------------------------- |
|
|
193
192
|
| `enableReconnect` | `true` | Reconnects after unexpected disconnects. |
|
|
194
|
-
| `protocolVersion` | `2` | Protocol version sent during handshake. |
|
|
195
193
|
|
|
196
194
|
The exported `SrpcClientOptions` type describes this object. `connect({ supersede?: boolean })` controls only that connection attempt and is separate from the constructor options.
|
|
197
195
|
|
|
198
|
-
|
|
199
|
-
Protocol version 1 retains the legacy behavior: a new connection replaces the existing connection with the same client ID even without the supersede flag. Prefer version 2 when duplicate ownership must be explicit.
|
|
196
|
+
Duplicate `clientId` connections are rejected unless `connect({ supersede: true })` is used.
|
|
200
197
|
|
|
201
198
|
After the initial ping handshake, the client sends a ping every 55 seconds. A connection with no pong for 75 seconds closes with the `timeout` cause. The server checks the same 75-second inactivity window every 15 seconds. Unexpected client disconnects reconnect after one second when `enableReconnect` is true; `disconnect()`, conflicts, and an explicit `enableReconnect: false` suppress reconnection. `triggerConnectionCheck()` forces an immediate ping-based liveness check.
|
|
202
199
|
|
|
203
200
|
## Authentication
|
|
204
201
|
|
|
205
|
-
Clients sign connection metadata with HMAC-SHA256.
|
|
202
|
+
Clients sign connection metadata with HMAC-SHA256. Raw clients must send `authv=2`, `_v=2`, `appv`, `ts`, `nonce`, `aud`, `id`, `cid`, `signature`, optional `_supersede`, and custom metadata under `m--<key>` WebSocket query parameters.
|
|
206
203
|
|
|
207
204
|
By default the server verifies signatures with `SRPC_AUTH_SECRET`. Provide per-client secrets with:
|
|
208
205
|
|
|
@@ -267,7 +264,16 @@ receiver.on('data', chunk => {
|
|
|
267
264
|
|
|
268
265
|
Byte stream operations are carried in the SRPC envelope `byteStreamOperation` field. Pending receiver data is bounded and expires if a receiver is never attached.
|
|
269
266
|
|
|
270
|
-
Data that arrives before `createReceiver()` is buffered for at most five
|
|
267
|
+
Data that arrives before `createReceiver()` is buffered for at most five
|
|
268
|
+
seconds. A pending receiver is limited to 2 MiB, all pending receivers on one
|
|
269
|
+
parent stream share a 2 MiB total limit, and at most 1,024 pending receiver IDs
|
|
270
|
+
are retained. Exceeding a byte limit turns that pending receiver into an error.
|
|
271
|
+
An operation for a 1,025th unknown ID is a deterministic resource/protocol
|
|
272
|
+
failure that fences the parent SRPC transport; write, finish, and destroy are
|
|
273
|
+
never silently dropped. A remote `destroy` is retained independently from its
|
|
274
|
+
optional reason, so `destroy(undefined)` remains a clean terminal operation
|
|
275
|
+
when the receiver later attaches and is not echoed back to the peer. These are
|
|
276
|
+
protocol safety limits, not configurable application buffering.
|
|
271
277
|
|
|
272
278
|
## Observers
|
|
273
279
|
|
|
@@ -283,9 +289,26 @@ Observers receive connection entries with `{ type, stream, at }`, disconnection
|
|
|
283
289
|
|
|
284
290
|
## Errors And Timeouts
|
|
285
291
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
292
|
+
Throw `new SrpcError(message, true)` from either a server handler or a
|
|
293
|
+
client-side handler to mark an expected user-facing failure. The reply envelope
|
|
294
|
+
preserves the message and `userError` flag in both directions, and the invoking
|
|
295
|
+
peer rejects with an `SrpcError` whose `isUserError` value is retained. Other
|
|
296
|
+
thrown values are serialized as ordinary remote errors and do not acquire the
|
|
297
|
+
user-error flag.
|
|
298
|
+
|
|
299
|
+
`invoke()` defaults to a 30-second timeout on both client and server; a
|
|
300
|
+
per-call timeout overrides it. Both peers close with `badArg` for unknown or
|
|
301
|
+
missing request IDs, decode failures, invalid protocol frames, and outgoing
|
|
302
|
+
WebSocket backpressure. Before initiating that close, the peer synchronously
|
|
303
|
+
revokes the affected stream generation: buffered frames can no longer dispatch,
|
|
304
|
+
delayed handlers and byte-stream writes cannot respond, request and pressure
|
|
305
|
+
accounting is cleared, `stream.connected` becomes false, new byte streams are
|
|
306
|
+
rejected, and close-event cleanup is idempotent. The server applies
|
|
307
|
+
`maxMessageBytes` to outbound synchronous responses, asynchronous responses,
|
|
308
|
+
and byte-stream frames as well as inbound frames. A definitive WebSocket send
|
|
309
|
+
throw or callback error also revokes before closing. Normal graceful
|
|
310
|
+
disconnects retain their ordinary close-event semantics and carry the supplied
|
|
311
|
+
bounded close reason.
|
|
289
312
|
|
|
290
313
|
## Telemetry Boundary
|
|
291
314
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zyno-io/ts-server-foundation",
|
|
3
|
-
"version": "26.
|
|
3
|
+
"version": "26.731.113",
|
|
4
4
|
"description": "TypeScript server foundation with reflected type metadata",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
|
@@ -83,18 +83,18 @@
|
|
|
83
83
|
"@opentelemetry/sdk-trace-base": "^2.10.0",
|
|
84
84
|
"@opentelemetry/sdk-trace-node": "^2.10.0",
|
|
85
85
|
"@sentry/node": "^10.68.0",
|
|
86
|
-
"@ttsc/graph": "^0.
|
|
86
|
+
"@ttsc/graph": "^0.23.0",
|
|
87
87
|
"@types/ws": "^8.18.1",
|
|
88
88
|
"@zyno-io/config": "^1.14.0",
|
|
89
89
|
"bcrypt": "^6.0.0",
|
|
90
90
|
"bullmq": "^5.81.2",
|
|
91
91
|
"busboy": "^1.6.0",
|
|
92
92
|
"debug": "^4.4.3",
|
|
93
|
-
"fast-jwt": "^6.
|
|
93
|
+
"fast-jwt": "^6.3.0",
|
|
94
94
|
"file-type": "^22.0.1",
|
|
95
95
|
"google-libphonenumber": "^3.2.44",
|
|
96
96
|
"ioredis": "^5.11.1",
|
|
97
|
-
"mysql2": "^3.23.
|
|
97
|
+
"mysql2": "^3.23.2",
|
|
98
98
|
"nodemailer": "^9.0.3",
|
|
99
99
|
"pg": "^8.22.0",
|
|
100
100
|
"pino": "^10.3.1",
|
|
@@ -114,14 +114,14 @@
|
|
|
114
114
|
"@types/busboy": "^1.5.4",
|
|
115
115
|
"@types/debug": "^4.1.13",
|
|
116
116
|
"@types/google-libphonenumber": "^7.4.30",
|
|
117
|
-
"@types/node": "^26.1.
|
|
117
|
+
"@types/node": "^26.1.2",
|
|
118
118
|
"@types/nodemailer": "^8.0.1",
|
|
119
119
|
"@types/pg": "^8.20.0",
|
|
120
120
|
"@vitejs/plugin-vue": "^6.0.8",
|
|
121
121
|
"dotenv-cli": "^11.0.0",
|
|
122
122
|
"lefthook": "^2.1.10",
|
|
123
|
-
"oxlint": "^1.
|
|
124
|
-
"ttsc": "^0.
|
|
123
|
+
"oxlint": "^1.76.0",
|
|
124
|
+
"ttsc": "^0.23.0",
|
|
125
125
|
"typescript": "^7.0.2",
|
|
126
126
|
"vite": "^8.1.5",
|
|
127
127
|
"vite-plugin-oxlint": "^2.1.2",
|