@geekmidas/constructs 10.0.0-alpha.146 → 10.0.0-alpha.147

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.
@@ -125,7 +125,9 @@ export declare class InvalidWebSocketMessage extends Error {
125
125
  * How anything reaches a socket — `services.realtime` in an endpoint, and
126
126
  * `sockets` in a route of the surface itself.
127
127
  *
128
- * A message is `{ action, data }`, the shape a client's frames arrive in.
128
+ * A message is `{ action, data }`, the shape a client's frames arrive in —
129
+ * or, where the surface names a `frame.discriminator`, flat: `{ [key]: action,
130
+ * ...data }`.
129
131
  * Where the surface declares its messages, `action` is one of them and
130
132
  * `data` is typed and checked by its schema before anything is sent; where it
131
133
  * declares none, any action and any JSON value go. A message is serialised
@@ -142,6 +144,8 @@ export declare class WebSocketPublisher<TMessages extends WebSocketMessages = No
142
144
  private readonly local?;
143
145
  /** The surface's declared messages, which every send is checked by. */
144
146
  private readonly declared?;
147
+ /** How the surface writes a frame. Absent, `{ action, data }`. */
148
+ private readonly frame;
145
149
  constructor(transport: WebSocketTransport,
146
150
  /**
147
151
  * Delivers to this process's own sockets without a round trip through
@@ -155,7 +159,9 @@ export declare class WebSocketPublisher<TMessages extends WebSocketMessages = No
155
159
  declared?: {
156
160
  surface: string;
157
161
  messages: TMessages;
158
- } | undefined);
162
+ } | undefined,
163
+ /** How the surface writes a frame. Absent, `{ action, data }`. */
164
+ frame?: FrameShape);
159
165
  /** Send `action`'s message to each connection. */
160
166
  send<TAction extends MessageAction<TMessages>>(ids: string | readonly string[], action: TAction, data: MessageData<TMessages, TAction>): Promise<void>;
161
167
  /** Send `action`'s message to every open connection, on every process. */
@@ -168,13 +174,85 @@ export declare class WebSocketPublisher<TMessages extends WebSocketMessages = No
168
174
  * The frame, checked by the action's schema where the surface declares
169
175
  * its messages.
170
176
  *
171
- * @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}
177
+ * @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}, and for a
178
+ * flat frame {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator}
172
179
  */
173
180
  private payload;
174
181
  /** One delivery per process that holds any of `ids`. */
175
182
  private each;
176
183
  }
177
184
  //#endregion
