@geekmidas/constructs 10.0.0-alpha.153 → 10.0.0-alpha.155
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/adaptors/testing.cjs +206 -0
- package/dist/adaptors/testing.cjs.map +1 -1
- package/dist/adaptors/testing.d.cts +81 -2
- package/dist/adaptors/testing.d.cts.map +1 -1
- package/dist/adaptors/testing.d.mts +81 -2
- package/dist/adaptors/testing.d.mts.map +1 -1
- package/dist/adaptors/testing.mjs +201 -2
- package/dist/adaptors/testing.mjs.map +1 -1
- package/dist/site.cjs +19 -0
- package/dist/site.cjs.map +1 -1
- package/dist/site.d.cts +34 -0
- package/dist/site.d.cts.map +1 -1
- package/dist/site.d.mts +34 -0
- package/dist/site.d.mts.map +1 -1
- package/dist/site.mjs +19 -1
- package/dist/site.mjs.map +1 -1
- package/dist/websocket-api-9bXfgrqd.cjs +1439 -0
- package/dist/websocket-api-9bXfgrqd.cjs.map +1 -0
- package/dist/websocket-api-CLnV_7CB.d.cts +908 -0
- package/dist/websocket-api-CLnV_7CB.d.cts.map +1 -0
- package/dist/websocket-api-DSWDhZph.d.mts +908 -0
- package/dist/websocket-api-DSWDhZph.d.mts.map +1 -0
- package/dist/websocket-api-Dn_3Y2fI.mjs +1302 -0
- package/dist/websocket-api-Dn_3Y2fI.mjs.map +1 -0
- package/dist/websocket-api.cjs +24 -1121
- package/dist/websocket-api.d.cts +2 -699
- package/dist/websocket-api.d.mts +2 -699
- package/dist/websocket-api.mjs +2 -1102
- package/package.json +31 -31
- package/dist/websocket-api.cjs.map +0 -1
- package/dist/websocket-api.d.cts.map +0 -1
- package/dist/websocket-api.d.mts.map +0 -1
- package/dist/websocket-api.mjs.map +0 -1
package/dist/websocket-api.d.mts
CHANGED
|
@@ -1,699 +1,2 @@
|
|
|
1
|
-
import { n as
|
|
2
|
-
|
|
3
|
-
import { n as Telemetry } from "./telemetry-CObow3Dn.mjs";
|
|
4
|
-
import { ConstructName, Declaration } from "@geekmidas/manifest";
|
|
5
|
-
import { Service, ServiceRecord, ServiceRegisterOptions } from "@geekmidas/services";
|
|
6
|
-
import { EnvironmentParser } from "@geekmidas/envkit";
|
|
7
|
-
import { Hono } from "hono";
|
|
8
|
-
import { Logger } from "@geekmidas/logger";
|
|
9
|
-
import { InferStandardSchema } from "@geekmidas/schema";
|
|
10
|
-
import { IncomingMessage, Server } from "node:http";
|
|
11
|
-
import { Duplex } from "node:stream";
|
|
12
|
-
//#region src/websocket/publisher.d.ts
|
|
13
|
-
/**
|
|
14
|
-
* Where a publisher's frames go once they are encoded — the one thing a
|
|
15
|
-
* runtime supplies to send to its sockets.
|
|
16
|
-
*
|
|
17
|
-
* On Node it is a `TransportSink`: each id's process, over Redis or memory.
|
|
18
|
-
* On API Gateway it would be the management API's `postToConnection`; under
|
|
19
|
-
* test, a recording. A payload is the frame already serialised, once, however
|
|
20
|
-
* many ids it goes to. An id that is gone is dropped, not an error.
|
|
21
|
-
*/
|
|
22
|
-
interface WebSocketSink {
|
|
23
|
-
send(ids: readonly string[], payload: string): Promise<void>;
|
|
24
|
-
/** Every open connection but `except`. */
|
|
25
|
-
broadcast(payload: string, except?: readonly string[]): Promise<void>;
|
|
26
|
-
close(ids: readonly string[], code: number, reason: string): Promise<void>;
|
|
27
|
-
}
|
|
28
|
-
/**
|
|
29
|
-
* What a surface sends its sockets, by action — `WebSocketApiConfig.messages`.
|
|
30
|
-
*/
|
|
31
|
-
type WebSocketMessages = Record<string, StandardSchemaV1>;
|
|
32
|
-
/** A surface that declares no messages: any action, any data. */
|
|
33
|
-
type NoMessages = Record<never, never>;
|
|
34
|
-
/** The actions a publisher sends: the declared ones, or any. */
|
|
35
|
-
type MessageAction<TMessages extends WebSocketMessages> = [keyof TMessages] extends [never] ? string : keyof TMessages & string;
|
|
36
|
-
/** What `action`'s data is, as its schema takes it. */
|
|
37
|
-
type MessageData<TMessages extends WebSocketMessages, TAction extends string> = TAction extends keyof TMessages ? StandardSchemaV1.InferInput<TMessages[TAction]> : unknown;
|
|
38
|
-
/** A message sent on an action the surface does not declare. */
|
|
39
|
-
export declare class UnknownWebSocketMessage extends Error {
|
|
40
|
-
readonly surface: string;
|
|
41
|
-
readonly action: string;
|
|
42
|
-
readonly declared: readonly string[];
|
|
43
|
-
constructor(surface: string, action: string, declared: readonly string[]);
|
|
44
|
-
}
|
|
45
|
-
/** A message whose data its action's schema refused. */
|
|
46
|
-
export declare class InvalidWebSocketMessage extends Error {
|
|
47
|
-
readonly surface: string;
|
|
48
|
-
readonly action: string;
|
|
49
|
-
readonly issues: readonly StandardSchemaV1.Issue[];
|
|
50
|
-
constructor(surface: string, action: string, issues: readonly StandardSchemaV1.Issue[]);
|
|
51
|
-
}
|
|
52
|
-
/**
|
|
53
|
-
* How anything reaches a socket — `services.realtime` in an endpoint, and
|
|
54
|
-
* `sockets` in a route of the surface itself.
|
|
55
|
-
*
|
|
56
|
-
* A message is `{ action, data }`, the shape a client's frames arrive in —
|
|
57
|
-
* or, where the surface names a `frame.discriminator`, flat: `{ [key]: action,
|
|
58
|
-
* ...data }`.
|
|
59
|
-
* Where the surface declares its messages, `action` is one of them and
|
|
60
|
-
* `data` is typed and checked by its schema before anything is sent; where it
|
|
61
|
-
* declares none, any action and any JSON value go. A message is serialised
|
|
62
|
-
* once, whatever the number of sockets it goes to. An id whose process has
|
|
63
|
-
* gone is dropped silently, as API Gateway's `postToConnection` to a closed
|
|
64
|
-
* connection is a no-op the sender rarely wants to handle.
|
|
65
|
-
*/
|
|
66
|
-
export declare class WebSocketPublisher<TMessages extends WebSocketMessages = NoMessages> {
|
|
67
|
-
/** Where an encoded frame goes. */
|
|
68
|
-
private readonly sink;
|
|
69
|
-
/** The surface's declared messages, which every send is checked by. */
|
|
70
|
-
private readonly declared?;
|
|
71
|
-
/** How the surface writes a frame. Absent, `{ action, data }`. */
|
|
72
|
-
private readonly frame;
|
|
73
|
-
constructor(
|
|
74
|
-
/** Where an encoded frame goes. */
|
|
75
|
-
sink: WebSocketSink,
|
|
76
|
-
/** The surface's declared messages, which every send is checked by. */
|
|
77
|
-
declared?: {
|
|
78
|
-
surface: string;
|
|
79
|
-
messages: TMessages;
|
|
80
|
-
} | undefined,
|
|
81
|
-
/** How the surface writes a frame. Absent, `{ action, data }`. */
|
|
82
|
-
frame?: FrameShape);
|
|
83
|
-
/** Send `action`'s message to each connection. */
|
|
84
|
-
send<TAction extends MessageAction<TMessages>>(ids: string | readonly string[], action: TAction, data: MessageData<TMessages, TAction>): Promise<void>;
|
|
85
|
-
/** Send `action`'s message to every open connection, on every process. */
|
|
86
|
-
broadcast<TAction extends MessageAction<TMessages>>(action: TAction, data: MessageData<TMessages, TAction>, options?: {
|
|
87
|
-
except?: readonly string[];
|
|
88
|
-
}): Promise<void>;
|
|
89
|
-
/** Close each connection, with a close code and reason its client sees. */
|
|
90
|
-
close(ids: string | readonly string[], code?: number, reason?: string): Promise<void>;
|
|
91
|
-
/**
|
|
92
|
-
* The frame, checked by the action's schema where the surface declares
|
|
93
|
-
* its messages.
|
|
94
|
-
*
|
|
95
|
-
* @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}, and for a
|
|
96
|
-
* flat frame {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator}
|
|
97
|
-
*/
|
|
98
|
-
private payload;
|
|
99
|
-
}
|
|
100
|
-
//#endregion
|
|
101
|
-
//#region src/websocket/frame.d.ts
|
|
102
|
-
/** `WebSocketApiConfig.frame`: where a flat frame keeps its action. */
|
|
103
|
-
interface WebSocketFrame {
|
|
104
|
-
/** The key a frame's action lives in — `type` for `{ "type": … }`. */
|
|
105
|
-
discriminator: string;
|
|
106
|
-
}
|
|
107
|
-
/** A frame as the server reads it, whatever shape it arrived in. */
|
|
108
|
-
interface DecodedFrame {
|
|
109
|
-
action: string;
|
|
110
|
-
/** Echoed on the reply. Only an `{ action, data }` frame carries one. */
|
|
111
|
-
id?: string | number;
|
|
112
|
-
data?: unknown;
|
|
113
|
-
}
|
|
114
|
-
/** A declared message whose schema does not describe an object. */
|
|
115
|
-
export declare class WebSocketMessageNotAnObject extends Error {
|
|
116
|
-
readonly surface: string;
|
|
117
|
-
readonly action: string;
|
|
118
|
-
readonly discriminator: string;
|
|
119
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
120
|
-
}
|
|
121
|
-
/** A declared message whose schema has a field named the discriminator. */
|
|
122
|
-
export declare class WebSocketMessageDeclaresDiscriminator extends Error {
|
|
123
|
-
readonly surface: string;
|
|
124
|
-
readonly action: string;
|
|
125
|
-
readonly discriminator: string;
|
|
126
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
127
|
-
}
|
|
128
|
-
/** Data sent in a flat frame that is not an object. */
|
|
129
|
-
export declare class WebSocketDataNotAnObject extends Error {
|
|
130
|
-
readonly surface: string;
|
|
131
|
-
readonly action: string;
|
|
132
|
-
readonly discriminator: string;
|
|
133
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
134
|
-
}
|
|
135
|
-
/** Data sent in a flat frame that carries the discriminator itself. */
|
|
136
|
-
export declare class WebSocketDataHasDiscriminator extends Error {
|
|
137
|
-
readonly surface: string;
|
|
138
|
-
readonly action: string;
|
|
139
|
-
readonly discriminator: string;
|
|
140
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
141
|
-
}
|
|
142
|
-
/** How one surface writes and reads its frames. */
|
|
143
|
-
declare class FrameShape {
|
|
144
|
-
readonly surface: string;
|
|
145
|
-
/** The flat frame's key; absent, frames are `{ action, data }`. */
|
|
146
|
-
readonly discriminator?: string | undefined;
|
|
147
|
-
constructor(surface: string,
|
|
148
|
-
/** The flat frame's key; absent, frames are `{ action, data }`. */
|
|
149
|
-
discriminator?: string | undefined);
|
|
150
|
-
/** The key an inbound frame names its action under. */
|
|
151
|
-
get key(): string;
|
|
152
|
-
/**
|
|
153
|
-
* The frame for `action`'s `data`, serialised.
|
|
154
|
-
*
|
|
155
|
-
* @throws {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator} for
|
|
156
|
-
* a flat frame whose data cannot sit beside the discriminator.
|
|
157
|
-
*/
|
|
158
|
-
encode(action: string, data: unknown, id?: string | number): string;
|
|
159
|
-
/** A parsed frame's action, id and data — `undefined` when it names none. */
|
|
160
|
-
decode(frame: unknown): DecodedFrame | undefined;
|
|
161
|
-
/** The id a frame that names no action carried, to echo on its error. */
|
|
162
|
-
idOf(frame: unknown): string | number | undefined;
|
|
163
|
-
/**
|
|
164
|
-
* Refuse a declared message a flat frame cannot carry: one that is not an
|
|
165
|
-
* object, or that has a field named the discriminator.
|
|
166
|
-
*
|
|
167
|
-
* @throws {WebSocketMessageNotAnObject}, {WebSocketMessageDeclaresDiscriminator}
|
|
168
|
-
*/
|
|
169
|
-
check(messages: WebSocketMessages): void;
|
|
170
|
-
}
|
|
171
|
-
//#endregion
|
|
172
|
-
//#region src/websocket/route.d.ts
|
|
173
|
-
/** One open connection, as a handler sees it. */
|
|
174
|
-
interface Connection {
|
|
175
|
-
readonly id: string;
|
|
176
|
-
/**
|
|
177
|
-
* What the connect handler returned — who the connection is for, the room
|
|
178
|
-
* it joined. `{}` when it returned nothing.
|
|
179
|
-
*/
|
|
180
|
-
readonly data: Record<string, unknown>;
|
|
181
|
-
}
|
|
182
|
-
interface BaseContext<TServices extends Service[], TMessages extends WebSocketMessages> {
|
|
183
|
-
services: ServiceRecord<TServices>;
|
|
184
|
-
logger: Logger;
|
|
185
|
-
/** Every socket this surface holds, on whichever process holds it. */
|
|
186
|
-
sockets: WebSocketPublisher<TMessages>;
|
|
187
|
-
}
|
|
188
|
-
interface ConnectContext<TServices extends Service[], TMessages extends WebSocketMessages = NoMessages> extends BaseContext<TServices, TMessages> {
|
|
189
|
-
connectionId: string;
|
|
190
|
-
headers: Headers;
|
|
191
|
-
query: URLSearchParams;
|
|
192
|
-
/**
|
|
193
|
-
* Whose connection it is, from the surface's `.auth()` — `null` when the
|
|
194
|
-
* upgrade carried no session, and when the surface names no authenticator.
|
|
195
|
-
* Throw an `UnauthorizedError` to refuse it.
|
|
196
|
-
*/
|
|
197
|
-
session: unknown;
|
|
198
|
-
}
|
|
199
|
-
interface MessageContext<TBody, TServices extends Service[], TMessages extends WebSocketMessages = NoMessages> extends BaseContext<TServices, TMessages> {
|
|
200
|
-
connection: Connection;
|
|
201
|
-
body: TBody;
|
|
202
|
-
/** Send to this connection alone. */
|
|
203
|
-
reply(message: unknown): void;
|
|
204
|
-
}
|
|
205
|
-
interface DisconnectContext<TServices extends Service[], TMessages extends WebSocketMessages = NoMessages> extends BaseContext<TServices, TMessages> {
|
|
206
|
-
connection: Connection;
|
|
207
|
-
code: number;
|
|
208
|
-
reason: string;
|
|
209
|
-
}
|
|
210
|
-
/** What a frame is dispatched on: an action, or the connection's lifecycle. */
|
|
211
|
-
type RouteKind = 'connect' | 'disconnect' | 'message';
|
|
212
|
-
/**
|
|
213
|
-
* A handler bound to a WebSocket surface — what `realtime.route('chat.send')
|
|
214
|
-
* …handle()` returns, and what a file exports.
|
|
215
|
-
*
|
|
216
|
-
* Carries `surface` and `constructs` the way an endpoint does, so discovery
|
|
217
|
-
* records what its process reaches without knowing what a route is.
|
|
218
|
-
*/
|
|
219
|
-
export declare class WebSocketRoute {
|
|
220
|
-
readonly kind: RouteKind;
|
|
221
|
-
/** The `action` it answers; `$connect` and `$disconnect` for the lifecycle. */
|
|
222
|
-
readonly action: string;
|
|
223
|
-
readonly surface: {
|
|
224
|
-
id: string;
|
|
225
|
-
};
|
|
226
|
-
readonly services: readonly Service[];
|
|
227
|
-
/** Construct ids it depends on — its edges in the manifest. */
|
|
228
|
-
readonly constructs: readonly string[];
|
|
229
|
-
readonly handler: (context: never) => unknown;
|
|
230
|
-
readonly schema?: StandardSchemaV1 | undefined;
|
|
231
|
-
readonly __IS_WEBSOCKET_ROUTE__ = true;
|
|
232
|
-
static isRoute(value: unknown): value is WebSocketRoute;
|
|
233
|
-
constructor(kind: RouteKind,
|
|
234
|
-
/** The `action` it answers; `$connect` and `$disconnect` for the lifecycle. */
|
|
235
|
-
action: string, surface: {
|
|
236
|
-
id: string;
|
|
237
|
-
}, services: readonly Service[],
|
|
238
|
-
/** Construct ids it depends on — its edges in the manifest. */
|
|
239
|
-
constructs: readonly string[], handler: (context: never) => unknown, schema?: StandardSchemaV1 | undefined);
|
|
240
|
-
}
|
|
241
|
-
/** The builder `connect()`, `disconnect()` and `route()` start. */
|
|
242
|
-
export declare class WebSocketRouteBuilder<TKind extends RouteKind, TSchema extends StandardSchemaV1 | undefined = undefined, TServices extends Service[] = [],
|
|
243
|
-
/** The surface's declared messages, which `sockets` sends. */
|
|
244
|
-
TMessages extends WebSocketMessages = NoMessages> {
|
|
245
|
-
private readonly kind;
|
|
246
|
-
private readonly action;
|
|
247
|
-
private readonly surface;
|
|
248
|
-
private readonly _services;
|
|
249
|
-
private readonly _constructs;
|
|
250
|
-
private readonly schema?;
|
|
251
|
-
constructor(kind: TKind, action: string, surface: {
|
|
252
|
-
id: string;
|
|
253
|
-
}, _services?: readonly Service[], _constructs?: readonly string[], schema?: TSchema | undefined);
|
|
254
|
-
/** The schema a frame's `data` must satisfy before the handler runs. */
|
|
255
|
-
body<S extends StandardSchemaV1>(schema: S): WebSocketRouteBuilder<TKind, S, TServices, TMessages>;
|
|
256
|
-
/** What the handler reaches, as `services.<id>` — per route, as an endpoint's. */
|
|
257
|
-
dependsOn<const T extends readonly Consumable[]>(constructs: T): WebSocketRouteBuilder<TKind, TSchema, [...TServices, ...ServicesOf<T>], TMessages>;
|
|
258
|
-
/**
|
|
259
|
-
* The handler. A message handler's return value, when there is one, is
|
|
260
|
-
* sent back to the connection as the reply to that frame; a connect
|
|
261
|
-
* handler's is kept as the connection's `data`.
|
|
262
|
-
*/
|
|
263
|
-
handle(handler: TKind extends 'connect' ? (context: ConnectContext<TServices, TMessages>) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> : TKind extends 'disconnect' ? (context: DisconnectContext<TServices, TMessages>) => unknown : (context: MessageContext<TSchema extends StandardSchemaV1 ? InferStandardSchema<TSchema> : unknown, TServices, TMessages>) => unknown): WebSocketRoute;
|
|
264
|
-
}
|
|
265
|
-
//#endregion
|
|
266
|
-
//#region src/websocket/core.d.ts
|
|
267
|
-
/** Two routes answer one action. */
|
|
268
|
-
export declare class DuplicateWebSocketRoute extends Error {
|
|
269
|
-
readonly surface: string;
|
|
270
|
-
readonly action: string;
|
|
271
|
-
constructor(surface: string, action: string);
|
|
272
|
-
}
|
|
273
|
-
interface WebSocketCoreOptions<TMessages extends WebSocketMessages = NoMessages> {
|
|
274
|
-
surface: string;
|
|
275
|
-
/** Every route handed in; those built from another surface are skipped. */
|
|
276
|
-
routes: readonly WebSocketRoute[];
|
|
277
|
-
/** What the surface sends its sockets — see `WebSocketApiConfig.messages`. */
|
|
278
|
-
messages?: TMessages;
|
|
279
|
-
/** The shape its frames take — see `WebSocketApiConfig.frame`. */
|
|
280
|
-
frame?: WebSocketFrame;
|
|
281
|
-
/** Where `sockets` sends, in every handler: the adaptor's own. */
|
|
282
|
-
sink: WebSocketSink;
|
|
283
|
-
envParser: EnvironmentParser<{}>;
|
|
284
|
-
logger: Logger;
|
|
285
|
-
/** What turns a handshake's headers into the `session` connect sees. */
|
|
286
|
-
authenticator?: Authenticator;
|
|
287
|
-
}
|
|
288
|
-
/** A handshake, as the adaptor that received it saw it. */
|
|
289
|
-
interface ConnectRequest {
|
|
290
|
-
/** The id the adaptor gives the connection — sends address it by this. */
|
|
291
|
-
connectionId: string;
|
|
292
|
-
headers: Headers;
|
|
293
|
-
query: URLSearchParams;
|
|
294
|
-
/**
|
|
295
|
-
* Whose connection it is, when the adaptor already knows (a test).
|
|
296
|
-
* Absent, the surface's authenticator verifies `headers`; `null` is no
|
|
297
|
-
* session.
|
|
298
|
-
*/
|
|
299
|
-
session?: unknown;
|
|
300
|
-
}
|
|
301
|
-
/**
|
|
302
|
-
* For one call: services to use in place of registering them — a test's
|
|
303
|
-
* transaction for `database`. Only those the route depends on are handed in.
|
|
304
|
-
*/
|
|
305
|
-
interface WebSocketCallOptions {
|
|
306
|
-
services?: Record<string, unknown>;
|
|
307
|
-
}
|
|
308
|
-
/** Whether a handshake may become a connection. */
|
|
309
|
-
type ConnectOutcome = {
|
|
310
|
-
accepted: true;
|
|
311
|
-
connection: Connection;
|
|
312
|
-
} | {
|
|
313
|
-
accepted: false;
|
|
314
|
-
/** The status a refused upgrade answers with: the `HttpError`'s, or 500. */
|
|
315
|
-
status: number;
|
|
316
|
-
statusText: string;
|
|
317
|
-
/** What the connect handler, or the authenticator, threw. */
|
|
318
|
-
error: unknown;
|
|
319
|
-
};
|
|
320
|
-
/** Writes one serialised frame to the connection a message arrived on. */
|
|
321
|
-
type WriteFrame = (payload: string) => void;
|
|
322
|
-
/** What became of one inbound frame. Whatever it wrote went through `write`. */
|
|
323
|
-
type MessageOutcome = {
|
|
324
|
-
ok: true;
|
|
325
|
-
action: string;
|
|
326
|
-
id?: string | number;
|
|
327
|
-
/** The handler's return — sent back as the reply when defined. */
|
|
328
|
-
returned: unknown;
|
|
329
|
-
} | {
|
|
330
|
-
ok: false;
|
|
331
|
-
/** Absent when the frame named no action. */
|
|
332
|
-
action?: string;
|
|
333
|
-
id?: string | number;
|
|
334
|
-
/** What the `$error` frame said. */
|
|
335
|
-
message: string;
|
|
336
|
-
issues?: readonly StandardSchemaV1.Issue[];
|
|
337
|
-
/** What the handler threw, when it got that far. */
|
|
338
|
-
error?: unknown;
|
|
339
|
-
};
|
|
340
|
-
type DisconnectOutcome = {
|
|
341
|
-
ok: true;
|
|
342
|
-
} | {
|
|
343
|
-
ok: false;
|
|
344
|
-
error: unknown;
|
|
345
|
-
};
|
|
346
|
-
export declare class WebSocketCore<TMessages extends WebSocketMessages = NoMessages> {
|
|
347
|
-
private readonly options;
|
|
348
|
-
readonly surface: string;
|
|
349
|
-
/** How frames are read and written — what an adaptor decodes replies by. */
|
|
350
|
-
readonly frame: FrameShape;
|
|
351
|
-
/** `sockets` in every handler. */
|
|
352
|
-
readonly sockets: WebSocketPublisher<TMessages>;
|
|
353
|
-
private readonly routes;
|
|
354
|
-
private readonly lifecycle;
|
|
355
|
-
/**
|
|
356
|
-
* @throws {DuplicateWebSocketRoute} when two routes answer one action, and
|
|
357
|
-
* the frame checks of `FrameShape.check` for declared messages.
|
|
358
|
-
*/
|
|
359
|
-
constructor(options: WebSocketCoreOptions<TMessages>);
|
|
360
|
-
/**
|
|
361
|
-
* Run the connect handler for a handshake: accepted with the connection's
|
|
362
|
-
* `data` (what the handler returned, `{}` for nothing), or refused with
|
|
363
|
-
* the status of the `HttpError` it threw — 500 for anything else. A surface
|
|
364
|
-
* with no connect handler accepts every handshake, and verifies no session.
|
|
365
|
-
*/
|
|
366
|
-
connect(request: ConnectRequest, options?: WebSocketCallOptions): Promise<ConnectOutcome>;
|
|
367
|
-
/**
|
|
368
|
-
* Parse, validate and run one inbound frame. The reply — the handler's
|
|
369
|
-
* return, encoded — and every `$error` are written with `write`; an error
|
|
370
|
-
* is a frame, never a close. A binary frame is refused: frames are text.
|
|
371
|
-
*/
|
|
372
|
-
message(connection: Connection, raw: string | Uint8Array, write: WriteFrame, options?: WebSocketCallOptions): Promise<MessageOutcome>;
|
|
373
|
-
/**
|
|
374
|
-
* Run the disconnect handler for a connection that has closed. What it
|
|
375
|
-
* throws is logged and returned, never thrown: the socket is gone either
|
|
376
|
-
* way.
|
|
377
|
-
*/
|
|
378
|
-
disconnect(connection: Connection, close: {
|
|
379
|
-
code: number;
|
|
380
|
-
reason: string;
|
|
381
|
-
}, options?: WebSocketCallOptions): Promise<DisconnectOutcome>;
|
|
382
|
-
/** Run a handler with its services, inside a request context of its own. */
|
|
383
|
-
private run;
|
|
384
|
-
/** The route's services: the overrides it names, the rest registered. */
|
|
385
|
-
private services;
|
|
386
|
-
private error;
|
|
387
|
-
}
|
|
388
|
-
//#endregion
|
|
389
|
-
//#region src/websocket/transport.d.ts
|
|
390
|
-
/** What one process is asked to do with the sockets it holds. */
|
|
391
|
-
type Delivery = {
|
|
392
|
-
kind: 'send';
|
|
393
|
-
ids: readonly string[];
|
|
394
|
-
payload: string;
|
|
395
|
-
} | {
|
|
396
|
-
kind: 'broadcast';
|
|
397
|
-
payload: string;
|
|
398
|
-
except?: readonly string[];
|
|
399
|
-
} | {
|
|
400
|
-
kind: 'close';
|
|
401
|
-
ids: readonly string[];
|
|
402
|
-
code: number;
|
|
403
|
-
reason: string;
|
|
404
|
-
};
|
|
405
|
-
interface WebSocketTransport {
|
|
406
|
-
/** Deliver to one instance, or to every instance when it is `'*'`. */
|
|
407
|
-
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
408
|
-
/** Receive what is published to `instance`, and every broadcast. */
|
|
409
|
-
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
410
|
-
close(): Promise<void>;
|
|
411
|
-
}
|
|
412
|
-
/**
|
|
413
|
-
* A publisher's sink over a transport: a send goes to the instance each
|
|
414
|
-
* connection id names, a broadcast to every instance. What `services.<id>`
|
|
415
|
-
* sends through, and what the Node adaptor's own `sockets` do.
|
|
416
|
-
*/
|
|
417
|
-
export declare class TransportSink implements WebSocketSink {
|
|
418
|
-
private readonly transport;
|
|
419
|
-
/**
|
|
420
|
-
* Delivers to this process's own sockets without a round trip through
|
|
421
|
-
* the transport — set by the process that holds them.
|
|
422
|
-
*/
|
|
423
|
-
private readonly local?;
|
|
424
|
-
constructor(transport: WebSocketTransport,
|
|
425
|
-
/**
|
|
426
|
-
* Delivers to this process's own sockets without a round trip through
|
|
427
|
-
* the transport — set by the process that holds them.
|
|
428
|
-
*/
|
|
429
|
-
local?: {
|
|
430
|
-
instance: string;
|
|
431
|
-
deliver(delivery: Delivery): void;
|
|
432
|
-
} | undefined);
|
|
433
|
-
send(ids: readonly string[], payload: string): Promise<void>;
|
|
434
|
-
broadcast(payload: string, except?: readonly string[]): Promise<void>;
|
|
435
|
-
close(ids: readonly string[], code: number, reason: string): Promise<void>;
|
|
436
|
-
/** One delivery per process that holds any of `ids`. */
|
|
437
|
-
private each;
|
|
438
|
-
}
|
|
439
|
-
/** A connection string names no transport this package knows. */
|
|
440
|
-
export declare class UnsupportedWebSocketTransport extends Error {
|
|
441
|
-
readonly connectionString: string;
|
|
442
|
-
constructor(connectionString: string);
|
|
443
|
-
}
|
|
444
|
-
/**
|
|
445
|
-
* In one process: the server and whoever sends meet in a map, keyed by the
|
|
446
|
-
* channel the connection string names.
|
|
447
|
-
*/
|
|
448
|
-
export declare class MemoryTransport implements WebSocketTransport {
|
|
449
|
-
private readonly channel;
|
|
450
|
-
private readonly subscribed;
|
|
451
|
-
constructor(channel: string);
|
|
452
|
-
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
453
|
-
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
454
|
-
close(): Promise<void>;
|
|
455
|
-
}
|
|
456
|
-
/** The subset of an ioredis client the transport uses. */
|
|
457
|
-
interface RedisClient {
|
|
458
|
-
publish(channel: string, message: string): Promise<number>;
|
|
459
|
-
subscribe(...channels: string[]): Promise<unknown>;
|
|
460
|
-
on(event: 'message', listener: (channel: string, message: string) => void): unknown;
|
|
461
|
-
duplicate(): RedisClient;
|
|
462
|
-
quit(): Promise<unknown>;
|
|
463
|
-
}
|
|
464
|
-
/**
|
|
465
|
-
* Over Redis pub/sub: one channel per instance and one for broadcasts, under
|
|
466
|
-
* a prefix that keeps two surfaces — or two projects on one Redis — apart.
|
|
467
|
-
* Channels are not scoped by database index, so the prefix is what does it.
|
|
468
|
-
*
|
|
469
|
-
* Publishing and subscribing take separate connections, because a connection
|
|
470
|
-
* that has subscribed can do nothing else.
|
|
471
|
-
*/
|
|
472
|
-
export declare class RedisTransport implements WebSocketTransport {
|
|
473
|
-
private readonly client;
|
|
474
|
-
private readonly prefix;
|
|
475
|
-
private subscriber?;
|
|
476
|
-
private closed?;
|
|
477
|
-
constructor(client: RedisClient, prefix: string);
|
|
478
|
-
private channel;
|
|
479
|
-
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
480
|
-
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
481
|
-
/** Idempotent: the server and a shutdown hook may both close it. */
|
|
482
|
-
close(): Promise<void>;
|
|
483
|
-
}
|
|
484
|
-
/**
|
|
485
|
-
* The transport a connection string names.
|
|
486
|
-
*
|
|
487
|
-
* `redis://` and `rediss://` take an optional `channel` query parameter, the
|
|
488
|
-
* prefix every channel is named under; `memory://<channel>` is in-process.
|
|
489
|
-
* Absent, the channel is `fallback` — the surface's own.
|
|
490
|
-
*/
|
|
491
|
-
export declare function transportFromConnectionString(connectionString: string, fallback: string): Promise<WebSocketTransport>;
|
|
492
|
-
//#endregion
|
|
493
|
-
//#region src/websocket/server.d.ts
|
|
494
|
-
/** Close codes a client sees. */
|
|
495
|
-
export declare const CLOSE: {
|
|
496
|
-
readonly normal: 1000;
|
|
497
|
-
/** The process is stopping; reconnect and land on another. */
|
|
498
|
-
readonly serviceRestart: 1012;
|
|
499
|
-
/** It stopped reading, and what was queued for it passed the limit. */
|
|
500
|
-
readonly tooSlow: 1013;
|
|
501
|
-
};
|
|
502
|
-
interface WebSocketServerOptions<TMessages extends WebSocketMessages = NoMessages> {
|
|
503
|
-
/**
|
|
504
|
-
* The surface's core, over the sink this process sends through — its own
|
|
505
|
-
* sockets directly, every other process's over `transport`.
|
|
506
|
-
*/
|
|
507
|
-
core(sink: WebSocketSink): WebSocketCore<TMessages>;
|
|
508
|
-
transport: WebSocketTransport;
|
|
509
|
-
/**
|
|
510
|
-
* Origins a browser may open a socket from. A request with an `Origin`
|
|
511
|
-
* not in the list is refused with 403; one with none — a server, a load
|
|
512
|
-
* generator — is not a browser, and is let through.
|
|
513
|
-
*/
|
|
514
|
-
trustedOrigins: readonly string[];
|
|
515
|
-
/**
|
|
516
|
-
* The surface's own public address, `<ID>_URL`. Its origin is always
|
|
517
|
-
* trusted: a native client (React Native's `WebSocket`) sends the socket's
|
|
518
|
-
* own origin as its `Origin`.
|
|
519
|
-
*/
|
|
520
|
-
url?: string;
|
|
521
|
-
/** How often each socket is pinged; one that missed the last is dropped. */
|
|
522
|
-
heartbeatMs?: number;
|
|
523
|
-
/** The largest frame accepted, in bytes. */
|
|
524
|
-
maxPayload?: number;
|
|
525
|
-
/** Queued bytes a socket may hold before it is closed as too slow. */
|
|
526
|
-
maxBufferedBytes?: number;
|
|
527
|
-
}
|
|
528
|
-
export declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages = NoMessages> {
|
|
529
|
-
private readonly wss;
|
|
530
|
-
private readonly options;
|
|
531
|
-
/** This process, as connection ids name it. */
|
|
532
|
-
readonly instance: string;
|
|
533
|
-
/** Where each handshake, frame and close is handed. */
|
|
534
|
-
readonly core: WebSocketCore<TMessages>;
|
|
535
|
-
private readonly held;
|
|
536
|
-
private readonly heartbeat;
|
|
537
|
-
private readonly trusted;
|
|
538
|
-
private next;
|
|
539
|
-
private closing;
|
|
540
|
-
private constructor();
|
|
541
|
-
static start<TMessages extends WebSocketMessages = NoMessages>(options: WebSocketServerOptions<TMessages>): Promise<WebSocketSurfaceServer<TMessages>>;
|
|
542
|
-
/** `sockets` in a route: local sends skip the transport. */
|
|
543
|
-
get publisher(): WebSocketPublisher<TMessages>;
|
|
544
|
-
/** How many sockets this process holds. */
|
|
545
|
-
get size(): number;
|
|
546
|
-
/** Take over `server`'s upgrades. */
|
|
547
|
-
attach(server: Server): void;
|
|
548
|
-
/** Upgrade one request, or refuse it with a status line. */
|
|
549
|
-
upgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
|
|
550
|
-
private open;
|
|
551
|
-
/** Write, unless the socket has stopped reading and its queue is full. */
|
|
552
|
-
private write;
|
|
553
|
-
/** What the transport, or a local publisher, asked of this process. */
|
|
554
|
-
private deliver;
|
|
555
|
-
/** Drop every socket that missed the last ping, and ping the rest. */
|
|
556
|
-
private beat;
|
|
557
|
-
/**
|
|
558
|
-
* Stop: refuse new upgrades, close every socket with `code` — 1012 tells
|
|
559
|
-
* a client to reconnect, and it lands on a process that is still up — and
|
|
560
|
-
* leave the transport.
|
|
561
|
-
*/
|
|
562
|
-
close(code?: number, reason?: string): Promise<void>;
|
|
563
|
-
}
|
|
564
|
-
//#endregion
|
|
565
|
-
//#region src/websocket-api.d.ts
|
|
566
|
-
export interface WebSocketApiConfig<TMessages extends WebSocketMessages = NoMessages> {
|
|
567
|
-
/** The app that serves it, relative to the workspace root. */
|
|
568
|
-
path: string;
|
|
569
|
-
/**
|
|
570
|
-
* What it sends its sockets, by action — each with the schema its `data`
|
|
571
|
-
* is checked by before it is sent.
|
|
572
|
-
*
|
|
573
|
-
* ```ts
|
|
574
|
-
* messages: {
|
|
575
|
-
* announcement: z.object({ text: z.string() }),
|
|
576
|
-
* 'chat.said': z.object({ from: z.string(), text: z.string() }),
|
|
577
|
-
* }
|
|
578
|
-
* ```
|
|
579
|
-
*
|
|
580
|
-
* The publisher is typed by it — `services.realtime.broadcast(
|
|
581
|
-
* 'announcement', { text })` — in an endpoint and in a route's `sockets`
|
|
582
|
-
* alike. Absent, any action and any data go, unchecked.
|
|
583
|
-
*/
|
|
584
|
-
messages?: TMessages;
|
|
585
|
-
/**
|
|
586
|
-
* The shape its frames take. Absent, `{ "action": …, "id"?: …, "data": … }`.
|
|
587
|
-
*
|
|
588
|
-
* With a `discriminator`, frames are flat — the action under that key and
|
|
589
|
-
* the data's fields beside it, both ways, `$error` replies included:
|
|
590
|
-
*
|
|
591
|
-
* ```ts
|
|
592
|
-
* frame: { discriminator: 'type' },
|
|
593
|
-
* // realtime.send(ids, 'chat.message.created', { chatId, message })
|
|
594
|
-
* // wire: {"type":"chat.message.created","chatId":"…","message":{…}}
|
|
595
|
-
* ```
|
|
596
|
-
*
|
|
597
|
-
* Every message must then be an object schema that has no field of that
|
|
598
|
-
* name; one that is not is refused when the surface is built. A flat frame
|
|
599
|
-
* carries no `id`: every other field is the data.
|
|
600
|
-
*/
|
|
601
|
-
frame?: WebSocketFrame;
|
|
602
|
-
/** The label it answers on. Absent, its id kebab-cased. */
|
|
603
|
-
subdomain?: string;
|
|
604
|
-
/** How many processes serve it on one machine. Default 1. */
|
|
605
|
-
replicas?: number;
|
|
606
|
-
logger?: Logger;
|
|
607
|
-
envParser?: EnvironmentParser<{}>;
|
|
608
|
-
telemetry?: Telemetry;
|
|
609
|
-
/** Seconds between pings; a socket that misses one is dropped. Default 30. */
|
|
610
|
-
heartbeat?: number;
|
|
611
|
-
/** The largest frame accepted, in bytes. Default 1 MiB. */
|
|
612
|
-
maxPayload?: number;
|
|
613
|
-
}
|
|
614
|
-
/** A replica count that is not a whole number of at least one. */
|
|
615
|
-
export declare class InvalidReplicaCount extends Error {
|
|
616
|
-
readonly id: string;
|
|
617
|
-
readonly replicas: number;
|
|
618
|
-
constructor(id: string, replicas: number);
|
|
619
|
-
}
|
|
620
|
-
export declare class WebSocketApi<TName extends string = string, TMessages extends WebSocketMessages = NoMessages> implements Declarable<TName> {
|
|
621
|
-
private readonly config;
|
|
622
|
-
/** Internal: how `.auth()` carries the authenticator into its copy. */
|
|
623
|
-
readonly authenticator?: Authenticator | undefined;
|
|
624
|
-
readonly id: TName;
|
|
625
|
-
readonly keys: {
|
|
626
|
-
url: string;
|
|
627
|
-
trustedOrigins: string;
|
|
628
|
-
publisherConnectionString: string;
|
|
629
|
-
};
|
|
630
|
-
readonly logger: Logger;
|
|
631
|
-
readonly envParser: EnvironmentParser<{}>;
|
|
632
|
-
readonly telemetry?: Telemetry;
|
|
633
|
-
/**
|
|
634
|
-
* The shape its frames take — `{ action, data }`, or flat under
|
|
635
|
-
* `discriminator`. What a client of the surface decodes by.
|
|
636
|
-
*/
|
|
637
|
-
readonly frame: {
|
|
638
|
-
readonly discriminator?: string;
|
|
639
|
-
};
|
|
640
|
-
/**
|
|
641
|
-
* The surface as a dependency: `services.<id>` is its publisher, so an
|
|
642
|
-
* endpoint sends to a socket the way a route beside it does.
|
|
643
|
-
*/
|
|
644
|
-
readonly service: Service<Uncapitalize<TName>, WebSocketPublisher<TMessages>>;
|
|
645
|
-
constructor(id: ConstructName<TName>, config: WebSocketApiConfig<TMessages>,
|
|
646
|
-
/** Internal: how `.auth()` carries the authenticator into its copy. */
|
|
647
|
-
authenticator?: Authenticator | undefined);
|
|
648
|
-
/** The handler a connection's upgrade runs: refuse it, or say who it is. */
|
|
649
|
-
connect(): WebSocketRouteBuilder<'connect', undefined, [], TMessages>;
|
|
650
|
-
/** The handler a closed connection runs. */
|
|
651
|
-
disconnect(): WebSocketRouteBuilder<'disconnect', undefined, [], TMessages>;
|
|
652
|
-
/**
|
|
653
|
-
* The handler for frames whose `action` — or, for flat frames, whose
|
|
654
|
-
* discriminator — is `action`. `$default` answers
|
|
655
|
-
* any action nothing else does.
|
|
656
|
-
*/
|
|
657
|
-
route(action: string): WebSocketRouteBuilder<'message', undefined, [], TMessages>;
|
|
658
|
-
/** What authenticates a connection — its session reaches `connect()`. */
|
|
659
|
-
auth(construct: Authenticator): WebSocketApi<TName, TMessages>;
|
|
660
|
-
/**
|
|
661
|
-
* Serve it: the routes exported by `modules` that were built from this
|
|
662
|
-
* surface, on whatever HTTP server `attach` is handed.
|
|
663
|
-
*
|
|
664
|
-
* `app` answers plain HTTP — the generated entry puts `/health` in front
|
|
665
|
-
* of it — and `attach` takes over the server's upgrades. The sockets are
|
|
666
|
-
* closed with 1012 when the server shuts down.
|
|
667
|
-
*/
|
|
668
|
-
server(options: ServiceRegisterOptions & {
|
|
669
|
-
modules?: readonly object[];
|
|
670
|
-
}): Promise<{
|
|
671
|
-
app: Hono;
|
|
672
|
-
attach(server: Server): void;
|
|
673
|
-
/** Close every socket with 1012, so the HTTP server can close. */
|
|
674
|
-
release(): Promise<void>;
|
|
675
|
-
server: WebSocketSurfaceServer<TMessages>;
|
|
676
|
-
}>;
|
|
677
|
-
/**
|
|
678
|
-
* The surface with no socket in it — what every runtime serves. The
|
|
679
|
-
* routes exported by `modules` that were built from this surface answer
|
|
680
|
-
* its frames; `sink` is where its handlers' `sockets` send.
|
|
681
|
-
*
|
|
682
|
-
* `server()` is the Node adaptor over it. Another runtime (a Lambda
|
|
683
|
-
* behind API Gateway, a test) builds one with a sink of its own and
|
|
684
|
-
* calls `connect()`, `message()` and `disconnect()` per connection id.
|
|
685
|
-
*
|
|
686
|
-
* @throws {DuplicateWebSocketRoute} when two routes answer one action.
|
|
687
|
-
*/
|
|
688
|
-
core(options: {
|
|
689
|
-
envParser: EnvironmentParser<{}>;
|
|
690
|
-
sink: WebSocketSink;
|
|
691
|
-
modules?: readonly object[];
|
|
692
|
-
}): WebSocketCore<TMessages>;
|
|
693
|
-
/** The declared messages, with the surface they are checked for. */
|
|
694
|
-
private get declared();
|
|
695
|
-
declare(): Declaration[];
|
|
696
|
-
}
|
|
697
|
-
//#endregion
|
|
698
|
-
export type { ConnectContext, ConnectOutcome, ConnectRequest, Connection, Delivery, DisconnectContext, DisconnectOutcome, MessageAction, MessageContext, MessageData, MessageOutcome, NoMessages, RouteKind, WebSocketCallOptions, WebSocketCoreOptions, WebSocketFrame, WebSocketMessages, WebSocketServerOptions, WebSocketSink, WebSocketTransport, WriteFrame };
|
|
699
|
-
//# sourceMappingURL=websocket-api.d.mts.map
|
|
1
|
+
import { $ as WebSocketSink, A as DuplicateWebSocketRoute, B as RouteKind, C as TestMessageRequest, D as ConnectOutcome, E as WebSocketTestSurface, F as WriteFrame, G as WebSocketRouteResult, H as WebSocketRoute, I as ConnectContext, J as MessageData, K as InvalidWebSocketMessage, L as Connection, M as WebSocketCallOptions, N as WebSocketCore, O as ConnectRequest, P as WebSocketCoreOptions, Q as WebSocketPublisher, R as DisconnectContext, S as TestDisconnectRequest, T as TestWebSocketPublisher, U as WebSocketRouteBuilder, V as TestCallOverrides, W as WebSocketRouteRequest, X as UnknownWebSocketMessage, Y as NoMessages, Z as WebSocketMessages, _ as RecordedMessage, a as WebSocketServerOptions, b as TestConnectRequest, c as MemoryTransport, d as UnsupportedWebSocketTransport, et as WebSocketDataHasDiscriminator, f as WebSocketTransport, g as RecordedClose, h as RecordedBroadcast, i as CLOSE, it as WebSocketMessageNotAnObject, j as MessageOutcome, k as DisconnectOutcome, l as RedisTransport, m as InvalidWebSocketRequest, n as WebSocketApi, nt as WebSocketFrame, o as WebSocketSurfaceServer, p as transportFromConnectionString, q as MessageAction, r as WebSocketApiConfig, rt as WebSocketMessageDeclaresDiscriminator, s as Delivery, t as InvalidReplicaCount, tt as WebSocketDataNotAnObject, u as TransportSink, v as RecordedSend, w as TestMessageResponse, x as TestConnection, y as RecordingSink, z as MessageContext } from "./websocket-api-DSWDhZph.mjs";
|
|
2
|
+
export { CLOSE, type ConnectContext, type ConnectOutcome, type ConnectRequest, type Connection, type Delivery, type DisconnectContext, type DisconnectOutcome, DuplicateWebSocketRoute, InvalidReplicaCount, InvalidWebSocketMessage, InvalidWebSocketRequest, MemoryTransport, type MessageAction, type MessageContext, type MessageData, type MessageOutcome, type NoMessages, type RecordedBroadcast, type RecordedClose, type RecordedMessage, type RecordedSend, RecordingSink, RedisTransport, type RouteKind, type TestCallOverrides, type TestConnectRequest, type TestConnection, type TestDisconnectRequest, type TestMessageRequest, type TestMessageResponse, TestWebSocketPublisher, TransportSink, UnknownWebSocketMessage, UnsupportedWebSocketTransport, WebSocketApi, WebSocketApiConfig, type WebSocketCallOptions, WebSocketCore, type WebSocketCoreOptions, WebSocketDataHasDiscriminator, WebSocketDataNotAnObject, type WebSocketFrame, WebSocketMessageDeclaresDiscriminator, WebSocketMessageNotAnObject, type WebSocketMessages, WebSocketPublisher, WebSocketRoute, WebSocketRouteBuilder, type WebSocketRouteRequest, type WebSocketRouteResult, type WebSocketServerOptions, type WebSocketSink, WebSocketSurfaceServer, type WebSocketTestSurface, type WebSocketTransport, type WriteFrame, transportFromConnectionString };
|