posipaki 0.44.0 → 0.45.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/dist/{hooks-Dpbe39oa.d.ts → hooks-DO-efRM_.d.ts} +2 -2
- package/dist/{hooks-Dpbe39oa.d.ts.map → hooks-DO-efRM_.d.ts.map} +1 -1
- package/dist/hooks.d.ts +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.js +1 -1
- package/dist/plugins/debug-logger.d.ts +2 -2
- package/dist/plugins/tree-introspection.d.ts +2 -2
- package/dist/{process-CoEKoY5f.d.ts → process-eCAv2tIS.d.ts} +2 -2
- package/dist/{process-CoEKoY5f.d.ts.map → process-eCAv2tIS.d.ts.map} +1 -1
- package/dist/remote/gateway-cli.js +1157 -50
- package/dist/remote/gateway-cli.js.map +1 -1
- package/dist/remote/index.d.ts +4 -232
- package/dist/remote/index.d.ts.map +1 -1
- package/dist/remote/index.js +2 -2
- package/dist/remote/index.js.map +1 -1
- package/dist/remote/node.d.ts +29 -54
- package/dist/remote/node.d.ts.map +1 -1
- package/dist/remote/node.js +128 -128
- package/dist/remote/node.js.map +1 -1
- package/dist/testing/index.d.ts +4 -4
- package/dist/testing/index.d.ts.map +1 -1
- package/dist/testing/index.js.map +1 -1
- package/dist/{types-CuabnerI.d.ts → types-U3NvKgpg.d.ts} +10 -1
- package/dist/{types-CuabnerI.d.ts.map → types-U3NvKgpg.d.ts.map} +1 -1
- package/dist/{version-B6eNJRZD.js → version-yonmO5bG.js} +2 -2
- package/dist/{version-B6eNJRZD.js.map → version-yonmO5bG.js.map} +1 -1
- package/dist/websocket-DT8zKD34.d.ts +836 -0
- package/dist/websocket-DT8zKD34.d.ts.map +1 -0
- package/dist/{websocket-DecgMfb3.js → websocket-DkDAHMFm.js} +1102 -85
- package/dist/websocket-DkDAHMFm.js.map +1 -0
- package/dist/xfetch.d.ts +2 -2
- package/package.json +1 -1
- package/dist/websocket-DecgMfb3.js.map +0 -1
- package/dist/websocket-sGQcEDbm.d.ts +0 -310
- package/dist/websocket-sGQcEDbm.d.ts.map +0 -1
|
@@ -0,0 +1,836 @@
|
|
|
1
|
+
import { a as Message, i as FrameChannel } from "./types-U3NvKgpg.js";
|
|
2
|
+
import { b as SpawnedFrom, h as MethodOptions, l as ActorDefinition, p as HandlerOptions, v as ReflectionOptions } from "./hooks-DO-efRM_.js";
|
|
3
|
+
//#region src/remote/remote-process.d.ts
|
|
4
|
+
interface RemoteExit {
|
|
5
|
+
code: number;
|
|
6
|
+
state: unknown;
|
|
7
|
+
}
|
|
8
|
+
/** How a handle gets a frame onto the connection it belongs to, addressed to a
|
|
9
|
+
* process the far side holds. The answer is handed back when a caller has to know
|
|
10
|
+
* the frame is out — the root's end is said that way, just before the wire closes. */
|
|
11
|
+
type FrameSink = (frame: Record<string, unknown>, to: number) => void | Promise<void>;
|
|
12
|
+
/** What a side does when it lets go of a handle: stop knowing the id, so nothing
|
|
13
|
+
* arriving for it can land here again. */
|
|
14
|
+
type ReleaseHook = (id: number) => void;
|
|
15
|
+
/** An out-message of the far process, and the name it came with. */
|
|
16
|
+
type RemoteMessage<OutMsg extends Message = Message> = (msg: OutMsg, fromName: string) => void;
|
|
17
|
+
declare class RemoteProcess<InMsg extends Message = Message, OutMsg extends Message = Message> {
|
|
18
|
+
/** The name the far side knows it by. */
|
|
19
|
+
readonly pname: string;
|
|
20
|
+
/** The id this connection knows it by — the far side's own, since it is the
|
|
21
|
+
* side that holds the process. */
|
|
22
|
+
readonly ref: ProcessRef;
|
|
23
|
+
/** A symbol of this side's own, so a handle can be told apart from any other
|
|
24
|
+
* the way a process is: by holding one. */
|
|
25
|
+
readonly id: symbol;
|
|
26
|
+
/** What the far side has said about its state so far. */
|
|
27
|
+
state: Record<string, unknown> | null;
|
|
28
|
+
/** The methods the far side announced it can answer. */
|
|
29
|
+
readonly $reflection: Record<string, (...args: unknown[]) => Promise<unknown>>;
|
|
30
|
+
private pvtSend;
|
|
31
|
+
private pvtFromName;
|
|
32
|
+
private pvtConnected;
|
|
33
|
+
/** This side let it go: nothing more is asked of it, and nothing arriving for it
|
|
34
|
+
* is news any more. Not the same as ending, and not the same as the connection
|
|
35
|
+
* going: in all three the handle is dead, and only the reason differs. */
|
|
36
|
+
private pvtReleased;
|
|
37
|
+
private pvtLetGo;
|
|
38
|
+
/** What the far side said when it ended, or null while it is running. */
|
|
39
|
+
private pvtExit;
|
|
40
|
+
private pvtExitWaiter;
|
|
41
|
+
private pvtMessageSubs;
|
|
42
|
+
private pvtStateSubs;
|
|
43
|
+
/** Whoever is waiting to hear what it holds, settled by the first word of it. */
|
|
44
|
+
private pvtReadyWaiters;
|
|
45
|
+
/** How many times this reference has been kept. Nothing is heard about a process
|
|
46
|
+
* nothing here keeps, so the count is what makes a handle usable rather than a name. */
|
|
47
|
+
private pvtRefCount;
|
|
48
|
+
/** The handles this one keeps because they sit in what it holds. Counted, and given
|
|
49
|
+
* back when this one is let go of: the thing holding them is here. */
|
|
50
|
+
private pvtOwnedRefs;
|
|
51
|
+
/** The handles that arrived here on their way somewhere else, in a message or an answer.
|
|
52
|
+
* Not counted — nobody here asked for them, and whoever receives them is the one to deal
|
|
53
|
+
* with them — but remembered, so that one nobody ever keeps is let go of after all. */
|
|
54
|
+
private pvtTransientRefs;
|
|
55
|
+
/** What this side has asked to be told about it. A process that crosses is
|
|
56
|
+
* silent, so a handle starts out having asked for nothing and hears nothing
|
|
57
|
+
* until something here wants it — which is the same rule the far side holds,
|
|
58
|
+
* written from the other end. */
|
|
59
|
+
private pvtWanted;
|
|
60
|
+
constructor(ref: ProcessRef, send: FrameSink, fromName: string, letGo?: ReleaseHook);
|
|
61
|
+
/**
|
|
62
|
+
* Whether the process this handle names can still be reached: the wire is there, and
|
|
63
|
+
* this side has not let the handle go.
|
|
64
|
+
*
|
|
65
|
+
* Reaching it is not the same as it being alive. A process that has ended is still
|
|
66
|
+
* one this side has a handle on — it is what the handle points at, and what it left
|
|
67
|
+
* behind is here — so an end does not put it out of reach; `hasEnded()` is that
|
|
68
|
+
* answer, and the two are asked separately. From the two ways out there is no coming
|
|
69
|
+
* back: no reconnect, and no way to un-release.
|
|
70
|
+
*/
|
|
71
|
+
isConnected(): boolean;
|
|
72
|
+
/**
|
|
73
|
+
* The connection is gone. Every handle this side holds goes out of reach with it,
|
|
74
|
+
* and says so: there is no reconnect to wait for, so a send fails here and now
|
|
75
|
+
* rather than disappearing into nothing.
|
|
76
|
+
*/
|
|
77
|
+
disconnect(): void;
|
|
78
|
+
/** Whether the process it names has ended, as far as this side has been told. */
|
|
79
|
+
hasEnded(): boolean;
|
|
80
|
+
/** Why nothing can be asked *of the process* — let go, ended, or out of reach — or
|
|
81
|
+
* nothing when something can. Those are not one thing said three ways: an ended
|
|
82
|
+
* process is still reached, it simply has nothing left to receive. */
|
|
83
|
+
private pvtWhyNotAskable;
|
|
84
|
+
private pvtRequireAskable;
|
|
85
|
+
/**
|
|
86
|
+
* Keep this reference: from here it is counted, which is what lets anything be asked of
|
|
87
|
+
* it. It returns the handle, so what is kept is written in one line —
|
|
88
|
+
* `this.pvtRemoteRefsHeld.push(ref.holdRef())` — and a table of them reads as what it is.
|
|
89
|
+
*/
|
|
90
|
+
holdRef(): this;
|
|
91
|
+
/**
|
|
92
|
+
* Give the count back. Whoever gives the last one back lets the reference go, which is
|
|
93
|
+
* what tells the far side that nothing here wants to hear about the process again. A
|
|
94
|
+
* reference nobody ever kept is let go of by this too, which is how whoever receives one
|
|
95
|
+
* they do not want is rid of it.
|
|
96
|
+
*/
|
|
97
|
+
releaseRef(): void;
|
|
98
|
+
/** Let go of the binding here without asking the far side for anything: what the process
|
|
99
|
+
* was is over, or the wire that carried it is. */
|
|
100
|
+
private pvtDropBinding;
|
|
101
|
+
/** How many times this reference has been kept. */
|
|
102
|
+
refCount(): number;
|
|
103
|
+
/**
|
|
104
|
+
* What this is, in JSON: the same reference the wire would carry, or the unstable thing
|
|
105
|
+
* it is when nothing keeps it. Written so that an unheld reference cannot be mistaken
|
|
106
|
+
* for a process that merely looks odd in a state, and so that one that is kept reads as
|
|
107
|
+
* the reference it is rather than as whatever fields it happens to have.
|
|
108
|
+
*/
|
|
109
|
+
toJSON(): unknown;
|
|
110
|
+
/**
|
|
111
|
+
* Remember the references inside a value that arrived here to be passed on. They are not
|
|
112
|
+
* counted — the receiver is the one to deal with them — and this is what keeps one from
|
|
113
|
+
* being nobody's for ever: when this handle is let go of, they are dropped with it.
|
|
114
|
+
*/
|
|
115
|
+
markTransient(value: unknown): void;
|
|
116
|
+
/** Stop treating a reference as one that was only passing through. */
|
|
117
|
+
private pvtDropTransient;
|
|
118
|
+
/**
|
|
119
|
+
* Keep the references sitting in what this process holds. What it holds is here, so the
|
|
120
|
+
* thing keeping those references alive is this handle, and it holds them until it is let
|
|
121
|
+
* go of itself.
|
|
122
|
+
*/
|
|
123
|
+
private pvtHoldOwned;
|
|
124
|
+
/** Nothing is heard about a process nothing here keeps. A subscription, a tuning and a
|
|
125
|
+
* wait for the state are all ways of hearing, so they are where a reference has to have
|
|
126
|
+
* been kept first — and where the mistake says what to do about it. */
|
|
127
|
+
private pvtRequireHeld;
|
|
128
|
+
/**
|
|
129
|
+
* Wait until what it holds is here.
|
|
130
|
+
*
|
|
131
|
+
* A handle starts out knowing nothing about the process: the far side says what a
|
|
132
|
+
* process holds when something over here asks to hear it, so the asking and the waiting
|
|
133
|
+
* are one act, and this is both. It settles with whatever has arrived when nothing more
|
|
134
|
+
* can: a process that has ended has said its last, and a connection that has gone has
|
|
135
|
+
* nothing left to say. Asking twice is asking about what is already here.
|
|
136
|
+
*/
|
|
137
|
+
ready(): Promise<void>;
|
|
138
|
+
/** Everyone waiting for what it holds has heard it, or never will. */
|
|
139
|
+
private pvtSettleReady;
|
|
140
|
+
/**
|
|
141
|
+
* Wait for the process to end. Its exit crosses back like everything else it
|
|
142
|
+
* does, and what it left behind is the answer.
|
|
143
|
+
*
|
|
144
|
+
* A handle whose connection is gone rejects instead: what is left to wait for
|
|
145
|
+
* after that is nothing, and a process that keeps running is not something this
|
|
146
|
+
* side can tell from one that died with the wire.
|
|
147
|
+
*/
|
|
148
|
+
wait(): Promise<RemoteExit>;
|
|
149
|
+
/**
|
|
150
|
+
* Ask the far side to stop it. Stops the way it always does there, and this
|
|
151
|
+
* resolves when its exit has crossed back — which is all this side can know.
|
|
152
|
+
* There is no deadline, so a process that refuses to stop leaves this pending.
|
|
153
|
+
*/
|
|
154
|
+
stop(): Promise<void>;
|
|
155
|
+
/**
|
|
156
|
+
* Let it go: the far side forgets this id and stops telling this side anything
|
|
157
|
+
* about the process behind it. The process itself is untouched — it runs on, it
|
|
158
|
+
* is simply nobody's here any more — and this handle is done: nothing reaches it,
|
|
159
|
+
* nothing is waited for, and what arrives for it later is not news.
|
|
160
|
+
*/
|
|
161
|
+
release(): void;
|
|
162
|
+
/** Stop feeding it messages. It is still there: `send` still reaches it. */
|
|
163
|
+
pause(): void;
|
|
164
|
+
/** Feed it messages again. */
|
|
165
|
+
resume(): void;
|
|
166
|
+
/**
|
|
167
|
+
* What to be told about it from now on: any of `message`, `state` and `exit`,
|
|
168
|
+
* or `"silent"` for none of it.
|
|
169
|
+
*
|
|
170
|
+
* A process that crossed is silent to begin with, so this is how a handle asks
|
|
171
|
+
* to hear anything at all — and what is heard is only ever what was asked for.
|
|
172
|
+
* An exit nobody asked for is not sent: silence is silence, which makes this the
|
|
173
|
+
* one way to leave a handle that will not answer a `wait()`, and the far side's
|
|
174
|
+
* books the one place an end can go unrecorded.
|
|
175
|
+
*/
|
|
176
|
+
tune(kinds: StreamKind[] | "silent"): void;
|
|
177
|
+
/** Ask the far side to say exactly this much, and nothing when it is already
|
|
178
|
+
* saying it. The list goes in the order the three are named in, so asking for
|
|
179
|
+
* the same thing twice sends the same frame twice. */
|
|
180
|
+
private pvtTune;
|
|
181
|
+
/** Ask for one more category, because something here now wants it. A handle
|
|
182
|
+
* that is gone asks nothing: there is no far side left to hear it, and nothing
|
|
183
|
+
* was asked for, so what was wanted stays what it was. */
|
|
184
|
+
private pvtWant;
|
|
185
|
+
/** Hand the far process a message. */
|
|
186
|
+
send(msg: InMsg): void;
|
|
187
|
+
/** Subscribe to what it says, or to what it holds. Asking here is asking the far
|
|
188
|
+
* side: a subscription is the first thing that wants the category, so it is what
|
|
189
|
+
* turns it on, and unsubscribing leaves it on — the far side is not told to stop
|
|
190
|
+
* saying something that another subscriber may still want. */
|
|
191
|
+
subscribe(channel: "message", cb: RemoteMessage<OutMsg>): () => void;
|
|
192
|
+
subscribe(channel: "state", cb: () => void): () => void;
|
|
193
|
+
private pvtUnsubscribe;
|
|
194
|
+
/** Its state, as the far side just published it. */
|
|
195
|
+
receiveState(state: Record<string, unknown>): void;
|
|
196
|
+
/** A message it emitted. */
|
|
197
|
+
receiveMessage(msg: OutMsg, fromName: string): void;
|
|
198
|
+
/** It has ended, and this is what it left behind. The last thing said about a
|
|
199
|
+
* process: nothing crosses about it after its exit, though the handle still
|
|
200
|
+
* reaches it for what it left. */
|
|
201
|
+
receiveExit(exit: RemoteExit): void;
|
|
202
|
+
/** The methods it can answer, as functions that ask it for an answer. `call`
|
|
203
|
+
* is the connection's own: a handle knows what to ask for, not how a call is
|
|
204
|
+
* made or paired with its answer. */
|
|
205
|
+
receiveMethods(names: string[], call: (name: string, args: unknown[]) => Promise<unknown>): void;
|
|
206
|
+
}
|
|
207
|
+
//#endregion
|
|
208
|
+
//#region src/remote/process-ref.d.ts
|
|
209
|
+
/** The key that marks a process reference inside an otherwise JSON value. */
|
|
210
|
+
declare const PROCESS_REF = "$p";
|
|
211
|
+
/**
|
|
212
|
+
* The id a side gives its own root: the first id of its parity. The two ends of a
|
|
213
|
+
* connection therefore number their roots differently, and an id says whose root it is
|
|
214
|
+
* as it says who holds every other process. A side hands out its next id from two
|
|
215
|
+
* steps further on, the one in between belonging to the root of the side it talks to.
|
|
216
|
+
*/
|
|
217
|
+
declare function rootIdFor(parity: IdParity): number;
|
|
218
|
+
/** What crosses the wire in place of a process. */
|
|
219
|
+
interface ProcessRef {
|
|
220
|
+
id: number;
|
|
221
|
+
pname: string;
|
|
222
|
+
}
|
|
223
|
+
/** Which ids a side hands out: the client takes the odd ones, the server the
|
|
224
|
+
* even ones, so one number can never name a process on both sides at once. */
|
|
225
|
+
type IdParity = "odd" | "even";
|
|
226
|
+
/**
|
|
227
|
+
* The ids one side of a connection hands out: its own parity, from the far side of the low band.
|
|
228
|
+
*
|
|
229
|
+
* Everything numbered on the connection draws from one space — a process reference and a stream alike —
|
|
230
|
+
* so a number names one thing, and the parity says which side made it. Each side builds its own and
|
|
231
|
+
* hands the same one to whatever allocates.
|
|
232
|
+
*/
|
|
233
|
+
declare class IdSpace {
|
|
234
|
+
readonly parity: IdParity;
|
|
235
|
+
private pvtNext;
|
|
236
|
+
/** True for a space inside the low band, which refuses to leave it. */
|
|
237
|
+
private readonly pvtBand;
|
|
238
|
+
constructor(parity: IdParity, first?: number);
|
|
239
|
+
/** This side's own end of the connection: the first id of its parity, never handed out. */
|
|
240
|
+
root(): number;
|
|
241
|
+
/** The next id of this side's parity, and never the same one twice. */
|
|
242
|
+
next(): number;
|
|
243
|
+
}
|
|
244
|
+
/** Whether `value` has the shape of a handle on a far-side process. Judged by
|
|
245
|
+
* what it holds rather than by `instanceof`, for the reason a process is: one
|
|
246
|
+
* build can hold two copies of the class. */
|
|
247
|
+
declare function isRemoteProcess(value: unknown): value is RemoteProcess;
|
|
248
|
+
//#endregion
|
|
249
|
+
//#region src/remote/channel.d.ts
|
|
250
|
+
interface StringTransport {
|
|
251
|
+
send(frame: string): void | Promise<void>;
|
|
252
|
+
/**
|
|
253
|
+
* A line arrived. Answer with the number of raw octets that follow it, if any: a frame
|
|
254
|
+
* may announce a run of bytes (a chunk of a stream), and the transport then hands those
|
|
255
|
+
* octets over instead of reading them as more lines.
|
|
256
|
+
*/
|
|
257
|
+
onMessage(handler: (frame: string) => number | void): void;
|
|
258
|
+
/** The octets a line announced, whole, in the order they were sent. */
|
|
259
|
+
onBytes(handler: (bytes: Uint8Array) => void): void;
|
|
260
|
+
removeHandler(): void;
|
|
261
|
+
/** Raw octets, written after whatever went before them. */
|
|
262
|
+
sendBytes(bytes: Uint8Array): void | Promise<void>;
|
|
263
|
+
/** Fires when the peer disconnects (transport closes from the other side). */
|
|
264
|
+
onClose(handler: () => void): void;
|
|
265
|
+
close(): Promise<void>;
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* What the frame layer needs of a connection's values: two walks, and no knowledge of how the
|
|
269
|
+
* bytes travel. The frame vocabulary lives in this file and the machinery in
|
|
270
|
+
* `stream.ts`, so a store comes in as this shape rather than as an import from here.
|
|
271
|
+
*/
|
|
272
|
+
interface ValueCodec {
|
|
273
|
+
/** Replace every value that must cross by reference with one this connection serves. */
|
|
274
|
+
encode(value: unknown): unknown;
|
|
275
|
+
/** Replace every reference in a value with something the reader can hold. */
|
|
276
|
+
decode(value: unknown): unknown;
|
|
277
|
+
}
|
|
278
|
+
/** The frames of one connection, as the remote layer speaks them: the process's own `FrameChannel`,
|
|
279
|
+
* where a reader has the unsubscribe `onMessage` returned rather than a handler to take back. */
|
|
280
|
+
type Channel = FrameChannel;
|
|
281
|
+
type ProtoFrame = {
|
|
282
|
+
$proto: string;
|
|
283
|
+
};
|
|
284
|
+
type InitFrame = {
|
|
285
|
+
$init: Record<string, unknown>;
|
|
286
|
+
};
|
|
287
|
+
type StateFrame = {
|
|
288
|
+
$state: Record<string, unknown>;
|
|
289
|
+
};
|
|
290
|
+
type MsgFrame = {
|
|
291
|
+
$msg: {
|
|
292
|
+
fromName: string;
|
|
293
|
+
body: Message;
|
|
294
|
+
};
|
|
295
|
+
};
|
|
296
|
+
type ExitFrame = {
|
|
297
|
+
$exit: {
|
|
298
|
+
code: number;
|
|
299
|
+
state: unknown;
|
|
300
|
+
};
|
|
301
|
+
};
|
|
302
|
+
declare function isProto(msg: Record<string, unknown>): msg is ProtoFrame;
|
|
303
|
+
declare function isInit(msg: Record<string, unknown>): msg is InitFrame;
|
|
304
|
+
declare function isState(msg: Record<string, unknown>): msg is StateFrame;
|
|
305
|
+
declare function isMsg(msg: Record<string, unknown>): msg is MsgFrame;
|
|
306
|
+
declare function isExit(msg: Record<string, unknown>): msg is ExitFrame;
|
|
307
|
+
/** How much of an unreadable line is carried: enough to see what it was, never enough to be it.
|
|
308
|
+
* A line that failed to parse is the one line nobody vouched for, so quoting it whole would move
|
|
309
|
+
* whatever it holds — a credential in a paste accident is how that happens — into every log,
|
|
310
|
+
* transcript and context window that later reads the frame. Why, how long, and a short head of
|
|
311
|
+
* it. (`reason` carries a little of the line on its own: a JSON parser says where it gave up and
|
|
312
|
+
* quotes what it was looking at. That is the parser's business, not a promise this file makes.) */
|
|
313
|
+
declare const BAD_PREFIX_LIMIT = 32;
|
|
314
|
+
type BadFrame = {
|
|
315
|
+
$bad: {
|
|
316
|
+
reason: string;
|
|
317
|
+
};
|
|
318
|
+
};
|
|
319
|
+
declare function isBad(msg: Record<string, unknown>): msg is BadFrame;
|
|
320
|
+
/** The frame that says a frame could not be read: why, how long it was, and the head of it. */
|
|
321
|
+
declare function badFrame(reason: string, raw: string): Record<string, unknown>;
|
|
322
|
+
/** Why a frame could not be read, or null when it is not a frame that says so. */
|
|
323
|
+
declare function badReason(msg: Record<string, unknown>): string | null;
|
|
324
|
+
type ErrorFrame = {
|
|
325
|
+
$error: string;
|
|
326
|
+
};
|
|
327
|
+
declare function isError(msg: Record<string, unknown>): msg is ErrorFrame;
|
|
328
|
+
/** The frame that says the wire is over: the reason, and the connection ends with it. */
|
|
329
|
+
declare function errorFrame(reason: string): Record<string, unknown>;
|
|
330
|
+
/** The reason a wire error carries, or null when it is not one. */
|
|
331
|
+
declare function errorReason(msg: Record<string, unknown>): string | null;
|
|
332
|
+
type StreamKind = "message" | "state" | "exit";
|
|
333
|
+
type StopFrame = {
|
|
334
|
+
$stop: Record<string, unknown>;
|
|
335
|
+
};
|
|
336
|
+
type PauseFrame = {
|
|
337
|
+
$pause: Record<string, unknown>;
|
|
338
|
+
};
|
|
339
|
+
type ResumeFrame = {
|
|
340
|
+
$resume: Record<string, unknown>;
|
|
341
|
+
};
|
|
342
|
+
type ReleaseFrame = {
|
|
343
|
+
$release: Record<string, unknown>;
|
|
344
|
+
};
|
|
345
|
+
type TuneFrame = {
|
|
346
|
+
$tune: Record<string, unknown>;
|
|
347
|
+
};
|
|
348
|
+
declare function isStop(msg: Record<string, unknown>): msg is StopFrame;
|
|
349
|
+
declare function isPause(msg: Record<string, unknown>): msg is PauseFrame;
|
|
350
|
+
declare function isResume(msg: Record<string, unknown>): msg is ResumeFrame;
|
|
351
|
+
declare function isRelease(msg: Record<string, unknown>): msg is ReleaseFrame;
|
|
352
|
+
type ReflectionMethodsFrame = {
|
|
353
|
+
"$r.methods": string[];
|
|
354
|
+
};
|
|
355
|
+
/** A call frame: the method in the key, the call in the body (`$r.call.<name>`). */
|
|
356
|
+
type ReflectionCallFrame = {
|
|
357
|
+
[key: `$r.call.${string}`]: {
|
|
358
|
+
seq: number;
|
|
359
|
+
args?: unknown[];
|
|
360
|
+
};
|
|
361
|
+
};
|
|
362
|
+
/** An answer frame: `value` or `error`, naming the seq it settles. */
|
|
363
|
+
type ReflectionResultFrame = {
|
|
364
|
+
[key: `$r.result.${string}`]: {
|
|
365
|
+
seq: number;
|
|
366
|
+
value?: unknown;
|
|
367
|
+
error?: string;
|
|
368
|
+
};
|
|
369
|
+
};
|
|
370
|
+
type Frame = ProtoFrame | InitFrame | StateFrame | MsgFrame | ExitFrame | BadFrame | ErrorFrame | StopFrame | PauseFrame | ResumeFrame | ReleaseFrame | TuneFrame | ReflectionMethodsFrame | ReflectionCallFrame | ReflectionResultFrame;
|
|
371
|
+
//#endregion
|
|
372
|
+
//#region src/remote/stream.d.ts
|
|
373
|
+
/** What a blob knows about itself: the facts ride the reference, not the stream behind it. */
|
|
374
|
+
interface BlobFacts {
|
|
375
|
+
/** Bytes in total. A blob is whole by definition, so this is always known. */
|
|
376
|
+
readonly size: number;
|
|
377
|
+
/** The media type, when the sender knows it. */
|
|
378
|
+
readonly type?: string;
|
|
379
|
+
/** A name for a file, when one had it. */
|
|
380
|
+
readonly name?: string;
|
|
381
|
+
}
|
|
382
|
+
/** A stream of octets: what the library takes at one end of a connection and gives at the other.
|
|
383
|
+
* It says nothing about what the octets are — that belongs to the value that references it. */
|
|
384
|
+
type Stream = AsyncIterable<Uint8Array>;
|
|
385
|
+
/** What a message carries in place of a stream: an id, or the name the far side announced it under. */
|
|
386
|
+
interface StreamRef {
|
|
387
|
+
$s: {
|
|
388
|
+
id: number;
|
|
389
|
+
} | {
|
|
390
|
+
name: string;
|
|
391
|
+
};
|
|
392
|
+
}
|
|
393
|
+
declare function isStreamRef(value: unknown): value is StreamRef;
|
|
394
|
+
/** What a message carries in place of a typed array: its octets, and the length they add up to. */
|
|
395
|
+
interface BytesRef {
|
|
396
|
+
$bytes: {
|
|
397
|
+
id: number;
|
|
398
|
+
size: number;
|
|
399
|
+
};
|
|
400
|
+
}
|
|
401
|
+
declare function isBytesRef(value: unknown): value is BytesRef;
|
|
402
|
+
/** What a message carries in place of a blob: its octets and the facts about them. */
|
|
403
|
+
interface BlobRef {
|
|
404
|
+
$blob: {
|
|
405
|
+
id: number;
|
|
406
|
+
} & BlobFacts;
|
|
407
|
+
}
|
|
408
|
+
declare function isBlobRef(value: unknown): value is BlobRef;
|
|
409
|
+
/** What may be offered in place of a whole file: sized, and read on demand. A platform `Blob` or
|
|
410
|
+
* `File` is one as it stands, and so is a `RemoteBlob` that arrived from a connection — which is how
|
|
411
|
+
* a file that was received can be passed on without being read here. */
|
|
412
|
+
interface BlobSource {
|
|
413
|
+
readonly size: number;
|
|
414
|
+
readonly type?: string;
|
|
415
|
+
readonly name?: string;
|
|
416
|
+
/** A window of the bytes, when the value can give one without reading the rest. */
|
|
417
|
+
readonly slice?: (start?: number, end?: number) => BlobSource;
|
|
418
|
+
readonly arrayBuffer: () => Promise<ArrayBuffer>;
|
|
419
|
+
/** The bytes over time, for a value that cannot be sliced. */
|
|
420
|
+
readonly stream?: () => AsyncIterable<Uint8Array>;
|
|
421
|
+
}
|
|
422
|
+
/** What a message carries in place of a blob: the same value, read off the connection. */
|
|
423
|
+
interface Blob {
|
|
424
|
+
readonly size?: number;
|
|
425
|
+
readonly type?: string;
|
|
426
|
+
readonly name?: string;
|
|
427
|
+
/** Read it once: the bytes are on the wire, not here. */
|
|
428
|
+
stream(): Stream;
|
|
429
|
+
arrayBuffer(): Promise<ArrayBuffer>;
|
|
430
|
+
}
|
|
431
|
+
/** What a stream on this side costs and asks for, without knowing the connection. */
|
|
432
|
+
interface ReaderHooks {
|
|
433
|
+
/** Octets taken by the consumer: credit spent, and the writer may be asked for more. */
|
|
434
|
+
consumed(bytes: number): void;
|
|
435
|
+
/** The consumer will take no more. */
|
|
436
|
+
cancelled(reason: string): void;
|
|
437
|
+
/** The consumer is waiting for octets: what the far side may now be asked for. */
|
|
438
|
+
wanted(): void;
|
|
439
|
+
}
|
|
440
|
+
/**
|
|
441
|
+
* Bytes the far side offers, read at the consumer's pace.
|
|
442
|
+
*
|
|
443
|
+
* An async iterable of octets, and nothing more: turning it into an array, a `Blob` or a digest
|
|
444
|
+
* is the platform's job — `new Response(stream).arrayBuffer()` where there is a `Response`,
|
|
445
|
+
* `for await` where there is not.
|
|
446
|
+
*/
|
|
447
|
+
declare class RemoteStream implements Stream {
|
|
448
|
+
private readonly hooks;
|
|
449
|
+
private readonly queue;
|
|
450
|
+
private readonly waiting;
|
|
451
|
+
private ended;
|
|
452
|
+
private failure;
|
|
453
|
+
private stopped;
|
|
454
|
+
private platform;
|
|
455
|
+
constructor(hooks: ReaderHooks);
|
|
456
|
+
/** The far side sent more of it. */
|
|
457
|
+
push(bytes: Uint8Array): void;
|
|
458
|
+
/** The far side has sent all of it. */
|
|
459
|
+
end(): void;
|
|
460
|
+
/** The far side gave up on it, or it arrived corrupt. */
|
|
461
|
+
fail(reason: string): void;
|
|
462
|
+
/** Take no more of it. Said to the far side, so it stops reading its source. */
|
|
463
|
+
cancel(reason?: string): void;
|
|
464
|
+
next(): Promise<IteratorResult<Uint8Array>>;
|
|
465
|
+
return(): Promise<IteratorResult<Uint8Array>>;
|
|
466
|
+
/**
|
|
467
|
+
* The runtime's own stream, built over this one the first time something asks for it. What a
|
|
468
|
+
* sender usually hands over is a `ReadableStream`, so what arrives offers the same interface —
|
|
469
|
+
* `getReader()`, `pipeTo()`, `tee()` — rather than a narrower shape of its own. A runtime
|
|
470
|
+
* without `ReadableStream` keeps the iterable, which is the library's own interface.
|
|
471
|
+
*/
|
|
472
|
+
asReadableStream(): ReadableStream<Uint8Array>;
|
|
473
|
+
getReader(): ReadableStreamDefaultReader<Uint8Array>;
|
|
474
|
+
pipeTo(destination: WritableStream<Uint8Array>, options?: StreamPipeOptions): Promise<void>;
|
|
475
|
+
tee(): [ReadableStream<Uint8Array>, ReadableStream<Uint8Array>];
|
|
476
|
+
/** One consumer, whichever door it comes through: where the runtime has a platform stream this
|
|
477
|
+
* path goes through it, so the lock and the queue are the platform's and not two of ours. */
|
|
478
|
+
[Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
|
|
479
|
+
}
|
|
480
|
+
/**
|
|
481
|
+
* A blob that came over a connection: the same value the far side offered, with its bytes still
|
|
482
|
+
* over there. Reading it is what asks for them — and only at the pace the reader takes them, so a
|
|
483
|
+
* file nobody opens costs nothing on the wire.
|
|
484
|
+
*/
|
|
485
|
+
declare class RemoteBlob implements Blob {
|
|
486
|
+
readonly facts: BlobFacts;
|
|
487
|
+
private readonly body;
|
|
488
|
+
constructor(body: RemoteStream, facts: BlobFacts);
|
|
489
|
+
get size(): number;
|
|
490
|
+
get type(): string | undefined;
|
|
491
|
+
get name(): string | undefined;
|
|
492
|
+
stream(): Stream;
|
|
493
|
+
arrayBuffer(): Promise<ArrayBuffer>;
|
|
494
|
+
}
|
|
495
|
+
/**
|
|
496
|
+
* Bytes that crossed a connection: the sender's array, taken apart into a stream and put back
|
|
497
|
+
* together here as the chunks arrive. Not lazy — the sender was asked the moment the reference
|
|
498
|
+
* arrived — so awaiting this is waiting for the last chunk, not for a read to start.
|
|
499
|
+
*/
|
|
500
|
+
declare class RemoteBytes implements PromiseLike<Uint8Array> {
|
|
501
|
+
/** The length the sender stated, which the octets must add up to. */
|
|
502
|
+
readonly size: number;
|
|
503
|
+
private readonly body;
|
|
504
|
+
private filling;
|
|
505
|
+
constructor(body: RemoteStream, size: number);
|
|
506
|
+
/** Start re-assembling. Called by the store once its record for this stream is in place. */
|
|
507
|
+
start(): void;
|
|
508
|
+
/** The octets, once they are all here. */
|
|
509
|
+
bytes(): Promise<Uint8Array>;
|
|
510
|
+
/** The same octets as an array's buffer, for a caller that wants the platform's shape. */
|
|
511
|
+
arrayBuffer(): Promise<ArrayBuffer>;
|
|
512
|
+
then<TResult1 = Uint8Array, TResult2 = never>(onfulfilled?: ((value: Uint8Array) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
|
|
513
|
+
private pvtFill;
|
|
514
|
+
}
|
|
515
|
+
interface StreamStoreOptions {
|
|
516
|
+
chunkBytes?: number;
|
|
517
|
+
windowBytes?: number;
|
|
518
|
+
maxBytes?: number;
|
|
519
|
+
/** Where stream ids come from. One space per side, shared with the process table so a number
|
|
520
|
+
* names one thing on the connection whatever it names. */
|
|
521
|
+
ids?: IdSpace;
|
|
522
|
+
/** Whether the store reads the connection itself. A party that carries a connection it does not
|
|
523
|
+
* speak — a first stage — sets this false and hands frames in with `handle()`, so the far side's
|
|
524
|
+
* frames are never mistaken for its own. */
|
|
525
|
+
attach?: boolean;
|
|
526
|
+
}
|
|
527
|
+
/**
|
|
528
|
+
* One connection's streams, as this side sees them.
|
|
529
|
+
*
|
|
530
|
+
* Both directions are in one table, because both are the same numbering: what this side offers
|
|
531
|
+
* (and answers asks for) and what it may read from the far side. Ids follow the process table's
|
|
532
|
+
* parity, so an id names one stream on one connection and nothing anywhere else.
|
|
533
|
+
*/
|
|
534
|
+
declare class StreamStore implements ValueCodec {
|
|
535
|
+
private readonly channel;
|
|
536
|
+
private readonly chunkBytes;
|
|
537
|
+
private readonly windowBytes;
|
|
538
|
+
readonly maxBytes: number;
|
|
539
|
+
private readonly pvtOffers;
|
|
540
|
+
private readonly pvtIncoming;
|
|
541
|
+
private readonly ids;
|
|
542
|
+
/** Why streams that are over failed, for a reference that arrives after the fact. */
|
|
543
|
+
private readonly pvtRefused;
|
|
544
|
+
/** What this side announced under a name, and what the far side did. A name is taken while it is
|
|
545
|
+
* in either map, so the two directions never answer to one name at once. */
|
|
546
|
+
private readonly pvtNamesOut;
|
|
547
|
+
private readonly pvtNamesIn;
|
|
548
|
+
/** Told about every named stream the far side announces: the live ones replay, then each arrival. */
|
|
549
|
+
private readonly pvtNamedListeners;
|
|
550
|
+
private readonly pvtOff;
|
|
551
|
+
private readonly pvtSegmentOff;
|
|
552
|
+
private pvtClosed;
|
|
553
|
+
constructor(channel: Channel, parity: IdParity, options?: StreamStoreOptions);
|
|
554
|
+
/** Whether this connection can carry a stream at all: it must carry octets beside its lines. */
|
|
555
|
+
get canCarryStreams(): boolean;
|
|
556
|
+
/**
|
|
557
|
+
* Offer a stream to the connection: the announcement goes out now, and the bytes when the far
|
|
558
|
+
* side asks for them. What comes back is what a message carries in their place.
|
|
559
|
+
*
|
|
560
|
+
* A `name` makes the stream findable: the far side can reference it by that name instead of the
|
|
561
|
+
* id, and ask for it with `named()` without waiting for a message to carry a reference.
|
|
562
|
+
*/
|
|
563
|
+
offer(stream: Stream, name?: string): StreamRef;
|
|
564
|
+
/**
|
|
565
|
+
* Offer a blob — a whole file, read on demand. It crosses as a stream over its bytes and arrives
|
|
566
|
+
* on the far side as a `RemoteBlob`, so nothing of it is read until somebody wants the bytes.
|
|
567
|
+
*/
|
|
568
|
+
offerBlob(blob: BlobSource): BlobRef;
|
|
569
|
+
/**
|
|
570
|
+
* Offer bytes this side already holds. The reference states the length, so the far side can
|
|
571
|
+
* check it against its bound and size the array before the first chunk arrives — a typed array
|
|
572
|
+
* is one piece, so the wire carries it as a stream of one.
|
|
573
|
+
*/
|
|
574
|
+
offerBytes(bytes: Uint8Array): BytesRef;
|
|
575
|
+
private pvtAnnounce;
|
|
576
|
+
private pvtOnePiece;
|
|
577
|
+
/** A blob's octets, a window at a time: sliced where the value can, streamed where it cannot. */
|
|
578
|
+
private pvtBlobChunks;
|
|
579
|
+
/** A value on its way out: every stream in it becomes an announcement and a reference. */
|
|
580
|
+
encode(value: unknown): unknown;
|
|
581
|
+
/** A value just read: every reference in it becomes something this side can read. */
|
|
582
|
+
decode(value: unknown): unknown;
|
|
583
|
+
/** Drop every stream of this connection, in both directions. Called when it ends. */
|
|
584
|
+
close(): void;
|
|
585
|
+
/** The ids this side is holding, in the order they were offered. */
|
|
586
|
+
held(): number[];
|
|
587
|
+
/**
|
|
588
|
+
* Take a frame if it is one this store answers for, and say whether it did. A party that carries a
|
|
589
|
+
* connection it does not speak — a first stage, relaying a client to a payload — has to know which
|
|
590
|
+
* inbound frames are its own and which belong to the far side, and this is the question it asks.
|
|
591
|
+
* Only frames about a stream this side offered are claimed, so a stream the far side offers passes
|
|
592
|
+
* through untouched.
|
|
593
|
+
*/
|
|
594
|
+
handle(frame: Record<string, unknown>): boolean;
|
|
595
|
+
/**
|
|
596
|
+
* The stream the far side announced under `name`, if it is still live — the way a caller finds a
|
|
597
|
+
* stream nobody sent it a reference to. A name that was never announced answers `undefined`, and a
|
|
598
|
+
* name whose stream is over does too: the sentence lives on the value the reference would give.
|
|
599
|
+
*/
|
|
600
|
+
named(name: string): RemoteStream | undefined;
|
|
601
|
+
/**
|
|
602
|
+
* Every named stream the far side announces, now and later. The listener is called for the names
|
|
603
|
+
* already live when it is installed and for each new one as it arrives, so a caller that wires a
|
|
604
|
+
* sink to `stdout` does not have to know whether the far side has printed yet.
|
|
605
|
+
*/
|
|
606
|
+
onNamed(listener: (name: string, stream: RemoteStream) => void): () => void;
|
|
607
|
+
private pvtSend;
|
|
608
|
+
private pvtEncode;
|
|
609
|
+
private pvtTake;
|
|
610
|
+
private pvtPull;
|
|
611
|
+
private pvtPump;
|
|
612
|
+
private pvtDrop;
|
|
613
|
+
/**
|
|
614
|
+
* Take a stream out of the live table and remember why it ended, for a reference that arrives
|
|
615
|
+
* after the fact: "no stream was announced" is the wrong sentence for a stream that was refused.
|
|
616
|
+
*/
|
|
617
|
+
private pvtRetire;
|
|
618
|
+
/** A stream that is over gives its name back, so the next announcement of it is not a duplicate. */
|
|
619
|
+
private pvtRelease;
|
|
620
|
+
private pvtDecode;
|
|
621
|
+
private pvtValueFor;
|
|
622
|
+
/** The value a name the far side announced stands for — or one that says it was never announced. */
|
|
623
|
+
private pvtValueForNamed;
|
|
624
|
+
private pvtBuild;
|
|
625
|
+
private pvtAsk;
|
|
626
|
+
private pvtAnnounced;
|
|
627
|
+
private onSegment;
|
|
628
|
+
private onFrame;
|
|
629
|
+
}
|
|
630
|
+
//#endregion
|
|
631
|
+
//#region src/remote/server.d.ts
|
|
632
|
+
type Spawner = () => Promise<Channel>;
|
|
633
|
+
/** The process a definition's spawn gives back: what a caller reports when it serves one. */
|
|
634
|
+
type ServedProcess<T extends ActorDefinition<any, any, any, any, any>> = SpawnedFrom<T>;
|
|
635
|
+
/** A process, whatever definition it came from: all the serving half needs of one. */
|
|
636
|
+
type AnyProcess = ServedProcess<ActorDefinition<any, any, any, any, any>>;
|
|
637
|
+
/** What the far side stated when it opened the connection: the args it asks to be spawned with, and its own
|
|
638
|
+
* name for its end of the connection. */
|
|
639
|
+
interface Init<Args = unknown> {
|
|
640
|
+
readonly args: Args;
|
|
641
|
+
/** The name the process answers to as a sender: the far side's word, or the default when it stated none. */
|
|
642
|
+
readonly rootName: string;
|
|
643
|
+
readonly parentName: string | null;
|
|
644
|
+
readonly parentId: symbol | null;
|
|
645
|
+
}
|
|
646
|
+
/** What a factory answers: the process to serve, and what the serving half has to know about it. */
|
|
647
|
+
interface Served<Meta = unknown> {
|
|
648
|
+
readonly proc: AnyProcess;
|
|
649
|
+
/** What the factory resolved, when it has more to say about the session than the connection did. */
|
|
650
|
+
readonly meta?: Meta;
|
|
651
|
+
/**
|
|
652
|
+
* What ends this session: run once, when the connection closes and when the reactor stops. It defaults to
|
|
653
|
+
* stopping the process, which is what a factory that spawned one wants; a factory that hands over a process
|
|
654
|
+
* it did not spawn returns its own, since that process outlives every connection.
|
|
655
|
+
*/
|
|
656
|
+
readonly cleanup?: () => void | Promise<void>;
|
|
657
|
+
}
|
|
658
|
+
//#endregion
|
|
659
|
+
//#region src/remote/reactor.d.ts
|
|
660
|
+
/** Any actor definition: the reactor serves it, and does not care which one it is. */
|
|
661
|
+
type AnyActorDefinition = ActorDefinition<any, any, any, any, any>;
|
|
662
|
+
/**
|
|
663
|
+
* A way in, as a listener hands it over: a transport the reactor runs the protocol step on, or a channel
|
|
664
|
+
* that has already been through one (a spawner's, where the handshake is not the reactor's to do).
|
|
665
|
+
*/
|
|
666
|
+
type Incoming = {
|
|
667
|
+
readonly transport: StringTransport;
|
|
668
|
+
readonly channel?: undefined;
|
|
669
|
+
} | {
|
|
670
|
+
readonly channel: Channel;
|
|
671
|
+
readonly transport?: undefined;
|
|
672
|
+
};
|
|
673
|
+
/** An admitted connection: the way in, and whatever the listener knows about it. */
|
|
674
|
+
type Connection<Meta = unknown> = Incoming & {
|
|
675
|
+
/** The transport's own facts: what the listener resolved, the URL, the peer. */
|
|
676
|
+
readonly meta: Meta;
|
|
677
|
+
};
|
|
678
|
+
/** A connection as a session is built on it: what it was admitted by, what the listener resolved,
|
|
679
|
+
* and the channel above the protocol step. Past admission the way in *is* that channel: the
|
|
680
|
+
* reactor owns the protocol step, so a listener never has to carry one for it. */
|
|
681
|
+
type ServedConnection<Meta = unknown> = {
|
|
682
|
+
/** The transport it was admitted on, when the listener handed one over rather than a channel.
|
|
683
|
+
* What the connection came in on, kept as that; the session speaks over `channel`. */
|
|
684
|
+
readonly transport?: StringTransport;
|
|
685
|
+
/** What the listener resolved about the connection. */
|
|
686
|
+
readonly meta: Meta;
|
|
687
|
+
/** The frames of this connection: the channel above the protocol step. This is what the
|
|
688
|
+
* session's process is given as `ctx.connection`, and what a serving half answers with. */
|
|
689
|
+
readonly channel: Channel;
|
|
690
|
+
};
|
|
691
|
+
/** Where connections come from. A listener owns its medium and its own admission. */
|
|
692
|
+
interface Listener<Meta = unknown> {
|
|
693
|
+
/** The next admitted connection. Rejects once the listener is closed. */
|
|
694
|
+
accept(signal?: AbortSignal): Promise<Connection<Meta>>;
|
|
695
|
+
/** Stop accepting, and release what the listener owns. */
|
|
696
|
+
close(): Promise<void>;
|
|
697
|
+
}
|
|
698
|
+
/** One served connection, as the reactor reports it. */
|
|
699
|
+
interface Session<Meta = unknown> {
|
|
700
|
+
/** The served process. It is a root process: the seam spawned it for this connection. */
|
|
701
|
+
readonly proc: ServedProcess<AnyActorDefinition>;
|
|
702
|
+
/** What the listener resolved, plus whatever the factory added. */
|
|
703
|
+
readonly meta: Meta;
|
|
704
|
+
/** The frames of this connection: the one the factory was given, so a starter reads and prints on
|
|
705
|
+
* exactly the channel the process is served over. */
|
|
706
|
+
readonly channel: Channel;
|
|
707
|
+
/** Settles when the connection closes and the serve is over. */
|
|
708
|
+
readonly done: Promise<void>;
|
|
709
|
+
}
|
|
710
|
+
/** What a connection becomes: the process to serve. It is called once the `$init` has been read, so the
|
|
711
|
+
* args the far side asked for are in hand. A bare actor definition is the shortcut for a factory that
|
|
712
|
+
* spawns one with them. */
|
|
713
|
+
type SessionFactory<Meta = unknown> = (connection: ServedConnection<Meta>, init: Init) => Served<Meta> | AnyProcess | Promise<Served<Meta> | AnyProcess>;
|
|
714
|
+
interface ReactorOptions<Meta = unknown> {
|
|
715
|
+
/** A connection was admitted and its process is up. What it returns is called when the session is
|
|
716
|
+
* over: the place a starter uninstalls what it put on this connection. */
|
|
717
|
+
onSession?(session: Session<Meta>): void | (() => void | Promise<void>);
|
|
718
|
+
/** Its connection closed, and the serve is over. */
|
|
719
|
+
onClosed?(session: Session<Meta>): void;
|
|
720
|
+
/** A connection could not be served: a handshake that never came, a wire that went early. */
|
|
721
|
+
onError?(error: unknown, connection: Connection<Meta>): void;
|
|
722
|
+
/**
|
|
723
|
+
* Every decoded frame, before the serve handles it. Returning true swallows the frame, which is
|
|
724
|
+
* where a subprocess's own output frames (`$fd`) are captured instead of passed on.
|
|
725
|
+
*/
|
|
726
|
+
onIncomingFrame?(frame: Record<string, unknown>): boolean | void;
|
|
727
|
+
/** The served side's streams: its own bound on what it will read, and how it chunks what it
|
|
728
|
+
* sends. A connection's reader decides how much it is willing to hold, so the bound is
|
|
729
|
+
* the server's to set — the default refuses anything over 64 MiB. */
|
|
730
|
+
streams?: StreamStoreOptions;
|
|
731
|
+
}
|
|
732
|
+
interface Reactor {
|
|
733
|
+
/** Stop accepting and stop every live session. */
|
|
734
|
+
stop(): Promise<void>;
|
|
735
|
+
/** How many sessions are being served right now. */
|
|
736
|
+
readonly live: number;
|
|
737
|
+
}
|
|
738
|
+
declare function reactor<Meta = unknown>(listener: Listener<Meta>, serve: AnyActorDefinition | SessionFactory<Meta>, options?: ReactorOptions<Meta>): Reactor;
|
|
739
|
+
/**
|
|
740
|
+
* A listener with exactly one connection: what a caller serves on when the medium is already open for it,
|
|
741
|
+
* as a spawner that hands back a channel is. The connection is taken once, a second `accept()` is a
|
|
742
|
+
* mistake worth naming, and `close()` releases an accept that is still waiting for one.
|
|
743
|
+
*/
|
|
744
|
+
declare function oneConnection<Meta = unknown>(spawner: Spawner, meta?: Meta): Listener<Meta>;
|
|
745
|
+
/**
|
|
746
|
+
* One actor over one connection: the reactor with a listener that carries exactly one. A caller that
|
|
747
|
+
* has a spawner and no loop of its own gets the same serving, the same reports and the same teardown a
|
|
748
|
+
* listener gets. The promise settles when the serve is over, and rejects when the connection could not
|
|
749
|
+
* be served at all — the two outcomes the seam has always had.
|
|
750
|
+
*/
|
|
751
|
+
declare function serveRemoteActor<Args, State, InMsg extends Message, OutMsg extends Message, R extends ReflectionOptions>(actor: ActorDefinition<Args, State, InMsg, OutMsg, R>, spawner: Spawner, onSpawned?: (proc: ServedProcess<ActorDefinition<Args, State, InMsg, OutMsg, R>>) => void, streams?: StreamStoreOptions): Promise<void>;
|
|
752
|
+
//#endregion
|
|
753
|
+
//#region src/remote/output.d.ts
|
|
754
|
+
/** Where the far end's own output goes: the stream it came on, and the text it carried. */
|
|
755
|
+
type OutputSink = (name: string, data: string) => void;
|
|
756
|
+
/** Write the far end's output to our stderr, tagged with the name of the process that printed. */
|
|
757
|
+
declare function stderrSink(pname?: string): OutputSink;
|
|
758
|
+
/**
|
|
759
|
+
* Read a named stream into a sink, decoding the octets as text as they arrive.
|
|
760
|
+
*
|
|
761
|
+
* A stream that fails ends the pump quietly: the far end going away is the end of its output, not an
|
|
762
|
+
* error to raise on this side.
|
|
763
|
+
*/
|
|
764
|
+
declare function pumpOutput(stream: Stream, name: string, sink: OutputSink): void;
|
|
765
|
+
//#endregion
|
|
766
|
+
//#region src/remote/client.d.ts
|
|
767
|
+
type ClientSpawner<Args> = (args: Args) => Promise<Channel>;
|
|
768
|
+
/** What the proxy knows about itself when its connection is handed over: enough to name itself. */
|
|
769
|
+
interface ClientContext {
|
|
770
|
+
/** The full name of the proxy process, which is the name the far side serves it under. */
|
|
771
|
+
readonly pname: string;
|
|
772
|
+
}
|
|
773
|
+
/**
|
|
774
|
+
* What a caller may install on the connection a proxy opens. `onChannel` is called once the channel
|
|
775
|
+
* is up and before the first frame is sent or read, so a reader put there misses nothing; what it
|
|
776
|
+
* returns is called when the proxy is over, before the channel is closed.
|
|
777
|
+
*/
|
|
778
|
+
interface RemoteClientOptions {
|
|
779
|
+
onChannel?(channel: Channel, ctx: ClientContext): void | (() => void | Promise<void>);
|
|
780
|
+
/**
|
|
781
|
+
* Where what the far end prints goes. A process that prints announces its `stdout` and `stderr`
|
|
782
|
+
* as streams on the connection; this is the sink they are read into, and the first two names are
|
|
783
|
+
* the only ones taken. Defaults to our own stderr, tagged with the process's name.
|
|
784
|
+
*/
|
|
785
|
+
onOutput?: OutputSink;
|
|
786
|
+
}
|
|
787
|
+
/**
|
|
788
|
+
* Why a proxy ends when the wire under it goes.
|
|
789
|
+
*
|
|
790
|
+
* The far side is *unreachable*, which is not the same as ended: the handles that came across are
|
|
791
|
+
* still here and still readable, and what the far process left behind is still what it left behind.
|
|
792
|
+
* But nothing it says can arrive and nothing here can reach it, and that is news of its own — so the
|
|
793
|
+
* proxy ends with this reason rather than sitting there silent. Whoever forked the proxy hears it
|
|
794
|
+
* where it hears everything else about a child, in `onChildExit`.
|
|
795
|
+
*/
|
|
796
|
+
declare const CHANNEL_LOST = "channel-lost";
|
|
797
|
+
declare function remoteClient<Args, State, InMsg extends Message, OutMsg extends Message, Methods extends MethodOptions = MethodOptions, Handlers extends HandlerOptions<InMsg> = HandlerOptions<InMsg>, R extends ReflectionOptions = ReflectionOptions>(name: string, spawner: ClientSpawner<Args>, options?: RemoteClientOptions): ActorDefinition<Args, State, InMsg, OutMsg, R>;
|
|
798
|
+
//#endregion
|
|
799
|
+
//#region src/remote/transports/websocket.d.ts
|
|
800
|
+
/**
|
|
801
|
+
* The subset of a WebSocket the transport needs. The WHATWG client WebSocket
|
|
802
|
+
* (Node, Bun, browsers) satisfies this directly; a Bun server socket is adapted
|
|
803
|
+
* by the consumer (see spawners/ws-server.ts).
|
|
804
|
+
*/
|
|
805
|
+
interface WebSocketLike {
|
|
806
|
+
send(data: string | Uint8Array): void;
|
|
807
|
+
close(code?: number, reason?: string): void;
|
|
808
|
+
readonly readyState: number;
|
|
809
|
+
onmessage: ((event: {
|
|
810
|
+
data: unknown;
|
|
811
|
+
}) => void) | null;
|
|
812
|
+
onclose: (() => void) | null;
|
|
813
|
+
}
|
|
814
|
+
/** WHATWG WebSocket readyState: OPEN. */
|
|
815
|
+
declare const WS_OPEN = 1;
|
|
816
|
+
declare class WebSocketTransport implements StringTransport {
|
|
817
|
+
private ws;
|
|
818
|
+
private pvtOnMessage;
|
|
819
|
+
private pvtOnBytes;
|
|
820
|
+
private pvtOnClose;
|
|
821
|
+
private closed;
|
|
822
|
+
private readonly reader;
|
|
823
|
+
constructor(ws: WebSocketLike);
|
|
824
|
+
get canSend(): boolean;
|
|
825
|
+
onMessage(handler: (frame: string) => number | void): void;
|
|
826
|
+
onBytes(handler: (bytes: Uint8Array) => void): void;
|
|
827
|
+
removeHandler(): ((frame: string) => number | void) | null;
|
|
828
|
+
onClose(handler: () => void): void;
|
|
829
|
+
get hasHandler(): boolean;
|
|
830
|
+
send(frame: string): Promise<void>;
|
|
831
|
+
sendBytes(bytes: Uint8Array): Promise<void>;
|
|
832
|
+
close(): Promise<void>;
|
|
833
|
+
}
|
|
834
|
+
//#endregion
|
|
835
|
+
export { isInit as $, BlobSource as A, isBytesRef as B, Init as C, Blob as D, Spawner as E, Stream as F, StringTransport as G, BAD_PREFIX_LIMIT as H, StreamRef as I, errorFrame as J, badFrame as K, StreamStore as L, RemoteBlob as M, RemoteBytes as N, BlobFacts as O, RemoteStream as P, isExit as Q, StreamStoreOptions as R, serveRemoteActor as S, ServedProcess as T, Channel as U, isStreamRef as V, Frame as W, isBad as X, errorReason as Y, isError as Z, ServedConnection as _, ClientContext as a, isState as at, oneConnection as b, remoteClient as c, ProcessRef as ct, stderrSink as d, FrameSink as dt, isMsg as et, AnyActorDefinition as f, RemoteMessage as ft, ReactorOptions as g, Reactor as h, CHANNEL_LOST as i, isResume as it, BytesRef as j, BlobRef as k, OutputSink as l, isRemoteProcess as lt, Listener as m, WebSocketLike as n, isProto as nt, ClientSpawner as o, isStop as ot, Connection as p, RemoteProcess as pt, badReason as q, WebSocketTransport as r, isRelease as rt, RemoteClientOptions as s, PROCESS_REF as st, WS_OPEN as t, isPause as tt, pumpOutput as u, rootIdFor as ut, Session as v, Served as w, reactor as x, SessionFactory as y, isBlobRef as z };
|
|
836
|
+
//# sourceMappingURL=websocket-DT8zKD34.d.ts.map
|