185
+ //#region src/websocket/frame.d.ts
186
+ /** `WebSocketApiConfig.frame`: where a flat frame keeps its action. */
187
+ interface WebSocketFrame {
188
+ /** The key a frame's action lives in — `type` for `{ "type": … }`. */
189
+ discriminator: string;
190
+ }
191
+ /** A frame as the server reads it, whatever shape it arrived in. */
192
+ interface DecodedFrame {
193
+ action: string;
194
+ /** Echoed on the reply. Only an `{ action, data }` frame carries one. */
195
+ id?: string | number;
196
+ data?: unknown;
197
+ }
198
+ /** A declared message whose schema does not describe an object. */
199
+ export declare class WebSocketMessageNotAnObject extends Error {
200
+ readonly surface: string;
201
+ readonly action: string;
202
+ readonly discriminator: string;
203
+ constructor(surface: string, action: string, discriminator: string);
204
+ }
205
+ /** A declared message whose schema has a field named the discriminator. */
206
+ export declare class WebSocketMessageDeclaresDiscriminator extends Error {
207
+ readonly surface: string;
208
+ readonly action: string;
209
+ readonly discriminator: string;
210
+ constructor(surface: string, action: string, discriminator: string);
211
+ }
212
+ /** Data sent in a flat frame that is not an object. */
213
+ export declare class WebSocketDataNotAnObject extends Error {
214
+ readonly surface: string;
215
+ readonly action: string;
216
+ readonly discriminator: string;
217
+ constructor(surface: string, action: string, discriminator: string);
218
+ }
219
+ /** Data sent in a flat frame that carries the discriminator itself. */
220
+ export declare class WebSocketDataHasDiscriminator extends Error {
221
+ readonly surface: string;
222
+ readonly action: string;
223
+ readonly discriminator: string;
224
+ constructor(surface: string, action: string, discriminator: string);
225
+ }
226
+ /** How one surface writes and reads its frames. */
227
+ declare class FrameShape {
228
+ readonly surface: string;
229
+ /** The flat frame's key; absent, frames are `{ action, data }`. */
230
+ readonly discriminator?: string | undefined;
231
+ constructor(surface: string,
232
+ /** The flat frame's key; absent, frames are `{ action, data }`. */
233
+ discriminator?: string | undefined);
234
+ /** The key an inbound frame names its action under. */
235
+ get key(): string;
236
+ /**
237
+ * The frame for `action`'s `data`, serialised.
238
+ *
239
+ * @throws {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator} for
240
+ * a flat frame whose data cannot sit beside the discriminator.
241
+ */
242
+ encode(action: string, data: unknown, id?: string | number): string;
243
+ /** A parsed frame's action, id and data — `undefined` when it names none. */
244
+ decode(frame: unknown): DecodedFrame | undefined;
245
+ /** The id a frame that names no action carried, to echo on its error. */
246
+ idOf(frame: unknown): string | number | undefined;
247
+ /**
248
+ * Refuse a declared message a flat frame cannot carry: one that is not an
249
+ * object, or that has a field named the discriminator.
250
+ *
251
+ * @throws {WebSocketMessageNotAnObject}, {WebSocketMessageDeclaresDiscriminator}
252
+ */
253
+ check(messages: WebSocketMessages): void;
254
+ }
255
+ //#endregion
178
256
  //#region src/websocket/route.d.ts
179
257
  /** One open connection, as a handler sees it. */
