@provino/rpc 0.0.0-stage → 0.1.0-rc.0
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/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/index.d.ts +109 -0
- package/dist/index.js +361 -0
- package/package.json +34 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pixel Perfect Software
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @provino/rpc
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A typed RPC between the coordinator and its workers: clone-safe method schemas over `MessagePort` and child-process IPC links.
|
|
4
|
+
|
|
5
|
+
This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner that is pre-alpha and not on npm yet. The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
|
|
6
|
+
|
|
7
|
+
**Versioning:** this package is `@beta` as a whole. There is no semver promise for it before 1.0, and its API can change in any release.
|
|
8
|
+
|
|
9
|
+
[MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
import { MessageLink, RpcCall, RpcClient, RpcReply, RpcSchema, SerializedError } from "@provino/types";
|
|
2
|
+
import { ChildProcess } from "node:child_process";
|
|
3
|
+
import { MessagePort, Worker } from "node:worker_threads";
|
|
4
|
+
/**
|
|
5
|
+
* Error codes `@provino/rpc` uses. A caller sees `RPC_CLOSED` (the link went away, `cause` is why)
|
|
6
|
+
* and `RPC_REMOTE_ERROR` (the method threw, `remote` is what); `RPC_UNKNOWN_METHOD` and
|
|
7
|
+
* `RPC_UNCLONABLE` reach the caller as the `remote` error's `code`, or as the rejection's code when
|
|
8
|
+
* the caller's own arguments can't be sent.
|
|
9
|
+
* @public
|
|
10
|
+
*/
|
|
11
|
+
type RpcErrorCode = "RPC_CLOSED" | "RPC_REMOTE_ERROR" | "RPC_UNKNOWN_METHOD" | "RPC_UNCLONABLE";
|
|
12
|
+
/**
|
|
13
|
+
* Options for an `RpcError`: `cause` as for any error, plus the remote error it reports.
|
|
14
|
+
* @public
|
|
15
|
+
*/
|
|
16
|
+
interface RpcErrorOptions extends ErrorOptions {
|
|
17
|
+
readonly remote?: SerializedError;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* An RPC failure with a stable code.
|
|
21
|
+
* @public
|
|
22
|
+
*/
|
|
23
|
+
export declare class RpcError extends Error {
|
|
24
|
+
readonly code: RpcErrorCode;
|
|
25
|
+
/** For `RPC_REMOTE_ERROR`: the error the remote method threw, as it crossed the link. */
|
|
26
|
+
readonly remote?: SerializedError;
|
|
27
|
+
constructor(code: RpcErrorCode, message: string, options?: RpcErrorOptions);
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* A link over a `MessagePort`: a thread's `parentPort`, or either end of a `MessageChannel`.
|
|
31
|
+
* Closing it closes the port, which closes the other end too.
|
|
32
|
+
* @public
|
|
33
|
+
*/
|
|
34
|
+
export declare function messagePortLink<Out, In>(port: MessagePort): MessageLink<Out, In>;
|
|
35
|
+
/**
|
|
36
|
+
* A link from a forked child to its parent, over `process.send`. The fork must use
|
|
37
|
+
* `serialization: 'advanced'` (as `forksTransport` does): JSON would turn a `Map`, a `Date` or a
|
|
38
|
+
* `bigint` into something else. Closing it disconnects the IPC
|
|
39
|
+
* channel once every message sent so far has been written (a disconnect cancels queued writes),
|
|
40
|
+
* so the child can exit once nothing else keeps it alive; `process` emits `disconnect` then.
|
|
41
|
+
* @public
|
|
42
|
+
*/
|
|
43
|
+
export declare function processLink<Out, In>(proc: NodeJS.Process): MessageLink<Out, In>;
|
|
44
|
+
/**
|
|
45
|
+
* A link from the parent to a forked child, over `child.send`; the fork must use
|
|
46
|
+
* `serialization: 'advanced'`. It closes when the IPC channel
|
|
47
|
+
* disconnects, which happens after every message the child sent has arrived; a child's `exit`
|
|
48
|
+
* can come before its last messages are read, so the link doesn't close on it. A send that
|
|
49
|
+
* fails once the channel is going away is dropped: the link's exit is what reports it.
|
|
50
|
+
* @public
|
|
51
|
+
*/
|
|
52
|
+
export declare function childProcessLink<Out, In>(child: ChildProcess): MessageLink<Out, In>;
|
|
53
|
+
/**
|
|
54
|
+
* A link from the parent to a worker thread. It closes when the thread exits; closing it doesn't
|
|
55
|
+
* stop the thread (the transport terminates it).
|
|
56
|
+
* @public
|
|
57
|
+
*/
|
|
58
|
+
export declare function workerLink<Out, In>(worker: Worker): MessageLink<Out, In>;
|
|
59
|
+
/**
|
|
60
|
+
* What `createRpc` runs over: a `Transport` on the coordinator side and a `WorkerPort` on the
|
|
61
|
+
* worker side both fit as they are. `Out` is what this side sends (its calls and its replies);
|
|
62
|
+
* other messages on the port pass by untouched.
|
|
63
|
+
* @public
|
|
64
|
+
*/
|
|
65
|
+
interface RpcPort<Out> {
|
|
66
|
+
send(message: Out): void;
|
|
67
|
+
onMessage(listener: (message: {
|
|
68
|
+
readonly t: string;
|
|
69
|
+
}) => void): () => void;
|
|
70
|
+
/** Called once when the port closes; `cause` becomes every pending call's rejection cause. */
|
|
71
|
+
onExit(listener: (cause: unknown) => void): () => void;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* The implementations of `Methods` that this side serves. A handler may return its result or a
|
|
75
|
+
* promise of it.
|
|
76
|
+
* @public
|
|
77
|
+
*/
|
|
78
|
+
type RpcHandlers<Methods> = { readonly [K in keyof Methods]: Methods[K] extends ((...args: infer A) => infer R) ? (...args: A) => Awaited<R> | Promise<Awaited<R>> : never; };
|
|
79
|
+
/**
|
|
80
|
+
* Options for `createRpc`.
|
|
81
|
+
* @public
|
|
82
|
+
*/
|
|
83
|
+
interface RpcOptions {
|
|
84
|
+
/** Serializes a handler's error for its reply. The default keeps name, message, stack, `code` and causes. */
|
|
85
|
+
readonly serializeError?: (error: unknown) => SerializedError;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Serves `handlers` (this side's `Local` methods) on `port` and returns a client for the other
|
|
89
|
+
* side's `Remote` methods. Both method sets must be clone-safe (`RpcSchema`): a method taking
|
|
90
|
+
* `() => void` doesn't compile.
|
|
91
|
+
*
|
|
92
|
+
* Arguments and results must also survive the link: a fork's advanced serialization rejects a
|
|
93
|
+
* `SharedArrayBuffer` (threads and inline accept it), and a class instance arrives as a plain
|
|
94
|
+
* object everywhere, a `Buffer` as a `Uint8Array` over threads and inline.
|
|
95
|
+
*
|
|
96
|
+
* A handler's error comes back as `RpcError('RPC_REMOTE_ERROR')` with the error on `.remote`. When
|
|
97
|
+
* the port exits, every pending call, and every call made after, rejects with
|
|
98
|
+
* `RpcError('RPC_CLOSED')` whose `cause` is the port's exit value (the `WorkerExit` on the
|
|
99
|
+
* coordinator side).
|
|
100
|
+
* @public
|
|
101
|
+
*/
|
|
102
|
+
export declare function createRpc<Local extends RpcSchema<Local>, Remote extends RpcSchema<Remote>>(port: RpcPort<RpcCall<Remote> | RpcReply<Local>>, handlers: RpcHandlers<Local>, options?: RpcOptions): RpcClient<Remote>;
|
|
103
|
+
/**
|
|
104
|
+
* Turns anything thrown into a clone-safe `SerializedError`. Never throws: a field that can't be
|
|
105
|
+
* read is left out.
|
|
106
|
+
* @public
|
|
107
|
+
*/
|
|
108
|
+
export declare function serializeError(value: unknown): SerializedError;
|
|
109
|
+
export type { RpcErrorCode, RpcErrorOptions, RpcHandlers, RpcOptions, RpcPort };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
// src/errors.ts
|
|
2
|
+
/**
|
|
3
|
+
* An RPC failure with a stable code.
|
|
4
|
+
* @public
|
|
5
|
+
*/
|
|
6
|
+
var RpcError = class extends Error {
|
|
7
|
+
code;
|
|
8
|
+
/** For `RPC_REMOTE_ERROR`: the error the remote method threw, as it crossed the link. */
|
|
9
|
+
remote;
|
|
10
|
+
constructor(code, message, options = {}) {
|
|
11
|
+
super(message, options);
|
|
12
|
+
this.name = "RpcError";
|
|
13
|
+
this.code = code;
|
|
14
|
+
if (options.remote !== void 0) this.remote = options.remote;
|
|
15
|
+
}
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
// src/links.ts
|
|
19
|
+
const CLOSED = Object.freeze({ type: "closed" });
|
|
20
|
+
/** A send that fails once the channel is going away is dropped; the link's exit reports it. */
|
|
21
|
+
const ignoreSendError = () => {};
|
|
22
|
+
function createLink(channel) {
|
|
23
|
+
const listeners = /* @__PURE__ */ new Set();
|
|
24
|
+
const exitListeners = /* @__PURE__ */ new Set();
|
|
25
|
+
/** Messages nobody has taken yet, oldest first. Short: it fills only while nobody listens. */
|
|
26
|
+
const queue = [];
|
|
27
|
+
let drainScheduled = false;
|
|
28
|
+
let closed = false;
|
|
29
|
+
/** Delivers queued messages, in order, while someone listens. */
|
|
30
|
+
const pump = () => {
|
|
31
|
+
while (queue.length > 0 && listeners.size > 0 && !closed) {
|
|
32
|
+
const message = queue.shift();
|
|
33
|
+
for (const listener of [...listeners]) listener(message);
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
const onClose = () => {
|
|
37
|
+
if (closed) return;
|
|
38
|
+
closed = true;
|
|
39
|
+
queue.length = 0;
|
|
40
|
+
listeners.clear();
|
|
41
|
+
for (const listener of exitListeners) listener(CLOSED);
|
|
42
|
+
exitListeners.clear();
|
|
43
|
+
};
|
|
44
|
+
channel.listen((message) => {
|
|
45
|
+
if (closed || typeof message !== "object" || message === null) return;
|
|
46
|
+
queue.push(message);
|
|
47
|
+
if (!drainScheduled) pump();
|
|
48
|
+
}, onClose);
|
|
49
|
+
return {
|
|
50
|
+
send(message, transfer) {
|
|
51
|
+
if (!closed) channel.post(message, transfer);
|
|
52
|
+
},
|
|
53
|
+
onMessage(listener) {
|
|
54
|
+
if (closed) return () => {};
|
|
55
|
+
listeners.add(listener);
|
|
56
|
+
if (queue.length > 0 && !drainScheduled) {
|
|
57
|
+
drainScheduled = true;
|
|
58
|
+
queueMicrotask(() => {
|
|
59
|
+
drainScheduled = false;
|
|
60
|
+
pump();
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
return () => {
|
|
64
|
+
listeners.delete(listener);
|
|
65
|
+
};
|
|
66
|
+
},
|
|
67
|
+
onExit(listener) {
|
|
68
|
+
if (closed) {
|
|
69
|
+
listener(CLOSED);
|
|
70
|
+
return () => {};
|
|
71
|
+
}
|
|
72
|
+
exitListeners.add(listener);
|
|
73
|
+
return () => {
|
|
74
|
+
exitListeners.delete(listener);
|
|
75
|
+
};
|
|
76
|
+
},
|
|
77
|
+
close() {
|
|
78
|
+
if (closed) return;
|
|
79
|
+
channel.close();
|
|
80
|
+
onClose();
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* A link over a `MessagePort`: a thread's `parentPort`, or either end of a `MessageChannel`.
|
|
86
|
+
* Closing it closes the port, which closes the other end too.
|
|
87
|
+
* @public
|
|
88
|
+
*/
|
|
89
|
+
function messagePortLink(port) {
|
|
90
|
+
return createLink({
|
|
91
|
+
post: (message, transfer) => port.postMessage(message, transfer),
|
|
92
|
+
listen(onMessage, onClose) {
|
|
93
|
+
port.on("message", onMessage);
|
|
94
|
+
port.once("close", onClose);
|
|
95
|
+
},
|
|
96
|
+
close: () => port.close()
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* A link from a forked child to its parent, over `process.send`. The fork must use
|
|
101
|
+
* `serialization: 'advanced'` (as `forksTransport` does): JSON would turn a `Map`, a `Date` or a
|
|
102
|
+
* `bigint` into something else. Closing it disconnects the IPC
|
|
103
|
+
* channel once every message sent so far has been written (a disconnect cancels queued writes),
|
|
104
|
+
* so the child can exit once nothing else keeps it alive; `process` emits `disconnect` then.
|
|
105
|
+
* @public
|
|
106
|
+
*/
|
|
107
|
+
function processLink(proc) {
|
|
108
|
+
const send = proc.send?.bind(proc);
|
|
109
|
+
if (send === void 0) throw new RpcError("RPC_CLOSED", "This process has no IPC channel");
|
|
110
|
+
let unwritten = 0;
|
|
111
|
+
let closing = false;
|
|
112
|
+
const disconnect = () => {
|
|
113
|
+
if (proc.connected) proc.disconnect();
|
|
114
|
+
};
|
|
115
|
+
const written = () => {
|
|
116
|
+
unwritten--;
|
|
117
|
+
if (closing && unwritten === 0) disconnect();
|
|
118
|
+
};
|
|
119
|
+
return createLink({
|
|
120
|
+
post: (message) => {
|
|
121
|
+
if (!proc.connected) return;
|
|
122
|
+
send(message, void 0, void 0, written);
|
|
123
|
+
unwritten++;
|
|
124
|
+
},
|
|
125
|
+
listen(onMessage, onClose) {
|
|
126
|
+
proc.on("message", onMessage);
|
|
127
|
+
proc.once("disconnect", onClose);
|
|
128
|
+
},
|
|
129
|
+
close: () => {
|
|
130
|
+
closing = true;
|
|
131
|
+
if (unwritten === 0) disconnect();
|
|
132
|
+
}
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* A link from the parent to a forked child, over `child.send`; the fork must use
|
|
137
|
+
* `serialization: 'advanced'`. It closes when the IPC channel
|
|
138
|
+
* disconnects, which happens after every message the child sent has arrived; a child's `exit`
|
|
139
|
+
* can come before its last messages are read, so the link doesn't close on it. A send that
|
|
140
|
+
* fails once the channel is going away is dropped: the link's exit is what reports it.
|
|
141
|
+
* @public
|
|
142
|
+
*/
|
|
143
|
+
function childProcessLink(child) {
|
|
144
|
+
return createLink({
|
|
145
|
+
post: (message) => {
|
|
146
|
+
if (child.connected) child.send(message, ignoreSendError);
|
|
147
|
+
},
|
|
148
|
+
listen(onMessage, onClose) {
|
|
149
|
+
child.on("message", onMessage);
|
|
150
|
+
child.once("disconnect", onClose);
|
|
151
|
+
},
|
|
152
|
+
close: () => {
|
|
153
|
+
if (child.connected) child.disconnect();
|
|
154
|
+
}
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* A link from the parent to a worker thread. It closes when the thread exits; closing it doesn't
|
|
159
|
+
* stop the thread (the transport terminates it).
|
|
160
|
+
* @public
|
|
161
|
+
*/
|
|
162
|
+
function workerLink(worker) {
|
|
163
|
+
return createLink({
|
|
164
|
+
post: (message, transfer) => worker.postMessage(message, transfer),
|
|
165
|
+
listen(onMessage, onClose) {
|
|
166
|
+
worker.on("message", onMessage);
|
|
167
|
+
worker.once("exit", onClose);
|
|
168
|
+
},
|
|
169
|
+
close: () => {}
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
// src/serialize.ts
|
|
174
|
+
/** How deep a `cause` chain is followed. */
|
|
175
|
+
const MAX_CAUSES = 10;
|
|
176
|
+
/**
|
|
177
|
+
* Turns anything thrown into a clone-safe `SerializedError`. Never throws: a field that can't be
|
|
178
|
+
* read is left out.
|
|
179
|
+
* @public
|
|
180
|
+
*/
|
|
181
|
+
function serializeError(value) {
|
|
182
|
+
return serialize(value, 0);
|
|
183
|
+
}
|
|
184
|
+
function serialize(value, depth) {
|
|
185
|
+
if (typeof value !== "object" || value === null) return {
|
|
186
|
+
name: "Error",
|
|
187
|
+
message: describe(value)
|
|
188
|
+
};
|
|
189
|
+
const name = read(value, "name");
|
|
190
|
+
const message = read(value, "message");
|
|
191
|
+
const stack = read(value, "stack");
|
|
192
|
+
const code = read(value, "code");
|
|
193
|
+
const cause = depth < MAX_CAUSES ? read(value, "cause") : void 0;
|
|
194
|
+
return {
|
|
195
|
+
name: typeof name === "string" ? name : "Error",
|
|
196
|
+
message: typeof message === "string" ? message : describe(message),
|
|
197
|
+
...typeof stack === "string" ? { stack } : {},
|
|
198
|
+
...typeof code === "string" ? { code } : {},
|
|
199
|
+
...cause === void 0 ? {} : { cause: serialize(cause, depth + 1) }
|
|
200
|
+
};
|
|
201
|
+
}
|
|
202
|
+
function read(value, key) {
|
|
203
|
+
try {
|
|
204
|
+
return value[key];
|
|
205
|
+
} catch {
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
function describe(value) {
|
|
210
|
+
try {
|
|
211
|
+
return String(value);
|
|
212
|
+
} catch {
|
|
213
|
+
return Object.prototype.toString.call(value);
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
// src/rpc.ts
|
|
218
|
+
/**
|
|
219
|
+
* Serves `handlers` (this side's `Local` methods) on `port` and returns a client for the other
|
|
220
|
+
* side's `Remote` methods. Both method sets must be clone-safe (`RpcSchema`): a method taking
|
|
221
|
+
* `() => void` doesn't compile.
|
|
222
|
+
*
|
|
223
|
+
* Arguments and results must also survive the link: a fork's advanced serialization rejects a
|
|
224
|
+
* `SharedArrayBuffer` (threads and inline accept it), and a class instance arrives as a plain
|
|
225
|
+
* object everywhere, a `Buffer` as a `Uint8Array` over threads and inline.
|
|
226
|
+
*
|
|
227
|
+
* A handler's error comes back as `RpcError('RPC_REMOTE_ERROR')` with the error on `.remote`. When
|
|
228
|
+
* the port exits, every pending call, and every call made after, rejects with
|
|
229
|
+
* `RpcError('RPC_CLOSED')` whose `cause` is the port's exit value (the `WorkerExit` on the
|
|
230
|
+
* coordinator side).
|
|
231
|
+
* @public
|
|
232
|
+
*/
|
|
233
|
+
function createRpc(port, handlers, options = {}) {
|
|
234
|
+
const serialize = options.serializeError ?? serializeError;
|
|
235
|
+
const pending = /* @__PURE__ */ new Map();
|
|
236
|
+
let nextId = 0;
|
|
237
|
+
let closed;
|
|
238
|
+
const send = port.send.bind(port);
|
|
239
|
+
const offMessage = port.onMessage((message) => {
|
|
240
|
+
if (message.t === "call") answer(message);
|
|
241
|
+
else if (message.t === "reply") settle(message);
|
|
242
|
+
});
|
|
243
|
+
port.onExit((cause) => {
|
|
244
|
+
if (closed !== void 0) return;
|
|
245
|
+
closed = { cause };
|
|
246
|
+
offMessage();
|
|
247
|
+
for (const call of pending.values()) call.reject(new RpcError("RPC_CLOSED", `The link closed before \`${call.method}\` was answered`, { cause }));
|
|
248
|
+
pending.clear();
|
|
249
|
+
});
|
|
250
|
+
async function answer(call) {
|
|
251
|
+
let reply;
|
|
252
|
+
try {
|
|
253
|
+
const value = await invoke(handlers, call.method, call.args);
|
|
254
|
+
reply = {
|
|
255
|
+
t: "reply",
|
|
256
|
+
id: call.id,
|
|
257
|
+
ok: true,
|
|
258
|
+
value
|
|
259
|
+
};
|
|
260
|
+
} catch (error) {
|
|
261
|
+
reply = {
|
|
262
|
+
t: "reply",
|
|
263
|
+
id: call.id,
|
|
264
|
+
ok: false,
|
|
265
|
+
error: serializeOr(error)
|
|
266
|
+
};
|
|
267
|
+
}
|
|
268
|
+
if (closed !== void 0) return;
|
|
269
|
+
try {
|
|
270
|
+
send(reply);
|
|
271
|
+
} catch (error) {
|
|
272
|
+
const what = reply.ok ? "result" : "error";
|
|
273
|
+
const message = `\`${call.method}\`'s ${what} can't cross the link: ${messageOf(error)}`;
|
|
274
|
+
try {
|
|
275
|
+
send({
|
|
276
|
+
t: "reply",
|
|
277
|
+
id: call.id,
|
|
278
|
+
ok: false,
|
|
279
|
+
error: unclonable(message)
|
|
280
|
+
});
|
|
281
|
+
} catch {}
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
/** The configured serializer, or a fixed error if it throws: a reply must always be built. */
|
|
285
|
+
function serializeOr(error) {
|
|
286
|
+
try {
|
|
287
|
+
return serialize(error);
|
|
288
|
+
} catch (failure) {
|
|
289
|
+
return unclonable(`The error couldn't be serialized: ${messageOf(failure)}`);
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
function settle(reply) {
|
|
293
|
+
const call = pending.get(reply.id);
|
|
294
|
+
if (call === void 0) return;
|
|
295
|
+
pending.delete(reply.id);
|
|
296
|
+
if (reply.ok) call.resolve(reply.value);
|
|
297
|
+
else call.reject(new RpcError("RPC_REMOTE_ERROR", reply.error.message, { remote: reply.error }));
|
|
298
|
+
}
|
|
299
|
+
function call(method, args) {
|
|
300
|
+
if (closed !== void 0) return Promise.reject(new RpcError("RPC_CLOSED", `The link is closed; \`${method}\` wasn't sent`, { cause: closed.cause }));
|
|
301
|
+
const id = nextId++;
|
|
302
|
+
return new Promise((resolve, reject) => {
|
|
303
|
+
pending.set(id, {
|
|
304
|
+
method,
|
|
305
|
+
resolve,
|
|
306
|
+
reject
|
|
307
|
+
});
|
|
308
|
+
try {
|
|
309
|
+
send({
|
|
310
|
+
t: "call",
|
|
311
|
+
id,
|
|
312
|
+
method,
|
|
313
|
+
args
|
|
314
|
+
});
|
|
315
|
+
} catch (error) {
|
|
316
|
+
pending.delete(id);
|
|
317
|
+
reject(new RpcError("RPC_UNCLONABLE", `\`${method}\`'s arguments can't cross the link: ${messageOf(error)}`, { cause: error }));
|
|
318
|
+
}
|
|
319
|
+
});
|
|
320
|
+
}
|
|
321
|
+
const methods = /* @__PURE__ */ new Map();
|
|
322
|
+
return new Proxy(Object.create(null), { get(_target, key) {
|
|
323
|
+
if (typeof key !== "string") return void 0;
|
|
324
|
+
let method = methods.get(key);
|
|
325
|
+
if (method === void 0) {
|
|
326
|
+
if (NOT_METHODS.has(key) || key in Object.prototype) return void 0;
|
|
327
|
+
method = (...args) => call(key, args);
|
|
328
|
+
methods.set(key, method);
|
|
329
|
+
}
|
|
330
|
+
return method;
|
|
331
|
+
} });
|
|
332
|
+
}
|
|
333
|
+
/** Names read by promise resolution, `JSON.stringify`, pretty-format and the like, never methods. */
|
|
334
|
+
const NOT_METHODS = /* @__PURE__ */ new Set([
|
|
335
|
+
"then",
|
|
336
|
+
"toJSON",
|
|
337
|
+
"asymmetricMatch",
|
|
338
|
+
"$$typeof",
|
|
339
|
+
"nodeType",
|
|
340
|
+
"@@__IMMUTABLE_ITERABLE__@@",
|
|
341
|
+
"@@__IMMUTABLE_RECORD__@@"
|
|
342
|
+
]);
|
|
343
|
+
/** A plain-strings error for a reply that couldn't be built or sent. */
|
|
344
|
+
function unclonable(message) {
|
|
345
|
+
return {
|
|
346
|
+
name: "RpcError",
|
|
347
|
+
message,
|
|
348
|
+
code: "RPC_UNCLONABLE"
|
|
349
|
+
};
|
|
350
|
+
}
|
|
351
|
+
/** Calls `handlers[method]`, rejecting names that aren't served (including `Object.prototype`'s). */
|
|
352
|
+
function invoke(handlers, method, args) {
|
|
353
|
+
const handler = handlers[method];
|
|
354
|
+
if (typeof handler !== "function" || handler === Object.prototype[method]) throw new RpcError("RPC_UNKNOWN_METHOD", `No RPC method \`${method}\` is served here`);
|
|
355
|
+
return Reflect.apply(handler, handlers, args);
|
|
356
|
+
}
|
|
357
|
+
function messageOf(error) {
|
|
358
|
+
return error instanceof Error ? error.message : String(error);
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
export { RpcError, childProcessLink, createRpc, messagePortLink, processLink, serializeError, workerLink };
|
package/package.json
CHANGED
|
@@ -1,6 +1,37 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@provino/rpc",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0-rc.0",
|
|
4
|
+
"description": "Provino's typed RPC between the coordinator and its workers: clone-safe method schemas over MessagePort and child-process IPC links.",
|
|
5
|
+
"homepage": "https://github.com/pixel-perfect-software/provino#readme",
|
|
6
|
+
"bugs": {
|
|
7
|
+
"url": "https://github.com/pixel-perfect-software/provino/issues"
|
|
8
|
+
},
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/pixel-perfect-software/provino.git",
|
|
12
|
+
"directory": "packages/rpc"
|
|
13
|
+
},
|
|
14
|
+
"license": "MIT",
|
|
15
|
+
"type": "module",
|
|
16
|
+
"sideEffects": false,
|
|
17
|
+
"exports": {
|
|
18
|
+
".": {
|
|
19
|
+
"provino-source": "./src/index.ts",
|
|
20
|
+
"types": "./dist/index.d.ts",
|
|
21
|
+
"import": "./dist/index.js"
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"dist"
|
|
26
|
+
],
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": "^22.15.0 || >=24"
|
|
29
|
+
},
|
|
30
|
+
"dependencies": {
|
|
31
|
+
"@provino/types": "0.1.0-rc.0"
|
|
32
|
+
},
|
|
33
|
+
"scripts": {
|
|
34
|
+
"build": "tsdown --config ../../tooling/packaging/tsdown.config.ts",
|
|
35
|
+
"test": "node --test --conditions=provino-source \"src/**/*.test.ts\""
|
|
36
|
+
}
|
|
6
37
|
}
|