@geekmidas/constructs 10.0.0-alpha.152 → 10.0.0-alpha.154
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/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.cjs +523 -352
- package/dist/websocket-api.cjs.map +1 -1
- package/dist/websocket-api.d.cts +268 -125
- package/dist/websocket-api.d.cts.map +1 -1
- package/dist/websocket-api.d.mts +268 -125
- package/dist/websocket-api.d.mts.map +1 -1
- package/dist/websocket-api.mjs +522 -353
- package/dist/websocket-api.mjs.map +1 -1
- package/package.json +31 -31
package/dist/websocket-api.d.mts
CHANGED
|
@@ -9,94 +9,22 @@ import { Logger } from "@geekmidas/logger";
|
|
|
9
9
|
import { InferStandardSchema } from "@geekmidas/schema";
|
|
10
10
|
import { IncomingMessage, Server } from "node:http";
|
|
11
11
|
import { Duplex } from "node:stream";
|
|
12
|
-
//#region src/websocket/
|
|
13
|
-
/**
|
|
14
|
-
* How a send reaches the process holding the socket.
|
|
15
|
-
*
|
|
16
|
-
* A connection id names the process it lives on — `<instance>.<n>` — so a send
|
|
17
|
-
* needs no registry: it is published to that instance's channel and nowhere
|
|
18
|
-
* else. A broadcast goes to every instance. On a stack the channels are Redis
|
|
19
|
-
* pub/sub, so an endpoint in another container reaches a socket the same way a
|
|
20
|
-
* route beside it does; in one process (a test, a single dev server) they are
|
|
21
|
-
* a map.
|
|
22
|
-
*/
|
|
23
|
-
/** What one process is asked to do with the sockets it holds. */
|
|
24
|
-
type Delivery = {
|
|
25
|
-
kind: 'send';
|
|
26
|
-
ids: readonly string[];
|
|
27
|
-
payload: string;
|
|
28
|
-
} | {
|
|
29
|
-
kind: 'broadcast';
|
|
30
|
-
payload: string;
|
|
31
|
-
except?: readonly string[];
|
|
32
|
-
} | {
|
|
33
|
-
kind: 'close';
|
|
34
|
-
ids: readonly string[];
|
|
35
|
-
code: number;
|
|
36
|
-
reason: string;
|
|
37
|
-
};
|
|
38
|
-
interface WebSocketTransport {
|
|
39
|
-
/** Deliver to one instance, or to every instance when it is `'*'`. */
|
|
40
|
-
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
41
|
-
/** Receive what is published to `instance`, and every broadcast. */
|
|
42
|
-
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
43
|
-
close(): Promise<void>;
|
|
44
|
-
}
|
|
45
|
-
/** A connection string names no transport this package knows. */
|
|
46
|
-
export declare class UnsupportedWebSocketTransport extends Error {
|
|
47
|
-
readonly connectionString: string;
|
|
48
|
-
constructor(connectionString: string);
|
|
49
|
-
}
|
|
50
|
-
/**
|
|
51
|
-
* In one process: the server and whoever sends meet in a map, keyed by the
|
|
52
|
-
* channel the connection string names.
|
|
53
|
-
*/
|
|
54
|
-
export declare class MemoryTransport implements WebSocketTransport {
|
|
55
|
-
private readonly channel;
|
|
56
|
-
private readonly subscribed;
|
|
57
|
-
constructor(channel: string);
|
|
58
|
-
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
59
|
-
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
60
|
-
close(): Promise<void>;
|
|
61
|
-
}
|
|
62
|
-
/** The subset of an ioredis client the transport uses. */
|
|
63
|
-
interface RedisClient {
|
|
64
|
-
publish(channel: string, message: string): Promise<number>;
|
|
65
|
-
subscribe(...channels: string[]): Promise<unknown>;
|
|
66
|
-
on(event: 'message', listener: (channel: string, message: string) => void): unknown;
|
|
67
|
-
duplicate(): RedisClient;
|
|
68
|
-
quit(): Promise<unknown>;
|
|
69
|
-
}
|
|
12
|
+
//#region src/websocket/publisher.d.ts
|
|
70
13
|
/**
|
|
71
|
-
*
|
|
72
|
-
*
|
|
73
|
-
* Channels are not scoped by database index, so the prefix is what does it.
|
|
14
|
+
* Where a publisher's frames go once they are encoded — the one thing a
|
|
15
|
+
* runtime supplies to send to its sockets.
|
|
74
16
|
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
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.
|
|
77
21
|
*/
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
constructor(client: RedisClient, prefix: string);
|
|
84
|
-
private channel;
|
|
85
|
-
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
86
|
-
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
87
|
-
/** Idempotent: the server and a shutdown hook may both close it. */
|
|
88
|
-
close(): Promise<void>;
|
|
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>;
|
|
89
27
|
}
|
|
90
|
-
/**
|
|
91
|
-
* The transport a connection string names.
|
|
92
|
-
*
|
|
93
|
-
* `redis://` and `rediss://` take an optional `channel` query parameter, the
|
|
94
|
-
* prefix every channel is named under; `memory://<channel>` is in-process.
|
|
95
|
-
* Absent, the channel is `fallback` — the surface's own.
|
|
96
|
-
*/
|
|
97
|
-
export declare function transportFromConnectionString(connectionString: string, fallback: string): Promise<WebSocketTransport>;
|
|
98
|
-
//#endregion
|
|
99
|
-
//#region src/websocket/publisher.d.ts
|
|
100
28
|
/**
|
|
101
29
|
* What a surface sends its sockets, by action — `WebSocketApiConfig.messages`.
|
|
102
30
|
*/
|
|
@@ -136,25 +64,15 @@ export declare class InvalidWebSocketMessage extends Error {
|
|
|
136
64
|
* connection is a no-op the sender rarely wants to handle.
|
|
137
65
|
*/
|
|
138
66
|
export declare class WebSocketPublisher<TMessages extends WebSocketMessages = NoMessages> {
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
* Delivers to this process's own sockets without a round trip through
|
|
142
|
-
* the transport — set on the server's own publisher.
|
|
143
|
-
*/
|
|
144
|
-
private readonly local?;
|
|
67
|
+
/** Where an encoded frame goes. */
|
|
68
|
+
private readonly sink;
|
|
145
69
|
/** The surface's declared messages, which every send is checked by. */
|
|
146
70
|
private readonly declared?;
|
|
147
71
|
/** How the surface writes a frame. Absent, `{ action, data }`. */
|
|
148
72
|
private readonly frame;
|
|
149
|
-
constructor(
|
|
150
|
-
/**
|
|
151
|
-
|
|
152
|
-
* the transport — set on the server's own publisher.
|
|
153
|
-
*/
|
|
154
|
-
local?: {
|
|
155
|
-
instance: string;
|
|
156
|
-
deliver(delivery: Delivery): void;
|
|
157
|
-
} | undefined,
|
|
73
|
+
constructor(
|
|
74
|
+
/** Where an encoded frame goes. */
|
|
75
|
+
sink: WebSocketSink,
|
|
158
76
|
/** The surface's declared messages, which every send is checked by. */
|
|
159
77
|
declared?: {
|
|
160
78
|
surface: string;
|
|
@@ -178,8 +96,6 @@ export declare class WebSocketPublisher<TMessages extends WebSocketMessages = No
|
|
|
178
96
|
* flat frame {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator}
|
|
179
97
|
*/
|
|
180
98
|
private payload;
|
|
181
|
-
/** One delivery per process that holds any of `ids`. */
|
|
182
|
-
private each;
|
|
183
99
|
}
|
|
184
100
|
//#endregion
|
|
185
101
|
//#region src/websocket/frame.d.ts
|
|
@@ -338,7 +254,7 @@ TMessages extends WebSocketMessages = NoMessages> {
|
|
|
338
254
|
/** The schema a frame's `data` must satisfy before the handler runs. */
|
|
339
255
|
body<S extends StandardSchemaV1>(schema: S): WebSocketRouteBuilder<TKind, S, TServices, TMessages>;
|
|
340
256
|
/** What the handler reaches, as `services.<id>` — per route, as an endpoint's. */
|
|
341
|
-
dependsOn<const T extends readonly Consumable[]>(constructs: T): WebSocketRouteBuilder<TKind, TSchema, [...TServices, ...
|
|
257
|
+
dependsOn<const T extends readonly Consumable[]>(constructs: T): WebSocketRouteBuilder<TKind, TSchema, [...TServices, ...ServicesOf<T>], TMessages>;
|
|
342
258
|
/**
|
|
343
259
|
* The handler. A message handler's return value, when there is one, is
|
|
344
260
|
* sent back to the connection as the reply to that frame; a connect
|
|
@@ -347,32 +263,249 @@ TMessages extends WebSocketMessages = NoMessages> {
|
|
|
347
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;
|
|
348
264
|
}
|
|
349
265
|
//#endregion
|
|
350
|
-
//#region src/websocket/
|
|
351
|
-
/** Close codes a client sees. */
|
|
352
|
-
export declare const CLOSE: {
|
|
353
|
-
readonly normal: 1000;
|
|
354
|
-
/** The process is stopping; reconnect and land on another. */
|
|
355
|
-
readonly serviceRestart: 1012;
|
|
356
|
-
/** It stopped reading, and what was queued for it passed the limit. */
|
|
357
|
-
readonly tooSlow: 1013;
|
|
358
|
-
};
|
|
266
|
+
//#region src/websocket/core.d.ts
|
|
359
267
|
/** Two routes answer one action. */
|
|
360
268
|
export declare class DuplicateWebSocketRoute extends Error {
|
|
361
269
|
readonly surface: string;
|
|
362
270
|
readonly action: string;
|
|
363
271
|
constructor(surface: string, action: string);
|
|
364
272
|
}
|
|
365
|
-
interface
|
|
273
|
+
interface WebSocketCoreOptions<TMessages extends WebSocketMessages = NoMessages> {
|
|
366
274
|
surface: string;
|
|
275
|
+
/** Every route handed in; those built from another surface are skipped. */
|
|
276
|
+
routes: readonly WebSocketRoute[];
|
|
367
277
|
/** What the surface sends its sockets — see `WebSocketApiConfig.messages`. */
|
|
368
278
|
messages?: TMessages;
|
|
369
279
|
/** The shape its frames take — see `WebSocketApiConfig.frame`. */
|
|
370
280
|
frame?: WebSocketFrame;
|
|
371
|
-
|
|
372
|
-
|
|
281
|
+
/** Where `sockets` sends, in every handler: the adaptor's own. */
|
|
282
|
+
sink: WebSocketSink;
|
|
373
283
|
envParser: EnvironmentParser<{}>;
|
|
374
284
|
logger: Logger;
|
|
285
|
+
/** What turns a handshake's headers into the `session` connect sees. */
|
|
375
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;
|
|
376
509
|
/**
|
|
377
510
|
* Origins a browser may open a socket from. A request with an `Origin`
|
|
378
511
|
* not in the list is refused with 403; one with none — a server, a load
|
|
@@ -397,18 +530,17 @@ export declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages
|
|
|
397
530
|
private readonly options;
|
|
398
531
|
/** This process, as connection ids name it. */
|
|
399
532
|
readonly instance: string;
|
|
400
|
-
/**
|
|
401
|
-
readonly
|
|
533
|
+
/** Where each handshake, frame and close is handed. */
|
|
534
|
+
readonly core: WebSocketCore<TMessages>;
|
|
402
535
|
private readonly held;
|
|
403
|
-
private readonly routes;
|
|
404
|
-
private readonly lifecycle;
|
|
405
536
|
private readonly heartbeat;
|
|
406
|
-
private readonly frame;
|
|
407
537
|
private readonly trusted;
|
|
408
538
|
private next;
|
|
409
539
|
private closing;
|
|
410
540
|
private constructor();
|
|
411
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>;
|
|
412
544
|
/** How many sockets this process holds. */
|
|
413
545
|
get size(): number;
|
|
414
546
|
/** Take over `server`'s upgrades. */
|
|
@@ -416,11 +548,6 @@ export declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages
|
|
|
416
548
|
/** Upgrade one request, or refuse it with a status line. */
|
|
417
549
|
upgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
|
|
418
550
|
private open;
|
|
419
|
-
/** Parse, validate and run one frame. Errors go back as frames, not closes. */
|
|
420
|
-
private dispatch;
|
|
421
|
-
/** Run a handler with its services, inside a request context of its own. */
|
|
422
|
-
private run;
|
|
423
|
-
private error;
|
|
424
551
|
/** Write, unless the socket has stopped reading and its queue is full. */
|
|
425
552
|
private write;
|
|
426
553
|
/** What the transport, or a local publisher, asked of this process. */
|
|
@@ -547,10 +674,26 @@ export declare class WebSocketApi<TName extends string = string, TMessages exten
|
|
|
547
674
|
release(): Promise<void>;
|
|
548
675
|
server: WebSocketSurfaceServer<TMessages>;
|
|
549
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>;
|
|
550
693
|
/** The declared messages, with the surface they are checked for. */
|
|
551
694
|
private get declared();
|
|
552
695
|
declare(): Declaration[];
|
|
553
696
|
}
|
|
554
697
|
//#endregion
|
|
555
|
-
export type { ConnectContext, Connection, Delivery, DisconnectContext, MessageAction, MessageContext, MessageData, NoMessages, RouteKind, WebSocketFrame, WebSocketMessages, WebSocketServerOptions, WebSocketTransport };
|
|
698
|
+
export type { ConnectContext, ConnectOutcome, ConnectRequest, Connection, Delivery, DisconnectContext, DisconnectOutcome, MessageAction, MessageContext, MessageData, MessageOutcome, NoMessages, RouteKind, WebSocketCallOptions, WebSocketCoreOptions, WebSocketFrame, WebSocketMessages, WebSocketServerOptions, WebSocketSink, WebSocketTransport, WriteFrame };
|
|
556
699
|
//# sourceMappingURL=websocket-api.d.mts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"websocket-api.d.mts","names":[],"sources":["../src/websocket/
|
|
1
|
+
{"version":3,"file":"websocket-api.d.mts","names":[],"sources":["../src/websocket/publisher.ts","../src/websocket/frame.ts","../src/websocket/route.ts","../src/websocket/core.ts","../src/websocket/transport.ts","../src/websocket/server.ts","../src/websocket-api.ts"],"mappings":"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"}
|