@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,255 +1,90 @@
1
1
  # MeshService
2
2
 
3
- Typed RPC between distributed application instances. Each node gets a unique integer ID and can invoke handlers on any other node (or itself) with full type safety. Uses Redis pub/sub for messaging and sorted sets for node tracking.
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
- ## Usage
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
- ### Define a message map
13
+ ## Broadcasts
8
14
 
9
- ```typescript
10
- import { MeshService, MeshMessageMap } from '@zyno-io/ts-server-foundation';
15
+ Declare the messages that may be broadcast, register handlers before starting
16
+ the mesh, then publish when needed:
11
17
 
12
- type MyMessages = {
13
- getStatus: { request: { verbose: boolean }; response: { status: string; uptime: number } };
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
- ```typescript
39
- // Call a specific node by its instance ID
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
- ### Track node departures
25
+ const mesh = new MeshService<Broadcasts>('my-app');
63
26
 
64
- ```typescript
65
- mesh.setNodeCleanedUpCallback(async instanceId => {
66
- console.log(`Node ${instanceId} left the mesh`);
67
- // Clean up resources associated with that node
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
- ### Graceful shutdown
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
- ```typescript
103
- await mesh.stop();
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
- ## API
46
+ ## Membership and cleanup
107
47
 
108
- ### `new MeshService<T extends MeshMessageMap, B extends MeshBroadcastMap>(key: string, options?: MeshServiceOptions)`
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
- Creates a new mesh node.
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
- - **`key`** -- Logical mesh name. All nodes using the same key form one mesh. Different keys are fully independent.
113
- - **`options`** -- Optional tuning parameters (see below).
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
- ### `MeshServiceOptions`
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
- ### Properties
64
+ ### `new MeshService<B extends MeshBroadcastMap = {}>(key, options?)`
125
65
 
126
- | Property | Type | Description |
127
- | ------------ | -------- | ----------------------------------------------------------------------- |
128
- | `instanceId` | `number` | Unique integer ID assigned to this node on `start()`. `0` before start. |
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
- #### `registerHandler<K>(type: K, handler: (data: T[K]['request']) => T[K]['response'] | Promise<T[K]['response']>): void`
133
-
134
- Register a handler for a message type. Handlers can be registered before or after `start()`. Registering a handler for a type that already has one replaces it.
135
-
136
- #### `invoke<K>(instanceId: number, type: K, data: T[K]['request'], timeoutMs?: number): Promise<T[K]['response']>`
137
-
138
- Send a typed request to a specific node and wait for the response.
139
-
140
- - **`timeoutMs`** -- Optional per-request timeout. Falls back to the service-level `requestTimeoutMs` if not provided. The handler-side heartbeat interval automatically adjusts to the caller's timeout.
141
- - If `instanceId` matches the local node, the handler is called directly (no pub/sub, no timeout).
142
- - If the target node doesn't exist or doesn't respond, the promise rejects with `MeshRequestTimeoutError`.
143
- - If the target has no handler for the type, rejects with `MeshNoHandlerError`.
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`.
@@ -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
- With protocol version 2, duplicate `clientId` connections are rejected unless `connect({ supersede: true })` is used.
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. The client sends `authv`, `appv`, `ts`, `id`, `cid`, `signature`, `_v`, optional `_supersede`, and custom metadata under `m--<key>` WebSocket query parameters.
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 seconds. A pending receiver is limited to 2 MiB, all pending receivers on one parent stream share a 2 MiB total limit, and at most 1,024 pending receiver IDs are retained. Exceeding a byte limit turns that pending receiver into an error; exceeding the count limit drops data for additional unknown IDs. These are protocol safety limits, not configurable application buffering.
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
- On the server, `SrpcError(message, true)` sets `userError` on the reply envelope. The current client rejects that reply as a plain `Error`, so callers can observe the message but not the user-error flag or `SrpcError` class. Errors thrown by client-side handlers are likewise sent without `userError`. Other thrown values are serialized as ordinary remote errors.
287
-
288
- `invoke()` defaults to a 30-second timeout on both client and server; a per-call timeout overrides it. The server closes with `badArg` for unknown or missing request IDs and decode failures. After the initial handshake, the client also closes for unknown or missing request IDs, while an undecodable server payload is logged and ignored.
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.729.1927",
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.22.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.2.4",
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.1",
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.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.75.0",
124
- "ttsc": "^0.22.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",