@mnmal-ai/substrate 1.0.0-alpha.18 → 1.0.0-alpha.19

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 (40) hide show
  1. package/README.md +4 -4
  2. package/dist/{boot-store-C8KrACZ5.js → boot-store-DL2Wkzun.js} +191 -268
  3. package/dist/{bridge-5VHZiH9o.d.ts → bridge-BhiJKwfF.d.ts} +1 -1
  4. package/dist/{cli-zZ7nHhY5.js → cli-BYyPsfdY.js} +25 -28
  5. package/dist/client.browser.js +2478 -0
  6. package/dist/client.d.ts +176 -164
  7. package/dist/client.js +5 -5
  8. package/dist/{errors-DHgT7Fa8.d.ts → errors-CYOaWZ8l.d.ts} +1 -1
  9. package/dist/{index-DKJXQ031.d.ts → index-rW7fu2Af.d.ts} +3 -11
  10. package/dist/{node-version-CxqcqECU.js → node-version-BlYrbY2I.js} +8 -1
  11. package/dist/pack.d.ts +59 -11
  12. package/dist/pack.js +2 -2
  13. package/dist/{pg-edges-store-D7etFxNK.js → pg-edges-store-B0Krqoac.js} +1 -1
  14. package/dist/{plugin-DcoJGEMM.js → plugin-Dk9h__NU.js} +2 -2
  15. package/dist/proposals-bootstrap.js +2 -2
  16. package/dist/proposals.d.ts +2 -2
  17. package/dist/proposals.js +1 -1
  18. package/dist/recall-bootstrap.js +2 -2
  19. package/dist/recall.d.ts +1 -1
  20. package/dist/recall.js +2 -2
  21. package/dist/{repl-SY8cLOZl.js → repl-D6_CBsue.js} +1 -1
  22. package/dist/{row-DHxnCnhA.d.ts → row-CfsHSEfB.d.ts} +4 -4
  23. package/dist/{run-Cr-53N3F.js → run-BJMgCcCC.js} +18 -9
  24. package/dist/{schema-B5WBO8yh.d.ts → schema-laGLMvMC.d.ts} +15 -40
  25. package/dist/{script-B-32wZGY.js → script-DgXaJY1Y.js} +1 -1
  26. package/dist/sdk.d.ts +6 -6
  27. package/dist/sdk.js +3 -3
  28. package/dist/{src-CdbUzLhB.js → src-B6nsPVmD.js} +201 -25
  29. package/dist/{src-DV6PcXym.js → src-B_oTGi3X.js} +648 -845
  30. package/dist/{src-BcuotITf.js → src-BcigMQdR.js} +7 -4
  31. package/dist/{src-DR_hUj2p.js → src-D3ACIp1y.js} +1 -1
  32. package/dist/{src-B4dTiEWw.js → src-Dlmuq32R.js} +3 -3
  33. package/dist/{src-DZfgQ2gR.js → src-DreZjBk7.js} +3 -3
  34. package/dist/{src-D55T3ZcP.js → src-oO0DtS6y.js} +313 -887
  35. package/dist/substrate-admin.js +2 -2
  36. package/dist/substrate.js +2 -2
  37. package/dist/testing.d.ts +13 -47
  38. package/dist/testing.js +6 -167
  39. package/dist/{ws-BL9nSELO.d.ts → ws-BT8kL1IF.d.ts} +4 -4
  40. package/package.json +21 -23
@@ -1,6 +1,6 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { A as expandFlat, D as isActiveAdminKeyRow, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, l as requireNamespace, m as grantedIn, o as denyVerbs, p as grantOf, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or } from "./src-DR_hUj2p.js";
3
- import { A as parseInt64, D as parseQualifiedKey, E as formatQualifiedKey, F as EXPR_FUNCTIONS, I as EXPR_LIMITS, L as DEFAULT_FILTER_WRITE_LIMITS, N as DATE_UNITS, O as isInt16, P as EXPR_AGGREGATES, R as assertNever, S as withData, T as naturalOrderOf, _ as encodeEnvelope, b as packEnvelopeParts, c as isPlainRequestData, j as stringifyJson, k as isInt32, o as decodeWsEnvelope, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, v as encodePositional, w as isColumnField, x as positionValue } from "./src-CdbUzLhB.js";
2
+ import { A as expandFlat, D as isActiveAdminKeyRow, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, l as requireNamespace, m as grantedIn, o as denyVerbs, p as grantOf, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or } from "./src-D3ACIp1y.js";
3
+ import { B as isInt32, F as isColumnField, G as EXPR_AGGREGATES, H as stringifyJson, I as naturalOrderOf, J as DEFAULT_FILTER_WRITE_LIMITS, K as EXPR_FUNCTIONS, L as formatQualifiedKey, M as positionValue, N as withData, O as encodeEnvelope, R as parseQualifiedKey, V as parseInt64, W as DATE_UNITS, Y as assertNever, a as FRAMES_JSON_MIME, b as MUTATION_ACK_FIELDS, c as HEARTBEAT_FRAME, d as framesEncodingFromAccept, j as packEnvelopeParts, k as encodePositional, o as FRAMES_PACK_MIME, q as EXPR_LIMITS, s as FrameStreamError, u as encodeStreamFrame, x as mutationReturns, z as isInt16 } from "./src-B6nsPVmD.js";
4
4
  import { n as acceptsPack, t as PACK_MIME } from "./content-type-C7T28xNb.js";
5
5
  import { readFileSync } from "node:fs";
6
6
  import { createCipheriv, createDecipheriv, createHash, createHmac, createPrivateKey, createPublicKey, createVerify, hkdfSync, randomBytes, randomUUID, sign, timingSafeEqual, verify } from "node:crypto";
