@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.
Files changed (167) hide show
  1. package/README.md +24 -0
  2. package/dist/{Construct-DySlwh8o.d.mts → Construct-BMk_CRSD.d.mts} +2 -2
  3. package/dist/{Construct-DySlwh8o.d.mts.map → Construct-BMk_CRSD.d.mts.map} +1 -1
  4. package/dist/{Cron-D8mB_cPX.d.mts → Cron-D6Y7BBt3.d.mts} +5 -5
  5. package/dist/{Cron-D8mB_cPX.d.mts.map → Cron-D6Y7BBt3.d.mts.map} +1 -1
  6. package/dist/{CronBuilder-Cmajva3g.d.mts → CronBuilder-4BZhkChG.d.mts} +5 -5
  7. package/dist/{CronBuilder-Cmajva3g.d.mts.map → CronBuilder-4BZhkChG.d.mts.map} +1 -1
  8. package/dist/{Endpoint-BbHh3Qoc.d.mts → Endpoint-BUoDD96P.d.mts} +5 -5
  9. package/dist/{Endpoint-BbHh3Qoc.d.mts.map → Endpoint-BUoDD96P.d.mts.map} +1 -1
  10. package/dist/{EndpointFactory-qcLzi4f-.d.mts → EndpointFactory-BbVOeryo.d.mts} +5 -5
  11. package/dist/{EndpointFactory-qcLzi4f-.d.mts.map → EndpointFactory-BbVOeryo.d.mts.map} +1 -1
  12. package/dist/{Function-DfMzTGS4.d.mts → Function-BKReud5p.d.mts} +3 -3
  13. package/dist/{Function-DfMzTGS4.d.mts.map → Function-BKReud5p.d.mts.map} +1 -1
  14. package/dist/{HonoEndpointAdaptor-DR3j7S35.mjs → HonoEndpointAdaptor-2xHA3bvn.mjs} +5 -4
  15. package/dist/HonoEndpointAdaptor-2xHA3bvn.mjs.map +1 -0
  16. package/dist/{HonoEndpointAdaptor-BXBdb2Bt.cjs → HonoEndpointAdaptor-CZ1TooUu.cjs} +6 -5
  17. package/dist/HonoEndpointAdaptor-CZ1TooUu.cjs.map +1 -0
  18. package/dist/{ObjectSubscriberBuilder-Cv8C7yS1.d.mts → ObjectSubscriberBuilder-DfzXQEKW.d.mts} +4 -4
  19. package/dist/{ObjectSubscriberBuilder-Cv8C7yS1.d.mts.map → ObjectSubscriberBuilder-DfzXQEKW.d.mts.map} +1 -1
  20. package/dist/ObjectSubscriberBuilder-LWkey_oq.d.cts.map +1 -1
  21. package/dist/{ProcessorBuilder-CwfP-M33.d.mts → ProcessorBuilder-D4oYvZeG.d.mts} +2 -2
  22. package/dist/{ProcessorBuilder-CwfP-M33.d.mts.map → ProcessorBuilder-D4oYvZeG.d.mts.map} +1 -1
  23. package/dist/{Queue-BnK3UH8r.d.mts → Queue-B8HGg439.d.mts} +3 -3
  24. package/dist/{Queue-BnK3UH8r.d.mts.map → Queue-B8HGg439.d.mts.map} +1 -1
  25. package/dist/{QueueBuilder-DmwFtLzQ.d.mts → QueueBuilder-CVS_qPuo.d.mts} +2 -2
  26. package/dist/{QueueBuilder-DmwFtLzQ.d.mts.map → QueueBuilder-CVS_qPuo.d.mts.map} +1 -1
  27. package/dist/{Subscriber-CW_Dl-YR.d.mts → Subscriber-CtQXhcL7.d.mts} +3 -3
  28. package/dist/{Subscriber-CW_Dl-YR.d.mts.map → Subscriber-CtQXhcL7.d.mts.map} +1 -1
  29. package/dist/{SubscriberBuilder-BL_GTcwh.mjs → SubscriberBuilder-CpFhShTJ.mjs} +3 -2
  30. package/dist/SubscriberBuilder-CpFhShTJ.mjs.map +1 -0
  31. package/dist/{SubscriberBuilder-CWzKwX1p.cjs → SubscriberBuilder-DJEvNRdD.cjs} +3 -2
  32. package/dist/SubscriberBuilder-DJEvNRdD.cjs.map +1 -0
  33. package/dist/adaptors/aws.cjs +18 -13
  34. package/dist/adaptors/aws.cjs.map +1 -1
  35. package/dist/adaptors/aws.d.cts.map +1 -1
  36. package/dist/adaptors/aws.d.mts +6 -6
  37. package/dist/adaptors/aws.d.mts.map +1 -1
  38. package/dist/adaptors/aws.mjs +17 -12
  39. package/dist/adaptors/aws.mjs.map +1 -1
  40. package/dist/adaptors/awsWebsocket.cjs +354 -0
  41. package/dist/adaptors/awsWebsocket.cjs.map +1 -0
  42. package/dist/adaptors/awsWebsocket.d.cts +156 -0
  43. package/dist/adaptors/awsWebsocket.d.cts.map +1 -0
  44. package/dist/adaptors/awsWebsocket.d.mts +156 -0
  45. package/dist/adaptors/awsWebsocket.d.mts.map +1 -0
  46. package/dist/adaptors/awsWebsocket.mjs +347 -0
  47. package/dist/adaptors/awsWebsocket.mjs.map +1 -0
  48. package/dist/adaptors/hono.cjs +1 -1
  49. package/dist/adaptors/hono.d.mts +2 -2
  50. package/dist/adaptors/hono.mjs +1 -1
  51. package/dist/adaptors/testing.cjs +19 -9
  52. package/dist/adaptors/testing.cjs.map +1 -1
  53. package/dist/adaptors/testing.d.cts +1 -1
  54. package/dist/adaptors/testing.d.cts.map +1 -1
  55. package/dist/adaptors/testing.d.mts +9 -9
  56. package/dist/adaptors/testing.d.mts.map +1 -1
  57. package/dist/adaptors/testing.mjs +17 -7
  58. package/dist/adaptors/testing.mjs.map +1 -1
  59. package/dist/auth-BqWz2JxC.d.cts.map +1 -1
  60. package/dist/auth-DnB9H9KL.d.mts.map +1 -1
  61. package/dist/auth.cjs +7 -21
  62. package/dist/auth.cjs.map +1 -1
  63. package/dist/auth.mjs +6 -20
  64. package/dist/auth.mjs.map +1 -1
  65. package/dist/{cache-e3tfMQ9g.d.mts → cache-CCHcO9Oo.d.mts} +2 -2
  66. package/dist/cache-CCHcO9Oo.d.mts.map +1 -0
  67. package/dist/cache-CQjMNPrC.d.cts.map +1 -1
  68. package/dist/cache.cjs +3 -19
  69. package/dist/cache.cjs.map +1 -1
  70. package/dist/cache.d.mts +1 -1
  71. package/dist/cache.mjs +2 -18
  72. package/dist/cache.mjs.map +1 -1
  73. package/dist/crons/index.cjs +2 -1
  74. package/dist/crons/index.cjs.map +1 -1
  75. package/dist/crons/index.d.cts.map +1 -1
  76. package/dist/crons/index.d.mts +2 -2
  77. package/dist/crons/index.d.mts.map +1 -1
  78. package/dist/crons/index.mjs +2 -1
  79. package/dist/crons/index.mjs.map +1 -1
  80. package/dist/database/kysely.d.mts +1 -1
  81. package/dist/email.cjs +4 -16
  82. package/dist/email.cjs.map +1 -1
  83. package/dist/email.d.cts.map +1 -1
  84. package/dist/email.d.mts.map +1 -1
  85. package/dist/email.mjs +2 -14
  86. package/dist/email.mjs.map +1 -1
  87. package/dist/endpoints/index.cjs +1 -1
  88. package/dist/endpoints/index.d.cts +1 -1
  89. package/dist/endpoints/index.d.cts.map +1 -1
  90. package/dist/endpoints/index.d.mts +4 -4
  91. package/dist/endpoints/index.d.mts.map +1 -1
  92. package/dist/endpoints/index.mjs +1 -1
  93. package/dist/file-server.d.mts +1 -1
  94. package/dist/functions/index.d.mts +2 -2
  95. package/dist/{inbox-CjxpLVkH.d.mts → inbox-YOdxlyfj.d.mts} +2 -2
  96. package/dist/{inbox-CjxpLVkH.d.mts.map → inbox-YOdxlyfj.d.mts.map} +1 -1
  97. package/dist/inbox.d.mts +1 -1
  98. package/dist/{index-DCkDQkwj.d.mts → index-BoQ3-M-K.d.mts} +4 -4
  99. package/dist/{index-DCkDQkwj.d.mts.map → index-BoQ3-M-K.d.mts.map} +1 -1
  100. package/dist/index.d.mts +1 -1
  101. package/dist/{kysely-DE4kADWD.d.mts → kysely-De5rAC-E.d.mts} +2 -2
  102. package/dist/{kysely-DE4kADWD.d.mts.map → kysely-De5rAC-E.d.mts.map} +1 -1
  103. package/dist/optionalPeers-D7Wt6dnF.mjs +140 -0
  104. package/dist/optionalPeers-D7Wt6dnF.mjs.map +1 -0
  105. package/dist/optionalPeers-DuNQXXe1.cjs +223 -0
  106. package/dist/optionalPeers-DuNQXXe1.cjs.map +1 -0
  107. package/dist/origins-BjxYht13.cjs +96 -0
  108. package/dist/origins-BjxYht13.cjs.map +1 -0
  109. package/dist/origins-Boc9qbo-.mjs +73 -0
  110. package/dist/origins-Boc9qbo-.mjs.map +1 -0
  111. package/dist/privateAddress-Bg5fUsbp.mjs +21 -0
  112. package/dist/privateAddress-Bg5fUsbp.mjs.map +1 -0
  113. package/dist/privateAddress-CqGyuFHn.cjs +26 -0
  114. package/dist/privateAddress-CqGyuFHn.cjs.map +1 -0
  115. package/dist/processors/index.d.mts +1 -1
  116. package/dist/queue/index.d.mts +2 -2
  117. package/dist/{readRequestBody-BTIl3k-D.mjs → readRequestBody-BmKnPl0a.mjs} +26 -4
  118. package/dist/readRequestBody-BmKnPl0a.mjs.map +1 -0
  119. package/dist/{readRequestBody-Dej_L3c4.cjs → readRequestBody-CN9GVdeE.cjs} +26 -4
  120. package/dist/readRequestBody-CN9GVdeE.cjs.map +1 -0
  121. package/dist/{requestLogger-BZcXwdBs.cjs → requestLogger-CnoYd-Ah.cjs} +4 -63
  122. package/dist/requestLogger-CnoYd-Ah.cjs.map +1 -0
  123. package/dist/{requestLogger-pA4gi3E1.mjs → requestLogger-D2JS7pPM.mjs} +3 -56
  124. package/dist/requestLogger-D2JS7pPM.mjs.map +1 -0
  125. package/dist/rest-api.d.mts +2 -2
  126. package/dist/{runSubscriber-DyHWp_Lf.mjs → runSubscriber-HEqXkin1.mjs} +3 -2
  127. package/dist/runSubscriber-HEqXkin1.mjs.map +1 -0
  128. package/dist/{runSubscriber-CC_2C9F2.cjs → runSubscriber-sVJfLA0-.cjs} +3 -2
  129. package/dist/runSubscriber-sVJfLA0-.cjs.map +1 -0
  130. package/dist/subscribers/index.cjs +6 -6
  131. package/dist/subscribers/index.cjs.map +1 -1
  132. package/dist/subscribers/index.d.cts +1 -1
  133. package/dist/subscribers/index.d.mts +3 -3
  134. package/dist/subscribers/index.mjs +3 -3
  135. package/dist/subscribers/index.mjs.map +1 -1
  136. package/dist/topic/index.d.mts +1 -1
  137. package/dist/{websocket-api-Dn_3Y2fI.mjs → websocket-api-Bg9SowJ5.mjs} +452 -44
  138. package/dist/websocket-api-Bg9SowJ5.mjs.map +1 -0
  139. package/dist/{websocket-api-DSWDhZph.d.mts → websocket-api-CPEzJyDt.d.mts} +501 -208
  140. package/dist/websocket-api-CPEzJyDt.d.mts.map +1 -0
  141. package/dist/{websocket-api-CLnV_7CB.d.cts → websocket-api-DkF8Hva-.d.cts} +501 -208
  142. package/dist/websocket-api-DkF8Hva-.d.cts.map +1 -0
  143. package/dist/{websocket-api-9bXfgrqd.cjs → websocket-api-czxhekGG.cjs} +493 -43
  144. package/dist/websocket-api-czxhekGG.cjs.map +1 -0
  145. package/dist/websocket-api.cjs +11 -1
  146. package/dist/websocket-api.d.cts +2 -2
  147. package/dist/websocket-api.d.mts +2 -2
  148. package/dist/websocket-api.mjs +3 -2
  149. package/dist/worker.cjs +1 -1
  150. package/dist/worker.d.mts +9 -9
  151. package/dist/worker.mjs +1 -1
  152. package/package.json +57 -31
  153. package/dist/HonoEndpointAdaptor-BXBdb2Bt.cjs.map +0 -1
  154. package/dist/HonoEndpointAdaptor-DR3j7S35.mjs.map +0 -1
  155. package/dist/SubscriberBuilder-BL_GTcwh.mjs.map +0 -1
  156. package/dist/SubscriberBuilder-CWzKwX1p.cjs.map +0 -1
  157. package/dist/cache-e3tfMQ9g.d.mts.map +0 -1
  158. package/dist/readRequestBody-BTIl3k-D.mjs.map +0 -1
  159. package/dist/readRequestBody-Dej_L3c4.cjs.map +0 -1
  160. package/dist/requestLogger-BZcXwdBs.cjs.map +0 -1
  161. package/dist/requestLogger-pA4gi3E1.mjs.map +0 -1
  162. package/dist/runSubscriber-CC_2C9F2.cjs.map +0 -1
  163. package/dist/runSubscriber-DyHWp_Lf.mjs.map +0 -1
  164. package/dist/websocket-api-9bXfgrqd.cjs.map +0 -1
  165. package/dist/websocket-api-CLnV_7CB.d.cts.map +0 -1
  166. package/dist/websocket-api-DSWDhZph.d.mts.map +0 -1
  167. 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/testing.d.ts