180
258
  interface Connection {
@@ -288,6 +366,8 @@ interface WebSocketServerOptions<TMessages extends WebSocketMessages = NoMessage
288
366
  surface: string;
289
367
  /** What the surface sends its sockets — see `WebSocketApiConfig.messages`. */
290
368
  messages?: TMessages;
369
+ /** The shape its frames take — see `WebSocketApiConfig.frame`. */
370
+ frame?: WebSocketFrame;
291
371
  routes: readonly WebSocketRoute[];
292
372
  transport: WebSocketTransport;
293
373
  envParser: EnvironmentParser<{}>;
@@ -299,6 +379,12 @@ interface WebSocketServerOptions<TMessages extends WebSocketMessages = NoMessage
299
379
  * generator — is not a browser, and is let through.
300
380
  */
301
381
  trustedOrigins: readonly string[];
382
+ /**
383
+ * The surface's own public address, `<ID>_URL`. Its origin is always
384
+ * trusted: a native client (React Native's `WebSocket`) sends the socket's
385
+ * own origin as its `Origin`.
386
+ */
387
+ url?: string;
302
388
  /** How often each socket is pinged; one that missed the last is dropped. */
303
389
  heartbeatMs?: number;
304
390
  /** The largest frame accepted, in bytes. */
@@ -317,6 +403,8 @@ export declare class WebSocketSurfaceServer<TMessages extends WebSocketMessages
317
403
  private readonly routes;
318
404
  private readonly lifecycle;
319
405
  private readonly heartbeat;
406
+ private readonly frame;
407
+ private readonly trusted;
320
408
  private next;
321
409
  private closing;
322
410
  private constructor();
@@ -367,6 +455,23 @@ export interface WebSocketApiConfig<TMessages extends WebSocketMessages = NoMess
367
455
  * alike. Absent, any action and any data go, unchecked.
368
456
  */
369
457
  messages?: TMessages;
458
+ /**
459
+ * The shape its frames take. Absent, `{ "action": …, "id"?: …, "data": … }`.
460
+ *
461
+ * With a `discriminator`, frames are flat — the action under that key and
462
+ * the data's fields beside it, both ways, `$error` replies included:
463
+ *
464
+ * ```ts
465
+ * frame: { discriminator: 'type' },
466
+ * // realtime.send(ids, 'chat.message.created', { chatId, message })
467
+ * // wire: {"type":"chat.message.created","chatId":"…","message":{…}}
468
+ * ```
469
+ *
470
+ * Every message must then be an object schema that has no field of that
471
+ * name; one that is not is refused when the surface is built. A flat frame
472
+ * carries no `id`: every other field is the data.
473
+ */
474
+ frame?: WebSocketFrame;
370
475
  /** The label it answers on. Absent, its id kebab-cased. */
371
476
  subdomain?: string;
372
477
  /** How many processes serve it on one machine. Default 1. */
@@ -398,6 +503,13 @@ export declare class WebSocketApi<TName extends string = string, TMessages exten
398
503
  readonly logger: Logger;
399
504
  readonly envParser: EnvironmentParser<{}>;
400
505
  readonly telemetry?: Telemetry;
506
+ /**
507
+ * The shape its frames take — `{ action, data }`, or flat under
508
+ * `discriminator`. What a client of the surface decodes by.
509
+ */
510
+ readonly frame: {
511
+ readonly discriminator?: string;
512
+ };
401
513
  /**
402
514
  * The surface as a dependency: `services.<id>` is its publisher, so an
403
515
  * endpoint sends to a socket the way a route beside it does.
@@ -411,7 +523,8 @@ export declare class WebSocketApi<TName extends string = string, TMessages exten
411
523
  /** The handler a closed connection runs. */
412
524
  disconnect(): WebSocketRouteBuilder<'disconnect', undefined, [], TMessages>;
413
525
  /**
414
- * The handler for frames whose `action` is `action`. `$default` answers
526
+ * The handler for frames whose `action` — or, for flat frames, whose
527
+ * discriminator — is `action`. `$default` answers
415
528
  * any action nothing else does.
416
529
  */
417
530
  route(action: string): WebSocketRouteBuilder<'message', undefined, [], TMessages>;
@@ -439,5 +552,5 @@ export declare class WebSocketApi<TName extends string = string, TMessages exten
439
552
  declare(): Declaration[];
440
553
  }
441
554
  //#endregion
442
- export type { ConnectContext, Connection, Delivery, DisconnectContext, MessageAction, MessageContext, MessageData, NoMessages, RouteKind, WebSocketMessages, WebSocketServerOptions, WebSocketTransport };
555
+ export type { ConnectContext, Connection, Delivery, DisconnectContext, MessageAction, MessageContext, MessageData, NoMessages, RouteKind, WebSocketFrame, WebSocketMessages, WebSocketServerOptions, WebSocketTransport };
443
556
  //# sourceMappingURL=websocket-api.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"websocket-api.d.mts","names":[],"sources":["../src/websocket/transport.ts","../src/websocket/publisher.ts","../src/websocket/route.ts","../src/websocket/server.ts","../src/websocket-api.ts"],"mappings":"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"}
1
+ {"version":3,"file":"websocket-api.d.mts","names":[],"sources":["../src/websocket/transport.ts","../src/websocket/publisher.ts","../src/websocket/frame.ts","../src/websocket/route.ts","../src/websocket/server.ts","../src/websocket-api.ts"],"mappings":"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"}
@@ -6,6 +6,172 @@ import { DEFAULT_LOGGER } from "@geekmidas/logger/console";
6
6
  import { randomBytes } from "node:crypto";
7
7
  import { ServiceDiscovery, runWithRequestContext } from "@geekmidas/services";
8
8
  import { HttpError } from "@geekmidas/errors";