@@ -727,7 +727,7 @@ function normaliseVocabWhere(where, fieldDefs) {
727
727
  //#endregion
728
728
  //#region ../../packages/substrate-types/src/ws.ts
729
729
  /**
730
- * Terminal-cause vocabulary (docs/ws-subscription-contract.md). The overload
730
+ * Terminal-cause vocabulary (docs/stream-contract.md). The overload
731
731
  * token is BOTH the `code` of the terminal `error` frame and the `reason` of
732
732
  * the following `end` frame — one token per condition, no second spelling.
733
733
  */
@@ -1087,7 +1087,7 @@ function rejectionDetail(reason) {
1087
1087
  }
1088
1088
  /**
1089
1089
  * The parts of a Key row a verification relied on. A string, so it survives
1090
- * the SSE ticket's JSON round trip on the identity.
1090
+ * a JSON round trip on the identity.
1091
1091
  */
1092
1092
  function keyRecordDigest(alg, publicKey, namespaces, capabilities) {
1093
1093
  return createHash("sha256").update(JSON.stringify([
@@ -1230,7 +1230,7 @@ function projectionFields(envelope, frame, key) {
1230
1230
  return entry.fields;
1231
1231
  }
1232
1232
  /**
1233
- * WS analog of `projectEnvelope` — applies the same row-trimming to the
1233
+ * Frame analog of `projectEnvelope` — applies the same row-trimming to the
1234
1234
  * `data` payload of a `WsResponseFrame` using the per-key `fieldsByKey`
1235
1235
  * map the route layer captures at subscribe / stream time.
1236
1236
  *
@@ -1561,7 +1561,7 @@ function buildEncodeCtx(engine, frame, opts) {
1561
1561
  //#region ../../packages/substrate-compose/src/routes/whoami.ts
1562
1562
  /**
1563
1563
  * The caller-facing projection of an `Identity`: `{ id, grants }`. Shared with
1564
- * the WS `whoami` frame.
1564
+ * the `whoami` frame.
1565
1565
  */
1566
1566
  function describeIdentity(identity) {
1567
1567
  return {
@@ -1622,7 +1622,7 @@ var HttpBridgeClient = class {
1622
1622
  constructor(opts) {
1623
1623
  this.name = opts.name;
1624
1624
  this.baseUrl = opts.baseUrl.endsWith("/") ? opts.baseUrl.slice(0, -1) : opts.baseUrl;
1625
- this.#fetch = opts.fetch ?? fetch;
1625
+ this.#fetch = opts.fetch;
1626
1626
  this.#intervalMs = opts.healthCheckIntervalMs ?? DEFAULT_HEALTH_INTERVAL_MS;
1627
1627
  this.#auth = opts.auth;
1628
1628
  this.#timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -7309,12 +7309,17 @@ function hashContent(types, mutations) {
7309
7309
  mutations
7310
7310
  })));
7311
7311
  }
7312
+ /** A create or update over a declared type, not a struct of its own (updateMany's `{ count, ids }`). */
7313
+ function writesRows(entry) {
7314
+ return (entry.verb === "create" || entry.verb === "update") && entry.returns?.kind === "struct" && entry.fields !== void 0 && Object.keys(entry.fields).length > 0;
7315
+ }
7312
7316
  function publishSchema(registry) {
7313
7317
  const types = {};
7314
7318
  const mutations = {};
7315
7319
  for (const [name, entry] of registry.all()) if (entry.kind === "mutation") mutations[name] = {
7316
7320
  params: entry.params,
7317
- returns: entry.returns ?? UNKNOWN_RETURNS
7321
+ returns: entry.returns ?? UNKNOWN_RETURNS,
7322
+ ...writesRows(entry) ? { writesRows: true } : {}
7318
7323
  };
7319
7324
  else types[name] = entry.orderedBy !== void 0 ? {
7320
7325
  fields: entry.fields,
@@ -16927,8 +16932,7 @@ function wrapPluginRouterWithSystemActor(router, actor) {
16927
16932
  post: (path, h) => router.post(path, w(h)),
16928
16933
  put: (path, h) => router.put(path, w(h)),
16929
16934
  delete: (path, h) => router.delete(path, w(h)),
16930
- patch: (path, h) => router.patch(path, w(h)),
16931
- websocket: (path, h) => router.websocket(path, h)
16935
+ patch: (path, h) => router.patch(path, w(h))
16932
16936
  };
16933
16937
  }
16934
16938
  /**
@@ -16973,87 +16977,11 @@ function withAuth(handler, cfg, required, onAnonymousRead) {
16973
16977
  };
16974
16978
  }
16975
16979
  /**
16976
- * Cap on frames buffered before a plugin WS handler's `onMessage` registers
16977
- * (the early-frame race — see `wrapWsHandler`). An unauthenticated peer that
16978
- * never reaches a registered listener, whether rejected outright or simply
16979
- * connected to a handler that never calls `onMessage`, must not be able to
16980
- * grow this queue without bound while the socket stays open.
16981
- */
16982
- const WS_EARLY_FRAME_QUEUE_LIMIT = 64;
16983
- /**
16984
- * Authenticate a plugin WebSocket route and hand the inner handler a request
16985
- * carrying `identity` when the caller presented a valid bearer token. A plugin
16986
- * serving its own frame protocol at `/substrate/v1/plugins/<name>/ws` gets neither the
16987
- * binary's handshake auth nor the engine's per-frame gate.
16988
- *
16989
- * Mirrors `withAuth`'s mode handling: an absent token is rejected (1008)
16990
- * unless `cfg.mode === 'attribute'`, in which case the
16991
- * caller proceeds anonymous, with any caller-supplied `identity` stripped —
16992
- * the same defence-in-depth `withAuth` applies on its own anonymous path.
16993
- * A token that is present but invalid is always rejected, regardless of
16994
- * mode: presenting a bad credential is an error, never a downgrade to
16995
- * anonymous. Which frames are privileged, and what capability each
16996
- * requires, stays the plugin's call — this wrapper only resolves identity.
16997
- */
16998
- function wrapWsHandler(handler, cfg) {
16999
- return async (req, conn) => {
17000
- const queued = [];
17001
- const listeners = [];
17002
- let rejected = false;
17003
- function rejectAndClose(reason) {
17004
- rejected = true;
17005
- queued.length = 0;
17006
- conn.close(1008, reason);
17007
- }
17008
- conn.onMessage((b) => {
17009
- if (rejected) return;
17010
- if (listeners.length > 0) {
17011
- for (const cb of listeners) cb(b);
17012
- return;
17013
- }
17014
- queued.push(b);
17015
- if (queued.length > WS_EARLY_FRAME_QUEUE_LIMIT) rejectAndClose("frame backlog");
17016
- });
17017
- const token = extractBearer(req.headers.authorization);
17018
- if (token === null) {
17019
- if (cfg.mode !== "attribute") {
17020
- rejectAndClose("unauthorized");
17021
- return;
17022
- }
17023
- const { identity: _identity, ...anonReq } = req;
17024
- req = anonReq;
17025
- } else {
17026
- const verdict = authenticateBearer(token, cfg);
17027
- if (!verdict.ok) {
17028
- rejectAndClose("unauthorized");
17029
- return;
17030
- }
17031
- req = {
17032
- ...req,
17033
- identity: verdict.identity
17034
- };
17035
- const stop = watchCredential(verdict.identity, cfg, (lapse) => conn.close(1008, lapse));
17036
- conn.onClose(stop);
17037
- }
17038
- if (rejected) return;
17039
- const shim = {
17040
- ...conn,
17041
- onMessage: (cb) => {
17042
- while (queued.length > 0) for (const b of queued.splice(0)) cb(b);
17043
- listeners.push(cb);
17044
- }
17045
- };
17046
- await handler(req, shim);
17047
- };
17048
- }
17049
- /**
17050
16980
  * Wrap a `PluginRouter` so every registered route runs through `withAuth`
17051
16981
  * with a capability inferred from the HTTP method — GET reads, everything
17052
16982
  * else mutates. An authenticated caller must hold that capability in one of
17053
16983
  * `namespaces` (the plugin's declared namespaces); a plugin that declares
17054
- * none accepts the capability held in any namespace. WS routes are wrapped by
17055
- * `wrapWsHandler`, which resolves identity but leaves the
17056
- * privileged/anonymous decision to the plugin.
16984
+ * none accepts the capability held in any namespace.
17057
16985
  */
17058
16986
  function wrapPluginRouter(router, cfg, namespaces = []) {
17059
16987
  const gate = (method, h) => {
@@ -17071,32 +16999,20 @@ function wrapPluginRouter(router, cfg, namespaces = []) {
17071
16999
  post: (path, h) => router.post(path, gate("POST", h)),
17072
17000
  put: (path, h) => router.put(path, gate("PUT", h)),
17073
17001
  delete: (path, h) => router.delete(path, gate("DELETE", h)),
17074
- patch: (path, h) => router.patch(path, gate("PATCH", h)),
17075
- websocket: (path, h) => router.websocket(path, wrapWsHandler(h, cfg))
17002
+ patch: (path, h) => router.patch(path, gate("PATCH", h))
17076
17003
  };
17077
17004
  }
17078
17005
 
17079
17006
  //#endregion
17080
17007
  //#region ../../packages/substrate-compose/src/compose/guards.ts
17081
- /**
17082
- * Floor for the SSE stream-ticket HMAC key. 16 chars is the shortest length
17083
- * that isn't trivially brute-forced offline — an attacker can test candidate
17084
- * keys against any ticket they observe, with no server round-trip to rate-limit.
17085
- */
17086
- const MIN_STREAM_TICKET_SECRET_LEN = 16;
17087
17008
  function resolveBootGuards(opts) {
17088
- const streamTicketSecret = opts.streamTicketSecret?.trim();
17089
- if (opts.auth !== void 0 && (streamTicketSecret === void 0 || streamTicketSecret.length < MIN_STREAM_TICKET_SECRET_LEN)) throw new Error(`compose: \`streamTicketSecret\` must be at least ${MIN_STREAM_TICKET_SECRET_LEN} characters when auth is enabled — it signs the SSE stream tickets that are the only authentication on GET /substrate/v1/stream and /substrate/v1/subscribe, so a short, empty, or whitespace-only key is a forgeable one (set SUBSTRATE_STREAM_TICKET_SECRET for the binary)`);
17090
17009
  const systemActor = opts.systemActor?.trim();
17091
17010
  if (opts.auth === void 0 && (systemActor === void 0 || systemActor.length === 0)) throw new Error("compose: `systemActor` is required when auth is disabled — with no bearer there is nothing to attribute a write to, and Substrate no longer defaults to `system:anonymous`. Declare who this deployment writes as, e.g. systemActor: 'local-dev' (SUBSTRATE_SYSTEM_ACTOR for the binary). Enable auth instead if callers should be attributed individually.");
17092
- return {
17093
- streamTicketSecret,
17094
- systemIdentity: systemActor !== void 0 && systemActor.length > 0 ? {
17095
- kind: "system",
17096
- id: systemActor,
17097
- grants: { "*": ["read", "mutate"] }
17098
- } : null
17099
- };
17011
+ return { systemIdentity: systemActor !== void 0 && systemActor.length > 0 ? {
17012
+ kind: "system",
17013
+ id: systemActor,
17014
+ grants: { "*": ["read", "mutate"] }
17015
+ } : null };
17100
17016
  }
17101
17017
 
17102
17018
  //#endregion
@@ -17543,13 +17459,8 @@ const failed = (err) => ({
17543
17459
 
17544
17460
  //#endregion
17545
17461
  //#region ../../packages/substrate-compose/src/routes/connection-limit.ts
17546
- /** Most WS sockets plus SSE streams one client may hold open at once. */
17462
+ /** Most long-lived responses one client may hold open at once. */
17547
17463
  const MAX_CONNECTIONS_PER_CLIENT = 64;
17548
- /**
17549
- * Most subscribe/stream sessions one client may hold open at once, across
17550
- * every WS socket and SSE stream. Each one is engine work on every write.
17551
- */
17552
- const MAX_SESSIONS_PER_CLIENT = 1024;
17553
17464
  function createConnectionLimiter(max = 64) {
17554
17465
  const open = /* @__PURE__ */ new Map();
17555
17466
  return { acquire(identity, clientIp) {
@@ -17647,13 +17558,11 @@ function healthRoute(deps) {
17647
17558
  * POST /substrate/v1/mutate — accept a frame, dispatch to the engine, return envelope.
17648
17559
  *
17649
17560
  * Under `Accept: application/vnd.substrate.pack`, mutation responses are positionally
17650
- * encoded using the per-mutation `MutationSchema.returns` metadata emitted
17651
- * by the registry. The route pulls each mutation's registry entry via
17652
- * `engine.registryFor(ns)` and threads the declared `returns` FieldDef into
17653
- * the substrate-pack encoder (§5.2).
17561
+ * encoded by each mutation's published `MutationSchema.returns` (§5.2).
17654
17562
  *
17655
- * On the JSON wire, a create or update that names no `fields` answers with
17656
- * `{ id, shortId }` rather than the whole written row.
17563
+ * A mutation answers by the frame's `fields` on both wires, and a create or
17564
+ * update that names none answers `{ id, shortId }`: JSON projects the result,
17565
+ * pack encodes it by `returns` narrowed the same way (`mutationReturns`).
17657
17566
  */
17658
17567
  function mutateRoute(engine, trustedProxies, authEnabled) {
17659
17568
  return async (req) => {
@@ -17666,19 +17575,19 @@ function mutateRoute(engine, trustedProxies, authEnabled) {
17666
17575
  ctx: buildContext(req, trustedProxies, authEnabled),
17667
17576
  ...req.signal !== void 0 ? { signal: req.signal } : {}
17668
17577
  });
17578
+ const schemas = engine.federatedSchema();
17669
17579
  const returnsByKey = {};
17670
17580
  const currentNsByKey = {};
17671
17581
  const projectBy = { ...frame };
17672
17582
  for (const [key, frameEntry] of Object.entries(frame)) {
17673
17583
  const parsed = parseQualifiedKey(key);
17674
17584
  if (parsed === null) continue;
17675
- const { ns, name } = parsed;
17676
- const entry = engine.registryFor(ns)?.get(name);
17677
- if (entry?.returns !== void 0) {
17678
- returnsByKey[key] = entry.returns;
17679
- currentNsByKey[key] = ns;
17680
- }
17681
- if (entry !== void 0 && writesRows(entry)) projectBy[key] = Array.isArray(frameEntry) ? frameEntry.map(withAckFields) : withAckFields(frameEntry);
17585
+ const mutation = schemas[parsed.ns]?.mutations[parsed.name];
17586
+ if (mutation === void 0) continue;
17587
+ currentNsByKey[key] = parsed.ns;
17588
+ const shapeOf = (f) => mutationReturns(mutation, f.fields);
17589
+ returnsByKey[key] = Array.isArray(frameEntry) ? frameEntry.map(shapeOf) : shapeOf(frameEntry);
17590
+ if (mutation.writesRows === true) projectBy[key] = Array.isArray(frameEntry) ? frameEntry.map(withAckFields) : withAckFields(frameEntry);
17682
17591
  }
17683
17592
  return serializeEnvelope(req, envelope, engine, projectBy, {
17684
17593
  returnsByKey,
@@ -17686,19 +17595,10 @@ function mutateRoute(engine, trustedProxies, authEnabled) {
17686
17595
  });
17687
17596
  };
17688
17597
  }
17689
- /** What a row-writing mutation answers when the frame names no `fields`. */
17690
- const ACK_FIELDS = {
17691
- id: true,
17692
- shortId: true
17693
- };
17694
- /** A create or update that returns rows of a declared type, not a struct of its own (delete's `{ id, deleted }`). */
17695
- function writesRows(entry) {
17696
- return (entry.verb === "create" || entry.verb === "update") && entry.returns !== void 0 && entry.fields !== void 0 && Object.keys(entry.fields).length > 0;
17697
- }
17698
17598
  function withAckFields(frameEntry) {
17699
17599
  return frameEntry.fields === void 0 ? {
17700
17600
  ...frameEntry,
17701
- fields: ACK_FIELDS
17601
+ fields: MUTATION_ACK_FIELDS
17702
17602
  } : frameEntry;
17703
17603
  }
17704
17604
 
@@ -17760,7 +17660,7 @@ const HTTP_INSTRUCTIONS = {
17760
17660
  "`authEnabled: false` means this deployment verifies nothing, which is NOT the same as you being anonymous",
17761
17661
  "USE IT BEFORE CONCLUDING A CREDENTIAL WORKS: on a reads-open stack an authenticated read and an anonymous one return byte-identical results, so a successful query is never evidence of identity",
17762
17662
  "the grant is returned AS RECORDED — a wildcard stays a `\"*\"` key in `grants` rather than expanding into every namespace",
17763
- "also available as the MCP tool `whoami`, and as a WS frame `{ id, op: \"whoami\" }` — ask on the SOCKET when the socket is what you are asking about, since its auth is a separate code path from HTTP"
17663
+ "also available as the MCP tool `whoami`"
17764
17664
  ]
17765
17665
  },
17766
17666
  federatedSchema: {
@@ -17769,80 +17669,51 @@ const HTTP_INSTRUCTIONS = {
17769
17669
  notes: [
17770
17670
  "returns `Record<namespace, Schema>` for every active namespace",
17771
17671
  "cache at cold-start + rebuild when a response signals a federatedVersion mismatch",
17772
- "build the WS nsIndex map from sorted(federatedSchema keys)"
17672
+ "build the pack nsIndex map from sorted(federatedSchema keys)"
17773
17673
  ]
17774
17674
  }
17775
17675
  };
17776
17676
  /**
17777
- * The live subscription surfaces: WS and SSE carry the same engine operations
17778
- * in different envelopes, so both are described.
17677
+ * The live subscription surfaces: one POST per subscription or stream, the
17678
+ * response body a sequence of length-prefixed frames.
17779
17679
  *
17780
17680
  * Every string here is a claim about the wire, held to the real routes by
17781
- * `onboard-wire-shapes.test.ts`. A claim conditioned on an auth mode is only
17782
- * defended if that test composes a server in that mode.
17681
+ * `onboard-wire-shapes.test.ts`.
17783
17682
  */
17784
- const WS_INSTRUCTIONS = {
17683
+ const STREAM_INSTRUCTIONS = {
17785
17684
  subscribe: {
17786
- transport: "ws",
17787
- path: "/substrate/v1/ws",
17788
- frame: "{\"id\":\"1\",\"op\":\"subscribe\",\"frame\":{\"<ns>/<TypeName>\":{\"params\":{\"where\":{}},\"fields\":{\"id\":true}}}}",
17789
- /**
17790
- * Structured rather than prose: each field is one cell of the
17791
- * {mode} × {token} matrix, so `onboard-wire-shapes.test.ts` can read a cell
17792
- * and drive that cell.
17793
- */
17794
- authByMode: {
17795
- required: "DEFAULT. A tokenless upgrade receives one { id:\"\", kind:\"error\", errors:[{ code:\"unauthorized\" }] } frame and is closed with code 4001",
17796
- attribute: "A tokenless upgrade is ADMITTED and runs anonymously, matching the HTTP routes under this mode — send `{ id, op:\"whoami\" }` and `identity` comes back null.",
17797
- invalidToken: "Closed 4001 in BOTH modes. This is the distinction to design against rather than the mode: `attribute` relaxes \"you sent nothing\", never \"what you sent is broken\", so a caller that always sends a token sees identical behaviour either way"
17798
- },
17685
+ method: "POST",
17686
+ path: "/substrate/v1/subscribe",
17687
+ accept: "application/vnd.substrate.frames+json",
17688
+ body: "{\"<ns>/<TypeName>\":{\"params\":{\"where\":{}},\"fields\":{\"id\":true}}}",
17799
17689
  notes: [
17800
- "ops are `subscribe` | `stream` | `cancel` | `whoami` — any other `op`, and any frame missing a string `id`, is refused with { id:\"\", kind:\"error\", errors:[{ code:\"invalid_frame\" }] }",
17801
- "server replies { id, kind:\"snapshot\", data:{ \"<ns>/<TypeName>\": rows }, shapes } immediately, then pushes kind:\"add\" | \"update\" | \"remove\" (a remove carries `removedId`, no `data`)",
17690
+ "send `Accept: application/vnd.substrate.frames+json` (or `+pack`, see `substratePack`); any other Accept is refused 406 with code `not_acceptable`",
17691
+ "the response body is a sequence of frames: a 4-byte big-endian length, then that many bytes of payload. A zero-length frame is a heartbeat; skip it",
17692
+ "the first frame is { id, kind:\"snapshot\", data:{ \"<ns>/<TypeName>\": rows }, shapes }, then kind:\"add\" | \"update\" | \"remove\" (a remove carries `removedId`, no `data`)",
17802
17693
  "PARAMS ARE NARROWER THAN QUERY: subscribe accepts only `where` and `orderBy`. `limit` is a POST /substrate/v1/query param and is refused here with code `unknown_param` — the allowlist is in the message",
17803
- "multi-key subscribe IS supported (unlike stream); one socket multiplexes many sessions, keyed by your `id`",
17804
- "cancel with { id, op:\"cancel\" } — the server acknowledges a cancelled SUBSCRIBE with { id, kind:\"end\", final:true }",
17805
- "`{ id, op:\"whoami\" }` answers { id, kind:\"whoami\", data:{ authEnabled, identity } } without opening a session — ask it on the socket rather than over HTTP when the socket is what you are asking about",
17806
- "subscriptions are connection-scoped — cancelled automatically on disconnect",
17694
+ "multi-key subscribe IS supported (unlike stream)",
17695
+ "one subscription per response: close the response to cancel it",
17807
17696
  "virtual namespaces cannot be subscribed: a `recall/*` key is refused with code `subscription_unsupported_frame` (one-shot query/mutate only)",
17808
- "AUTH FOLLOWS `mode` — see `authByMode` on this section for the cell-by-cell answer. The short version: the DEFAULT mode refuses a tokenless socket, `attribute` admits one, and neither mode admits a broken token",
17809
- "ANONYMOUS IS NOT PERMITTED — it is only ADMITTED. An anonymous socket still meets the namespace read policy inside `engine.subscribe`, which answers `policy_denied` on its own terms; the upgrade gate decides nothing except whether a tokenless caller reaches it"
17697
+ "auth is the same as POST /substrate/v1/query: the route needs `read`",
17698
+ "failures BEFORE the stream opens are ordinary HTTP status codes; once bytes are on the wire the status is spent and errors arrive in-band as { kind:\"error\", errors } frames",
17699
+ "a server shutting down sends { kind:\"end\", reason:\"server_restart\" } before closing: subscribe again for a fresh snapshot"
17810
17700
  ]
17811
17701
  },
17812
17702
  stream: {
17813
- transport: "ws",
17814
- path: "/substrate/v1/ws",
17815
- frame: "{\"id\":\"1\",\"op\":\"stream\",\"frame\":{\"<ns>/<TypeName>\":{\"params\":{},\"fields\":{\"id\":true}}}}",
17703
+ method: "POST",
17704
+ path: "/substrate/v1/stream",
17705
+ accept: "application/vnd.substrate.frames+json",
17706
+ body: "{\"<ns>/<TypeName>\":{\"params\":{},\"fields\":{\"id\":true}}}",
17816
17707
  notes: [
17817
17708
  "single op-key only — two keys are refused with code `stream_multi_key`",
17818
- "server pushes { id, kind:\"chunk\", data:{ \"<ns>/<TypeName>\": <entity> } } per chunk",
17709
+ "one { id, kind:\"chunk\", data:{ \"<ns>/<TypeName>\": <entity> } } frame per chunk",
17819
17710
  "terminates with { id, kind:\"end\", final:true } — errors terminate too, no partial-error-then-resume",
17820
17711
  "streaming needs a resolver returning an async iterable; autoCRUD types are not streamable and answer code `not_streamable`"
17821
17712
  ]
17822
17713
  },
17823
17714
  substratePack: {
17824
- transport: "ws",
17825
- path: "/substrate/v1/ws",
17826
- notes: [
17827
- "advertise `Sec-WebSocket-Protocol: substrate-pack` at handshake to negotiate MessagePack frames with positionally-encoded `data`",
17828
- "the negotiation is SYMMETRIC: on a pack socket your REQUEST frames must be MessagePack too — sending JSON text there is refused with code `invalid_frame`",
17829
- "positional `data` decodes against the field selection you sent, in declared field order — see @mnmal-ai/substrate-pack (encodeWsFrame / decodeWsEnvelope)"
17830
- ]
17831
- },
17832
- sse: {
17833
- transport: "sse",
17834
- paths: [
17835
- "/substrate/v1/subscribe",
17836
- "/substrate/v1/stream",
17837
- "/substrate/v1/stream/ticket"
17838
- ],
17839
- notes: [
17840
- "same two engine operations as WS, one session per HTTP response — cancellation IS disconnection, so there is no `cancel` op and no session id",
17841
- "POST /substrate/v1/subscribe (or /substrate/v1/stream) with the frame object as the BODY — the qualified-frame-keyed payload, exactly as POST /substrate/v1/query takes it",
17842
- "GET the same paths with ?frame=<url-encoded JSON> for EventSource, which cannot send an Authorization header: mint a ticket first with POST /substrate/v1/stream/ticket (body = the same frame) and pass ?ticket=<ticket>. A ticketless GET is 401 `ticket_missing`; the ticket is bound to that exact frame",
17843
- "THE EVENT ENVELOPE DIFFERS FROM WS: SSE emits `event: <kind>` with a per-frame payload — snapshot/add/update carry { key, rows } or { key, row }, remove carries { removedId }, end carries { reason }, error carries { code, message }. WS instead sends one object per frame carrying `data` keyed by the frame key",
17844
- "failures BEFORE the stream opens are ordinary HTTP status codes; once bytes are on the wire the status is spent and errors arrive in-band as `event: error`"
17845
- ]
17715
+ accept: "application/vnd.substrate.frames+pack",
17716
+ notes: ["send `Accept: application/vnd.substrate.frames+pack` on subscribe or stream for MessagePack frames with positionally-encoded `data`; the request body stays JSON", "positional `data` decodes against the field selection you sent, in declared field order — see @mnmal-ai/substrate-pack (decodeStreamFrames / decodeWsEnvelope)"]
17846
17717
  }
17847
17718
  };
17848
17719
  const CODE_MODE_INSTRUCTIONS = {
@@ -17940,10 +17811,9 @@ function buildOnboardBody(deps) {
17940
17811
  schemaForType: HTTP_INSTRUCTIONS.schemaForType,
17941
17812
  federatedSchema: HTTP_INSTRUCTIONS.federatedSchema,
17942
17813
  whoami: HTTP_INSTRUCTIONS.whoami,
17943
- subscribe: WS_INSTRUCTIONS.subscribe,
17944
- stream: WS_INSTRUCTIONS.stream,
17945
- substratePack: WS_INSTRUCTIONS.substratePack,
17946
- sse: WS_INSTRUCTIONS.sse,
17814
+ subscribe: STREAM_INSTRUCTIONS.subscribe,
17815
+ stream: STREAM_INSTRUCTIONS.stream,
17816
+ substratePack: STREAM_INSTRUCTIONS.substratePack,
17947
17817
  codeMode: CODE_MODE_INSTRUCTIONS,
17948
17818
  plugins: buildPluginContributions(deps.coordinators),
17949
17819
  pluginRoutes: buildPluginRoutes(deps.coordinators)
@@ -18235,62 +18105,220 @@ function mutationTargetsType(name, def, type, fields) {
18235
18105
  }
18236
18106
 
18237
18107
  //#endregion
18238
- //#region ../../packages/substrate-compose/src/routes/sse-frame.ts
18108
+ //#region ../../packages/substrate-compose/src/routes/demand-transport.ts
18109
+ const DEFAULT_HEARTBEAT_MS = 2e4;
18239
18110
  /**
18240
- * SSE wire framing. Spec §5. Pure — no I/O, so every wire-format decision is
18241
- * unit-testable without a server.
18242
- *
18243
- * Encoding is `json` ONLY. SSE `data:` is a text field; base64-ing msgpack
18244
- * would cost ~33% to ship the format that is supposed to be the compact one.
18245
- * The §7.4 pack codec stays reserved for a future binary transport.
18246
- */
18247
- const SSE_HEADERS = {
18248
- "content-type": "text/event-stream",
18249
- "cache-control": "no-store",
18250
- "x-accel-buffering": "no"
18251
- };
18252
- const SSE_HEARTBEAT = ": keepalive\n\n";
18253
- /** Browser default is 3s — too eager when every reconnect costs a snapshot. */
18254
- function sseRetry(ms) {
18255
- return `retry: ${ms}\n\n`;
18111
+ * How long a data frame may wait for the consumer to read before the stream is
18112
+ * cut off. Generous on purpose: a park also waits on every buffer between here
18113
+ * and a slow client (a 1 KB/s reader parks ~64 s), and dead peers are caught
18114
+ * by the server's HTTP/2 pings, so this only has to catch a live peer that
18115
+ * stopped reading.
18116
+ */
18117
+ const DEFAULT_STALL_MS = 3e5;
18118
+ /**
18119
+ * A response body paced to consumer demand, carrying one session's frames in
18120
+ * whatever wire encoding `encode` gives.
18121
+ */
18122
+ function createDemandTransport(opts) {
18123
+ const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
18124
+ const stallMs = opts.stallMs ?? 3e5;
18125
+ let controller = null;
18126
+ let heartbeat = null;
18127
+ let closed = false;
18128
+ /**
18129
+ * Resolvers of parked `emit` calls. Must be a Set, not a single slot: a
18130
+ * multi-key subscribe drains each key on its own task sharing one `onFrame`,
18131
+ * so two `emit`s can be in flight at once, and a single slot would strand
18132
+ * the first one's drain task.
18133
+ */
18134
+ const demand = /* @__PURE__ */ new Set();
18135
+ const stopHeartbeat = () => {
18136
+ if (heartbeat !== null) {
18137
+ clearInterval(heartbeat);
18138
+ heartbeat = null;
18139
+ }
18140
+ };
18141
+ /** Wake every parked `emit`, not just one — see the `demand` docblock. */
18142
+ const releaseDemand = () => {
18143
+ for (const resolve of demand) resolve();
18144
+ demand.clear();
18145
+ };
18146
+ /**
18147
+ * Shared by every teardown path (write failure, close, consumer cancel) so
18148
+ * none of them can leave the heartbeat ticking or an `emit` parked forever;
18149
+ * a parked `emit` strands the engine's producer loop.
18150
+ */
18151
+ const teardown = () => {
18152
+ closed = true;
18153
+ stopHeartbeat();
18154
+ releaseDemand();
18155
+ };
18156
+ const write = (bytes) => {
18157
+ if (closed || controller === null) return;
18158
+ try {
18159
+ controller.enqueue(bytes);
18160
+ } catch {
18161
+ teardown();
18162
+ controller = null;
18163
+ }
18164
+ };
18165
+ /** The consumer stopped reading with data waiting: error the body and cancel the session. */
18166
+ const stall = () => {
18167
+ if (closed) return;
18168
+ const c = controller;
18169
+ teardown();
18170
+ controller = null;
18171
+ try {
18172
+ c?.error(/* @__PURE__ */ new Error("consumer_stalled"));
18173
+ } catch {}
18174
+ opts.onStall?.();
18175
+ opts.onCancel?.();
18176
+ };
18177
+ return {
18178
+ transport: {
18179
+ emit: async (frame, fieldsByKey) => {
18180
+ if (closed) return;
18181
+ write(opts.encode(frame, fieldsByKey));
18182
+ if (frame.kind === "end" || frame.kind === "error") return;
18183
+ if (controller !== null && (controller.desiredSize ?? 1) <= 0) await new Promise((resolve) => {
18184
+ const timer = setTimeout(stall, stallMs);
18185
+ timer.unref?.();
18186
+ demand.add(() => {
18187
+ clearTimeout(timer);
18188
+ resolve();
18189
+ });
18190
+ });
18191
+ },
18192
+ close: (_reason) => {
18193
+ if (closed) return;
18194
+ teardown();
18195
+ try {
18196
+ controller?.close();
18197
+ } catch {}
18198
+ controller = null;
18199
+ }
18200
+ },
18201
+ body: new ReadableStream({
18202
+ start(c) {
18203
+ controller = c;
18204
+ heartbeat = setInterval(() => write(opts.heartbeat), heartbeatMs);
18205
+ heartbeat.unref?.();
18206
+ },
18207
+ pull() {
18208
+ releaseDemand();
18209
+ },
18210
+ cancel() {
18211
+ teardown();
18212
+ controller = null;
18213
+ opts.onCancel?.();
18214
+ }
18215
+ }),
18216
+ writeFrame: (frame) => write(opts.encode(frame, void 0))
18217
+ };
18256
18218
  }
18219
+
18220
+ //#endregion
18221
+ //#region ../../packages/substrate-compose/src/routes/pack-frame.ts
18257
18222
  /**
18258
- * Render one frame.
18259
- *
18260
- * NOTE: deliberately emits NO `id:` field. An `id:` causes the browser to send
18261
- * `Last-Event-ID` on reconnect, which advertises a resume capability Substrate does
18262
- * not implement (subscriptions are state-convergent, not event-sourced — spec
18263
- * §4). `sequence` travels inside `data` for client-side ordering instead.
18264
- */
18265
- function sseEvent(frame, fieldsByKey) {
18266
- return `event: ${frame.kind}\ndata: ${stringifyJson(payloadFor(frame, fieldsByKey))}\n\n`;
18267
- }
18268
- function payloadFor(frame, fieldsByKey) {
18269
- if (frame.kind === "end") return { reason: frame.reason ?? (frame._meta?.cancelled === true ? "cancelled" : "complete") };
18270
- if (frame.kind === "error") {
18271
- const first = frame.errors?.[0];
18272
- return {
18273
- code: first?.code ?? "error",
18274
- message: first?.message ?? "stream error"
18275
- };
18223
+ * Produce a wire-ready frame object — for substrate-pack, positionally encode
18224
+ * `data` against the per-key FieldInput + the engine's federated schema. Remove
18225
+ * frames (no `data`) and error/end frames pass through untouched.
18226
+ */
18227
+ function encodeDataForPack(frame, fieldsByKey, engine) {
18228
+ if (frame.data === void 0 || fieldsByKey === void 0) return frame;
18229
+ const schemas = engine.federatedSchema();
18230
+ const encoded = {};
18231
+ for (const [key, value] of Object.entries(frame.data)) {
18232
+ const parsed = parseQualifiedKey(key);
18233
+ if (parsed === null) {
18234
+ encoded[key] = value;
18235
+ continue;
18236
+ }
18237
+ const { ns, name } = parsed;
18238
+ const fields = fieldsByKey.get(key);
18239
+ const schema = schemas[ns];
18240
+ if (fields === void 0 || schema === void 0) {
18241
+ encoded[key] = value;
18242
+ continue;
18243
+ }
18244
+ const rawShape = frame.shapes?.[key];
18245
+ encoded[key] = encodeByShape(value, fields, schema, name, rawShape === "single" || rawShape === "list" ? rawShape : void 0, {
18246
+ schemas,
18247
+ currentNs: ns
18248
+ });
18276
18249
  }
18277
- if (frame.kind === "remove") return { removedId: frame.removedId };
18278
- const data = projectWsFrame(frame, fieldsByKey).data ?? {};
18279
- const key = Object.keys(data)[0];
18280
- if (key === void 0) return {};
18281
- const value = data[key];
18282
- const shape = frame.shapes?.[key];
18283
- const base = (shape !== void 0 ? shape === "list" : frame.kind === "snapshot") ? {
18284
- key,
18285
- rows: Array.isArray(value) ? value : [value]
18286
- } : {
18287
- key,
18288
- row: value
18250
+ return {
18251
+ ...frame,
18252
+ data: encoded
18253
+ };
18254
+ }
18255
+ function encodeByShape(value, fields, schema, typeName, shape, ctx) {
18256
+ if (value === null || value === void 0) return null;
18257
+ if (shape === "list") {
18258
+ if (!Array.isArray(value)) return value;
18259
+ return value.map((row) => encodePositional(row, fields, schema, typeName, ctx));
18260
+ }
18261
+ return encodePositional(value, fields, schema, typeName, ctx);
18262
+ }
18263
+
18264
+ //#endregion
18265
+ //#region ../../packages/substrate-compose/src/routes/frames-transport.ts
18266
+ function framesHeaders(mode) {
18267
+ return {
18268
+ "content-type": mode === "pack" ? FRAMES_PACK_MIME : FRAMES_JSON_MIME,
18269
+ "cache-control": "no-store",
18270
+ "x-accel-buffering": "no"
18271
+ };
18272
+ }
18273
+ function createFramesTransport(opts) {
18274
+ const { mode, engine } = opts;
18275
+ let tooLarge = false;
18276
+ const payload = (frame, fieldsByKey) => mode === "pack" ? encodeDataForPack(frame, fieldsByKey, engine) : projectWsFrame(frame, fieldsByKey);
18277
+ const encode = (frame, fieldsByKey) => {
18278
+ try {
18279
+ return encodeStreamFrame(payload(frame, fieldsByKey), mode);
18280
+ } catch (err) {
18281
+ if (!(err instanceof FrameStreamError)) throw err;
18282
+ tooLarge = true;
18283
+ const error = encodeStreamFrame({
18284
+ id: frame.id,
18285
+ kind: "error",
18286
+ errors: [{
18287
+ code: err.code,
18288
+ message: err.message
18289
+ }]
18290
+ }, mode);
18291
+ const end = encodeStreamFrame({
18292
+ id: frame.id,
18293
+ kind: "end",
18294
+ reason: err.code,
18295
+ final: true
18296
+ }, mode);
18297
+ const out = new Uint8Array(error.length + end.length);
18298
+ out.set(error);
18299
+ out.set(end, error.length);
18300
+ return out;
18301
+ }
18302
+ };
18303
+ const inner = createDemandTransport({
18304
+ encode,
18305
+ heartbeat: HEARTBEAT_FRAME,
18306
+ ...opts.heartbeatMs !== void 0 ? { heartbeatMs: opts.heartbeatMs } : {},
18307
+ ...opts.onCancel !== void 0 ? { onCancel: opts.onCancel } : {},
18308
+ ...opts.onStall !== void 0 ? { onStall: opts.onStall } : {}
18309
+ });
18310
+ return {
18311
+ ...inner,
18312
+ transport: {
18313
+ emit: async (frame, fieldsByKey) => {
18314
+ if (tooLarge) return;
18315
+ const sent = inner.transport.emit(frame, fieldsByKey);
18316
+ if (tooLarge) opts.onTooLarge();
18317
+ await sent;
18318
+ },
18319
+ close: inner.transport.close
18320
+ }
18289
18321
  };
18290
- return frame.sequence !== void 0 ? {
18291
- ...base,
18292
- sequence: frame.sequence
18293
- } : base;
18294
18322
  }
18295
18323
 
18296
18324
  //#endregion
@@ -18307,12 +18335,12 @@ function erroredKey(frame) {
18307
18335
  * Close reason → the token the engine records as
18308
18336
  * `engine_subscription_closed_<reason>`. Mapped here rather than per transport
18309
18337
  * so metric names are identical whichever transport opens the session.
18310
- * Pinned by apps/substrate/test/ws-teardown-contract.test.ts.
18338
+ * Pinned by apps/substrate/test/stream-teardown-contract.test.ts.
18311
18339
  */
18312
18340
  const ENGINE_CANCEL_REASON = {
18313
18341
  complete: "cancel",
18314
18342
  cancelled: "cancel",
18315
- client_disconnect: "socket_close",
18343
+ client_disconnect: "client_disconnect",
18316
18344
  shutdown: "shutdown"
18317
18345
  };
18318
18346
  var StreamSession = class StreamSession {
@@ -18398,214 +18426,13 @@ var StreamSession = class StreamSession {
18398
18426
  };
18399
18427
 
18400
18428
  //#endregion
18401
- //#region ../../packages/substrate-compose/src/routes/stream-ticket.ts
18402
- /**
18403
- * Stateless stream tickets. Spec §3.
18404
- *
18405
- * `EventSource` cannot set request headers, so Substrate's signed-request auth
18406
- * can't reach the browser SSE path. A ticket is minted by a NORMALLY-SIGNED
18407
- * POST and then carried in the query string.
18408
- *
18409
- * Stateless by design: no store, no TTL sweeper, and therefore no
18410
- * mint-on-instance-A/connect-to-instance-B failure the moment a second
18411
- * instance exists. Signed with a SERVER-held secret (symmetric HMAC is
18412
- * sufficient — only the issuing server verifies) so the Key registry
18413
- * stays out of a request-path hot loop. Rotating the secret invalidates
18414
- * outstanding tickets, which is the revocation escape hatch statelessness
18415
- * otherwise gives up; immaterial at a ~60s TTL.
18416
- */
18417
- /** Chosen so an EventSource reconnect lands inside the window. */
18418
- const TICKET_TTL_MS = 6e4;
18419
- /**
18420
- * Order-independent hash of a frame. Binding the ticket to this prevents
18421
- * replaying a ticket minted for one frame onto a different (e.g. broader) one.
18422
- *
18423
- * HMAC rather than a plain `createHash('sha256')` — but `'substrate-frame-hash'`
18424
- * is a DOMAIN-SEPARATION constant, not a secret, and doesn't need protecting.
18425
- * The frame hash only needs collision resistance (plain SHA-256 gives that
18426
- * too); its integrity against tampering is already covered by the outer
18427
- * ticket signature in `sign`, which is keyed on the real server secret.
18428
- */
18429
- function hashFrame(frame) {
18430
- return createHmac("sha256", "substrate-frame-hash").update(canonicalJson(frame)).digest("base64url");
18431
- }
18432
- /** Deterministic JSON with lexicographically sorted keys at every depth. */
18433
- function canonicalJson(value) {
18434
- if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
18435
- if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
18436
- return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
18437
- }
18438
- function sign$1(secret, body) {
18439
- return createHmac("sha256", secret).update(body).digest("base64url");
18440
- }
18441
- function mintStreamTicket(secret, payload, nowMs) {
18442
- const full = {
18443
- ...payload,
18444
- exp: nowMs + TICKET_TTL_MS
18445
- };
18446
- const body = Buffer.from(JSON.stringify(full)).toString("base64url");
18447
- return `${body}.${sign$1(secret, body)}`;
18448
- }
18449
- /** Full structural check of a decoded ticket body. See `verifyStreamTicket`. */
18450
- function isTicketPayload(value) {
18451
- if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
18452
- if (!("exp" in value) || typeof value.exp !== "number") return false;
18453
- if (!("frameHash" in value) || typeof value.frameHash !== "string") return false;
18454
- if (!("capabilities" in value)) return false;
18455
- const caps = value.capabilities;
18456
- if (!Array.isArray(caps) || caps.some((c) => typeof c !== "string")) return false;
18457
- if (!("identity" in value)) return false;
18458
- const identity = value.identity;
18459
- if (identity === null) return true;
18460
- return typeof identity === "object" && !Array.isArray(identity) && "id" in identity && typeof identity.id === "string";
18461
- }
18462
- function verifyStreamTicket(secret, ticket, frame, nowMs) {
18463
- const dot = ticket.indexOf(".");
18464
- if (dot <= 0) return {
18465
- ok: false,
18466
- code: "ticket_invalid"
18467
- };
18468
- const body = ticket.slice(0, dot);
18469
- const provided = ticket.slice(dot + 1);
18470
- const expected = sign$1(secret, body);
18471
- const a = Buffer.from(provided);
18472
- const b = Buffer.from(expected);
18473
- if (a.length !== b.length || !timingSafeEqual(a, b)) return {
18474
- ok: false,
18475
- code: "ticket_invalid"
18476
- };
18477
- let parsed;
18478
- try {
18479
- parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
18480
- } catch {
18481
- return {
18482
- ok: false,
18483
- code: "ticket_invalid"
18484
- };
18485
- }
18486
- if (!isTicketPayload(parsed)) return {
18487
- ok: false,
18488
- code: "ticket_invalid"
18489
- };
18490
- const payload = parsed;
18491
- if (nowMs > payload.exp) return {
18492
- ok: false,
18493
- code: "ticket_expired"
18494
- };
18495
- let expectedFrameHash;
18496
- try {
18497
- expectedFrameHash = hashFrame(frame);
18498
- } catch {
18499
- return {
18500
- ok: false,
18501
- code: "ticket_invalid"
18502
- };
18503
- }
18504
- if (payload.frameHash !== expectedFrameHash) return {
18505
- ok: false,
18506
- code: "ticket_frame_mismatch"
18507
- };
18508
- return {
18509
- ok: true,
18510
- payload
18511
- };
18512
- }
18513
-
18514
- //#endregion
18515
- //#region ../../packages/substrate-compose/src/routes/sse.ts
18516
- const DEFAULT_HEARTBEAT_MS = 2e4;
18517
- const DEFAULT_RETRY_MS = 5e3;
18518
- function createSseTransport(opts) {
18519
- const encoder = new TextEncoder();
18520
- const heartbeatMs = opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
18521
- let controller = null;
18522
- let heartbeat = null;
18523
- let closed = false;
18524
- /**
18525
- * Resolvers of parked `emit` calls. Must be a Set, not a single slot: a
18526
- * multi-key subscribe drains each key on its own task sharing one `onFrame`,
18527
- * so two `emit`s can be in flight at once, and a single slot would strand
18528
- * the first one's drain task.
18529
- */
18530
- const demand = /* @__PURE__ */ new Set();
18531
- const stopHeartbeat = () => {
18532
- if (heartbeat !== null) {
18533
- clearInterval(heartbeat);
18534
- heartbeat = null;
18535
- }
18536
- };
18537
- /** Wake every parked `emit`, not just one — see the `demand` docblock. */
18538
- const releaseDemand = () => {
18539
- for (const resolve of demand) resolve();
18540
- demand.clear();
18541
- };
18542
- /**
18543
- * Shared by every teardown path (write failure, close, consumer cancel) so
18544
- * none of them can leave the heartbeat ticking or an `emit` parked forever;
18545
- * a parked `emit` strands the engine's producer loop.
18546
- */
18547
- const teardown = () => {
18548
- closed = true;
18549
- stopHeartbeat();
18550
- releaseDemand();
18551
- };
18552
- const write = (text) => {
18553
- if (closed || controller === null) return;
18554
- try {
18555
- controller.enqueue(encoder.encode(text));
18556
- } catch {
18557
- teardown();
18558
- controller = null;
18559
- }
18560
- };
18561
- return {
18562
- transport: {
18563
- emit: async (frame, fieldsByKey) => {
18564
- if (closed) return;
18565
- write(sseEvent(frame, fieldsByKey));
18566
- if (frame.kind === "end" || frame.kind === "error") return;
18567
- if (controller !== null && (controller.desiredSize ?? 1) <= 0) await new Promise((resolve) => {
18568
- demand.add(resolve);
18569
- });
18570
- },
18571
- close: (_reason) => {
18572
- if (closed) return;
18573
- teardown();
18574
- try {
18575
- controller?.close();
18576
- } catch {}
18577
- controller = null;
18578
- }
18579
- },
18580
- body: new ReadableStream({
18581
- start(c) {
18582
- controller = c;
18583
- write(sseRetry(opts.retryMs ?? DEFAULT_RETRY_MS));
18584
- heartbeat = setInterval(() => write(SSE_HEARTBEAT), heartbeatMs);
18585
- heartbeat.unref?.();
18586
- },
18587
- pull() {
18588
- releaseDemand();
18589
- },
18590
- cancel() {
18591
- teardown();
18592
- controller = null;
18593
- opts.onCancel?.();
18594
- }
18595
- }),
18596
- writeFrame: (frame) => write(sseEvent(frame, void 0))
18597
- };
18598
- }
18599
- /** The capability a stream ticket must carry, and the one the mint route grants. */
18600
- const STREAM_CAPABILITY = "read";
18429
+ //#region ../../packages/substrate-compose/src/routes/stream-routes.ts
18601
18430
  /**
18602
18431
  * Shape validation: an object whose every VALUE is a plain object. Inner
18603
18432
  * `params`/`fields` bags stay opaque — the engine validates those.
18604
18433
  *
18605
18434
  * The values must be checked here: `StreamSession` reads `entry.fields` off
18606
18435
  * each one, and a throw after the transport opens leaks its heartbeat timer.
18607
- * The WS route uses it too, where that throw would escape the message
18608
- * listener and exit the process.
18609
18436
  *
18610
18437
  * Unlike `validateFrame` in `helpers.ts`, array values (the §5.13
18611
18438
  * batched-mutate shape) are rejected: streams cannot carry them, so this
@@ -18625,65 +18452,19 @@ function parseFrameJson(raw) {
18625
18452
  }
18626
18453
  return isFrameRecord(parsed) ? parsed : null;
18627
18454
  }
18628
- /**
18629
- * Resolve the frame + identity for a stream request.
18630
- *
18631
- * GET is the EventSource path: the frame rides the query string and auth rides
18632
- * a ticket, because EventSource can set neither a body nor headers. POST is the
18633
- * node/MCP path: frame in the body, auth already applied upstream by `gate`.
18634
- *
18635
- * Both paths feed the SAME `JSON.parse`, so a frame's value types are identical
18636
- * either way — a ticket minted from a POST body verifies against the same frame
18637
- * arriving via GET. Never coerce query values to strings.
18638
- */
18639
- function parseStreamRequest(req, secret, nowMs) {
18640
- const frame = parseFrameJson(req.method === "POST" ? req.body?.toString("utf8") ?? "" : req.query.frame ?? "");
18641
- if (frame === null) return {
18642
- ok: false,
18643
- status: 400,
18644
- code: "invalid_frame"
18645
- };
18646
- if (req.method === "POST") return {
18647
- ok: true,
18648
- frame,
18649
- identity: req.identity ?? null
18650
- };
18651
- const ticket = req.query.ticket;
18652
- if (ticket === void 0 || ticket === "") return {
18653
- ok: false,
18654
- status: 401,
18655
- code: "ticket_missing"
18656
- };
18657
- const verdict = verifyStreamTicket(secret, ticket, frame, nowMs);
18658
- if (!verdict.ok) return {
18659
- ok: false,
18660
- status: 401,
18661
- code: verdict.code
18662
- };
18663
- if (!verdict.payload.capabilities.includes(STREAM_CAPABILITY)) return {
18664
- ok: false,
18665
- status: 401,
18666
- code: "ticket_missing_capability"
18667
- };
18668
- return {
18669
- ok: true,
18670
- frame,
18671
- identity: verdict.payload.identity
18672
- };
18673
- }
18674
18455
  /** Errors BEFORE the stream opens are ordinary HTTP; after, they're in-band. */
18675
- function errorResponse(status, code) {
18456
+ function errorResponse(status, code, message = code) {
18676
18457
  return jsonResponse(status, { errors: [{
18677
- message: code,
18458
+ message,
18678
18459
  code
18679
18460
  }] });
18680
18461
  }
18681
- function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric, auth, connections, sessionCap) {
18462
+ const NOT_ACCEPTABLE = `streams answer ${FRAMES_JSON_MIME} or ${FRAMES_PACK_MIME}; send one in Accept`;
18463
+ function registerStreamRoutes(server, engine, trustedProxies, gate, metric, auth, connections) {
18682
18464
  /**
18683
- * Every SSE response currently held open, for the graceful-shutdown walk.
18684
- * Lives at route scope (WS keeps one per socket) because an SSE response
18685
- * has no connection object to hang a hook off. A subscribe never self-ends,
18686
- * so without this `server.stop()` would wait on it forever.
18465
+ * Every stream response currently held open, for the graceful-shutdown walk.
18466
+ * A subscribe never self-ends, so without this `server.stop()` would wait on
18467
+ * it forever.
18687
18468
  */
18688
18469
  const live = /* @__PURE__ */ new Set();
18689
18470
  /**
@@ -18702,21 +18483,31 @@ function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric,
18702
18483
  });
18703
18484
  const open = (mode) => async (req) => {
18704
18485
  if (shuttingDown) return errorResponse(503, "server_shutting_down");
18705
- const parsed = parseStreamRequest(req, secret, Date.now());
18706
- if (!parsed.ok) return errorResponse(parsed.status, parsed.code);
18486
+ const frames = framesEncodingFromAccept(req.headers.accept);
18487
+ if (frames === void 0) return errorResponse(406, "not_acceptable", NOT_ACCEPTABLE);
18488
+ const frame = parseFrameJson(req.body?.toString("utf8") ?? "");
18489
+ if (frame === null) return errorResponse(400, "invalid_frame");
18490
+ const parsed = {
18491
+ frame,
18492
+ identity: req.identity ?? null
18493
+ };
18707
18494
  const lapsed = auth === void 0 ? null : credentialLapse(parsed.identity, auth);
18708
18495
  if (lapsed !== null) return errorResponse(401, lapsed);
18709
18496
  const clientIp = extractClientIp(req, trustedProxies);
18710
18497
  const release = connections === void 0 ? () => {} : connections.acquire(auth === void 0 ? null : parsed.identity, clientIp);
18711
18498
  if (release === null) return errorResponse(429, "too_many_connections");
18712
- const releaseSlot = sessionCap === void 0 ? () => {} : sessionCap.acquire(auth === void 0 ? null : parsed.identity, clientIp);
18713
- if (releaseSlot === null) {
18714
- release();
18715
- return errorResponse(429, "too_many_sessions");
18716
- }
18717
18499
  let session;
18718
- const sessionId = `sse-${mode}`;
18719
- const { transport, body, writeFrame } = createSseTransport({ onCancel: () => session?.cancel("client_disconnect") });
18500
+ const sessionId = `frames-${mode}`;
18501
+ const { transport, body, writeFrame } = createFramesTransport({
18502
+ mode: frames,
18503
+ engine,
18504
+ onCancel: () => session?.cancel("client_disconnect"),
18505
+ onStall: () => metric("stream_consumer_stalled", {
18506
+ mode,
18507
+ wire: frames
18508
+ }),
18509
+ onTooLarge: () => session?.cancel("cancelled")
18510
+ });
18720
18511
  /**
18721
18512
  * This response's entry in the shutdown registry. Closures over
18722
18513
  * `session` rather than a field holding it, so the record can be built
@@ -18747,10 +18538,6 @@ function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric,
18747
18538
  let stopWatch = () => {};
18748
18539
  /** Set while `start` is in flight. */
18749
18540
  let starting;
18750
- const freeSlots = () => {
18751
- release();
18752
- releaseSlot();
18753
- };
18754
18541
  const watched = {
18755
18542
  emit: async (frame, fieldsByKey) => {
18756
18543
  if (registering) {
@@ -18761,8 +18548,8 @@ function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric,
18761
18548
  },
18762
18549
  close: (reason) => {
18763
18550
  live.delete(record);
18764
- if (starting === void 0) freeSlots();
18765
- else starting.then(freeSlots, freeSlots);
18551
+ if (starting === void 0) release();
18552
+ else starting.then(release, release);
18766
18553
  stopWatch();
18767
18554
  transport.close(reason);
18768
18555
  }
@@ -18778,7 +18565,7 @@ function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric,
18778
18565
  }, watched);
18779
18566
  } catch (err) {
18780
18567
  watched.close("complete");
18781
- metric("sse_stream_start_failed", {
18568
+ metric("stream_start_failed", {
18782
18569
  mode,
18783
18570
  keys: Object.keys(parsed.frame ?? {}),
18784
18571
  error: err instanceof Error ? err.message : String(err)
@@ -18794,7 +18581,7 @@ function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric,
18794
18581
  starting = started;
18795
18582
  await started;
18796
18583
  } catch (err) {
18797
- metric("sse_stream_start_failed", {
18584
+ metric("stream_start_failed", {
18798
18585
  mode,
18799
18586
  keys: Object.keys(parsed.frame ?? {}),
18800
18587
  error: err instanceof Error ? err.message : String(err)
@@ -18815,376 +18602,18 @@ function registerSseRoutes(server, engine, trustedProxies, secret, gate, metric,
18815
18602
  if (mode === "subscribe" && keys.every((k) => failedKeys.has(k))) session.cancel("complete");
18816
18603
  return {
18817
18604
  status: 200,
18818
- headers: SSE_HEADERS,
18605
+ headers: framesHeaders(frames),
18819
18606
  body
18820
18607
  };
18821
18608
  };
18822
- for (const [path, mode] of [["/substrate/v1/stream", "stream"], ["/substrate/v1/subscribe", "subscribe"]]) {
18823
- server.route("GET", path, open(mode));
18824
- server.route("POST", path, gate(open(mode), "read"));
18825
- }
18826
- server.route("POST", "/substrate/v1/stream/ticket", gate(async (req) => {
18827
- const frame = parseFrameJson(req.body?.toString("utf8") ?? "");
18828
- if (frame === null) return errorResponse(400, "invalid_frame");
18829
- const ticket = mintStreamTicket(secret, {
18830
- identity: req.identity ?? null,
18831
- capabilities: [STREAM_CAPABILITY],
18832
- frameHash: hashFrame(frame)
18833
- }, Date.now());
18834
- return jsonResponse(200, {
18835
- ticket,
18836
- expiresIn: TICKET_TTL_MS / 1e3
18837
- });
18838
- }, "read"));
18839
- }
18840
-
18841
- //#endregion
18842
- //#region ../../packages/substrate-compose/src/routes/ws.ts
18843
- /**
18844
- * Detect the negotiated subprotocol from the upgrade request. @fastify/websocket
18845
- * surfaces the accepted subprotocol in `sec-websocket-protocol`; the client's
18846
- * offered list arrives in the request headers the same way. We treat "the
18847
- * header mentions `substrate-pack`" as opt-in — the caller's responsibility is to
18848
- * advertise it at handshake.
18849
- */
18850
- function usesSubstratePack(req) {
18851
- const raw = req.headers["sec-websocket-protocol"];
18852
- if (raw === void 0) return false;
18853
- for (const clause of raw.split(",")) if (clause.trim() === "substrate-pack") return true;
18854
- return false;
18855
- }
18856
- function parseRequestFrame(buf, mode) {
18857
- try {
18858
- const value = decodeWsEnvelope(buf, mode);
18859
- if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
18860
- if (!isPlainRequestData(value)) return null;
18861
- const v = value;
18862
- if (typeof v.id !== "string") return null;
18863
- if (v.op !== "subscribe" && v.op !== "stream" && v.op !== "cancel" && v.op !== "whoami") return null;
18864
- if (v.frame !== void 0 && !isFrameRecord(v.frame)) return null;
18865
- return value;
18866
- } catch {
18867
- return null;
18868
- }
18869
- }
18870
- function serializeFrame(frame, mode, fieldsByKey, engine) {
18871
- if (mode === "json") return stringifyJson(projectWsFrame(frame, fieldsByKey));
18872
- const encoded = encodeDataForPack(frame, fieldsByKey, engine);
18873
- const wire = encodeWsFrame(encoded, mode);
18874
- return typeof wire === "string" ? wire : Buffer.from(wire);
18875
- }
18876
- /**
18877
- * Produce a wire-ready frame object — for substrate-pack, positionally encode
18878
- * `data` against the per-key FieldInput + the engine's federated schema. Remove
18879
- * frames (no `data`) and error/end frames pass through untouched.
18880
- */
18881
- function encodeDataForPack(frame, fieldsByKey, engine) {
18882
- if (frame.data === void 0 || fieldsByKey === void 0) return frame;
18883
- const schemas = engine.federatedSchema();
18884
- const encoded = {};
18885
- for (const [key, value] of Object.entries(frame.data)) {
18886
- const parsed = parseQualifiedKey(key);
18887
- if (parsed === null) {
18888
- encoded[key] = value;
18889
- continue;
18890
- }
18891
- const { ns, name } = parsed;
18892
- const fields = fieldsByKey.get(key);
18893
- const schema = schemas[ns];
18894
- if (fields === void 0 || schema === void 0) {
18895
- encoded[key] = value;
18896
- continue;
18897
- }
18898
- const rawShape = frame.shapes?.[key];
18899
- encoded[key] = encodeByShape(value, fields, schema, name, rawShape === "single" || rawShape === "list" ? rawShape : void 0, {
18900
- schemas,
18901
- currentNs: ns
18902
- });
18903
- }
18904
- return {
18905
- ...frame,
18906
- data: encoded
18907
- };
18908
- }
18909
- function encodeByShape(value, fields, schema, typeName, shape, ctx) {
18910
- if (value === null || value === void 0) return null;
18911
- if (shape === "list") {
18912
- if (!Array.isArray(value)) return value;
18913
- return value.map((row) => encodePositional(row, fields, schema, typeName, ctx));
18914
- }
18915
- return encodePositional(value, fields, schema, typeName, ctx);
18916
- }
18917
- /**
18918
- * Most logical sessions one socket may hold open. Each holds an engine
18919
- * subscription, so an unbounded count is unbounded server work per socket.
18920
- */
18921
- const MAX_SESSIONS_PER_SOCKET = 1024;
18922
- function registerWsRoute(server, engine, trustedProxies, metric, auth, systemIdentity = null, connections, sessionCap) {
18923
- server.websocket("/substrate/v1/ws", async (req, conn) => {
18924
- const wsClientIp = extractClientIp(req, trustedProxies);
18925
- let wsIdentity = auth === void 0 ? systemIdentity ?? void 0 : void 0;
18926
- if (auth !== void 0) {
18927
- const token = extractBearer(req.headers.authorization);
18928
- if (!(auth.mode === "attribute" && token === null)) {
18929
- const verdict = token === null ? null : authenticateBearer(token, auth);
18930
- if (verdict === null || !verdict.ok) {
18931
- const reason = verdict?.reason ?? null;
18932
- const errorBody = reason === null ? {
18933
- message: "unauthorized",
18934
- code: "unauthorized"
18935
- } : {
18936
- message: `unauthorized: ${reason}`,
18937
- code: "unauthorized",
18938
- reason
18939
- };
18940
- try {
18941
- conn.send(JSON.stringify({
18942
- id: "",
18943
- kind: "error",
18944
- errors: [errorBody]
18945
- }));
18946
- } catch {}
18947
- conn.close(4001, reason === null ? "unauthorized" : `unauthorized: ${reason}`);
18948
- return;
18949
- }
18950
- wsIdentity = verdict.identity;
18951
- }
18952
- }
18953
- const release = connections === void 0 ? () => {} : connections.acquire(auth === void 0 ? null : wsIdentity, wsClientIp);
18954
- if (release === null) {
18955
- try {
18956
- conn.send(JSON.stringify({
18957
- id: "",
18958
- kind: "error",
18959
- errors: [{
18960
- message: "too many connections",
18961
- code: "too_many_connections"
18962
- }]
18963
- }));
18964
- } catch {}
18965
- conn.close(1013, "too_many_connections");
18966
- return;
18967
- }
18968
- const mode = usesSubstratePack(req) ? "pack" : "json";
18969
- /**
18970
- * One socket carries many logical sessions, so multiplexing lives here
18971
- * rather than in `StreamSession`. `isStream` rides alongside because the
18972
- * cancel acknowledgement differs by mode (see the cancel handler) and the
18973
- * session deliberately doesn't expose its own mode.
18974
- */
18975
- const sessions = /* @__PURE__ */ new Map();
18976
- /** Raw send for frames that belong to no session (parse errors, cancel acks). */
18977
- const sendBare = (frame) => {
18978
- try {
18979
- conn.send(serializeFrame(frame, mode, void 0, engine));
18980
- } catch {}
18981
- };
18982
- /** `owner` lets a late close from a replaced session leave its successor's entry alone. */
18983
- const transportFor = (id, owner, releaseSlot, startOf) => ({
18984
- emit: async (frame, fieldsByKey) => {
18985
- const wire = serializeFrame(frame, mode, fieldsByKey, engine);
18986
- try {
18987
- conn.send(wire);
18988
- } catch {
18989
- return;
18990
- }
18991
- if (frame.kind !== "end" && frame.kind !== "error" && conn.drain !== void 0) await conn.drain();
18992
- },
18993
- close: () => {
18994
- const starting = startOf();
18995
- if (starting === void 0) releaseSlot();
18996
- else starting.then(releaseSlot, releaseSlot);
18997
- if (sessions.get(id)?.session === owner()) sessions.delete(id);
18998
- }
18999
- });
19000
- /**
19001
- * Register BEFORE dispatching to the engine: a `cancel` frame can arrive in
19002
- * the same synchronous batch as the `subscribe`/`stream` that precedes it
19003
- * (memory transports invoke message listeners inline), and a session that
19004
- * isn't in the map yet is a session that cancel cannot find.
19005
- */
19006
- function openSession(request, sessionMode) {
19007
- if (sessions.has(request.id)) {
19008
- sendBare({
19009
- id: request.id,
19010
- kind: "error",
19011
- errors: [{
19012
- message: `session id '${request.id}' is already open`,
19013
- code: "duplicate_id"
19014
- }]
19015
- });
19016
- return;
19017
- }
19018
- if (sessions.size >= 1024) {
19019
- sendBare({
19020
- id: request.id,
19021
- kind: "error",
19022
- errors: [{
19023
- message: `at most ${MAX_SESSIONS_PER_SOCKET} sessions per socket`,
19024
- code: "too_many_sessions"
19025
- }]
19026
- });
19027
- return;
19028
- }
19029
- const releaseSlot = sessionCap === void 0 ? () => {} : sessionCap.acquire(auth === void 0 ? null : wsIdentity, wsClientIp);
19030
- if (releaseSlot === null) {
19031
- sendBare({
19032
- id: request.id,
19033
- kind: "error",
19034
- errors: [{
19035
- message: `at most ${MAX_SESSIONS_PER_CLIENT} sessions per client`,
19036
- code: "too_many_sessions"
19037
- }]
19038
- });
19039
- return;
19040
- }
19041
- const keys = Object.keys(request.frame ?? {});
19042
- const failedKeys = /* @__PURE__ */ new Set();
19043
- let registering = true;
19044
- /** Set while `start` is in flight. */
19045
- let starting;
19046
- const transport = transportFor(request.id, () => session, releaseSlot, () => starting);
19047
- const session = StreamSession.create({
19048
- id: request.id,
19049
- mode: sessionMode,
19050
- frame: request.frame ?? {},
19051
- identity: wsIdentity ?? null,
19052
- headers: req.headers,
19053
- ...wsClientIp !== void 0 ? { clientIp: wsClientIp } : {}
19054
- }, {
19055
- emit: (frame, fieldsByKey) => {
19056
- if (registering) {
19057
- const key = erroredKey(frame);
19058
- if (key !== void 0) failedKeys.add(key);
19059
- }
19060
- return transport.emit(frame, fieldsByKey);
19061
- },
19062
- close: transport.close
19063
- });
19064
- sessions.set(request.id, {
19065
- session,
19066
- isStream: sessionMode === "stream"
19067
- });
19068
- const started = session.start(engine).finally(() => {
19069
- starting = void 0;
19070
- });
19071
- starting = started;
19072
- started.then(() => {
19073
- registering = false;
19074
- if (sessionMode === "subscribe" && keys.every((k) => failedKeys.has(k))) session.cancel("complete");
19075
- }, (err) => {
19076
- metric("ws_stream_start_failed", {
19077
- mode: sessionMode,
19078
- keys: Object.keys(request.frame ?? {}),
19079
- error: err instanceof Error ? err.message : String(err)
19080
- });
19081
- releaseSlot();
19082
- if (sessions.get(request.id)?.session === session) sessions.delete(request.id);
19083
- sendBare({
19084
- id: request.id,
19085
- kind: "error",
19086
- errors: [{
19087
- message: "stream_start_failed",
19088
- code: "stream_start_failed"
19089
- }]
19090
- });
19091
- sendBare({
19092
- id: request.id,
19093
- kind: "end",
19094
- final: true
19095
- });
19096
- });
19097
- }
19098
- conn.onMessage((buf) => {
19099
- const request = parseRequestFrame(buf, mode);
19100
- if (!request) {
19101
- sendBare({
19102
- id: "",
19103
- kind: "error",
19104
- errors: [{
19105
- message: "invalid frame",
19106
- code: "invalid_frame"
19107
- }]
19108
- });
19109
- return;
19110
- }
19111
- if (request.op === "whoami") {
19112
- const principal = wsIdentity === void 0 ? null : describeIdentity(wsIdentity);
19113
- sendBare({
19114
- id: request.id,
19115
- kind: "whoami",
19116
- data: {
19117
- authEnabled: auth !== void 0,
19118
- identity: auth === void 0 ? null : principal
19119
- }
19120
- });
19121
- return;
19122
- }
19123
- if (request.op === "subscribe") {
19124
- openSession(request, "subscribe");
19125
- return;
19126
- }
19127
- if (request.op === "stream") {
19128
- openSession(request, "stream");
19129
- return;
19130
- }
19131
- if (request.op === "cancel") {
19132
- const record = sessions.get(request.id);
19133
- if (record === void 0) {
19134
- sendBare({
19135
- id: request.id,
19136
- kind: "end",
19137
- final: true
19138
- });
19139
- return;
19140
- }
19141
- record.session.cancel("cancelled");
19142
- sessions.delete(request.id);
19143
- if (!record.isStream) sendBare({
19144
- id: request.id,
19145
- kind: "end",
19146
- final: true
19147
- });
19148
- }
19149
- });
19150
- const stopWatch = watchCredential(wsIdentity, auth, (lapse) => {
19151
- for (const [id, record] of sessions) {
19152
- sendBare({
19153
- id,
19154
- kind: "end",
19155
- reason: lapse,
19156
- final: true
19157
- });
19158
- record.session.cancel("cancelled");
19159
- }
19160
- sessions.clear();
19161
- conn.close(4001, lapse);
19162
- });
19163
- conn.onClose(() => {
19164
- release();
19165
- stopWatch();
19166
- for (const record of sessions.values()) record.session.cancel("client_disconnect");
19167
- sessions.clear();
19168
- });
19169
- conn.onShutdown?.((reason) => {
19170
- for (const [id, record] of sessions) {
19171
- sendBare({
19172
- id,
19173
- kind: "end",
19174
- reason,
19175
- final: true
19176
- });
19177
- record.session.cancel("shutdown");
19178
- }
19179
- sessions.clear();
19180
- });
19181
- });
18609
+ server.route("POST", "/substrate/v1/stream", gate(open("stream"), "read"));
18610
+ server.route("POST", "/substrate/v1/subscribe", gate(open("subscribe"), "read"));
19182
18611
  }
19183
18612
 
19184
18613
  //#endregion
19185
18614
  //#region ../../packages/substrate-compose/src/compose/routes.ts
19186
18615
  async function registerCoreRoutes(args) {
19187
- const { server, engine, gate, trustedProxies, auth, streamTicketSecret, version, stats, routeEventMetric, substrateDataset, substrateKeyRegistry, datasets, edges, namespaces, coordinatorPlugins, systemIdentity, routeMetric, bridges, registerRateLimiter, identityDirectory, adminCapability, configReport, storageReport, promoteFields, fieldWarnings, poolStats } = args;
18616
+ const { server, engine, gate, trustedProxies, auth, version, stats, routeEventMetric, substrateDataset, substrateKeyRegistry, datasets, edges, namespaces, coordinatorPlugins, systemIdentity, routeMetric, bridges, registerRateLimiter, identityDirectory, adminCapability, configReport, storageReport, promoteFields, fieldWarnings, poolStats } = args;
19188
18617
  server.route("GET", "/health", healthRoute({
19189
18618
  version: version ?? "0.0.0",
19190
18619
  startedAt: Date.now(),
@@ -19206,8 +18635,7 @@ async function registerCoreRoutes(args) {
19206
18635
  server.route("POST", "/substrate/v1/query", gate(queryRoute(engine, trustedProxies, auth !== void 0, args.pageLimits), "read"));
19207
18636
  server.route("POST", "/substrate/v1/mutate", gate(mutateRoute(engine, trustedProxies, auth !== void 0), "mutate"));
19208
18637
  const connections = createConnectionLimiter();
19209
- const sessionCap = createConnectionLimiter(MAX_SESSIONS_PER_CLIENT);
19210
- registerSseRoutes(server, engine, trustedProxies, streamTicketSecret !== void 0 && streamTicketSecret.length > 0 ? streamTicketSecret : "substrate-dev-insecure-stream-secret", gate, routeEventMetric, auth, connections, sessionCap);
18638
+ registerStreamRoutes(server, engine, trustedProxies, gate, routeEventMetric, auth, connections);
19211
18639
  server.observeRequests?.((o) => stats.recordRequest(o.op, o.ok, o.durationMs));
19212
18640
  server.route("GET", "/substrate/v1/metrics", gate(metricsRouteHandler(stats), "read"));
19213
18641
  server.route("GET", "/substrate/v1/errors", gate(errorsRouteHandler(stats, {
@@ -19319,7 +18747,6 @@ async function registerCoreRoutes(args) {
19319
18747
  server.route("POST", "/substrate/v1/_system/promote-fields", gate(adminStoreWide(promoteFieldsRoute(promoteFields)), "admin"));
19320
18748
  server.route("POST", "/substrate/v1/_system/register", registerRoute(substrateDataset, substrateKeyRegistry, rateLimiter, { trustedProxies }));
19321
18749
  server.route("GET", "/substrate/v1/whoami", whoamiRoute(auth));
19322
- registerWsRoute(server, engine, trustedProxies, routeEventMetric, auth, systemIdentity, connections, sessionCap);
19323
18750
  for (const plugin of coordinatorPlugins) {
19324
18751
  if (plugin.routes === void 0) continue;
19325
18752
  const rawRouter = withRouterRequestContext(server.createPluginRouter({ name: plugin.name }), trustedProxies, auth !== void 0);
@@ -19343,8 +18770,7 @@ function withRouterRequestContext(router, trustedProxies, authEnabled) {
19343
18770
  post: (path, h) => router.post(path, w(h)),
19344
18771
  put: (path, h) => router.put(path, w(h)),
19345
18772
  delete: (path, h) => router.delete(path, w(h)),
19346
- patch: (path, h) => router.patch(path, w(h)),
19347
- websocket: (path, h) => router.websocket(path, h)
18773
+ patch: (path, h) => router.patch(path, w(h))
19348
18774
  };
19349
18775
  }
19350
18776
 
@@ -19471,8 +18897,9 @@ async function compose(opts) {
19471
18897
  }
19472
18898
  }
19473
18899
  async function composeInner(opts, cleanup) {
19474
- const { streamTicketSecret, systemIdentity } = resolveBootGuards(opts);
19475
- if (streamTicketSecret !== void 0 && streamTicketSecret.length > 0) setCursorSealSecret(streamTicketSecret);
18900
+ const { systemIdentity } = resolveBootGuards(opts);
18901
+ const cursorSealSecret = opts.cursorSealSecret?.trim();
18902
+ if (cursorSealSecret !== void 0 && cursorSealSecret.length > 0) setCursorSealSecret(cursorSealSecret);
19476
18903
  const edges = opts.edges ?? new MemoryEdgesStore({ now: () => /* @__PURE__ */ new Date() });
19477
18904
  const bridges = opts.bridges ?? NO_BRIDGES;
19478
18905
  const datasets = new MemoryDatasetRegistry({ factory: (ns) => {
@@ -19631,7 +19058,6 @@ async function composeInner(opts, cleanup) {
19631
19058
  trustedProxies,
19632
19059
  pageLimits: opts.pageLimits ?? DEFAULT_PAGE_LIMITS,
19633
19060
  auth,
19634
- streamTicketSecret,
19635
19061
  version: opts.version,
19636
19062
  stats,
19637
19063
  routeEventMetric,