427
- /** One recorded message: its action and data, and the frame on the wire. */
428
- type RecordedMessage<TMessages extends WebSocketMessages = NoMessages> = [keyof TMessages] extends [never] ? {
429
- action: string;
430
- data: unknown;
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
- * A sink that keeps what it is handed, decoded by the surface's frame shape,
455
- * and sends it nowhere.
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
- declare class RecordingSink implements WebSocketSink {
458
- private readonly frame;
459
- readonly sent: RecordedSend<any>[];
460
- readonly broadcasts: RecordedBroadcast<any>[];
461
- readonly closed: RecordedClose[];
462
- constructor(frame: FrameShape);
463
- send(ids: readonly string[], payload: string): Promise<void>;
464
- broadcast(payload: string, except?: readonly string[]): Promise<void>;
465
- close(ids: readonly string[], code: number, reason: string): Promise<void>;
466
- clear(): void;
467
- private decode;
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
- * A surface's publisher that records rather than sends — what
471
- * `surface.testPublisher()` returns, of the type `services.<surface>` is.
472
- *
473
- * Every send is still checked by the declared `messages` and encoded by the
474
- * surface's `frame`, so an invalid push fails the spec as it would fail
475
- * deployed, and `frame` on each record is what the client would parse.
476
- */
477
- declare class TestWebSocketPublisher<TMessages extends WebSocketMessages = NoMessages> extends WebSocketPublisher<TMessages> {
478
- /** Where the records are kept — what `route.request()` builds its core on. */
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
- /** A frame `route.request()` sent was refused before its handler ran. */
494
- declare class InvalidWebSocketRequest extends Error {
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 action: string;
497
- /** What the `$error` frame said. */
498
- readonly reason: string;
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
- /** What a surface hands its routes' `request()`. */
505
- interface WebSocketTestSurface {
506
- readonly id: string;
507
- core(options: {
508
- envParser: EnvironmentParser<{}>;
509
- sink: WebSocketSink;
510
- modules?: readonly object[];
511
- }): WebSocketCore<any>;
512
- readonly envParser: EnvironmentParser<{}>;
513
- testPublisher(): TestWebSocketPublisher<any>;
514
- }
515
- /** Overrides every `request()` takes. */
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
- * The handler's `sockets`. Pass `surface.testPublisher()` to assert what
525
- * it sent; absent, a fresh one that nobody reads.
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
- sockets?: TestWebSocketPublisher<any>;
528
- }
529
- interface TestConnectRequest extends WebSocketTestCallOptions {
530
- /** The id the connection is given. Absent, `test.<n>`. */
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
- * What the surface's `.auth()` would have resolved — `null` for no
538
- * session. Absent, `.auth()` verifies `headers`, as on a real upgrade.
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
- session?: unknown;
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
- interface TestMessageRequest<TBody = unknown> extends WebSocketTestCallOptions {
543
- /** The connection the frame arrives on. Absent, `test.<n>` with no data. */
544
- connection?: TestConnection;
545
- /** The frame's data — checked by the route's `body`, as a frame's is. */
546
- body: TBody;
547
- /** The frame's `id`, echoed on its reply. Only `{ action, data }` frames. */
548
- id?: string | number;
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
- interface TestDisconnectRequest extends WebSocketTestCallOptions {
551
- /** The connection that closed. Absent, `test.<n>` with no data. */
552
- connection?: TestConnection;
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
- /** A connection a test names: either part may be left to its default. */
559
- interface TestConnection {
560
- id?: string;
561
- data?: Record<string, unknown>;
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
- /** What a message route's `fullRequest()` resolves with. */
564
- interface TestMessageResponse<TReturned = unknown> {
565
- /** The handler's return — the reply, before it was encoded. */
566
- returned: TReturned;
567
- /**
568
- * Every frame written back to the connection, parsed, in order: each
569
- * `reply()` and the reply to the frame itself.
570
- */
571
- frames: unknown[];
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
- /** Upgrade one request, or refuse it with a status line. */
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
- /** Drop every socket that missed the last ping, and ping the rest. */
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
- /** The largest frame accepted, in bytes. Default 1 MiB. */
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 { WebSocketSink as $, DuplicateWebSocketRoute as A, RouteKind as B, TestMessageRequest as C, ConnectOutcome as D, WebSocketTestSurface as E, WriteFrame as F, WebSocketRouteResult as G, WebSocketRoute as H, ConnectContext as I, MessageData as J, InvalidWebSocketMessage as K, Connection as L, WebSocketCallOptions as M, WebSocketCore as N, ConnectRequest as O, WebSocketCoreOptions as P, WebSocketPublisher as Q, DisconnectContext as R, TestDisconnectRequest as S, TestWebSocketPublisher as T, WebSocketRouteBuilder as U, TestCallOverrides as V, WebSocketRouteRequest as W, UnknownWebSocketMessage as X, NoMessages as Y, WebSocketMessages as Z, RecordedMessage as _, WebSocketServerOptions as a, TestConnectRequest as b, MemoryTransport as c, UnsupportedWebSocketTransport as d, WebSocketDataHasDiscriminator as et, WebSocketTransport as f, RecordedClose as g, RecordedBroadcast as h, CLOSE as i, WebSocketMessageNotAnObject as it, MessageOutcome as j, DisconnectOutcome as k, RedisTransport as l, InvalidWebSocketRequest as m, WebSocketApi as n, WebSocketFrame as nt, WebSocketSurfaceServer as o, transportFromConnectionString as p, MessageAction as q, WebSocketApiConfig as r, WebSocketMessageDeclaresDiscriminator as rt, Delivery as s, InvalidReplicaCount as t, WebSocketDataNotAnObject as tt, TransportSink as u, RecordedSend as v, TestMessageResponse as w, TestConnection as x, RecordingSink as y, MessageContext as z };
908
- //# sourceMappingURL=websocket-api-CLnV_7CB.d.cts.map
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