9
+ import { toJsonSchema } from "@geekmidas/schema/conversion";
10
+ //#region src/websocket/frame.ts
11
+ /**
12
+ * The shape a surface's frames take on the wire.
13
+ *
14
+ * By default a frame is `{ "action": …, "id"?: …, "data": … }` — API
15
+ * Gateway's shape. A surface that names a discriminator — `frame: {
16
+ * discriminator: 'type' }` — sends and reads flat frames instead: the action
17
+ * under that key, and the data's own fields beside it.
18
+ *
19
+ * ```json
20
+ * {"type":"chat.message.created","chatId":"c1","message":{…}}
21
+ * ```
22
+ *
23
+ * A flat frame has no `id` of its own: every field but the discriminator is
24
+ * the data, so a reply is paired by its action, not an echoed id.
25
+ */
26
+ /** A declared message whose schema does not describe an object. */
27
+ var WebSocketMessageNotAnObject = class extends Error {
28
+ surface;
29
+ action;
30
+ discriminator;
31
+ constructor(surface, action, discriminator) {
32
+ super(`${surface} sends flat frames, keyed by '${discriminator}', so each message's fields sit beside it — but '${action}' is not an object schema. Declare it as an object (z.object({ … })), or drop \`frame\` to send { action, data }.`);
33
+ this.surface = surface;
34
+ this.action = action;
35
+ this.discriminator = discriminator;
36
+ this.name = "WebSocketMessageNotAnObject";
37
+ }
38
+ };
39
+ /** A declared message whose schema has a field named the discriminator. */
40
+ var WebSocketMessageDeclaresDiscriminator = class extends Error {
41
+ surface;
42
+ action;
43
+ discriminator;
44
+ constructor(surface, action, discriminator) {
45
+ super(`${surface}'s '${action}' message declares a '${discriminator}' field, which is where its flat frames keep the action. Rename the field, or give \`frame.discriminator\` a key no message uses.`);
46
+ this.surface = surface;
47
+ this.action = action;
48
+ this.discriminator = discriminator;
49
+ this.name = "WebSocketMessageDeclaresDiscriminator";
50
+ }
51
+ };
52
+ /** Data sent in a flat frame that is not an object. */
53
+ var WebSocketDataNotAnObject = class extends Error {
54
+ surface;
55
+ action;
56
+ discriminator;
57
+ constructor(surface, action, discriminator) {
58
+ super(`${surface} sends flat frames, keyed by '${discriminator}', and '${action}''s data is not an object, so it has no fields to put beside it. Send an object. Nothing was sent.`);
59
+ this.surface = surface;
60
+ this.action = action;
61
+ this.discriminator = discriminator;
62
+ this.name = "WebSocketDataNotAnObject";
63
+ }
64
+ };
65
+ /** Data sent in a flat frame that carries the discriminator itself. */
66
+ var WebSocketDataHasDiscriminator = class extends Error {
67
+ surface;
68
+ action;
69
+ discriminator;
70
+ constructor(surface, action, discriminator) {
71
+ super(`'${action}''s data on ${surface} has a '${discriminator}' field, which is where its flat frames keep the action. Rename the field. Nothing was sent.`);
72
+ this.surface = surface;
73
+ this.action = action;
74
+ this.discriminator = discriminator;
75
+ this.name = "WebSocketDataHasDiscriminator";
76
+ }
77
+ };
78
+ /** How one surface writes and reads its frames. */
79
+ var FrameShape = class {
80
+ surface;
81
+ discriminator;
82
+ constructor(surface, discriminator) {
83
+ this.surface = surface;
84
+ this.discriminator = discriminator;
85
+ }
86
+ /** The key an inbound frame names its action under. */
87
+ get key() {
88
+ return this.discriminator ?? "action";
89
+ }
90
+ /**
91
+ * The frame for `action`'s `data`, serialised.
92
+ *
93
+ * @throws {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator} for
94
+ * a flat frame whose data cannot sit beside the discriminator.
95
+ */
96
+ encode(action, data, id) {
97
+ const { discriminator } = this;
98
+ if (discriminator === void 0) return JSON.stringify({
99
+ action,
100
+ ...id !== void 0 ? { id } : {},
101
+ data
102
+ });
103
+ if (!isRecord(data)) throw new WebSocketDataNotAnObject(this.surface, action, discriminator);
104
+ if (Object.hasOwn(data, discriminator)) throw new WebSocketDataHasDiscriminator(this.surface, action, discriminator);
105
+ return JSON.stringify({
106
+ [discriminator]: action,
107
+ ...data
108
+ });
109
+ }
110
+ /** A parsed frame's action, id and data — `undefined` when it names none. */
111
+ decode(frame) {
112
+ if (!isRecord(frame)) return void 0;
113
+ const { discriminator } = this;
114
+ if (discriminator === void 0) {
115
+ if (typeof frame.action !== "string") return void 0;
116
+ return {
117
+ action: frame.action,
118
+ ...isId(frame.id) ? { id: frame.id } : {},
119
+ data: frame.data
120
+ };
121
+ }
122
+ const { [discriminator]: action, ...data } = frame;
123
+ if (typeof action !== "string") return void 0;
124
+ return {
125
+ action,
126
+ data
127
+ };
128
+ }
129
+ /** The id a frame that names no action carried, to echo on its error. */
130
+ idOf(frame) {
131
+ if (this.discriminator !== void 0 || !isRecord(frame)) return void 0;
132
+ return isId(frame.id) ? frame.id : void 0;
133
+ }
134
+ /**
135
+ * Refuse a declared message a flat frame cannot carry: one that is not an
136
+ * object, or that has a field named the discriminator.
137
+ *
138
+ * @throws {WebSocketMessageNotAnObject}, {WebSocketMessageDeclaresDiscriminator}
139
+ */
140
+ check(messages) {
141
+ const { discriminator } = this;
142
+ if (discriminator === void 0) return;
143
+ for (const [action, schema] of Object.entries(messages)) {
144
+ const shape = objectShape(toJsonSchema(schema));
145
+ if (!shape) throw new WebSocketMessageNotAnObject(this.surface, action, discriminator);
146
+ if (shape.has(discriminator)) throw new WebSocketMessageDeclaresDiscriminator(this.surface, action, discriminator);
147
+ }
148
+ }
149
+ };
150
+ /**
151
+ * The fields a JSON Schema's object declares, or `undefined` when it is not
152
+ * an object. A union or intersection is one when each of its members is.
153
+ */
154
+ function objectShape(schema) {
155
+ if (!isRecord(schema)) return void 0;
156
+ const members = schema.anyOf ?? schema.oneOf ?? schema.allOf;
157
+ if (Array.isArray(members) && members.length > 0) {
158
+ const fields = /* @__PURE__ */ new Set();
159
+ for (const member of members) {
160
+ const shape = objectShape(member);
161
+ if (!shape) return void 0;
162
+ for (const field of shape) fields.add(field);
163
+ }
164
+ return fields;
165
+ }
166
+ if (schema.type !== "object") return void 0;
167
+ return new Set(isRecord(schema.properties) ? Object.keys(schema.properties) : []);
168
+ }
169
+ function isRecord(value) {
170
+ return typeof value === "object" && value !== null && !Array.isArray(value);
171
+ }
172
+ function isId(value) {
173
+ return typeof value === "string" || typeof value === "number";
174
+ }
9
175
  /** A connection string names no transport this package knows. */
