@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,26 +1,24 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { A as isReservedAutoCrudField, Ft as HttpBridgeClient, Lt as buildContext, Vt as parseAuthConfig, Wt as WS_REASON_SERVER_RESTART, Z as MemoryEdgesStore, _ as AUDIT_EVENT_TYPE, _t as getExtensionOperator, a as composeFromManifests, bt as unregisterExtensionOperator, c as MemoryDataset, et as effectiveFilterOperators, g as buildAuditRow, h as SYSTEM_TYPE_DEFS, i as PluginLoadError, n as kernelMigrationTracking, o as DEFAULT_NAMESPACE, r as mountKernelRoute, s as compose, t as composeKernelPlugins, u as isStoreProfileName, vt as listExtensionOperators, yt as registerExtensionOperator } from "./src-D55T3ZcP.js";
2
+ import { A as isReservedAutoCrudField, Ft as HttpBridgeClient, Lt as buildContext, Vt as parseAuthConfig, Wt as WS_REASON_SERVER_RESTART, Z as MemoryEdgesStore, _ as AUDIT_EVENT_TYPE, _t as getExtensionOperator, a as composeFromManifests, bt as unregisterExtensionOperator, c as MemoryDataset, et as effectiveFilterOperators, g as buildAuditRow, h as SYSTEM_TYPE_DEFS, i as PluginLoadError, n as kernelMigrationTracking, o as DEFAULT_NAMESPACE, r as mountKernelRoute, s as compose, t as composeKernelPlugins, u as isStoreProfileName, vt as listExtensionOperators, yt as registerExtensionOperator } from "./src-oO0DtS6y.js";
3
3
  import { a as adminClaimCapabilities, d as resolveDefaultKidPath, l as resolveAdminCredential, n as trimTrailingSlashes, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, t as parsePositiveInt, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
4
- import { D as isActiveAdminKeyRow, E as describeGrant, L as encodeList, M as grantEntryError, T as SYSTEM_NAMESPACE, v as grantEntriesConfer } from "./src-DR_hUj2p.js";
5
- import { L as DEFAULT_FILTER_WRITE_LIMITS } from "./src-CdbUzLhB.js";
6
- import { C as diagnose, S as DIAGNOSE_CHECKS, _ as SKIPPABLE_STEPS, b as planOnboarding, h as CURRENT_MARK, i as tokenAudience, v as STEP_MARKS, x as requiredOutstanding, y as currentStep } from "./src-DV6PcXym.js";
7
- import { _ as pendingMigrations, f as assertNotMigrating, h as deriveListIndexMigration, m as assertTablesLayout, n as PgDataset, t as PgIdempotencyStore, v as runDerivedMigrations, y as runMigrations } from "./src-BcuotITf.js";
8
- import { t as PgEdgesStore } from "./pg-edges-store-D7etFxNK.js";
9
- import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-DZfgQ2gR.js";
10
- import { et as memberKey } from "./plugin-DcoJGEMM.js";
4
+ import { D as isActiveAdminKeyRow, E as describeGrant, L as encodeList, M as grantEntryError, T as SYSTEM_NAMESPACE, v as grantEntriesConfer } from "./src-D3ACIp1y.js";
5
+ import { J as DEFAULT_FILTER_WRITE_LIMITS, a as FRAMES_JSON_MIME, f as withIdleTimeout, l as decodeStreamFrames } from "./src-B6nsPVmD.js";
6
+ import { C as diagnose, E as substrateFetch, S as DIAGNOSE_CHECKS, _ as SKIPPABLE_STEPS, b as planOnboarding, h as CURRENT_MARK, i as tokenAudience, v as STEP_MARKS, x as requiredOutstanding, y as currentStep } from "./src-B_oTGi3X.js";
7
+ import { _ as pendingMigrations, f as assertNotMigrating, h as deriveListIndexMigration, m as assertTablesLayout, n as PgDataset, t as PgIdempotencyStore, v as runDerivedMigrations, y as runMigrations } from "./src-BcigMQdR.js";
8
+ import { t as PgEdgesStore } from "./pg-edges-store-B0Krqoac.js";
9
+ import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-DreZjBk7.js";
10
+ import { et as memberKey } from "./plugin-Dk9h__NU.js";
11
11
  import { existsSync, linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
12
12
  import { homedir } from "node:os";
13
13
  import { basename, dirname, join, resolve } from "node:path";
14
14
  import { createHash, createPublicKey, generateKeyPairSync, randomUUID } from "node:crypto";
15
15
  import { BlockList, isIP } from "node:net";
16
- import WebSocket$1 from "ws";
16
+ import { constants } from "node:http2";
17
17
  import { readFile, readdir, stat, statfs } from "node:fs/promises";
18
18
  import postgres from "postgres";
19
19
  import { pathToFileURL } from "node:url";
20
- import { constants } from "node:http2";
21
20
  import compressPlugin from "@fastify/compress";
22
21
  import corsPlugin from "@fastify/cors";
23
- import websocketPlugin from "@fastify/websocket";
24
22
  import Fastify from "fastify";
25
23
  import { Readable } from "node:stream";
26
24
  import { setTimeout as setTimeout$1 } from "node:timers/promises";
@@ -711,6 +709,14 @@ function readEd25519PublicKey(path) {
711
709
  //#endregion
712
710
  //#region src/admin/route.ts
713
711
  /**
712
+ * Driving the admin-gated `PATCH /substrate/v1/_system/keys` route, and the refusal ->
713
+ * exit-code maps that go with it.
714
+ *
715
+ * The route is the DEFAULT for every mutating subcommand and `--direct` is what
716
+ * an operator has to type, because a direct write leaves the running server's
717
+ * registry stale — for `revoke` that means the credential keeps authenticating.
718
+ */
719
+ /**
714
720
  * Drive `PATCH /substrate/v1/_system/keys`. A write through the engine reaches the
715
721
  * running server's key registry; a direct write does not.
716
722
  *
@@ -718,7 +724,7 @@ function readEd25519PublicKey(path) {
718
724
  * because both sides ask `key-guards`. Statuses are mapped back to the
719
725
  * same exit codes so scripts do not care which transport ran.
720
726
  */
721
- async function runKeyPatchViaRoute(body, baseUrl, env, exitCodes, fetchImpl = fetch) {
727
+ async function runKeyPatchViaRoute(body, baseUrl, env, exitCodes, fetchImpl = substrateFetch) {
722
728
  const auth = resolveAdminAuth(env, baseUrl);
723
729
  if ("error" in auth) throw new AdminCliError(`${body.revoke === true ? "revoke" : "update"}: ${auth.error}`, 1);
724
730
  const url = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
@@ -781,7 +787,7 @@ const UPDATE_EXIT_CODES = {
781
787
  * Pages to exhaustion rather than returning the first page: a silently
782
788
  * truncated answer to "which identities exist" is worse than an error.
783
789
  */
784
- async function runKeyListViaRoute(baseUrl, env, fetchImpl = fetch) {
790
+ async function runKeyListViaRoute(baseUrl, env, fetchImpl = substrateFetch) {
785
791
  const auth = resolveAdminAuth(env, baseUrl);
786
792
  if ("error" in auth) throw new AdminCliError(`list: ${auth.error}`, 1);
787
793
  const base = `${trimTrailingSlashes(baseUrl)}/substrate/v1/_system/keys`;
@@ -1017,7 +1023,7 @@ const DIRECT_TARGET_REFUSAL = {
1017
1023
  * Runs every check against `target`, in dependency order. A failure
1018
1024
  * short-circuits its dependants into explicit skips.
1019
1025
  */
1020
- async function runDoctor(env, target, fetchImpl = fetch) {
1026
+ async function runDoctor(env, target, fetchImpl = substrateFetch) {
1021
1027
  if (target.kind !== "route") return {
1022
1028
  checks: [DIRECT_TARGET_REFUSAL, ...DIAGNOSE_CHECKS.map((name) => ({
1023
1029
  name,
@@ -1037,7 +1043,7 @@ async function runDoctor(env, target, fetchImpl = fetch) {
1037
1043
  };
1038
1044
  }
1039
1045
  /** Diagnose `baseUrl` with the admin credential `env` resolves — shared by doctor and onboard. */
1040
- async function diagnoseTarget(env, baseUrl, fetchImpl = fetch) {
1046
+ async function diagnoseTarget(env, baseUrl, fetchImpl = substrateFetch) {
1041
1047
  const auth = resolveAdminAuth(env, baseUrl);
1042
1048
  return diagnose({
1043
1049
  baseUrl,
@@ -1080,7 +1086,7 @@ function formatDoctorReport(report) {
1080
1086
  return `${lines.join("\n")}\n`;
1081
1087
  }
1082
1088
  /** Resolve the target and run — the shape `main` dispatches to. */
1083
- async function doctorCommand(argv, env, fetchImpl = fetch) {
1089
+ async function doctorCommand(argv, env, fetchImpl = substrateFetch) {
1084
1090
  validateArgv("doctor", argv);
1085
1091
  let url;
1086
1092
  let direct = false;
@@ -1369,7 +1375,7 @@ async function runRegister(args, env, openDataset = openPgDataset) {
1369
1375
  * writes the directory row in the same transaction. Throws `AdminCliError`
1370
1376
  * on a non-2xx response.
1371
1377
  */
1372
- async function runRegisterViaRoute(args, baseUrl, env, fetchImpl = fetch) {
1378
+ async function runRegisterViaRoute(args, baseUrl, env, fetchImpl = substrateFetch) {
1373
1379
  if (grantEntriesConfer(args.namespaces, args.capabilities, "admin") && !args.allowAdmin) throw new AdminCliError("register: 'admin' capability requires --allow-admin (bootstrap is the deliberate admin path)", 1);
1374
1380
  const publicKeyPem = readEd25519PublicKey(args.pubkeyPath);
1375
1381
  const fingerprint = `sha256:${base64Url(createHash("sha256").update(publicKeyPem).digest()).slice(0, 8)}`;
@@ -1641,7 +1647,7 @@ function registerArgs(kid, pubkeyPath, over) {
1641
1647
  };
1642
1648
  }
1643
1649
  /** The production action runners: the same functions the standalone subcommands call. */
1644
- function realOnboardActions(env, baseUrl, fetchImpl = fetch) {
1650
+ function realOnboardActions(env, baseUrl, fetchImpl = substrateFetch) {
1645
1651
  const cap = env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 && env.SUBSTRATE_ADMIN_CAPABILITY.length > 0 ? env.SUBSTRATE_ADMIN_CAPABILITY : DEFAULT_ADMIN_CAPABILITY;
1646
1652
  return {
1647
1653
  bootstrap: async () => formatBootstrapOutput(await runBootstrap(env)),
@@ -1663,7 +1669,7 @@ function realOnboardActions(env, baseUrl, fetchImpl = fetch) {
1663
1669
  };
1664
1670
  }
1665
1671
  /** Parse argv, resolve the target, and run — the shape `main` dispatches to. */
1666
- async function onboardCommand(argv, env, io, interactive, fetchImpl = fetch) {
1672
+ async function onboardCommand(argv, env, io, interactive, fetchImpl = substrateFetch) {
1667
1673
  validateArgv("onboard", argv);
1668
1674
  let url;
1669
1675
  let direct = false;
@@ -1748,7 +1754,7 @@ async function closeQuietly(sql) {
1748
1754
 
1749
1755
  //#endregion
1750
1756
  //#region package.json
1751
- var version = "1.0.0-alpha.18";
1757
+ var version = "1.0.0-alpha.19";
1752
1758
 
1753
1759
  //#endregion
1754
1760
  //#region src/plugin-manifest.ts
@@ -2136,20 +2142,21 @@ async function applySubstrateResponse(reply, res) {
2136
2142
  * createPluginRouter design call: plugin routes are mounted under
2137
2143
  * `/substrate/v1/plugins/<name>` so they can never shadow `/substrate/v1/*` and two plugins
2138
2144
  * declaring the same subpath (e.g. `/ping`) stay isolated. The facade
2139
- * prefixes every path before handing it to `registerRoute` / `registerWsRoute`
2145
+ * prefixes every path before handing it to `registerRoute`
2140
2146
  * — the main Fastify instance still sees one flat routing table.
2141
2147
  *
2142
2148
  * start() twice: Fastify's listen() rejects on a second call. We surface that
2143
2149
  * error as-is rather than caching and returning the prior address — the
2144
2150
  * caller's intent is ambiguous, fail loudly.
2145
2151
  */
2152
+ /** @fastify/compress's default filter. It already leaves `text/event-stream` alone. */
2153
+ const COMPRESSIBLE = /^text\/(?!event-stream)|(?:\+|\/)json(?:;|$)|(?:\+|\/)text(?:;|$)|(?:\+|\/)xml(?:;|$)|octet-stream(?:;|$)/u;
2154
+ /** Frame streams are `+json`, but a gzip stream buffers, which would stop them streaming. */
2155
+ const FRAME_STREAM = /^application\/vnd\.substrate\.frames\+/u;
2146
2156
  const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
2157
+ const DEFAULT_PING_INTERVAL_MS = 3e4;
2147
2158
  /** Streams one HTTP/2 connection may have open at once. Node's default is unbounded. */
2148
2159
  const H2_MAX_CONCURRENT_STREAMS = 128;
2149
- const DEFAULT_WS_MAX_PAYLOAD = 1 << 20;
2150
- const DEFAULT_WS_MAX_BUFFERED = 16 << 20;
2151
- /** How long a buffer-full socket gets to finish its close handshake before it is dropped. */
2152
- const WS_CLOSE_GRACE_MS = 1e3;
2153
2160
  const HANDLED_ERRORS = /* @__PURE__ */ new WeakSet();
2154
2161
  var FastifySubstrateServer = class {
2155
2162
  fastify;
@@ -2158,36 +2165,40 @@ var FastifySubstrateServer = class {
2158
2165
  #observer;
2159
2166
  #inFlightObserver;
2160
2167
  inFlight = /* @__PURE__ */ new Set();
2161
- inFlightWs = /* @__PURE__ */ new Map();
2162
2168
  #shutdownHooks = /* @__PURE__ */ new Set();
2163
- #streamedResponses = /* @__PURE__ */ new Set();
2164
- #wsMaxBuffered;
2165
- #onWarn;
2169
+ #sockets = /* @__PURE__ */ new Set();
2170
+ #refused = /* @__PURE__ */ new Set();
2166
2171
  constructor(options = {}) {
2167
- const { logger = false, bodyLimit, tls, cors, compression = true, requestTimeout = DEFAULT_REQUEST_TIMEOUT_MS, wsMaxPayload = DEFAULT_WS_MAX_PAYLOAD, wsMaxBuffered = DEFAULT_WS_MAX_BUFFERED, onWarn } = options;
2168
- this.#wsMaxBuffered = wsMaxBuffered;
2169
- this.#onWarn = onWarn;
2172
+ const { logger = false, bodyLimit, tls, cors, compression = true, requestTimeout = DEFAULT_REQUEST_TIMEOUT_MS, pingIntervalMs = DEFAULT_PING_INTERVAL_MS } = options;
2170
2173
  this.hasTls = tls !== void 0;
2171
2174
  const common = {
2172
2175
  logger,
2173
2176
  requestTimeout,
2174
2177
  ...bodyLimit !== void 0 ? { bodyLimit } : {}
2175
2178
  };
2176
- if (tls) {
2177
- this.fastify = Fastify({
2178
- ...common,
2179
- http2: true,
2180
- https: {
2181
- allowHTTP1: true,
2182
- cert: tls.cert,
2183
- key: tls.key,
2184
- ...tls.ca !== void 0 ? { ca: tls.ca } : {},
2185
- settings: { maxConcurrentStreams: H2_MAX_CONCURRENT_STREAMS }
2186
- }
2187
- });
2188
- this.fastify.server.requestTimeout = requestTimeout;
2189
- if (requestTimeout > 0) boundH2Requests(this.fastify, requestTimeout);
2190
- } else this.fastify = Fastify(common);
2179
+ const settings = { maxConcurrentStreams: H2_MAX_CONCURRENT_STREAMS };
2180
+ this.fastify = Fastify({
2181
+ ...common,
2182
+ http2: true,
2183
+ ...tls ? { https: {
2184
+ allowHTTP1: false,
2185
+ cert: tls.cert,
2186
+ key: tls.key,
2187
+ ...tls.ca !== void 0 ? { ca: tls.ca } : {},
2188
+ settings
2189
+ } } : { http: { settings } }
2190
+ });
2191
+ if (requestTimeout > 0) boundH2Requests(this.fastify, requestTimeout);
2192
+ if (pingIntervalMs > 0) pingSessions(this.fastify, pingIntervalMs);
2193
+ this.fastify.server.on("connection", (socket) => {
2194
+ this.#sockets.add(socket);
2195
+ socket.once("close", () => this.#sockets.delete(socket));
2196
+ });
2197
+ this.fastify.server.on("secureConnection", (socket) => {
2198
+ if (socket.alpnProtocol === "h2") return;
2199
+ this.#refused.add(socket);
2200
+ socket.once("close", () => this.#refused.delete(socket));
2201
+ });
2191
2202
  this.fastify.addContentTypeParser("application/octet-stream", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
2192
2203
  this.fastify.addContentTypeParser("application/vnd.substrate.pack", { parseAs: "buffer" }, (_req, body, done) => done(null, body));
2193
2204
  this.fastify.setErrorHandler((err, req, reply) => {
@@ -2210,7 +2221,10 @@ var FastifySubstrateServer = class {
2210
2221
  this.fastify.addHook("onError", async (req, _reply, err) => {
2211
2222
  this.invokeErrorHook(err, req);
2212
2223
  });
2213
- if (compression) this.fastify.register(compressPlugin, { threshold: 1024 });
2224
+ if (compression) this.fastify.register(compressPlugin, {
2225
+ threshold: 1024,
2226
+ customTypes: (type) => COMPRESSIBLE.test(type) && !FRAME_STREAM.test(type)
2227
+ });
2214
2228
  if (cors !== void 0) this.fastify.register(corsPlugin, {
2215
2229
  origin: cors.origins === "*" ? "*" : cors.origins,
2216
2230
  credentials: cors.credentials ?? cors.origins !== "*",
@@ -2228,7 +2242,6 @@ var FastifySubstrateServer = class {
2228
2242
  "Accept"
2229
2243
  ]
2230
2244
  });
2231
- this.fastify.register(websocketPlugin, { options: { maxPayload: wsMaxPayload } });
2232
2245
  }
2233
2246
  invokeErrorHook(err, req) {
2234
2247
  if (!this.errorHook) return;
@@ -2261,37 +2274,21 @@ var FastifySubstrateServer = class {
2261
2274
  };
2262
2275
  }
2263
2276
  async stop(opts) {
2264
- this.notifyWsShutdown(WS_REASON_SERVER_RESTART);
2265
2277
  this.#notifyShutdown(WS_REASON_SERVER_RESTART);
2266
2278
  if (opts?.abortInFlight === true) this.abortAllRequests("server_shutdown");
2279
+ for (const socket of this.#refused) socket.destroy();
2280
+ const closed = this.fastify.close();
2267
2281
  const grace = opts?.grace;
2268
- if (grace === void 0) {
2269
- await this.#drainThenClose();
2270
- return;
2282
+ if (grace !== void 0) {
2283
+ let timer;
2284
+ const late = await Promise.race([closed.then(() => false, () => false), new Promise((resolve) => {
2285
+ timer = setTimeout(() => resolve(true), grace);
2286
+ timer.unref();
2287
+ })]);
2288
+ clearTimeout(timer);
2289
+ if (late) for (const socket of this.#sockets) socket.destroy();
2271
2290
  }
2272
- await Promise.race([this.#drainThenClose(), new Promise((resolve) => {
2273
- setTimeout(resolve, grace).unref();
2274
- })]);
2275
- }
2276
- /**
2277
- * Let streamed responses finish before handing off to `fastify.close()`.
2278
- *
2279
- * `close()` takes exactly ONE pass at reaping idle keep-alive connections. A
2280
- * socket still flushing its final bytes at that instant survives the pass,
2281
- * and nothing revisits it — so `close()` waits on a connection that will
2282
- * never be reaped, and a bare `stop()` never returns.
2283
- *
2284
- * Unbounded on purpose: `fastify.close()` already waits on in-flight
2285
- * requests, so a route that ignores the shutdown notice blocks `stop()`
2286
- * anyway. Callers who need a ceiling pass `grace`, which races this whole
2287
- * sequence.
2288
- */
2289
- async #drainThenClose() {
2290
- await Promise.all([...this.#streamedResponses]);
2291
- await new Promise((resolve) => {
2292
- setImmediate(resolve);
2293
- });
2294
- await this.fastify.close();
2291
+ await closed;
2295
2292
  }
2296
2293
  abortAllRequests(reason) {
2297
2294
  const controllers = [...this.inFlight];
@@ -2310,24 +2307,8 @@ var FastifySubstrateServer = class {
2310
2307
  } catch {}
2311
2308
  }
2312
2309
  /**
2313
- * Walk every live WS connection and invoke its registered shutdown emitter,
2314
- * then close the socket with code 1012 (Service Restart). Synchronous so
2315
- * frames flush before the @fastify/websocket plugin's close pass runs.
2316
- */
2317
- notifyWsShutdown(reason) {
2318
- const entries = [...this.inFlightWs.entries()];
2319
- for (const [conn, emit] of entries) {
2320
- try {
2321
- emit?.(reason);
2322
- } catch {}
2323
- try {
2324
- conn.close(1012, reason);
2325
- } catch {}
2326
- }
2327
- }
2328
- /**
2329
2310
  * Wrap an HTTP-method route in a child plugin so it lands in the plugin
2330
- * queue *after* compress / cors / websocket have finished loading.
2311
+ * queue *after* compress / cors have finished loading.
2331
2312
  * @fastify/compress installs an `onRoute` hook that decorates each route
2332
2313
  * with compression metadata; routes added directly to the parent scope
2333
2314
  * before ready() runs miss that hook and are never compressed.
@@ -2337,14 +2318,7 @@ var FastifySubstrateServer = class {
2337
2318
  */
2338
2319
  #registerWrapped(method, path, handler, inFlight = this.inFlight) {
2339
2320
  this.fastify.register((scope, _opts, done) => {
2340
- registerRoute(scope, method, path, handler, inFlight, this.#streamedResponses);
2341
- done();
2342
- });
2343
- }
2344
- /** Same ordering guarantee as #registerWrapped but for WebSocket routes. */
2345
- #registerWsWrapped(path, handler) {
2346
- this.fastify.register((scope, _opts, done) => {
2347
- registerWsRoute(scope, path, handler, this.inFlightWs, (err) => this.invokeErrorHook(err), this.#wsMaxBuffered, this.#onWarn ?? ((message) => scope.log.warn(message)));
2321
+ registerRoute(scope, method, path, handler, inFlight);
2348
2322
  done();
2349
2323
  });
2350
2324
  }
@@ -2386,9 +2360,6 @@ var FastifySubstrateServer = class {
2386
2360
  observeRequests(observer) {
2387
2361
  this.#observer = observer;
2388
2362
  }
2389
- websocket(path, handler) {
2390
- this.#registerWsWrapped(path, handler);
2391
- }
2392
2363
  onError(hook) {
2393
2364
  this.errorHook = hook;
2394
2365
  }
@@ -2402,10 +2373,7 @@ var FastifySubstrateServer = class {
2402
2373
  "DELETE",
2403
2374
  "PATCH"
2404
2375
  ].map((method) => [method.toLowerCase(), (path, handler) => this.#registerWrapped(method, prefixed(path), handler, this.inFlight)]);
2405
- return {
2406
- ...Object.fromEntries(verbEntries),
2407
- websocket: (path, handler) => this.#registerWsWrapped(prefixed(path), handler)
2408
- };
2376
+ return { ...Object.fromEntries(verbEntries) };
2409
2377
  }
2410
2378
  async inject(req) {
2411
2379
  await this.fastify.ready();
@@ -2443,24 +2411,7 @@ function buildInjectUrl(path, query) {
2443
2411
  }
2444
2412
  return `${path}${path.includes("?") ? "&" : "?"}${qs.toString()}`;
2445
2413
  }
2446
- /**
2447
- * Register a response that streams its body, resolving when the underlying
2448
- * socket finishes (`close` covers both a completed response and a torn-down
2449
- * connection). `stop()` awaits these so it never calls `fastify.close()` while
2450
- * a socket is mid-flush.
2451
- */
2452
- function trackStreamedResponse(reply, streamed) {
2453
- let settle;
2454
- const finished = new Promise((resolve) => {
2455
- settle = resolve;
2456
- });
2457
- streamed.add(finished);
2458
- reply.raw.once("close", () => {
2459
- streamed.delete(finished);
2460
- settle();
2461
- });
2462
- }
2463
- function registerRoute(fastify, method, path, handler, inFlight, streamed) {
2414
+ function registerRoute(fastify, method, path, handler, inFlight) {
2464
2415
  fastify.route({
2465
2416
  method,
2466
2417
  url: path,
@@ -2468,12 +2419,11 @@ function registerRoute(fastify, method, path, handler, inFlight, streamed) {
2468
2419
  const controller = new AbortController();
2469
2420
  inFlight.add(controller);
2470
2421
  const onResponseClose = () => {
2471
- if (!reply.raw.writableFinished && !controller.signal.aborted) controller.abort("client_disconnect");
2422
+ if (!reply.raw.writableEnded && !controller.signal.aborted) controller.abort("client_disconnect");
2472
2423
  };
2473
2424
  reply.raw.once("close", onResponseClose);
2474
2425
  try {
2475
2426
  const hRes = await handler(toSubstrateRequest(req, controller.signal));
2476
- if (hRes.body instanceof ReadableStream) trackStreamedResponse(reply, streamed);
2477
2427
  await applySubstrateResponse(reply, hRes);
2478
2428
  } finally {
2479
2429
  reply.raw.off("close", onResponseClose);
@@ -2482,84 +2432,6 @@ function registerRoute(fastify, method, path, handler, inFlight, streamed) {
2482
2432
  }
2483
2433
  });
2484
2434
  }
2485
- function registerWsRoute(fastify, path, handler, inFlightWs, onHandlerError, maxBuffered, warn) {
2486
- const wsHandler = (socket, req) => {
2487
- const substrateReq = {
2488
- ...toSubstrateRequest(req),
2489
- body: null
2490
- };
2491
- let shutdownEmitter = null;
2492
- let bufferFull = false;
2493
- const conn = {
2494
- id: randomUUID(),
2495
- send(frame) {
2496
- if (bufferFull) return;
2497
- if (socket.bufferedAmount > maxBuffered) {
2498
- bufferFull = true;
2499
- warn(`websocket ${path} conn ${conn.id}: send buffer full (${socket.bufferedAmount} > ${maxBuffered} bytes); closing 1013`);
2500
- socket.close(1013, "send_buffer_full");
2501
- setTimeout(() => socket.terminate(), WS_CLOSE_GRACE_MS).unref?.();
2502
- return;
2503
- }
2504
- if (typeof frame === "string") socket.send(frame);
2505
- else if (Buffer.isBuffer(frame)) socket.send(frame);
2506
- else socket.send(Buffer.from(frame));
2507
- },
2508
- drain() {
2509
- const HIGH_WATER = 1 << 20;
2510
- if (socket.bufferedAmount <= HIGH_WATER || socket.readyState !== 1) return Promise.resolve();
2511
- return new Promise((resolve) => {
2512
- const check = () => {
2513
- if (socket.readyState !== 1 || socket.bufferedAmount <= HIGH_WATER) {
2514
- resolve();
2515
- return;
2516
- }
2517
- setTimeout(check, 10).unref?.();
2518
- };
2519
- setTimeout(check, 10).unref?.();
2520
- });
2521
- },
2522
- onMessage(cb) {
2523
- socket.on("message", (buf) => {
2524
- cb(Buffer.isBuffer(buf) ? buf : Buffer.from(buf));
2525
- });
2526
- },
2527
- onClose(cb) {
2528
- socket.on("close", (code) => {
2529
- cb(code);
2530
- });
2531
- },
2532
- close(code, reason) {
2533
- socket.close(code, reason);
2534
- },
2535
- onShutdown(cb) {
2536
- shutdownEmitter = cb;
2537
- inFlightWs.set(conn, shutdownEmitter);
2538
- }
2539
- };
2540
- inFlightWs.set(conn, null);
2541
- socket.on("close", () => {
2542
- inFlightWs.delete(conn);
2543
- });
2544
- const fail = (err) => {
2545
- onHandlerError(err instanceof Error ? err : new Error(String(err)));
2546
- socket.close(1011, "internal error");
2547
- };
2548
- try {
2549
- Promise.resolve(handler(substrateReq, conn)).catch(fail);
2550
- } catch (err) {
2551
- fail(err);
2552
- }
2553
- };
2554
- fastify.route({
2555
- method: "GET",
2556
- url: path,
2557
- handler: (_req, reply) => {
2558
- reply.status(426).send({ error: "Upgrade Required" });
2559
- },
2560
- wsHandler
2561
- });
2562
- }
2563
2435
  /**
2564
2436
  * HTTP/2 has no `requestTimeout`: give each h2 request `ms` to arrive in full
2565
2437
  * (headers and body), then reset its stream. The clock stops once the handler
@@ -2579,73 +2451,128 @@ function boundH2Requests(fastify, ms) {
2579
2451
  if (req.raw.stream?.closed === true) return reply.code(408).send();
2580
2452
  });
2581
2453
  }
2454
+ /**
2455
+ * Ping each HTTP/2 session every `ms`; a session with two pings in a row
2456
+ * unanswered is destroyed. That is how a peer that vanished without closing
2457
+ * its socket is noticed, and its streams' close paths run. Two, not one: a
2458
+ * ping can queue behind a full write buffer on a slow link, or its ack behind
2459
+ * a blocked event loop.
2460
+ */
2461
+ function pingSessions(fastify, ms) {
2462
+ fastify.server.on("session", (session) => {
2463
+ let unanswered = 0;
2464
+ const timer = setInterval(() => {
2465
+ if (unanswered >= 2) {
2466
+ session.destroy();
2467
+ return;
2468
+ }
2469
+ unanswered++;
2470
+ try {
2471
+ session.ping((err) => {
2472
+ if (err === null) unanswered = 0;
2473
+ });
2474
+ } catch {}
2475
+ }, ms);
2476
+ timer.unref();
2477
+ session.once("close", () => clearInterval(timer));
2478
+ });
2479
+ }
2582
2480
 
2583
2481
  //#endregion
2584
2482
  //#region ../../packages/substrate-sentinel-client/src/client.ts
2585
2483
  /**
2586
- * substrate-sentinel-client — watches a sentinel instance's WS topology stream and
2484
+ * substrate-sentinel-client — watches a sentinel instance's topology feed and
2587
2485
  * mutates a caller-owned BridgeRegistry on online/offline events.
2588
2486
  *
2589
- * - connect to sentinel WS, send {type:'watch'}
2487
+ * - GET <sentinel>/substrate/v1/plugins/substrate-sentinel/watch, a stream of
2488
+ * length-prefixed JSON frames
2590
2489
  * - on {event:'online'}: create HttpBridgeClient, register in bridges,
2591
2490
  * call engine.refreshBridgeSchemas()
2592
2491
  * - on {event:'offline'}: unregister bridge + dispose client
2593
- * - on error/close: reconnect with exponential backoff
2594
- * - stop(): closes WS + disposes all active bridges
2492
+ * - on a refusal or a dropped stream: reconnect with exponential backoff,
2493
+ * reset only after a stream that lasted `reconnectMaxMs`
2494
+ * - stop(): ends the stream + disposes all active bridges
2595
2495
  */
2496
+ const WATCH_PATH = "/substrate/v1/plugins/substrate-sentinel/watch";
2497
+ /** Three of the sentinel's heartbeats at its 30 s maximum `pingIntervalMs`, plus a margin. */
2498
+ const SENTINEL_IDLE_MS = 95e3;
2596
2499
  const NO_OP_METRIC = () => {};
2597
2500
  function startSentinelClient(opts) {
2598
2501
  const metric = opts.metric ?? NO_OP_METRIC;
2599
- const upgradeAuth = opts.auth;
2600
- const wsFactory = opts.wsFactory ?? ((url) => upgradeAuth === void 0 ? new WebSocket$1(url) : new WebSocket$1(url, { headers: { authorization: upgradeAuth() } }));
2502
+ const watchAuth = opts.auth;
2503
+ const fetchImpl = opts.fetch ?? substrateFetch;
2504
+ const watchUrl = `${trimTrailingSlashes(opts.sentinelUrl)}${WATCH_PATH}`;
2601
2505
  const baseMs = opts.reconnectBaseMs ?? 500;
2602
2506
  const maxMs = opts.reconnectMaxMs ?? 3e4;
2507
+ const idleMs = opts.idleMs ?? SENTINEL_IDLE_MS;
2603
2508
  const ownedBridges = /* @__PURE__ */ new Map();
2604
- let ws = null;
2509
+ const ctrl = new AbortController();
2605
2510
  let stopped = false;
2606
2511
  let connected = false;
2607
2512
  let currentBackoff = baseMs;
2608
- let reconnectTimer = null;
2609
- function scheduleReconnect() {
2610
- if (stopped) return;
2611
- const delay = currentBackoff;
2612
- metric("sentinel_client_reconnecting", { delayMs: delay });
2613
- const timer = setTimeout(() => {
2614
- reconnectTimer = null;
2615
- if (stopped) return;
2616
- currentBackoff = Math.min(currentBackoff * 2, maxMs);
2617
- connect();
2618
- }, delay);
2619
- timer.unref();
2620
- reconnectTimer = timer;
2513
+ /** Resolves after `ms`, or at once when stopped. The timer never holds the process open. */
2514
+ function pause(ms) {
2515
+ return new Promise((resolve) => {
2516
+ const timer = setTimeout(done, ms);
2517
+ timer.unref();
2518
+ function done() {
2519
+ clearTimeout(timer);
2520
+ ctrl.signal.removeEventListener("abort", done);
2521
+ resolve();
2522
+ }
2523
+ ctrl.signal.addEventListener("abort", done, { once: true });
2524
+ });
2621
2525
  }
2622
- function connect() {
2623
- if (stopped) return;
2624
- const socket = wsFactory(opts.sentinelUrl);
2625
- ws = socket;
2626
- socket.once("open", () => {
2627
- connected = true;
2628
- currentBackoff = baseMs;
2629
- metric("sentinel_client_connected");
2630
- socket.send(JSON.stringify({ type: "watch" }));
2526
+ /** One watch request, read to its end. */
2527
+ async function watchOnce() {
2528
+ const headers = { accept: FRAMES_JSON_MIME };
2529
+ if (watchAuth !== void 0) headers.authorization = watchAuth();
2530
+ const res = await fetchImpl(watchUrl, {
2531
+ method: "GET",
2532
+ headers,
2533
+ signal: ctrl.signal
2631
2534
  });
2632
- socket.on("message", (buf) => {
2633
- let frame;
2634
- try {
2635
- frame = JSON.parse(buf.toString("utf8"));
2636
- } catch {
2637
- return;
2535
+ const type = res.headers.get("content-type") ?? "";
2536
+ if (!res.ok || res.body === null || !type.startsWith("application/vnd.substrate.frames+json")) {
2537
+ await res.body?.cancel();
2538
+ metric("sentinel_client_error", {
2539
+ status: res.status,
2540
+ error: `watch answered ${res.status} ${type}`
2541
+ });
2542
+ return;
2543
+ }
2544
+ const openedAt = Date.now();
2545
+ connected = true;
2546
+ metric("sentinel_client_connected");
2547
+ try {
2548
+ const utf8 = new TextDecoder();
2549
+ for await (const payload of decodeStreamFrames(idleMs > 0 ? withIdleTimeout(res.body, idleMs) : res.body)) {
2550
+ let frame;
2551
+ try {
2552
+ frame = JSON.parse(utf8.decode(payload));
2553
+ } catch {
2554
+ continue;
2555
+ }
2556
+ if (frame.event === "online") handleOnline(frame);
2557
+ else if (frame.event === "offline") handleOffline(frame);
2638
2558
  }
2639
- if (frame.event === "online") handleOnline(frame);
2640
- else if (frame.event === "offline") handleOffline(frame);
2641
- else if (typeof frame.error === "string") metric("sentinel_client_error", { error: frame.error });
2642
- });
2643
- socket.once("close", () => {
2559
+ } finally {
2644
2560
  connected = false;
2561
+ if (Date.now() - openedAt >= maxMs) currentBackoff = baseMs;
2562
+ }
2563
+ }
2564
+ async function run() {
2565
+ while (!stopped) {
2566
+ try {
2567
+ await watchOnce();
2568
+ } catch {}
2569
+ if (stopped) return;
2645
2570
  metric("sentinel_client_disconnected");
2646
- scheduleReconnect();
2647
- });
2648
- socket.once("error", () => {});
2571
+ const delay = currentBackoff;
2572
+ metric("sentinel_client_reconnecting", { delayMs: delay });
2573
+ currentBackoff = Math.min(currentBackoff * 2, maxMs);
2574
+ await pause(delay);
2575
+ }
2649
2576
  }
2650
2577
  async function handleOnline(frame) {
2651
2578
  const name = typeof frame.name === "string" ? frame.name : void 0;
@@ -2698,7 +2625,8 @@ function startSentinelClient(opts) {
2698
2625
  const client = new HttpBridgeClient({
2699
2626
  name,
2700
2627
  baseUrl: url,
2701
- auth
2628
+ auth,
2629
+ fetch: substrateFetch
2702
2630
  });
2703
2631
  opts.bridges.register(ns, client);
2704
2632
  ownedBridges.set(ns, client);
@@ -2736,16 +2664,13 @@ function startSentinelClient(opts) {
2736
2664
  metric("sentinel_client_offline", { ns });
2737
2665
  }
2738
2666
  }
2739
- connect();
2667
+ const running = run();
2740
2668
  return {
2741
2669
  isConnected: () => connected,
2742
2670
  stop: async () => {
2743
2671
  if (stopped) return;
2744
2672
  stopped = true;
2745
- if (reconnectTimer !== null) {
2746
- clearTimeout(reconnectTimer);
2747
- reconnectTimer = null;
2748
- }
2673
+ ctrl.abort();
2749
2674
  for (const [ns, client] of ownedBridges) {
2750
2675
  try {
2751
2676
  opts.bridges.unregister(ns);
@@ -2753,10 +2678,7 @@ function startSentinelClient(opts) {
2753
2678
  client.dispose();
2754
2679
  }
2755
2680
  ownedBridges.clear();
2756
- if (ws !== null && ws.readyState !== WebSocket$1.CLOSED) await new Promise((resolve) => {
2757
- ws?.once("close", () => resolve());
2758
- ws?.close();
2759
- });
2681
+ await running;
2760
2682
  }
2761
2683
  };
2762
2684
  }
@@ -2785,7 +2707,7 @@ const DEFAULT_RECONNECT_MAX_MS = 3e4;
2785
2707
  function loadConfig(env = process.env) {
2786
2708
  const rawUrl = env.SUBSTRATE_SENTINEL_URL;
2787
2709
  if (rawUrl === void 0 || rawUrl.length === 0) return null;
2788
- if (!rawUrl.startsWith("ws://") && !rawUrl.startsWith("wss://")) throw new Error("SUBSTRATE_SENTINEL_URL must be a ws:// or wss:// URL");
2710
+ if (!rawUrl.startsWith("http://") && !rawUrl.startsWith("https://")) throw new Error("SUBSTRATE_SENTINEL_URL must be the sentinel's http:// or https:// base URL (e.g. https://sentinel.example:3100); the ws:// endpoint is retired");
2789
2711
  return {
2790
2712
  url: rawUrl,
2791
2713
  cred: parseCred(env.SUBSTRATE_SENTINEL_CREDENTIAL),
@@ -2913,7 +2835,8 @@ function buildBridgeRegistry(specs, creds) {
2913
2835
  const client = new HttpBridgeClient({
2914
2836
  name: spec.name,
2915
2837
  baseUrl: spec.url,
2916
- auth
2838
+ auth,
2839
+ fetch: substrateFetch
2917
2840
  });
2918
2841
  clients.push(client);
2919
2842
  registry.register(spec.ns, client);
@@ -3313,9 +3236,10 @@ function parseEnv(env) {
3313
3236
  const snapshotLimit = parseSnapshotLimit(env, knobs, pageLimits.maxLimit);
3314
3237
  const filterWriteLimits = parseFilterWriteLimits(env, knobs);
3315
3238
  const keyReprimeIntervalMs = parseKeyReprimeIntervalMs(env, knobs);
3316
- knobs.recordSecret("streamTicketSecret", "SUBSTRATE_STREAM_TICKET_SECRET", env.SUBSTRATE_STREAM_TICKET_SECRET);
3239
+ const cursorEnv = nonEmpty(env.SUBSTRATE_CURSOR_SECRET?.trim()) === void 0 && nonEmpty(env.SUBSTRATE_STREAM_TICKET_SECRET?.trim()) !== void 0 ? "SUBSTRATE_STREAM_TICKET_SECRET" : "SUBSTRATE_CURSOR_SECRET";
3240
+ knobs.recordSecret("cursorSealSecret", cursorEnv, env[cursorEnv]);
3317
3241
  knobs.record("systemActor", "SUBSTRATE_SYSTEM_ACTOR", env.SUBSTRATE_SYSTEM_ACTOR, nonEmpty(env.SUBSTRATE_SYSTEM_ACTOR?.trim()) ?? null);
3318
- const streamTicketSecret = nonEmpty(env.SUBSTRATE_STREAM_TICKET_SECRET?.trim()) ?? null;
3242
+ const cursorSealSecret = nonEmpty(env[cursorEnv]?.trim()) ?? null;
3319
3243
  return {
3320
3244
  storeSpec,
3321
3245
  memoryByDefault,
@@ -3347,7 +3271,7 @@ function parseEnv(env) {
3347
3271
  filterWriteLimits,
3348
3272
  keyReprimeIntervalMs,
3349
3273
  knobs: knobs.report(),
3350
- streamTicketSecret,
3274
+ cursorSealSecret,
3351
3275
  systemActor: nonEmpty(env.SUBSTRATE_SYSTEM_ACTOR?.trim()) ?? null
3352
3276
  };
3353
3277
  }
@@ -3702,8 +3626,8 @@ function parseBridgeCreds(raw) {
3702
3626
  /**
3703
3627
  * serve/compose-opts.ts — `compose()` options assembly.
3704
3628
  *
3705
- * Pure assembly over already-built pieces: datasets, bridges, auth, ticket
3706
- * secret, idempotency. No I/O except the sentinel-client env read; the
3629
+ * Pure assembly over already-built pieces: datasets, bridges, auth, the
3630
+ * cursor seal secret, idempotency. No I/O except the sentinel-client env read; the
3707
3631
  * substrate-migrations table ensure runs here too so it lands before any
3708
3632
  * substrate plugin migration.
3709
3633
  */
@@ -3763,7 +3687,7 @@ async function buildComposeOpts(args) {
3763
3687
  if (config.auth !== null) composeOpts.auth = config.auth;
3764
3688
  if (config.keyReprimeIntervalMs !== null) composeOpts.keyReprimeIntervalMs = config.keyReprimeIntervalMs;
3765
3689
  if (config.systemActor !== null) composeOpts.systemActor = config.systemActor;
3766
- if (config.streamTicketSecret !== null) composeOpts.streamTicketSecret = config.streamTicketSecret;
3690
+ if (config.cursorSealSecret !== null) composeOpts.cursorSealSecret = config.cursorSealSecret;
3767
3691
  let idempotencyStore = null;
3768
3692
  if (!config.idempotency.disabled) {
3769
3693
  idempotencyStore = storeSql !== null ? new PgIdempotencyStore({ sql: storeSql }) : new MemoryIdempotencyStore();
@@ -4045,7 +3969,6 @@ async function bootStore(opts) {
4045
3969
  opened.push(stopKernel);
4046
3970
  const server = new FastifySubstrateServer({
4047
3971
  logger: false,
4048
- onWarn: (message) => process.stderr.write(`${message}\n`),
4049
3972
  ...config.tls !== null ? { tls: config.tls } : {},
4050
3973
  ...config.cors !== null ? { cors: config.cors } : {},
4051
3974
  ...config.bodyLimit !== null ? { bodyLimit: config.bodyLimit } : {}