@geekmidas/constructs 10.0.0-alpha.155 → 10.0.0-alpha.157
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/README.md +24 -0
- package/dist/{Construct-DySlwh8o.d.mts → Construct-BMk_CRSD.d.mts} +2 -2
- package/dist/{Construct-DySlwh8o.d.mts.map → Construct-BMk_CRSD.d.mts.map} +1 -1
- package/dist/{Cron-D8mB_cPX.d.mts → Cron-D6Y7BBt3.d.mts} +5 -5
- package/dist/{Cron-D8mB_cPX.d.mts.map → Cron-D6Y7BBt3.d.mts.map} +1 -1
- package/dist/{CronBuilder-Cmajva3g.d.mts → CronBuilder-4BZhkChG.d.mts} +5 -5
- package/dist/{CronBuilder-Cmajva3g.d.mts.map → CronBuilder-4BZhkChG.d.mts.map} +1 -1
- package/dist/{Endpoint-BbHh3Qoc.d.mts → Endpoint-BUoDD96P.d.mts} +5 -5
- package/dist/{Endpoint-BbHh3Qoc.d.mts.map → Endpoint-BUoDD96P.d.mts.map} +1 -1
- package/dist/{EndpointFactory-qcLzi4f-.d.mts → EndpointFactory-BbVOeryo.d.mts} +5 -5
- package/dist/{EndpointFactory-qcLzi4f-.d.mts.map → EndpointFactory-BbVOeryo.d.mts.map} +1 -1
- package/dist/{Function-DfMzTGS4.d.mts → Function-BKReud5p.d.mts} +3 -3
- package/dist/{Function-DfMzTGS4.d.mts.map → Function-BKReud5p.d.mts.map} +1 -1
- package/dist/{HonoEndpointAdaptor-DR3j7S35.mjs → HonoEndpointAdaptor-2xHA3bvn.mjs} +5 -4
- package/dist/HonoEndpointAdaptor-2xHA3bvn.mjs.map +1 -0
- package/dist/{HonoEndpointAdaptor-BXBdb2Bt.cjs → HonoEndpointAdaptor-CZ1TooUu.cjs} +6 -5
- package/dist/HonoEndpointAdaptor-CZ1TooUu.cjs.map +1 -0
- package/dist/{ObjectSubscriberBuilder-Cv8C7yS1.d.mts → ObjectSubscriberBuilder-DfzXQEKW.d.mts} +4 -4
- package/dist/{ObjectSubscriberBuilder-Cv8C7yS1.d.mts.map → ObjectSubscriberBuilder-DfzXQEKW.d.mts.map} +1 -1
- package/dist/ObjectSubscriberBuilder-LWkey_oq.d.cts.map +1 -1
- package/dist/{ProcessorBuilder-CwfP-M33.d.mts → ProcessorBuilder-D4oYvZeG.d.mts} +2 -2
- package/dist/{ProcessorBuilder-CwfP-M33.d.mts.map → ProcessorBuilder-D4oYvZeG.d.mts.map} +1 -1
- package/dist/{Queue-BnK3UH8r.d.mts → Queue-B8HGg439.d.mts} +3 -3
- package/dist/{Queue-BnK3UH8r.d.mts.map → Queue-B8HGg439.d.mts.map} +1 -1
- package/dist/{QueueBuilder-DmwFtLzQ.d.mts → QueueBuilder-CVS_qPuo.d.mts} +2 -2
- package/dist/{QueueBuilder-DmwFtLzQ.d.mts.map → QueueBuilder-CVS_qPuo.d.mts.map} +1 -1
- package/dist/{Subscriber-CW_Dl-YR.d.mts → Subscriber-CtQXhcL7.d.mts} +3 -3
- package/dist/{Subscriber-CW_Dl-YR.d.mts.map → Subscriber-CtQXhcL7.d.mts.map} +1 -1
- package/dist/{SubscriberBuilder-BL_GTcwh.mjs → SubscriberBuilder-CpFhShTJ.mjs} +3 -2
- package/dist/SubscriberBuilder-CpFhShTJ.mjs.map +1 -0
- package/dist/{SubscriberBuilder-CWzKwX1p.cjs → SubscriberBuilder-DJEvNRdD.cjs} +3 -2
- package/dist/SubscriberBuilder-DJEvNRdD.cjs.map +1 -0
- package/dist/adaptors/aws.cjs +18 -13
- package/dist/adaptors/aws.cjs.map +1 -1
- package/dist/adaptors/aws.d.cts.map +1 -1
- package/dist/adaptors/aws.d.mts +6 -6
- package/dist/adaptors/aws.d.mts.map +1 -1
- package/dist/adaptors/aws.mjs +17 -12
- package/dist/adaptors/aws.mjs.map +1 -1
- package/dist/adaptors/awsWebsocket.cjs +354 -0
- package/dist/adaptors/awsWebsocket.cjs.map +1 -0
- package/dist/adaptors/awsWebsocket.d.cts +156 -0
- package/dist/adaptors/awsWebsocket.d.cts.map +1 -0
- package/dist/adaptors/awsWebsocket.d.mts +156 -0
- package/dist/adaptors/awsWebsocket.d.mts.map +1 -0
- package/dist/adaptors/awsWebsocket.mjs +347 -0
- package/dist/adaptors/awsWebsocket.mjs.map +1 -0
- package/dist/adaptors/hono.cjs +1 -1
- package/dist/adaptors/hono.d.mts +2 -2
- package/dist/adaptors/hono.mjs +1 -1
- package/dist/adaptors/testing.cjs +19 -9
- package/dist/adaptors/testing.cjs.map +1 -1
- package/dist/adaptors/testing.d.cts +1 -1
- package/dist/adaptors/testing.d.cts.map +1 -1
- package/dist/adaptors/testing.d.mts +9 -9
- package/dist/adaptors/testing.d.mts.map +1 -1
- package/dist/adaptors/testing.mjs +17 -7
- package/dist/adaptors/testing.mjs.map +1 -1
- package/dist/auth-BqWz2JxC.d.cts.map +1 -1
- package/dist/auth-DnB9H9KL.d.mts.map +1 -1
- package/dist/auth.cjs +7 -21
- package/dist/auth.cjs.map +1 -1
- package/dist/auth.mjs +6 -20
- package/dist/auth.mjs.map +1 -1
- package/dist/{cache-e3tfMQ9g.d.mts → cache-CCHcO9Oo.d.mts} +2 -2
- package/dist/cache-CCHcO9Oo.d.mts.map +1 -0
- package/dist/cache-CQjMNPrC.d.cts.map +1 -1
- package/dist/cache.cjs +3 -19
- package/dist/cache.cjs.map +1 -1
- package/dist/cache.d.mts +1 -1
- package/dist/cache.mjs +2 -18
- package/dist/cache.mjs.map +1 -1
- package/dist/crons/index.cjs +2 -1
- package/dist/crons/index.cjs.map +1 -1
- package/dist/crons/index.d.cts.map +1 -1
- package/dist/crons/index.d.mts +2 -2
- package/dist/crons/index.d.mts.map +1 -1
- package/dist/crons/index.mjs +2 -1
- package/dist/crons/index.mjs.map +1 -1
- package/dist/database/kysely.d.mts +1 -1
- package/dist/email.cjs +4 -16
- package/dist/email.cjs.map +1 -1
- package/dist/email.d.cts.map +1 -1
- package/dist/email.d.mts.map +1 -1
- package/dist/email.mjs +2 -14
- package/dist/email.mjs.map +1 -1
- package/dist/endpoints/index.cjs +1 -1
- package/dist/endpoints/index.d.cts +1 -1
- package/dist/endpoints/index.d.cts.map +1 -1
- package/dist/endpoints/index.d.mts +4 -4
- package/dist/endpoints/index.d.mts.map +1 -1
- package/dist/endpoints/index.mjs +1 -1
- package/dist/file-server.d.mts +1 -1
- package/dist/functions/index.d.mts +2 -2
- package/dist/{inbox-CjxpLVkH.d.mts → inbox-YOdxlyfj.d.mts} +2 -2
- package/dist/{inbox-CjxpLVkH.d.mts.map → inbox-YOdxlyfj.d.mts.map} +1 -1
- package/dist/inbox.d.mts +1 -1
- package/dist/{index-DCkDQkwj.d.mts → index-BoQ3-M-K.d.mts} +4 -4
- package/dist/{index-DCkDQkwj.d.mts.map → index-BoQ3-M-K.d.mts.map} +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/{kysely-DE4kADWD.d.mts → kysely-De5rAC-E.d.mts} +2 -2
- package/dist/{kysely-DE4kADWD.d.mts.map → kysely-De5rAC-E.d.mts.map} +1 -1
- package/dist/optionalPeers-D7Wt6dnF.mjs +140 -0
- package/dist/optionalPeers-D7Wt6dnF.mjs.map +1 -0
- package/dist/optionalPeers-DuNQXXe1.cjs +223 -0
- package/dist/optionalPeers-DuNQXXe1.cjs.map +1 -0
- package/dist/origins-BjxYht13.cjs +96 -0
- package/dist/origins-BjxYht13.cjs.map +1 -0
- package/dist/origins-Boc9qbo-.mjs +73 -0
- package/dist/origins-Boc9qbo-.mjs.map +1 -0
- package/dist/privateAddress-Bg5fUsbp.mjs +21 -0
- package/dist/privateAddress-Bg5fUsbp.mjs.map +1 -0
- package/dist/privateAddress-CqGyuFHn.cjs +26 -0
- package/dist/privateAddress-CqGyuFHn.cjs.map +1 -0
- package/dist/processors/index.d.mts +1 -1
- package/dist/queue/index.d.mts +2 -2
- package/dist/{readRequestBody-BTIl3k-D.mjs → readRequestBody-BmKnPl0a.mjs} +26 -4
- package/dist/readRequestBody-BmKnPl0a.mjs.map +1 -0
- package/dist/{readRequestBody-Dej_L3c4.cjs → readRequestBody-CN9GVdeE.cjs} +26 -4
- package/dist/readRequestBody-CN9GVdeE.cjs.map +1 -0
- package/dist/{requestLogger-BZcXwdBs.cjs → requestLogger-CnoYd-Ah.cjs} +4 -63
- package/dist/requestLogger-CnoYd-Ah.cjs.map +1 -0
- package/dist/{requestLogger-pA4gi3E1.mjs → requestLogger-D2JS7pPM.mjs} +3 -56
- package/dist/requestLogger-D2JS7pPM.mjs.map +1 -0
- package/dist/rest-api.d.mts +2 -2
- package/dist/{runSubscriber-DyHWp_Lf.mjs → runSubscriber-HEqXkin1.mjs} +3 -2
- package/dist/runSubscriber-HEqXkin1.mjs.map +1 -0
- package/dist/{runSubscriber-CC_2C9F2.cjs → runSubscriber-sVJfLA0-.cjs} +3 -2
- package/dist/runSubscriber-sVJfLA0-.cjs.map +1 -0
- package/dist/subscribers/index.cjs +6 -6
- package/dist/subscribers/index.cjs.map +1 -1
- package/dist/subscribers/index.d.cts +1 -1
- package/dist/subscribers/index.d.mts +3 -3
- package/dist/subscribers/index.mjs +3 -3
- package/dist/subscribers/index.mjs.map +1 -1
- package/dist/topic/index.d.mts +1 -1
- package/dist/{websocket-api-Dn_3Y2fI.mjs → websocket-api-Bg9SowJ5.mjs} +452 -44
- package/dist/websocket-api-Bg9SowJ5.mjs.map +1 -0
- package/dist/{websocket-api-DSWDhZph.d.mts → websocket-api-CPEzJyDt.d.mts} +501 -208
- package/dist/websocket-api-CPEzJyDt.d.mts.map +1 -0
- package/dist/{websocket-api-CLnV_7CB.d.cts → websocket-api-DkF8Hva-.d.cts} +501 -208
- package/dist/websocket-api-DkF8Hva-.d.cts.map +1 -0
- package/dist/{websocket-api-9bXfgrqd.cjs → websocket-api-czxhekGG.cjs} +493 -43
- package/dist/websocket-api-czxhekGG.cjs.map +1 -0
- package/dist/websocket-api.cjs +11 -1
- package/dist/websocket-api.d.cts +2 -2
- package/dist/websocket-api.d.mts +2 -2
- package/dist/websocket-api.mjs +3 -2
- package/dist/worker.cjs +1 -1
- package/dist/worker.d.mts +9 -9
- package/dist/worker.mjs +1 -1
- package/package.json +57 -31
- package/dist/HonoEndpointAdaptor-BXBdb2Bt.cjs.map +0 -1
- package/dist/HonoEndpointAdaptor-DR3j7S35.mjs.map +0 -1
- package/dist/SubscriberBuilder-BL_GTcwh.mjs.map +0 -1
- package/dist/SubscriberBuilder-CWzKwX1p.cjs.map +0 -1
- package/dist/cache-e3tfMQ9g.d.mts.map +0 -1
- package/dist/readRequestBody-BTIl3k-D.mjs.map +0 -1
- package/dist/readRequestBody-Dej_L3c4.cjs.map +0 -1
- package/dist/requestLogger-BZcXwdBs.cjs.map +0 -1
- package/dist/requestLogger-pA4gi3E1.mjs.map +0 -1
- package/dist/runSubscriber-CC_2C9F2.cjs.map +0 -1
- package/dist/runSubscriber-DyHWp_Lf.mjs.map +0 -1
- package/dist/websocket-api-9bXfgrqd.cjs.map +0 -1
- package/dist/websocket-api-CLnV_7CB.d.cts.map +0 -1
- package/dist/websocket-api-DSWDhZph.d.mts.map +0 -1
- package/dist/websocket-api-Dn_3Y2fI.mjs.map +0 -1
|
@@ -9,77 +9,6 @@ import { ConstructName, Declaration } from "@geekmidas/manifest";
|
|
|
9
9
|
import { Hono } from "hono";
|
|
10
10
|
import { IncomingMessage, Server } from "node:http";
|
|
11
11
|
import { Duplex } from "node:stream";
|
|
12
|
-
//#region src/websocket/frame.d.ts
|
|
13
|
-
/** `WebSocketApiConfig.frame`: where a flat frame keeps its action. */
|
|
14
|
-
interface WebSocketFrame {
|
|
15
|
-
/** The key a frame's action lives in — `type` for `{ "type": … }`. */
|
|
16
|
-
discriminator: string;
|
|
17
|
-
}
|
|
18
|
-
/** A frame as the server reads it, whatever shape it arrived in. */
|
|
19
|
-
interface DecodedFrame {
|
|
20
|
-
action: string;
|
|
21
|
-
/** Echoed on the reply. Only an `{ action, data }` frame carries one. */
|
|
22
|
-
id?: string | number;
|
|
23
|
-
data?: unknown;
|
|
24
|
-
}
|
|
25
|
-
/** A declared message whose schema does not describe an object. */
|
|
26
|
-
declare class WebSocketMessageNotAnObject extends Error {
|
|
27
|
-
readonly surface: string;
|
|
28
|
-
readonly action: string;
|
|
29
|
-
readonly discriminator: string;
|
|
30
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
31
|
-
}
|
|
32
|
-
/** A declared message whose schema has a field named the discriminator. */
|
|
33
|
-
declare class WebSocketMessageDeclaresDiscriminator extends Error {
|
|
34
|
-
readonly surface: string;
|
|
35
|
-
readonly action: string;
|
|
36
|
-
readonly discriminator: string;
|
|
37
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
38
|
-
}
|
|
39
|
-
/** Data sent in a flat frame that is not an object. */
|
|
40
|
-
declare class WebSocketDataNotAnObject extends Error {
|
|
41
|
-
readonly surface: string;
|
|
42
|
-
readonly action: string;
|
|
43
|
-
readonly discriminator: string;
|
|
44
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
45
|
-
}
|
|
46
|
-
/** Data sent in a flat frame that carries the discriminator itself. */
|
|
47
|
-
declare class WebSocketDataHasDiscriminator extends Error {
|
|
48
|
-
readonly surface: string;
|
|
49
|
-
readonly action: string;
|
|
50
|
-
readonly discriminator: string;
|
|
51
|
-
constructor(surface: string, action: string, discriminator: string);
|
|
52
|
-
}
|
|
53
|
-
/** How one surface writes and reads its frames. */
|
|
54
|
-
declare class FrameShape {
|
|
55
|
-
readonly surface: string;
|
|
56
|
-
/** The flat frame's key; absent, frames are `{ action, data }`. */
|
|
57
|
-
readonly discriminator?: string | undefined;
|
|
58
|
-
constructor(surface: string,
|
|
59
|
-
/** The flat frame's key; absent, frames are `{ action, data }`. */
|
|
60
|
-
discriminator?: string | undefined);
|
|
61
|
-
/** The key an inbound frame names its action under. */
|
|
62
|
-
get key(): string;
|
|
63
|
-
/**
|
|
64
|
-
* The frame for `action`'s `data`, serialised.
|
|
65
|
-
*
|
|
66
|
-
* @throws {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator} for
|
|
67
|
-
* a flat frame whose data cannot sit beside the discriminator.
|
|
68
|
-
*/
|
|
69
|
-
encode(action: string, data: unknown, id?: string | number): string;
|
|
70
|
-
/** A parsed frame's action, id and data — `undefined` when it names none. */
|
|
71
|
-
decode(frame: unknown): DecodedFrame | undefined;
|
|
72
|
-
/** The id a frame that names no action carried, to echo on its error. */
|
|
73
|
-
idOf(frame: unknown): string | number | undefined;
|
|
74
|
-
/**
|
|
75
|
-
* Refuse a declared message a flat frame cannot carry: one that is not an
|
|
76
|
-
* object, or that has a field named the discriminator.
|
|
77
|
-
*
|
|
78
|
-
* @throws {WebSocketMessageNotAnObject}, {WebSocketMessageDeclaresDiscriminator}
|
|
79
|
-
*/
|
|
80
|
-
check(messages: WebSocketMessages): void;
|
|
81
|
-
}
|
|
82
|
-
//#endregion
|
|
83
12
|
//#region src/websocket/publisher.d.ts
|
|
84
13
|
/**
|
|
85
14
|
* Where a publisher's frames go once they are encoded — the one thing a
|
|
@@ -169,6 +98,225 @@ declare class WebSocketPublisher<TMessages extends WebSocketMessages = NoMessage
|
|
|
169
98
|
private payload;
|
|
170
99
|
}
|
|
171
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
|
+
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
|
+
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
|
+
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
|
+
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/testing.d.ts
|
|
173
|
+
/** One recorded message: its action and data, and the frame on the wire. */
|
|
174
|
+
type RecordedMessage<TMessages extends WebSocketMessages = NoMessages> = [keyof TMessages] extends [never] ? {
|
|
175
|
+
action: string;
|
|
176
|
+
data: unknown;
|
|
177
|
+
frame: Record<string, unknown>;
|
|
178
|
+
} : { [A in keyof TMessages & string]: {
|
|
179
|
+
action: A;
|
|
180
|
+
/** As its schema returned it — what the client receives. */
|
|
181
|
+
data: StandardSchemaV1.InferOutput<TMessages[A]>;
|
|
182
|
+
/** The frame as the client parses it — the wire shape. */
|
|
183
|
+
frame: Record<string, unknown>;
|
|
184
|
+
}; }[keyof TMessages & string];
|
|
185
|
+
/** A `send(ids, …)`, as it was recorded. */
|
|
186
|
+
type RecordedSend<TMessages extends WebSocketMessages = NoMessages> = RecordedMessage<TMessages> & {
|
|
187
|
+
ids: string[];
|
|
188
|
+
};
|
|
189
|
+
/** A `broadcast(…)`, as it was recorded. */
|
|
190
|
+
type RecordedBroadcast<TMessages extends WebSocketMessages = NoMessages> = RecordedMessage<TMessages> & {
|
|
191
|
+
except: string[];
|
|
192
|
+
};
|
|
193
|
+
/** A `close(ids, code, reason)`, as it was recorded. */
|
|
194
|
+
interface RecordedClose {
|
|
195
|
+
ids: string[];
|
|
196
|
+
code: number;
|
|
197
|
+
reason: string;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* A sink that keeps what it is handed, decoded by the surface's frame shape,
|
|
201
|
+
* and sends it nowhere.
|
|
202
|
+
*/
|
|
203
|
+
declare class RecordingSink implements WebSocketSink {
|
|
204
|
+
private readonly frame;
|
|
205
|
+
readonly sent: RecordedSend<any>[];
|
|
206
|
+
readonly broadcasts: RecordedBroadcast<any>[];
|
|
207
|
+
readonly closed: RecordedClose[];
|
|
208
|
+
constructor(frame: FrameShape);
|
|
209
|
+
send(ids: readonly string[], payload: string): Promise<void>;
|
|
210
|
+
broadcast(payload: string, except?: readonly string[]): Promise<void>;
|
|
211
|
+
close(ids: readonly string[], code: number, reason: string): Promise<void>;
|
|
212
|
+
clear(): void;
|
|
213
|
+
private decode;
|
|
214
|
+
}
|
|
215
|
+
/**
|
|
216
|
+
* A surface's publisher that records rather than sends — what
|
|
217
|
+
* `surface.testPublisher()` returns, of the type `services.<surface>` is.
|
|
218
|
+
*
|
|
219
|
+
* Every send is still checked by the declared `messages` and encoded by the
|
|
220
|
+
* surface's `frame`, so an invalid push fails the spec as it would fail
|
|
221
|
+
* deployed, and `frame` on each record is what the client would parse.
|
|
222
|
+
*/
|
|
223
|
+
declare class TestWebSocketPublisher<TMessages extends WebSocketMessages = NoMessages> extends WebSocketPublisher<TMessages> {
|
|
224
|
+
/** Where the records are kept — what `route.request()` builds its core on. */
|
|
225
|
+
readonly recording: RecordingSink;
|
|
226
|
+
constructor(frame: FrameShape, declared?: {
|
|
227
|
+
surface: string;
|
|
228
|
+
messages: TMessages;
|
|
229
|
+
});
|
|
230
|
+
/** Each `send(ids, action, data)`, in order. */
|
|
231
|
+
get sent(): readonly RecordedSend<TMessages>[];
|
|
232
|
+
/** Each `broadcast(action, data, { except })`, in order. */
|
|
233
|
+
get broadcasts(): readonly RecordedBroadcast<TMessages>[];
|
|
234
|
+
/** Each `close(ids, code, reason)`, in order. */
|
|
235
|
+
get closed(): readonly RecordedClose[];
|
|
236
|
+
/** Forget everything recorded so far. */
|
|
237
|
+
clear(): void;
|
|
238
|
+
}
|
|
239
|
+
/** A frame `route.request()` sent was refused before its handler ran. */
|
|
240
|
+
declare class InvalidWebSocketRequest extends Error {
|
|
241
|
+
readonly surface: string;
|
|
242
|
+
readonly action: string;
|
|
243
|
+
/** What the `$error` frame said. */
|
|
244
|
+
readonly reason: string;
|
|
245
|
+
readonly issues?: readonly StandardSchemaV1.Issue[] | undefined;
|
|
246
|
+
constructor(surface: string, action: string,
|
|
247
|
+
/** What the `$error` frame said. */
|
|
248
|
+
reason: string, issues?: readonly StandardSchemaV1.Issue[] | undefined);
|
|
249
|
+
}
|
|
250
|
+
/** What a surface hands its routes' `request()`. */
|
|
251
|
+
interface WebSocketTestSurface {
|
|
252
|
+
readonly id: string;
|
|
253
|
+
core(options: {
|
|
254
|
+
envParser: EnvironmentParser<{}>;
|
|
255
|
+
sink: WebSocketSink;
|
|
256
|
+
modules?: readonly object[];
|
|
257
|
+
}): WebSocketCore<any>;
|
|
258
|
+
readonly envParser: EnvironmentParser<{}>;
|
|
259
|
+
testPublisher(): TestWebSocketPublisher<any>;
|
|
260
|
+
}
|
|
261
|
+
/** Overrides every `request()` takes. */
|
|
262
|
+
interface WebSocketTestCallOptions {
|
|
263
|
+
/**
|
|
264
|
+
* Instances for the route's dependencies, by service name — a test's
|
|
265
|
+
* transaction for `database`. Any it depends on and is not handed here is
|
|
266
|
+
* registered, as deployed.
|
|
267
|
+
*/
|
|
268
|
+
services?: Record<string, unknown>;
|
|
269
|
+
/**
|
|
270
|
+
* The handler's `sockets`. Pass `surface.testPublisher()` to assert what
|
|
271
|
+
* it sent; absent, a fresh one that nobody reads.
|
|
272
|
+
*/
|
|
273
|
+
sockets?: TestWebSocketPublisher<any>;
|
|
274
|
+
}
|
|
275
|
+
interface TestConnectRequest extends WebSocketTestCallOptions {
|
|
276
|
+
/** The id the connection is given. Absent, `test.<n>`. */
|
|
277
|
+
connectionId?: string;
|
|
278
|
+
/** The handshake's headers — what `.auth()` verifies without a `session`. */
|
|
279
|
+
headers?: ConstructorParameters<typeof Headers>[0];
|
|
280
|
+
/** The upgrade URL's query. */
|
|
281
|
+
query?: string | Record<string, string> | URLSearchParams;
|
|
282
|
+
/**
|
|
283
|
+
* What the surface's `.auth()` would have resolved — `null` for no
|
|
284
|
+
* session. Absent, `.auth()` verifies `headers`, as on a real upgrade.
|
|
285
|
+
*/
|
|
286
|
+
session?: unknown;
|
|
287
|
+
}
|
|
288
|
+
interface TestMessageRequest<TBody = unknown> extends WebSocketTestCallOptions {
|
|
289
|
+
/** The connection the frame arrives on. Absent, `test.<n>` with no data. */
|
|
290
|
+
connection?: TestConnection;
|
|
291
|
+
/** The frame's data — checked by the route's `body`, as a frame's is. */
|
|
292
|
+
body: TBody;
|
|
293
|
+
/** The frame's `id`, echoed on its reply. Only `{ action, data }` frames. */
|
|
294
|
+
id?: string | number;
|
|
295
|
+
}
|
|
296
|
+
interface TestDisconnectRequest extends WebSocketTestCallOptions {
|
|
297
|
+
/** The connection that closed. Absent, `test.<n>` with no data. */
|
|
298
|
+
connection?: TestConnection;
|
|
299
|
+
/** Default 1000. */
|
|
300
|
+
code?: number;
|
|
301
|
+
/** Default ''. */
|
|
302
|
+
reason?: string;
|
|
303
|
+
}
|
|
304
|
+
/** A connection a test names: either part may be left to its default. */
|
|
305
|
+
interface TestConnection {
|
|
306
|
+
id?: string;
|
|
307
|
+
data?: Record<string, unknown>;
|
|
308
|
+
}
|
|
309
|
+
/** What a message route's `fullRequest()` resolves with. */
|
|
310
|
+
interface TestMessageResponse<TReturned = unknown> {
|
|
311
|
+
/** The handler's return — the reply, before it was encoded. */
|
|
312
|
+
returned: TReturned;
|
|
313
|
+
/**
|
|
314
|
+
* Every frame written back to the connection, parsed, in order: each
|
|
315
|
+
* `reply()` and the reply to the frame itself.
|
|
316
|
+
*/
|
|
317
|
+
frames: unknown[];
|
|
318
|
+
}
|
|
319
|
+
//#endregion
|
|
172
320
|
//#region src/websocket/route.d.ts
|
|
173
321
|
/** One open connection, as a handler sees it. */
|
|
174
322
|
interface Connection {
|
|
@@ -423,152 +571,183 @@ declare class WebSocketCore<TMessages extends WebSocketMessages = NoMessages> {
|
|
|
423
571
|
private error;
|
|
424
572
|
}
|
|
425
573
|
//#endregion
|
|
426
|
-
//#region src/websocket/
|
|
427
|
-
/**
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
frame: Record<string, unknown>;
|
|
432
|
-
} : { [A in keyof TMessages & string]: {
|
|
433
|
-
action: A;
|
|
434
|
-
/** As its schema returned it — what the client receives. */
|
|
435
|
-
data: StandardSchemaV1.InferOutput<TMessages[A]>;
|
|
436
|
-
/** The frame as the client parses it — the wire shape. */
|
|
437
|
-
frame: Record<string, unknown>;
|
|
438
|
-
}; }[keyof TMessages & string];
|
|
439
|
-
/** A `send(ids, …)`, as it was recorded. */
|
|
440
|
-
type RecordedSend<TMessages extends WebSocketMessages = NoMessages> = RecordedMessage<TMessages> & {
|
|
441
|
-
ids: string[];
|
|
574
|
+
//#region src/websocket/limits.d.ts
|
|
575
|
+
/** Close codes the limits close a socket with. */
|
|
576
|
+
declare const LIMIT_CLOSE: {
|
|
577
|
+
/** Policy violation: it kept sending past its rate, or its identity has too many sockets. */
|
|
578
|
+
readonly policy: 1008;
|
|
442
579
|
};
|
|
443
|
-
/** A `broadcast(…)`, as it was recorded. */
|
|
444
|
-
type RecordedBroadcast<TMessages extends WebSocketMessages = NoMessages> = RecordedMessage<TMessages> & {
|
|
445
|
-
except: string[];
|
|
446
|
-
};
|
|
447
|
-
/** A `close(ids, code, reason)`, as it was recorded. */
|
|
448
|
-
interface RecordedClose {
|
|
449
|
-
ids: string[];
|
|
450
|
-
code: number;
|
|
451
|
-
reason: string;
|
|
452
|
-
}
|
|
453
580
|
/**
|
|
454
|
-
*
|
|
455
|
-
*
|
|
581
|
+
* What one client may ask of the surface. Every limit is on by default; set
|
|
582
|
+
* one to `false` to lift it.
|
|
456
583
|
*/
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
584
|
+
interface WebSocketLimits<TData = Record<string, unknown>> {
|
|
585
|
+
/**
|
|
586
|
+
* Handshakes one client address may start in a minute, across every
|
|
587
|
+
* replica. Past it, an upgrade is answered 429 with `Retry-After` before
|
|
588
|
+
* the connect handler — and the session lookup it makes — runs.
|
|
589
|
+
* Default 120.
|
|
590
|
+
*/
|
|
591
|
+
handshakesPerMinute?: number | false;
|
|
592
|
+
/**
|
|
593
|
+
* Handshakes one client address may have in flight at once — waiting on
|
|
594
|
+
* the connect handler. Past it, 429. Default 16.
|
|
595
|
+
*/
|
|
596
|
+
inFlightHandshakes?: number | false;
|
|
597
|
+
/**
|
|
598
|
+
* Open sockets one client address may hold, across every replica. Past
|
|
599
|
+
* it, a new upgrade is answered 429. Default 256: many people share an
|
|
600
|
+
* address behind a NAT.
|
|
601
|
+
*/
|
|
602
|
+
connectionsPerIp?: number | false;
|
|
603
|
+
/**
|
|
604
|
+
* Frames one socket may send a second, refilled continuously. Past it, a
|
|
605
|
+
* frame is dropped and the socket is sent one `$error`; if it keeps
|
|
606
|
+
* sending before its budget refills, it is closed with 1008. Default 50.
|
|
607
|
+
*/
|
|
608
|
+
messagesPerSecond?: number | false;
|
|
609
|
+
/** Frames a socket may send at once before the rate applies. Default 100. */
|
|
610
|
+
burst?: number;
|
|
611
|
+
/**
|
|
612
|
+
* Who a connection is, for {@link maxConnections}: a key read from what
|
|
613
|
+
* the connect handler returned — `(data) => data.userId`. Absent, or
|
|
614
|
+
* `undefined` for a connection, its sockets are not counted per identity.
|
|
615
|
+
*/
|
|
616
|
+
maxConnectionsPer?: (data: TData) => string | undefined;
|
|
617
|
+
/**
|
|
618
|
+
* Sockets one identity may hold, across every replica. Default 16, and
|
|
619
|
+
* only with {@link maxConnectionsPer}.
|
|
620
|
+
*/
|
|
621
|
+
maxConnections?: number;
|
|
622
|
+
/**
|
|
623
|
+
* What a socket over {@link maxConnections} does: `'refuse'` answers the
|
|
624
|
+
* new upgrade 429; `'closeOldest'` lets it in and closes that identity's
|
|
625
|
+
* oldest sockets with 1008 — a user who opened a new tab keeps it.
|
|
626
|
+
* Default `'refuse'`.
|
|
627
|
+
*/
|
|
628
|
+
overflow?: 'refuse' | 'closeOldest';
|
|
468
629
|
}
|
|
469
|
-
/**
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
readonly recording: RecordingSink;
|
|
480
|
-
constructor(frame: FrameShape, declared?: {
|
|
481
|
-
surface: string;
|
|
482
|
-
messages: TMessages;
|
|
483
|
-
});
|
|
484
|
-
/** Each `send(ids, action, data)`, in order. */
|
|
485
|
-
get sent(): readonly RecordedSend<TMessages>[];
|
|
486
|
-
/** Each `broadcast(action, data, { except })`, in order. */
|
|
487
|
-
get broadcasts(): readonly RecordedBroadcast<TMessages>[];
|
|
488
|
-
/** Each `close(ids, code, reason)`, in order. */
|
|
489
|
-
get closed(): readonly RecordedClose[];
|
|
490
|
-
/** Forget everything recorded so far. */
|
|
491
|
-
clear(): void;
|
|
630
|
+
/** The limits with every default filled in; `undefined` is off. */
|
|
631
|
+
interface ResolvedWebSocketLimits {
|
|
632
|
+
handshakesPerMinute?: number;
|
|
633
|
+
inFlightHandshakes?: number;
|
|
634
|
+
connectionsPerIp?: number;
|
|
635
|
+
messagesPerSecond?: number;
|
|
636
|
+
burst: number;
|
|
637
|
+
maxConnectionsPer?: (data: Record<string, unknown>) => string | undefined;
|
|
638
|
+
maxConnections: number;
|
|
639
|
+
overflow: 'refuse' | 'closeOldest';
|
|
492
640
|
}
|
|
493
|
-
|
|
494
|
-
|
|
641
|
+
declare const DEFAULT_WEBSOCKET_LIMITS: {
|
|
642
|
+
readonly handshakesPerMinute: 120;
|
|
643
|
+
readonly inFlightHandshakes: 16;
|
|
644
|
+
readonly connectionsPerIp: 256;
|
|
645
|
+
readonly messagesPerSecond: 50;
|
|
646
|
+
readonly burst: 100;
|
|
647
|
+
readonly maxConnections: 16;
|
|
648
|
+
};
|
|
649
|
+
/** A limit that is not a whole number of at least one. */
|
|
650
|
+
declare class InvalidWebSocketLimit extends Error {
|
|
495
651
|
readonly surface: string;
|
|
496
|
-
readonly
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
readonly issues?: readonly StandardSchemaV1.Issue[] | undefined;
|
|
500
|
-
constructor(surface: string, action: string,
|
|
501
|
-
/** What the `$error` frame said. */
|
|
502
|
-
reason: string, issues?: readonly StandardSchemaV1.Issue[] | undefined);
|
|
652
|
+
readonly limit: string;
|
|
653
|
+
readonly value: unknown;
|
|
654
|
+
constructor(surface: string, limit: string, value: unknown);
|
|
503
655
|
}
|
|
504
|
-
/**
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
interface WebSocketTestCallOptions {
|
|
517
|
-
/**
|
|
518
|
-
* Instances for the route's dependencies, by service name — a test's
|
|
519
|
-
* transaction for `database`. Any it depends on and is not handed here is
|
|
520
|
-
* registered, as deployed.
|
|
521
|
-
*/
|
|
522
|
-
services?: Record<string, unknown>;
|
|
656
|
+
/**
|
|
657
|
+
* Fill in the defaults.
|
|
658
|
+
*
|
|
659
|
+
* @throws {InvalidWebSocketLimit} for a limit that is not a positive integer.
|
|
660
|
+
*/
|
|
661
|
+
declare function resolveLimits(surface: string, limits?: WebSocketLimits<any>): ResolvedWebSocketLimits;
|
|
662
|
+
/**
|
|
663
|
+
* Where a surface's limits are counted. Every replica of a surface must see
|
|
664
|
+
* the same store for a limit to hold across them: the Redis transport's own
|
|
665
|
+
* Redis, or — in one process — memory.
|
|
666
|
+
*/
|
|
667
|
+
interface WebSocketLimitStore {
|
|
523
668
|
/**
|
|
524
|
-
*
|
|
525
|
-
*
|
|
669
|
+
* Count one more hit in the window `key` names, opening a window of
|
|
670
|
+
* `windowMs` on the first. Atomic: concurrent handshakes are each counted.
|
|
526
671
|
*/
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
connectionId?: string;
|
|
532
|
-
/** The handshake's headers — what `.auth()` verifies without a `session`. */
|
|
533
|
-
headers?: ConstructorParameters<typeof Headers>[0];
|
|
534
|
-
/** The upgrade URL's query. */
|
|
535
|
-
query?: string | Record<string, string> | URLSearchParams;
|
|
672
|
+
hit(key: string, windowMs: number): Promise<{
|
|
673
|
+
count: number;
|
|
674
|
+
resetMs: number;
|
|
675
|
+
}>;
|
|
536
676
|
/**
|
|
537
|
-
*
|
|
538
|
-
*
|
|
677
|
+
* Hold `member` in the set `key` until `ttlMs` from now — or until
|
|
678
|
+
* {@link release}d — and return every member still held, oldest first.
|
|
679
|
+
* A member a dead process never released lapses when its time is up.
|
|
539
680
|
*/
|
|
540
|
-
|
|
681
|
+
hold(key: string, member: string, ttlMs: number): Promise<string[]>;
|
|
682
|
+
/** Let `member` go. */
|
|
683
|
+
release(key: string, member: string): Promise<void>;
|
|
684
|
+
/** Hold each of `held` for another `ttlMs`. */
|
|
685
|
+
renew(held: readonly {
|
|
686
|
+
key: string;
|
|
687
|
+
member: string;
|
|
688
|
+
}[], ttlMs: number): Promise<void>;
|
|
541
689
|
}
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
690
|
+
/**
|
|
691
|
+
* In one process. Two servers on one `memory://` channel — replicas in a
|
|
692
|
+
* test — share it, as they share the channel.
|
|
693
|
+
*/
|
|
694
|
+
declare class MemoryLimitStore implements WebSocketLimitStore {
|
|
695
|
+
private readonly windows;
|
|
696
|
+
/** key → member → [opened, expires] */
|
|
697
|
+
private readonly sets;
|
|
698
|
+
hit(key: string, windowMs: number): Promise<{
|
|
699
|
+
count: number;
|
|
700
|
+
resetMs: number;
|
|
701
|
+
}>;
|
|
702
|
+
hold(key: string, member: string, ttlMs: number): Promise<string[]>;
|
|
703
|
+
release(key: string, member: string): Promise<void>;
|
|
704
|
+
renew(held: readonly {
|
|
705
|
+
key: string;
|
|
706
|
+
member: string;
|
|
707
|
+
}[], ttlMs: number): Promise<void>;
|
|
549
708
|
}
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
/** Default 1000. */
|
|
554
|
-
code?: number;
|
|
555
|
-
/** Default ''. */
|
|
556
|
-
reason?: string;
|
|
709
|
+
/** The subset of an ioredis client the Redis store uses. */
|
|
710
|
+
interface RedisEvalClient {
|
|
711
|
+
eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
|
|
557
712
|
}
|
|
558
|
-
/**
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
713
|
+
/**
|
|
714
|
+
* Over Redis — the transport's own — so every replica counts in one place.
|
|
715
|
+
* Each operation is one script, so concurrent handshakes on any replica are
|
|
716
|
+
* each counted.
|
|
717
|
+
*/
|
|
718
|
+
declare class RedisLimitStore implements WebSocketLimitStore {
|
|
719
|
+
private readonly client;
|
|
720
|
+
private readonly prefix;
|
|
721
|
+
/** member as handed in → member as stored, with its opening time. */
|
|
722
|
+
private readonly stored;
|
|
723
|
+
constructor(client: RedisEvalClient, prefix: string);
|
|
724
|
+
private key;
|
|
725
|
+
private storedAs;
|
|
726
|
+
hit(key: string, windowMs: number): Promise<{
|
|
727
|
+
count: number;
|
|
728
|
+
resetMs: number;
|
|
729
|
+
}>;
|
|
730
|
+
hold(key: string, member: string, ttlMs: number): Promise<string[]>;
|
|
731
|
+
release(key: string, member: string): Promise<void>;
|
|
732
|
+
renew(held: readonly {
|
|
733
|
+
key: string;
|
|
734
|
+
member: string;
|
|
735
|
+
}[], ttlMs: number): Promise<void>;
|
|
562
736
|
}
|
|
563
|
-
/**
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
737
|
+
/**
|
|
738
|
+
* A socket's inbound budget: `burst` frames at once, refilled at `rate` a
|
|
739
|
+
* second.
|
|
740
|
+
*/
|
|
741
|
+
declare class TokenBucket {
|
|
742
|
+
private readonly rate;
|
|
743
|
+
private readonly burst;
|
|
744
|
+
private tokens;
|
|
745
|
+
private at;
|
|
746
|
+
constructor(rate: number, burst: number);
|
|
747
|
+
/** Spend one token, if there is one. */
|
|
748
|
+
take(now?: number): boolean;
|
|
749
|
+
/** Whether it has refilled completely since it last ran dry. */
|
|
750
|
+
get full(): boolean;
|
|
572
751
|
}
|
|
573
752
|
//#endregion
|
|
574
753
|
//#region src/websocket/transport.d.ts
|
|
@@ -593,6 +772,12 @@ interface WebSocketTransport {
|
|
|
593
772
|
/** Receive what is published to `instance`, and every broadcast. */
|
|
594
773
|
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
595
774
|
close(): Promise<void>;
|
|
775
|
+
/**
|
|
776
|
+
* Where the surface's limits are counted — somewhere every process on
|
|
777
|
+
* this transport sees, so a limit holds across them. Absent, each
|
|
778
|
+
* process counts its own.
|
|
779
|
+
*/
|
|
780
|
+
limits?(): WebSocketLimitStore;
|
|
596
781
|
}
|
|
597
782
|
/**
|
|
598
783
|
* A publisher's sink over a transport: a send goes to the instance each
|
|
@@ -637,6 +822,7 @@ declare class MemoryTransport implements WebSocketTransport {
|
|
|
637
822
|
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
638
823
|
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
639
824
|
close(): Promise<void>;
|
|
825
|
+
limits(): WebSocketLimitStore;
|
|
640
826
|
}
|
|
641
827
|
/** The subset of an ioredis client the transport uses. */
|
|
642
828
|
interface RedisClient {
|
|
@@ -645,6 +831,7 @@ interface RedisClient {
|
|
|
645
831
|
on(event: 'message', listener: (channel: string, message: string) => void): unknown;
|
|
646
832
|
duplicate(): RedisClient;
|
|
647
833
|
quit(): Promise<unknown>;
|
|
834
|
+
eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
|
|
648
835
|
}
|
|
649
836
|
/**
|
|
650
837
|
* Over Redis pub/sub: one channel per instance and one for broadcasts, under
|
|
@@ -663,6 +850,8 @@ declare class RedisTransport implements WebSocketTransport {
|
|
|
663
850
|
private channel;
|
|
664
851
|
publish(instance: string, delivery: Delivery): Promise<void>;
|
|
665
852
|
subscribe(instance: string, receive: (delivery: Delivery) => void): Promise<void>;
|
|
853
|
+
/** Counted in this Redis, under the transport's prefix. */
|
|
854
|
+
limits(): WebSocketLimitStore;
|
|
666
855
|
/** Idempotent: the server and a shutdown hook may both close it. */
|
|
667
856
|
close(): Promise<void>;
|
|
668
857
|
}
|
|
@@ -679,6 +868,11 @@ declare function transportFromConnectionString(connectionString: string, fallbac
|
|
|
679
868
|
/** Close codes a client sees. */
|
|
680
869
|
declare const CLOSE: {
|
|
681
870
|
readonly normal: 1000;
|
|
871
|
+
/**
|
|
872
|
+
* It kept sending past its message rate, or its identity opened more
|
|
873
|
+
* sockets than `limits.maxConnections` and this was the oldest.
|
|
874
|
+
*/
|
|
875
|
+
readonly policy: 1008;
|
|
682
876
|
/** The process is stopping; reconnect and land on another. */
|
|
683
877
|
readonly serviceRestart: 1012;
|
|
684
878
|
/** It stopped reading, and what was queued for it passed the limit. */
|
|
@@ -694,9 +888,16 @@ interface WebSocketServerOptions<TMessages extends WebSocketMessages = NoMessage
|
|
|
694
888
|
/**
|
|
695
889
|
* Origins a browser may open a socket from. A request with an `Origin`
|
|
696
890
|
* not in the list is refused with 403; one with none — a server, a load
|
|
697
|
-
* generator — is not a browser, and is let through
|
|
891
|
+
* generator — is not a browser, and is let through unless
|
|
892
|
+
* `requireOrigin` is set.
|
|
698
893
|
*/
|
|
699
894
|
trustedOrigins: readonly string[];
|
|
895
|
+
/**
|
|
896
|
+
* Refuse, with 403, an upgrade that sends no `Origin`. Every browser
|
|
897
|
+
* sends one and a native client sends the socket's own; a server or a
|
|
898
|
+
* script sends none. Off by default: the limits hold either way.
|
|
899
|
+
*/
|
|
900
|
+
requireOrigin?: boolean;
|
|
700
901
|
/**
|
|
701
902
|
* The surface's own public address, `<ID>_URL`. Its origin is always
|
|
702
903
|
* trusted: a native client (React Native's `WebSocket`) sends the socket's
|
|
@@ -709,6 +910,13 @@ interface WebSocketServerOptions<TMessages extends WebSocketMessages = NoMessage
|
|
|
709
910
|
maxPayload?: number;
|
|
710
911
|
/** Queued bytes a socket may hold before it is closed as too slow. */
|
|
711
912
|
maxBufferedBytes?: number;
|
|
913
|
+
/**
|
|
914
|
+
* What one client may ask of it — `resolveLimits(id, config.limits)`.
|
|
915
|
+
* Absent, the defaults.
|
|
916
|
+
*/
|
|
917
|
+
limits?: ResolvedWebSocketLimits;
|
|
918
|
+
/** Where a limit store that cannot be reached is reported. */
|
|
919
|
+
logger?: Logger;
|
|
712
920
|
}
|
|
713
921
|
declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages = NoMessages> {
|
|
714
922
|
private readonly wss;
|
|
@@ -719,7 +927,11 @@ declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages = NoMes
|
|
|
719
927
|
readonly core: WebSocketCore<TMessages>;
|
|
720
928
|
private readonly held;
|
|
721
929
|
private readonly heartbeat;
|
|
930
|
+
private readonly heartbeatMs;
|
|
722
931
|
private readonly trusted;
|
|
932
|
+
private readonly sink;
|
|
933
|
+
private readonly limits;
|
|
934
|
+
private readonly store;
|
|
723
935
|
private next;
|
|
724
936
|
private closing;
|
|
725
937
|
private constructor();
|
|
@@ -730,14 +942,41 @@ declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages = NoMes
|
|
|
730
942
|
get size(): number;
|
|
731
943
|
/** Take over `server`'s upgrades. */
|
|
732
944
|
attach(server: Server): void;
|
|
733
|
-
/**
|
|
945
|
+
/**
|
|
946
|
+
* Upgrade one request, or refuse it with a status line. The cheap checks
|
|
947
|
+
* come first — the Origin, the client's handshake rate, its handshakes in
|
|
948
|
+
* flight and its open sockets — so a flood is refused before the connect
|
|
949
|
+
* handler, and the session lookup it makes, runs.
|
|
950
|
+
*/
|
|
734
951
|
upgrade(request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
|
|
735
952
|
private open;
|
|
953
|
+
/**
|
|
954
|
+
* Whether a frame is within its socket's budget. The first past it is
|
|
955
|
+
* answered with one `$error`; another before the budget has refilled
|
|
956
|
+
* closes the socket with 1008.
|
|
957
|
+
*/
|
|
958
|
+
private admit;
|
|
959
|
+
/**
|
|
960
|
+
* Take a place in `lease`'s count — or none, when that would put it past
|
|
961
|
+
* `max`. A store that cannot be reached lets the handshake through.
|
|
962
|
+
*/
|
|
963
|
+
private claim;
|
|
964
|
+
private release;
|
|
965
|
+
/**
|
|
966
|
+
* How long a socket's place in a count outlives its process, should it
|
|
967
|
+
* die without giving it back: three heartbeats, each of which renews it.
|
|
968
|
+
*/
|
|
969
|
+
private get connectionTtl();
|
|
970
|
+
/** The store's answer — or nothing, logged, when it fails. */
|
|
971
|
+
private guard;
|
|
736
972
|
/** Write, unless the socket has stopped reading and its queue is full. */
|
|
737
973
|
private write;
|
|
738
974
|
/** What the transport, or a local publisher, asked of this process. */
|
|
739
975
|
private deliver;
|
|
740
|
-
/**
|
|
976
|
+
/**
|
|
977
|
+
* Drop every socket that missed the last ping, and ping the rest — whose
|
|
978
|
+
* places in the limits' counts are renewed.
|
|
979
|
+
*/
|
|
741
980
|
private beat;
|
|
742
981
|
/**
|
|
743
982
|
* Stop: refuse new upgrades, close every socket with `code` — 1012 tells
|
|
@@ -747,6 +986,26 @@ declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages = NoMes
|
|
|
747
986
|
close(code?: number, reason?: string): Promise<void>;
|
|
748
987
|
}
|
|
749
988
|
//#endregion
|
|
989
|
+
//#region src/websocket/drivers.d.ts
|
|
990
|
+
/** What reaches a surface's sockets for one publisher-string scheme. */
|
|
991
|
+
interface WebSocketSinkDriver {
|
|
992
|
+
/** The scheme it handles, with its colon: `'apigateway:'`. */
|
|
993
|
+
readonly scheme: string;
|
|
994
|
+
/** The sink for a publisher string of that scheme. */
|
|
995
|
+
sink(connectionString: string): WebSocketSink;
|
|
996
|
+
}
|
|
997
|
+
/** Make a sink available for its scheme. Idempotent. */
|
|
998
|
+
declare function registerWebSocketSinkDriver(driver: WebSocketSinkDriver): void;
|
|
999
|
+
/**
|
|
1000
|
+
* A surface's publisher string names a scheme this process registered no
|
|
1001
|
+
* sink for — `apigateway:` in an entry not built for AWS.
|
|
1002
|
+
*/
|
|
1003
|
+
declare class UnregisteredWebSocketScheme extends Error {
|
|
1004
|
+
readonly surface: string;
|
|
1005
|
+
readonly scheme: string;
|
|
1006
|
+
constructor(surface: string, scheme: string);
|
|
1007
|
+
}
|
|
1008
|
+
//#endregion
|
|
750
1009
|
//#region src/websocket-api.d.ts
|
|
751
1010
|
interface WebSocketApiConfig<TMessages extends WebSocketMessages = NoMessages> {
|
|
752
1011
|
/** The app that serves it, relative to the workspace root. */
|
|
@@ -793,8 +1052,35 @@ interface WebSocketApiConfig<TMessages extends WebSocketMessages = NoMessages> {
|
|
|
793
1052
|
telemetry?: Telemetry;
|
|
794
1053
|
/** Seconds between pings; a socket that misses one is dropped. Default 30. */
|
|
795
1054
|
heartbeat?: number;
|
|
796
|
-
/**
|
|
1055
|
+
/**
|
|
1056
|
+
* The largest frame accepted, in bytes. Default 1 MiB. A surface that
|
|
1057
|
+
* only pushes — its clients write over HTTP — declares no routes and
|
|
1058
|
+
* sets this small.
|
|
1059
|
+
*/
|
|
797
1060
|
maxPayload?: number;
|
|
1061
|
+
/**
|
|
1062
|
+
* What one client may ask of it: handshakes a minute, handshakes in
|
|
1063
|
+
* flight and open sockets per client address, frames a second per
|
|
1064
|
+
* socket, and — with `maxConnectionsPer` — sockets per identity. All but
|
|
1065
|
+
* the last are on by default; on the Redis transport they hold across
|
|
1066
|
+
* every replica. See `WebSocketLimits`.
|
|
1067
|
+
*
|
|
1068
|
+
* ```ts
|
|
1069
|
+
* limits: {
|
|
1070
|
+
* messagesPerSecond: 20,
|
|
1071
|
+
* maxConnectionsPer: (data) => data.userId as string,
|
|
1072
|
+
* maxConnections: 5,
|
|
1073
|
+
* overflow: 'closeOldest',
|
|
1074
|
+
* }
|
|
1075
|
+
* ```
|
|
1076
|
+
*/
|
|
1077
|
+
limits?: WebSocketLimits;
|
|
1078
|
+
/**
|
|
1079
|
+
* Refuse, with 403, an upgrade that sends no `Origin` — which no browser
|
|
1080
|
+
* and no native client omits, but a script does. Default false: a server
|
|
1081
|
+
* may hold a socket too, and the limits apply to it either way.
|
|
1082
|
+
*/
|
|
1083
|
+
requireOrigin?: boolean;
|
|
798
1084
|
}
|
|
799
1085
|
/** A replica count that is not a whole number of at least one. */
|
|
800
1086
|
declare class InvalidReplicaCount extends Error {
|
|
@@ -822,6 +1108,8 @@ declare class WebSocketApi<TName extends string = string, TMessages extends WebS
|
|
|
822
1108
|
readonly frame: {
|
|
823
1109
|
readonly discriminator?: string;
|
|
824
1110
|
};
|
|
1111
|
+
/** What one client may ask of it, defaults filled in. */
|
|
1112
|
+
readonly limits: ResolvedWebSocketLimits;
|
|
825
1113
|
/**
|
|
826
1114
|
* The surface as a dependency: `services.<id>` is its publisher, so an
|
|
827
1115
|
* endpoint sends to a socket the way a route beside it does.
|
|
@@ -899,10 +1187,15 @@ declare class WebSocketApi<TName extends string = string, TMessages extends WebS
|
|
|
899
1187
|
* ```
|
|
900
1188
|
*/
|
|
901
1189
|
testPublisher(): TestWebSocketPublisher<TMessages>;
|
|
1190
|
+
/**
|
|
1191
|
+
* The per-address limits the edge in front of it enforces too, so a
|
|
1192
|
+
* flood is refused before it reaches a replica.
|
|
1193
|
+
*/
|
|
1194
|
+
private get edgeLimits();
|
|
902
1195
|
/** The declared messages, with the surface they are checked for. */
|
|
903
1196
|
private get declared();
|
|
904
1197
|
declare(): Declaration[];
|
|
905
1198
|
}
|
|
906
1199
|
//#endregion
|
|
907
|
-
export {
|
|
908
|
-
//# sourceMappingURL=websocket-api-
|
|
1200
|
+
export { TestConnection as $, DuplicateWebSocketRoute as A, RouteKind as B, TokenBucket as C, ConnectOutcome as D, resolveLimits as E, WriteFrame as F, WebSocketRouteResult as G, WebSocketRoute as H, ConnectContext as I, RecordedClose as J, InvalidWebSocketRequest as K, Connection as L, WebSocketCallOptions as M, WebSocketCore as N, ConnectRequest as O, WebSocketCoreOptions as P, TestConnectRequest as Q, DisconnectContext as R, ResolvedWebSocketLimits as S, WebSocketLimits as T, WebSocketRouteBuilder as U, TestCallOverrides as V, WebSocketRouteRequest as W, RecordedSend as X, RecordedMessage as Y, RecordingSink as Z, DEFAULT_WEBSOCKET_LIMITS as _, WebSocketSink as _t, WebSocketSinkDriver as a, WebSocketDataHasDiscriminator as at, MemoryLimitStore as b, WebSocketServerOptions as c, WebSocketMessageDeclaresDiscriminator as ct, MemoryTransport as d, MessageAction as dt, TestDisconnectRequest as et, RedisTransport as f, MessageData as ft, transportFromConnectionString as g, WebSocketPublisher as gt, WebSocketTransport as h, WebSocketMessages as ht, UnregisteredWebSocketScheme as i, WebSocketTestSurface as it, MessageOutcome as j, DisconnectOutcome as k, WebSocketSurfaceServer as l, WebSocketMessageNotAnObject as lt, UnsupportedWebSocketTransport as m, UnknownWebSocketMessage as mt, WebSocketApi as n, TestMessageResponse as nt, registerWebSocketSinkDriver as o, WebSocketDataNotAnObject as ot, TransportSink as p, NoMessages as pt, RecordedBroadcast as q, WebSocketApiConfig as r, TestWebSocketPublisher as rt, CLOSE as s, WebSocketFrame as st, InvalidReplicaCount as t, TestMessageRequest as tt, Delivery as u, InvalidWebSocketMessage as ut, InvalidWebSocketLimit as v, WebSocketLimitStore as w, RedisLimitStore as x, LIMIT_CLOSE as y, MessageContext as z };
|
|
1201
|
+
//# sourceMappingURL=websocket-api-DkF8Hva-.d.cts.map
|