10
176
  var UnsupportedWebSocketTransport = class extends Error {
11
177
  connectionString;
@@ -157,7 +323,9 @@ var InvalidWebSocketMessage = class extends Error {
157
323
  * How anything reaches a socket — `services.realtime` in an endpoint, and
158
324
  * `sockets` in a route of the surface itself.
159
325
  *
160
- * A message is `{ action, data }`, the shape a client's frames arrive in.
326
+ * A message is `{ action, data }`, the shape a client's frames arrive in —
327
+ * or, where the surface names a `frame.discriminator`, flat: `{ [key]: action,
328
+ * ...data }`.
161
329
  * Where the surface declares its messages, `action` is one of them and
162
330
  * `data` is typed and checked by its schema before anything is sent; where it
163
331
  * declares none, any action and any JSON value go. A message is serialised
@@ -169,10 +337,12 @@ var WebSocketPublisher = class {
169
337
  transport;
170
338
  local;
171
339
  declared;
172
- constructor(transport, local, declared) {
340
+ frame;
341
+ constructor(transport, local, declared, frame = new FrameShape(declared?.surface ?? "")) {
173
342
  this.transport = transport;
174
343
  this.local = local;
175
344
  this.declared = declared;
345
+ this.frame = frame;
176
346
  }
177
347
  /** Send `action`'s message to each connection. */
178
348
  async send(ids, action, data) {
@@ -205,22 +375,17 @@ var WebSocketPublisher = class {
205
375
  * The frame, checked by the action's schema where the surface declares
206
376
  * its messages.
207
377
  *
208
- * @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}
378
+ * @throws {UnknownWebSocketMessage}, {InvalidWebSocketMessage}, and for a
379
+ * flat frame {WebSocketDataNotAnObject}, {WebSocketDataHasDiscriminator}
209
380
  */
210
381
  async payload(action, data) {
211
- if (!this.declared) return JSON.stringify({
212
- action,
213
- data
214
- });
382
+ if (!this.declared) return this.frame.encode(action, data);
215
383
  const { surface, messages } = this.declared;
216
384
  const schema = messages[action];
217
385
  if (!schema) throw new UnknownWebSocketMessage(surface, action, Object.keys(messages));
218
386
  const result = await schema["~standard"].validate(data);
219
387
  if (result.issues) throw new InvalidWebSocketMessage(surface, action, result.issues);
220
- return JSON.stringify({
221
- action,
222
- data: result.value
223
- });
388
+ return this.frame.encode(action, result.value);
224
389
  }
225
390
  /** One delivery per process that holds any of `ids`. */
226
391
  async each(ids, delivery) {
@@ -339,6 +504,8 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
339
504
  routes = /* @__PURE__ */ new Map();
340
505
  lifecycle = {};
341
506
  heartbeat;
507
+ frame;
508
+ trusted;
342
509
  next = 0;
343
510
  closing = false;
344
511
  constructor(wss, options) {
@@ -354,13 +521,16 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
354
521
  this.lifecycle[route.kind] = route;
355
522
  }
356
523
  }
524
+ this.frame = new FrameShape(options.surface, options.frame?.discriminator);
525
+ if (options.messages) this.frame.check(options.messages);
526
+ this.trusted = [...options.trustedOrigins, ...ownOrigins(options.url)];
357
527
  this.publisher = new WebSocketPublisher(options.transport, {
358
528
  instance: this.instance,
359
529
  deliver: (delivery) => this.deliver(delivery)
360
530
  }, options.messages ? {
361
531
  surface: options.surface,
362
532
  messages: options.messages
363
- } : void 0);
533
+ } : void 0, this.frame);
364
534
  this.heartbeat = setInterval(() => this.beat(), options.heartbeatMs ?? 3e4);
365
535
  this.heartbeat.unref();
366
536
  }
@@ -390,7 +560,7 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
390
560
  async upgrade(request, socket, head) {
391
561
  if (this.closing) return refuse(socket, 503, "Service Unavailable");
392
562
  const origin = request.headers.origin;
393
- if (origin && !trustsOrigin(origin, this.options.trustedOrigins)) return refuse(socket, 403, "Forbidden");
563
+ if (origin && !trustsOrigin(origin, this.trusted)) return refuse(socket, 403, "Forbidden");
394
564
  const connectionId = `${this.instance}.${(this.next++).toString(36)}`;
395
565
  const headers = headersOf(request);
396
566
  let data = {};
@@ -452,13 +622,14 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
452
622
  }
453
623
  /** Parse, validate and run one frame. Errors go back as frames, not closes. */
454
624
  async dispatch(held, text) {
455
- let frame;
625
+ let parsed;
456
626
  try {
457
- frame = JSON.parse(text);
627
+ parsed = JSON.parse(text);
458
628
  } catch {
459
629
  return this.error(held, void 0, "Frames are JSON.");
460
630
  }
461
- if (!frame || typeof frame.action !== "string") return this.error(held, frame?.id, "A frame names its `action`.");
631
+ const frame = this.frame.decode(parsed);
632
+ if (!frame) return this.error(held, this.frame.idOf(parsed), `A frame names its \`${this.frame.key}\`.`);
462
633
  const route = this.routes.get(frame.action) ?? this.routes.get("$default");
463
634
  if (!route) return this.error(held, frame.id, `No route answers '${frame.action}'.`);
464
635
  let body = frame.data;
@@ -474,11 +645,7 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
474
645
  body,
475
646
  reply: (message) => this.write(held, JSON.stringify(message))
476
647
  }));
477
- if (returned !== void 0) this.write(held, JSON.stringify({
478
- action: frame.action,
479
- ...frame.id !== void 0 ? { id: frame.id } : {},
480
- data: returned
481
- }));
648
+ if (returned !== void 0) this.write(held, this.frame.encode(frame.action, returned, frame.id));
482
649
  } catch (error) {
483
650
  if (error instanceof HttpError) return this.error(held, frame.id, error.message);
484
651
  this.options.logger.error({
@@ -510,14 +677,10 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
510
677
  });
511
678
  }
512
679
  error(held, id, message, issues) {
513
- this.write(held, JSON.stringify({
514
- action: "$error",
515
- ...id !== void 0 ? { id } : {},
516
- data: {
517
- message,
518
- ...issues ? { issues } : {}
519
- }
520
- }));
680
+ this.write(held, this.frame.encode("$error", {
681
+ message,
682
+ ...issues ? { issues } : {}
683
+ }, id));
521
684
  }
522
685
  /** Write, unless the socket has stopped reading and its queue is full. */
523
686
  write(held, payload) {
@@ -583,6 +746,16 @@ var WebSocketSurfaceServer = class WebSocketSurfaceServer {
583
746
  this.wss.close();
584
747
  }
585
748
  };
749
+ /**
750
+ * The origins a client of the surface's own address sends: the `https://`
751
+ * one a native socket derives from `wss://`, and the address's own.
752
+ */
753
+ function ownOrigins(url) {
754
+ if (!url || !URL.canParse(url)) return [];
755
+ const own = new URL(url);
756
+ const web = new URL(url.replace(/^ws(s?):/i, "http$1:"));
757
+ return [.../* @__PURE__ */ new Set([`${own.protocol}//${own.host}`, web.origin])];
758
+ }
586
759
  function headersOf(request) {
587
760
  const headers = new Headers();
588
761
  for (const [name, value] of Object.entries(request.headers)) {
@@ -616,6 +789,11 @@ var WebSocketApi = class WebSocketApi {
616
789
  envParser;
617
790
  telemetry;
618
791
  /**
792
+ * The shape its frames take — `{ action, data }`, or flat under
793
+ * `discriminator`. What a client of the surface decodes by.
794
+ */
795
+ frame;
796
+ /**
619
797
  * The surface as a dependency: `services.<id>` is its publisher, so an
620
798
  * endpoint sends to a socket the way a route beside it does.
621
799
  */
@@ -627,6 +805,9 @@ var WebSocketApi = class WebSocketApi {
627
805
  this.id = canonical;
628
806
  const replicas = config.replicas ?? 1;
629
807
  if (!Number.isInteger(replicas) || replicas < 1) throw new InvalidReplicaCount(canonical, replicas);
808
+ const frame = new FrameShape(canonical, config.frame?.discriminator);
809
+ if (config.messages) frame.check(config.messages);
810
+ this.frame = config.frame ? { discriminator: config.frame.discriminator } : {};
630
811
  this.keys = {
631
812
  url: provideKey(canonical, "url"),
632
813
  trustedOrigins: provideKey(canonical, "trustedOrigins"),
@@ -647,7 +828,7 @@ var WebSocketApi = class WebSocketApi {
647
828
  const { connectionString } = envParser.create((get) => ({ connectionString: get(envVar).string() })).parse();
648
829
  const transport = await transportFromConnectionString(connectionString, channel);
649
830
  onShutdown(() => transport.close());
650
- return new WebSocketPublisher(transport, void 0, declared);
831
+ return new WebSocketPublisher(transport, void 0, declared, frame);
651
832
  }
652
833
  };
653
834
  }
@@ -660,7 +841,8 @@ var WebSocketApi = class WebSocketApi {
660
841
  return new WebSocketRouteBuilder("disconnect", "$disconnect", { id: this.id });
661
842
  }
662
843
  /**
663
- * The handler for frames whose `action` is `action`. `$default` answers
844
+ * The handler for frames whose `action` — or, for flat frames, whose
845
+ * discriminator — is `action`. `$default` answers
664
846
  * any action nothing else does.
665
847
  */
666
848
  route(action) {
@@ -681,9 +863,10 @@ var WebSocketApi = class WebSocketApi {
681
863
  async server(options) {
682
864
  const { Hono } = await import("hono");
683
865
  const routes = (options.modules ?? []).flatMap((module) => Object.values(module).filter(WebSocketRoute.isRoute));
684
- const { connectionString, origins } = options.envParser.create((get) => ({
866
+ const { connectionString, origins, url } = options.envParser.create((get) => ({
685
867
  connectionString: get(this.keys.publisherConnectionString).string().default(`memory://${channelOf(this.id)}`),
686
- origins: get(this.keys.trustedOrigins).string().default("").transform((value) => value.split(",").map((origin) => origin.trim()).filter(Boolean))
868
+ origins: get(this.keys.trustedOrigins).string().default("").transform((value) => value.split(",").map((origin) => origin.trim()).filter(Boolean)),
869
+ url: get(this.keys.url).string().optional()
687
870
  })).parse();
688
871
  const server = await WebSocketSurfaceServer.start({
689
872
  surface: this.id,
@@ -692,6 +875,8 @@ var WebSocketApi = class WebSocketApi {
692
875
  envParser: options.envParser,
693
876
  logger: this.logger,
694
877
  trustedOrigins: origins,
878
+ ...url ? { url } : {},
879
+ ...this.config.frame ? { frame: this.config.frame } : {},
695
880
  ...this.declared ? { messages: this.declared.messages } : {},
696
881
  ...this.authenticator ? { authenticator: this.authenticator } : {},
697
882
  ...this.config.heartbeat ? { heartbeatMs: this.config.heartbeat * 1e3 } : {},
@@ -743,6 +928,6 @@ function channelOf(id) {
743
928
  return `gkm:ws:${id}`;
744
929
  }
745
930
  //#endregion
746
- export { CLOSE, DuplicateWebSocketRoute, InvalidReplicaCount, InvalidWebSocketMessage, MemoryTransport, RedisTransport, UnknownWebSocketMessage, UnsupportedWebSocketTransport, WebSocketApi, WebSocketPublisher, WebSocketRoute, WebSocketRouteBuilder, WebSocketSurfaceServer, transportFromConnectionString };
931
+ export { CLOSE, DuplicateWebSocketRoute, InvalidReplicaCount, InvalidWebSocketMessage, MemoryTransport, RedisTransport, UnknownWebSocketMessage, UnsupportedWebSocketTransport, WebSocketApi, WebSocketDataHasDiscriminator, WebSocketDataNotAnObject, WebSocketMessageDeclaresDiscriminator, WebSocketMessageNotAnObject, WebSocketPublisher, WebSocketRoute, WebSocketRouteBuilder, WebSocketSurfaceServer, transportFromConnectionString };
747
932
 
748
933
  //# sourceMappingURL=websocket-api.mjs.map