@mnmal-ai/substrate-sentinel 1.0.0-alpha.2 → 1.0.0-alpha.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Coordinator plugin: a registry for dynamic bridge discovery.
4
4
 
5
- Owns the `sentinel` namespace (`Coordinator`, `CoordinatorNamespace`, `CoordinatorBridge`), describing the Substrate instances in a federation and the namespaces each serves. Peers register over the plugin's WebSocket route; a liveness loop pings them and marks a peer `offline` once it has been silent longer than `staleThresholdMs`. Other instances follow the registry over the plugin's WebSocket route with the sentinel client built into `@mnmal-ai/substrate` (enabled by `SUBSTRATE_SENTINEL_URL`), which registers and unregisters bridges as peers come and go.
5
+ Owns the `sentinel` namespace (`Coordinator`, `CoordinatorNamespace`, `CoordinatorBridge`), describing the Substrate instances in a federation and the namespaces each serves. Peers register over a long-lived `POST /register` frame stream, and stay online while it is open. The liveness loop sends each open stream a heartbeat frame, and closing the stream marks the peer `offline`. Other instances follow the registry over the `GET /watch` frame stream with the sentinel client built into `@mnmal-ai/substrate` (enabled by `SUBSTRATE_SENTINEL_URL`), which registers and unregisters bridges as peers come and go.
6
6
 
7
7
  ## Where it fits
8
8
 
@@ -15,9 +15,9 @@ cd <runtime-dir> # the directory SUBSTRATE_PLUGIN_DIR points at
15
15
  pnpm add @mnmal-ai/substrate-sentinel@next
16
16
  ```
17
17
 
18
- Defaults in `default-config.json`: `namespace: "sentinel"`, `pingIntervalMs: 30000` (liveness tick), `staleThresholdMs: 90000` (age after which a peer is treated as stale). Override them in `<SUBSTRATE_PLUGIN_DIR>/substrate-sentinel.config.json`.
18
+ Defaults in `default-config.json`: `namespace: "sentinel"`, `pingIntervalMs: 30000` (how often each open stream gets a heartbeat frame; at most 30000, since sentinel clients drop a watch stream silent for 95 s). `staleThresholdMs` is still accepted but ignored: a peer is online while its stream is open. Override them in `<SUBSTRATE_PLUGIN_DIR>/substrate-sentinel.config.json`.
19
19
 
20
- Routes: `GET /substrate/v1/plugins/substrate-sentinel/status` and the topology stream at `/substrate/v1/plugins/substrate-sentinel/ws`.
20
+ Routes, under `/substrate/v1/plugins/substrate-sentinel`: `GET /status`; `POST /register` (needs `mutate`) and `GET /watch` (needs `read`), each a stream of length-prefixed JSON frames.
21
21
 
22
22
  ## More
23
23
 
@@ -11,10 +11,9 @@
11
11
  "default": 30000,
12
12
  "type": "integer",
13
13
  "exclusiveMinimum": 0,
14
- "maximum": 9007199254740991
14
+ "maximum": 30000
15
15
  },
16
16
  "staleThresholdMs": {
17
- "default": 90000,
18
17
  "type": "integer",
19
18
  "exclusiveMinimum": 0,
20
19
  "maximum": 9007199254740991
@@ -1,5 +1,4 @@
1
1
  {
2
2
  "namespace": "sentinel",
3
- "pingIntervalMs": 30000,
4
- "staleThresholdMs": 90000
3
+ "pingIntervalMs": 30000
5
4
  }
@@ -8,7 +8,7 @@ import { z } from 'zod';
8
8
  export declare const SentinelBootstrapConfigSchema: z.ZodObject<{
9
9
  namespace: z.ZodDefault<z.ZodString>;
10
10
  pingIntervalMs: z.ZodDefault<z.ZodNumber>;
11
- staleThresholdMs: z.ZodDefault<z.ZodNumber>;
11
+ staleThresholdMs: z.ZodOptional<z.ZodNumber>;
12
12
  }, z.core.$strict>;
13
13
  export type SentinelBootstrapConfig = z.infer<typeof SentinelBootstrapConfigSchema>;
14
14
  export declare const bootstrap: import("@mnmal-ai/substrate/sdk").CoordinatorBootstrap;
@@ -1 +1 @@
1
- {"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,eAAO,MAAM,6BAA6B;;;;kBAW/B,CAAC;AAEZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,SAAS,wDAQpB,CAAC;eAEY,SAAS"}
1
+ {"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,eAAO,MAAM,6BAA6B;;;;kBAW/B,CAAC;AAEZ,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,eAAO,MAAM,SAAS,wDAOpB,CAAC;eAEY,SAAS"}
package/dist/bootstrap.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as createSentinelPlugin } from "./src-DSiwjCeD.js";
1
+ import { t as createSentinelPlugin } from "./src-CfscT6sX.js";
2
2
  import { defineBootstrap } from "@mnmal-ai/substrate/sdk";
3
3
  import { z } from "zod";
4
4
 
@@ -12,20 +12,19 @@ import { z } from "zod";
12
12
  const NamespaceSchema = z.string().min(1, "must not be empty").refine((s) => !s.includes("/"), { message: "must not contain '/'" });
13
13
  const SentinelBootstrapConfigSchema = z.object({
14
14
  namespace: NamespaceSchema.default("sentinel"),
15
- /** Interval between liveness ticks in milliseconds. */
16
- pingIntervalMs: z.number().int().positive().default(3e4),
17
15
  /**
18
- * Max heartbeat age before a coordinator is marked offline. Checked once
19
- * per `pingIntervalMs` tick, so eviction lands up to one interval later.
16
+ * Interval between heartbeat frames to every open peer, in milliseconds. At
17
+ * most 30 s: sentinel clients drop a watch stream silent for 95 s.
20
18
  */
21
- staleThresholdMs: z.number().int().positive().default(9e4)
19
+ pingIntervalMs: z.number().int().positive().max(3e4).default(3e4),
20
+ /** Ignored: a peer is online while its stream is open. Accepted so older config files still load. */
21
+ staleThresholdMs: z.number().int().positive().optional()
22
22
  }).strict();
23
23
  const bootstrap = defineBootstrap.coordinator({
24
24
  schema: SentinelBootstrapConfigSchema,
25
25
  build: (config) => createSentinelPlugin({
26
26
  namespace: config.namespace,
27
- pingIntervalMs: config.pingIntervalMs,
28
- staleThresholdMs: config.staleThresholdMs
27
+ pingIntervalMs: config.pingIntervalMs
29
28
  })
30
29
  });
31
30
 
package/dist/config.d.ts CHANGED
@@ -5,12 +5,7 @@
5
5
  export interface SentinelPluginConfig {
6
6
  /** Namespace the plugin's types and routes register under. */
7
7
  namespace: string;
8
- /** Interval between liveness ticks in milliseconds. */
8
+ /** Interval between heartbeat frames to every open peer, in milliseconds. */
9
9
  pingIntervalMs: number;
10
- /**
11
- * Max heartbeat age before a coordinator is marked offline. Checked once
12
- * per `pingIntervalMs` tick, so eviction lands up to one interval later.
13
- */
14
- staleThresholdMs: number;
15
10
  }
16
11
  //# sourceMappingURL=config.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B"}
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC;CACxB"}
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Coordinator registration and the topology feed, independent of transport:
3
+ * `handleRegister` upserts the coordinator, its namespaces and bridges and
4
+ * tracks the peer; `handleWatch` adds a watcher; `handleClose` marks a
5
+ * registrant offline and tells the watchers. `stream-routes.ts` mounts them.
6
+ *
7
+ * `register` needs the 'mutate' capability (it writes the coordinator table)
8
+ * and `watch` needs 'read' (it subscribes to the topology broadcast).
9
+ */
10
+ import type { EngineHandle, Identity } from '@mnmal-ai/substrate/sdk';
11
+ import type { LivenessRegistry, PeerConnection } from './liveness.js';
12
+ /**
13
+ * Does this identity hold `capability` IN `namespace`?
14
+ *
15
+ * Resolved through `grantOf` — the SAME function the server's own gates use —
16
+ * so this verdict cannot drift from what the engine enforces.
17
+ */
18
+ export declare function grantsCapability(identity: Identity | undefined, namespace: string, capability: string): boolean;
19
+ export declare function sendJson(conn: PeerConnection, payload: unknown): void;
20
+ export declare function parseFrame(buf: Buffer): Record<string, unknown> | undefined;
21
+ /** Why a register was refused, with the HTTP status a frame-stream route answers. */
22
+ export interface RegisterRefusal {
23
+ error: string;
24
+ status: 400 | 403 | 409 | 500;
25
+ }
26
+ /**
27
+ * Upsert the coordinator, track `conn` for it, send the register reply, then
28
+ * broadcast `online`. A refusal is returned for the caller to deliver as an
29
+ * HTTP status, before any stream opens.
30
+ */
31
+ export declare function handleRegister(engine: EngineHandle, namespace: string, identity: Identity | null, registry: LivenessRegistry, conn: PeerConnection, frame: Record<string, unknown>): Promise<RegisterRefusal | undefined>;
32
+ export declare function handleWatch(registry: LivenessRegistry, conn: PeerConnection): void;
33
+ export declare function handleClose(engine: EngineHandle, namespace: string, identity: Identity | null, registry: LivenessRegistry, conn: PeerConnection): Promise<void>;
34
+ //# sourceMappingURL=coordinators.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"coordinators.d.ts","sourceRoot":"","sources":["../src/coordinators.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAgB,MAAM,yBAAyB,CAAC;AASpF,OAAO,KAAK,EAAyB,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAmU7F;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAGT;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAMrE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAQ3E;AAmCD,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAgEtC;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAGlF;AAED,wBAAsB,WAAW,CAC/B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,GAAG,IAAI,EACzB,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,IAAI,CAAC,CAkBf"}
package/dist/index.d.ts CHANGED
@@ -1,16 +1,16 @@
1
1
  /**
2
2
  * @mnmal-ai/substrate-sentinel — coordinator plugin that manages dynamic
3
3
  * discovery for Substrate coordinators (Coordinator, CoordinatorNamespace,
4
- * CoordinatorBridge rows) plus a persistent WS surface for registration and
4
+ * CoordinatorBridge rows) plus frame-stream routes for registration and
5
5
  * topology watching.
6
6
  *
7
7
  * Coordinator plugin seam (§5.11):
8
8
  * - `namespaces[0]` — the 3-type autoCRUD surface (see `./namespace.ts`).
9
- * - `routes` — `/status` (health dashboard read) and `/ws` (registration +
10
- * watcher heartbeat).
9
+ * - `routes` — `/status` (health dashboard read), `POST /register` and
10
+ * `GET /watch` (see `./stream-routes.ts`).
11
11
  * - `schedule` — a single `<ns>-liveness` task runs every
12
- * `pingIntervalMs` (default 30s), pings every socket, and evicts
13
- * coordinators whose last heartbeat is older than `staleThresholdMs`.
12
+ * `pingIntervalMs` (default 30s) and sends every open stream a heartbeat
13
+ * frame.
14
14
  *
15
15
  * `createSentinelPlugin` is a pure factory taking a fully-resolved
16
16
  * `SentinelPluginConfig`. The structured-config `bootstrap` is the canonical
@@ -20,9 +20,9 @@
20
20
  import type { CoordinatorPlugin } from '@mnmal-ai/substrate/sdk';
21
21
  import type { SentinelPluginConfig } from './config.js';
22
22
  export type { SentinelPluginConfig } from './config.js';
23
- export { type CoordinatorConnection, createLivenessRegistry, type LivenessRegistry, type LivenessRegistryOptions, type LivenessTickResult, runLivenessTick } from './liveness.js';
23
+ export { type CoordinatorConnection, createLivenessRegistry, type LivenessRegistry, type LivenessTickResult, type PeerConnection, runLivenessTick } from './liveness.js';
24
24
  export { buildSentinelNamespace, SENTINEL_TYPE_NAMES } from './namespace.js';
25
25
  export { type CoordinatorRecord, registerSentinelStatusRoute } from './status-route.js';
26
- export { registerSentinelWsRoute } from './ws-route.js';
26
+ export { framePeer, registerSentinelStreamRoutes } from './stream-routes.js';
27
27
  export declare function createSentinelPlugin(cfg: SentinelPluginConfig): CoordinatorPlugin;
28
28
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAMxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,KAAK,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,oBAAoB,GAAG,iBAAiB,CAuBjF"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAMxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,KAAK,qBAAqB,EAC1B,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,eAAe,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,KAAK,iBAAiB,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,SAAS,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAE7E,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,oBAAoB,GAAG,iBAAiB,CAwBjF"}
package/dist/index.js CHANGED
@@ -1,3 +1,3 @@
1
- import { a as buildSentinelNamespace, i as SENTINEL_TYPE_NAMES, n as registerSentinelWsRoute, o as createLivenessRegistry, r as registerSentinelStatusRoute, s as runLivenessTick, t as createSentinelPlugin } from "./src-DSiwjCeD.js";
1
+ import { a as SENTINEL_TYPE_NAMES, c as runLivenessTick, i as registerSentinelStatusRoute, n as framePeer, o as buildSentinelNamespace, r as registerSentinelStreamRoutes, s as createLivenessRegistry, t as createSentinelPlugin } from "./src-CfscT6sX.js";
2
2
 
3
- export { SENTINEL_TYPE_NAMES, buildSentinelNamespace, createLivenessRegistry, createSentinelPlugin, registerSentinelStatusRoute, registerSentinelWsRoute, runLivenessTick };
3
+ export { SENTINEL_TYPE_NAMES, buildSentinelNamespace, createLivenessRegistry, createSentinelPlugin, framePeer, registerSentinelStatusRoute, registerSentinelStreamRoutes, runLivenessTick };
@@ -1,76 +1,56 @@
1
1
  /**
2
- * Liveness bookkeeping for the sentinel WS surface.
2
+ * The sentinel's open peers and the heartbeat that keeps them honest.
3
3
  *
4
- * `WsConnection` has no native ping surface, so this module maintains an
5
- * application-level liveness protocol over JSON frames:
4
+ * The registry tracks every open frame-stream response in one of two sets:
5
+ * `coordinators` (registered instances) or `watchers` (agents tailing the
6
+ * topology). A peer is online for exactly as long as its response is open, so
7
+ * there is nothing to age out: closing the response runs the route's close
8
+ * path, which marks a coordinator offline.
6
9
  *
7
- * - The registry tracks every live socket in one of two sets: `coordinators`
8
- * (registered HDS instances) or `watchers` (agents tailing topology).
9
- * - Each tracked socket records when it was last heard from (`lastSeenMs`),
10
- * set on add and refreshed by `markAlive()` on any inbound frame.
11
- * - A tick (driven by the plugin's `ScheduledTask`) calls `drainStale`, which
12
- * returns every socket whose last heartbeat is older than
13
- * `staleThresholdMs`, then pings the survivors.
14
- * - A stale coordinator is evicted: its connection is closed and the
15
- * matching `Coordinator` row is updated to `status: 'offline'`. A stale
16
- * watcher is dropped.
17
- *
18
- * Staleness is measured against a clock, not by counting ticks, so a late
19
- * scheduler tick or a slow pong cannot evict a peer early. The registry holds
20
- * no timers; the clock is injectable for tests.
10
+ * The plugin's `ScheduledTask` calls `runLivenessTick`, which writes a
11
+ * zero-length heartbeat frame to every peer. That keeps idle proxies from
12
+ * reaping the connection, and a write to a dead socket surfaces as the
13
+ * response closing.
21
14
  */
22
- import type { EngineHandle, WsConnection } from '@mnmal-ai/substrate/sdk';
23
- /** Per-coordinator WS metadata captured on `register` frames. */
15
+ /** A registered or watching peer: one open frame-stream response. */
16
+ export interface PeerConnection {
17
+ send(message: string): void;
18
+ close(code?: number, reason?: string): void;
19
+ heartbeat(): void;
20
+ }
21
+ /** Per-coordinator metadata captured on `register`. */
24
22
  export interface CoordinatorConnection {
25
23
  name: string;
26
24
  coordinatorId: string;
27
25
  url: string;
28
26
  }
29
- export interface LivenessRegistryOptions {
30
- /** Max age of a socket's last heartbeat before it is drained as stale. */
31
- staleThresholdMs: number;
32
- /** Clock in epoch milliseconds. Defaults to `Date.now`. */
33
- now?: () => number;
34
- }
35
27
  export interface LivenessRegistry {
36
28
  /**
37
29
  * Register a newly-online coordinator. Replaces any prior entry for the same
38
30
  * conn, and drops and closes any other conn registered for the same row.
39
31
  */
40
- addCoordinator(conn: WsConnection, meta: CoordinatorConnection): void;
41
- /** Remove a coordinator (on close or eviction). Returns its metadata if it was present. */
42
- removeCoordinator(conn: WsConnection): CoordinatorConnection | undefined;
32
+ addCoordinator(conn: PeerConnection, meta: CoordinatorConnection): void;
33
+ /** Remove a coordinator (on close). Returns its metadata if it was present. */
34
+ removeCoordinator(conn: PeerConnection): CoordinatorConnection | undefined;
43
35
  /** Register a conn as a topology watcher. Idempotent. */
44
- addWatcher(conn: WsConnection): void;
36
+ addWatcher(conn: PeerConnection): void;
45
37
  /** Drop a watcher (on close). */
46
- removeWatcher(conn: WsConnection): void;
47
- /** Record a heartbeat now for any tracked conn (coordinator or watcher). */
48
- markAlive(conn: WsConnection): void;
38
+ removeWatcher(conn: PeerConnection): void;
49
39
  /** Fan out a JSON event to every watcher. Silently drops on send errors. */
50
40
  broadcastEvent(event: Record<string, unknown>): void;
51
- /**
52
- * Sweep-tick primitive: returns every tracked conn whose last heartbeat is
53
- * more than `staleThresholdMs` old. Does not remove them.
54
- */
55
- drainStale(): Array<WsConnection>;
56
- /** Introspection for tests and the onClose handler. */
41
+ /** Introspection for tests and the close handler. */
57
42
  coordinators(): Array<{
58
- conn: WsConnection;
43
+ conn: PeerConnection;
59
44
  meta: CoordinatorConnection;
60
45
  }>;
61
46
  /** Introspection for tests. */
62
- watchers(): Array<WsConnection>;
47
+ watchers(): Array<PeerConnection>;
63
48
  }
64
- export declare function createLivenessRegistry(opts: LivenessRegistryOptions): LivenessRegistry;
49
+ export declare function createLivenessRegistry(): LivenessRegistry;
65
50
  /** Result snapshot returned from a tick. Metric payload shape. */
66
51
  export interface LivenessTickResult {
67
- stalePinged: number;
68
- markedOffline: number;
52
+ heartbeats: number;
69
53
  }
70
- /**
71
- * Drive one liveness cycle. Returns the number of sockets that were asked to
72
- * ping this tick, and the number of coordinators evicted (closed + row
73
- * flipped to offline).
74
- */
75
- export declare function runLivenessTick(registry: LivenessRegistry, engine: EngineHandle, namespace: string): Promise<LivenessTickResult>;
54
+ /** Send every open peer a heartbeat frame. */
55
+ export declare function runLivenessTick(registry: LivenessRegistry): LivenessTickResult;
76
56
  //# sourceMappingURL=liveness.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../src/liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG1E,iEAAiE;AACjE,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAaD,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtE,2FAA2F;IAC3F,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,qBAAqB,GAAG,SAAS,CAAC;IACzE,yDAAyD;IACzD,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACrC,iCAAiC;IACjC,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACxC,4EAA4E;IAC5E,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,4EAA4E;IAC5E,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrD;;;OAGG;IACH,UAAU,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;IAClC,uDAAuD;IACvD,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC;IAC3E,+BAA+B;IAC/B,QAAQ,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC;CACjC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,GAAG,gBAAgB,CAkEtF;AAED,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAyBD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,CAAC,CAuD7B"}
1
+ {"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../src/liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACxE,+EAA+E;IAC/E,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,qBAAqB,GAAG,SAAS,CAAC;IAC3E,yDAAyD;IACzD,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,iCAAiC;IACjC,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC1C,4EAA4E;IAC5E,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrD,qDAAqD;IACrD,YAAY,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,cAAc,CAAC;QAAC,IAAI,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC;IAC7E,+BAA+B;IAC/B,QAAQ,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC;CACnC;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CA+CzD;AAED,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAW9E"}
@@ -2,7 +2,7 @@
2
2
  * substrate-sentinel namespace definition.
3
3
  *
4
4
  * Three autoCRUD types: Coordinator, CoordinatorNamespace, CoordinatorBridge.
5
- * The WS handler composes upsert on top of create/update.
5
+ * `handleRegister` composes upsert on top of create/update.
6
6
  *
7
7
  * `coordinatorId` fields are plain string scalars rather than `field.crossRef`;
8
8
  * the §6.1 edge wiring for this surface is deferred.
@@ -1,137 +1,57 @@
1
1
  import { defineNamespace, field, formatQualifiedKey, grantOf, grantedIn, jsonResponse, makeCtx, queryAll, resolveIdentity } from "@mnmal-ai/substrate/sdk";
2
+ import { FRAMES_JSON_MIME, HEARTBEAT_FRAME } from "@mnmal-ai/substrate/pack";
2
3
 
3
4
  //#region src/liveness.ts
4
- function createLivenessRegistry(opts) {
5
- const { staleThresholdMs } = opts;
6
- const now = opts.now ?? Date.now;
5
+ function createLivenessRegistry() {
7
6
  const coords = /* @__PURE__ */ new Map();
8
- const watchers = /* @__PURE__ */ new Map();
7
+ const watchers = /* @__PURE__ */ new Set();
9
8
  return {
10
9
  addCoordinator(conn, meta) {
11
10
  for (const [old, entry] of coords) {
12
- if (old === conn || entry.meta.coordinatorId !== meta.coordinatorId) continue;
11
+ if (old === conn || entry.coordinatorId !== meta.coordinatorId) continue;
13
12
  coords.delete(old);
14
13
  try {
15
14
  old.close(4409, "superseded by a newer registration");
16
15
  } catch {}
17
16
  }
18
- coords.set(conn, {
19
- conn,
20
- meta,
21
- lastSeenMs: now()
22
- });
17
+ coords.set(conn, meta);
23
18
  },
24
19
  removeCoordinator(conn) {
25
- const entry = coords.get(conn);
26
- if (entry === void 0) return void 0;
20
+ const meta = coords.get(conn);
27
21
  coords.delete(conn);
28
- return entry.meta;
22
+ return meta;
29
23
  },
30
24
  addWatcher(conn) {
31
- if (watchers.has(conn)) return;
32
- watchers.set(conn, {
33
- conn,
34
- lastSeenMs: now()
35
- });
25
+ watchers.add(conn);
36
26
  },
37
27
  removeWatcher(conn) {
38
28
  watchers.delete(conn);
39
29
  },
40
- markAlive(conn) {
41
- const at = now();
42
- const coord = coords.get(conn);
43
- if (coord !== void 0) coord.lastSeenMs = at;
44
- const watcher = watchers.get(conn);
45
- if (watcher !== void 0) watcher.lastSeenMs = at;
46
- },
47
30
  broadcastEvent(event) {
48
31
  const msg = JSON.stringify(event);
49
- for (const entry of watchers.values()) try {
50
- entry.conn.send(msg);
32
+ for (const conn of watchers) try {
33
+ conn.send(msg);
51
34
  } catch {}
52
35
  },
53
- drainStale() {
54
- const cutoff = now() - staleThresholdMs;
55
- const stale = [];
56
- for (const entry of [...coords.values(), ...watchers.values()]) if (entry.lastSeenMs < cutoff) stale.push(entry.conn);
57
- return stale;
58
- },
59
36
  coordinators() {
60
- return [...coords.values()].map((e) => ({
61
- conn: e.conn,
62
- meta: e.meta
37
+ return [...coords].map(([conn, meta]) => ({
38
+ conn,
39
+ meta
63
40
  }));
64
41
  },
65
42
  watchers() {
66
- return [...watchers.values()].map((e) => e.conn);
43
+ return [...watchers];
67
44
  }
68
45
  };
69
46
  }
70
- async function markCoordinatorOffline(engine, namespace, coordinatorId) {
71
- const key = `${namespace}/updateCoordinator`;
72
- await engine.mutate({
73
- frame: { [key]: {
74
- params: {
75
- id: coordinatorId,
76
- status: "offline"
77
- },
78
- fields: {
79
- id: true,
80
- status: true
81
- }
82
- } },
83
- ctx: makeCtx(namespace, "mutate", {
84
- kind: "system",
85
- id: "sentinel-liveness",
86
- grants: { "*": ["read", "mutate"] }
87
- })
88
- });
89
- }
90
- /**
91
- * Drive one liveness cycle. Returns the number of sockets that were asked to
92
- * ping this tick, and the number of coordinators evicted (closed + row
93
- * flipped to offline).
94
- */
95
- async function runLivenessTick(registry, engine, namespace) {
96
- const coordByConn = new Map(registry.coordinators().map((entry) => [entry.conn, entry.meta]));
97
- const stale = registry.drainStale();
98
- let markedOffline = 0;
99
- for (const conn of stale) {
100
- const meta = coordByConn.get(conn);
101
- if (meta !== void 0) {
102
- try {
103
- conn.close(4408, "liveness timeout");
104
- } catch {}
105
- const coordId = registry.removeCoordinator(conn)?.coordinatorId ?? meta.coordinatorId;
106
- try {
107
- await markCoordinatorOffline(engine, namespace, coordId);
108
- markedOffline++;
109
- registry.broadcastEvent({
110
- event: "offline",
111
- name: meta.name,
112
- url: meta.url
113
- });
114
- } catch {}
115
- } else {
116
- registry.removeWatcher(conn);
117
- try {
118
- conn.close(4408, "liveness timeout");
119
- } catch {}
120
- }
121
- }
122
- const pingMsg = JSON.stringify({ type: "ping" });
123
- const survivors = [];
124
- for (const entry of registry.coordinators()) survivors.push(entry.conn);
125
- for (const w of registry.watchers()) survivors.push(w);
126
- let stalePinged = 0;
127
- for (const conn of survivors) try {
128
- conn.send(pingMsg);
129
- stalePinged++;
47
+ /** Send every open peer a heartbeat frame. */
48
+ function runLivenessTick(registry) {
49
+ let heartbeats = 0;
50
+ for (const conn of [...registry.coordinators().map((e) => e.conn), ...registry.watchers()]) try {
51
+ conn.heartbeat();
52
+ heartbeats++;
130
53
  } catch {}
131
- return {
132
- stalePinged,
133
- markedOffline
134
- };
54
+ return { heartbeats };
135
55
  }
136
56
 
137
57
  //#endregion
@@ -199,7 +119,7 @@ function registerSentinelStatusRoute(router, ctx, namespace) {
199
119
  }
200
120
 
201
121
  //#endregion
202
- //#region src/ws-route.ts
122
+ //#region src/coordinators.ts
203
123
  const COORDINATOR_FIELDS = {
204
124
  id: true,
205
125
  name: true,
@@ -396,13 +316,18 @@ function normaliseBridges(raw) {
396
316
  }
397
317
  return out;
398
318
  }
319
+ /**
320
+ * Upsert the coordinator, track `conn` for it, send the register reply, then
321
+ * broadcast `online`. A refusal is returned for the caller to deliver as an
322
+ * HTTP status, before any stream opens.
323
+ */
399
324
  async function handleRegister(engine, namespace, identity, registry, conn, frame) {
400
325
  const name = typeof frame.name === "string" ? frame.name : void 0;
401
326
  const url = typeof frame.url === "string" ? frame.url : void 0;
402
- if (name === void 0 || url === void 0) {
403
- sendJson(conn, { error: "register requires name and url" });
404
- return;
405
- }
327
+ if (name === void 0 || url === void 0) return {
328
+ error: "register requires name and url",
329
+ status: 400
330
+ };
406
331
  const namespaces = normaliseNamespaces(frame.namespaces);
407
332
  const version = typeof frame.version === "string" ? frame.version : void 0;
408
333
  const bridges = normaliseBridges(frame.bridges);
@@ -412,20 +337,20 @@ async function handleRegister(engine, namespace, identity, registry, conn, frame
412
337
  namespaces
413
338
  };
414
339
  if (version !== void 0) upsertArgs.version = version;
415
- if (actorOf(identity) === null) {
416
- sendJson(conn, { error: "register requires an attributable identity (an agent key, a token, or a system actor); this one cannot be recorded as the coordinator row's creator" });
417
- return;
418
- }
340
+ if (actorOf(identity) === null) return {
341
+ error: "register requires an attributable identity (an agent key, a token, or a system actor); this one cannot be recorded as the coordinator row's creator",
342
+ status: 403
343
+ };
419
344
  const result = await upsertCoordinator(engine, namespace, identity, upsertArgs);
420
- if (result.foreign === true) {
421
- sendJson(conn, { error: `coordinator '${name}' or url '${url}' is registered by another identity` });
422
- return;
423
- }
345
+ if (result.foreign === true) return {
346
+ error: `coordinator '${name}' or url '${url}' is registered by another identity`,
347
+ status: 409
348
+ };
424
349
  const coordinator = result.coordinator;
425
- if (coordinator === void 0) {
426
- sendJson(conn, { error: "failed to upsert coordinator record" });
427
- return;
428
- }
350
+ if (coordinator === void 0) return {
351
+ error: "failed to upsert coordinator record",
352
+ status: 500
353
+ };
429
354
  const meta = {
430
355
  name,
431
356
  coordinatorId: coordinator.id,
@@ -478,56 +403,168 @@ async function handleClose(engine, namespace, identity, registry, conn) {
478
403
  url: meta.url
479
404
  });
480
405
  }
481
- function registerSentinelWsRoute(router, ctx, namespace, registry) {
482
- router.websocket("/ws", (req, conn) => {
483
- const identity = req.identity;
484
- conn.onMessage((buf) => {
485
- const frame = parseFrame(buf);
486
- if (frame === void 0) {
487
- sendJson(conn, { error: "invalid JSON" });
488
- return;
489
- }
490
- registry.markAlive(conn);
491
- const type = typeof frame.type === "string" ? frame.type : void 0;
492
- const required = type === "register" ? "mutate" : type === "watch" ? "read" : void 0;
493
- if (required !== void 0) {
494
- if (identity === void 0) {
495
- ctx.metric("sentinel_frame_unauthorized", { type });
496
- sendJson(conn, { error: "unauthorized" });
497
- return;
498
- }
499
- if (!grantsCapability(identity, namespace, required)) {
500
- ctx.metric("sentinel_frame_forbidden", {
501
- type,
502
- required
503
- });
504
- sendJson(conn, { error: "forbidden" });
505
- return;
506
- }
507
- }
508
- if (type === "register") {
509
- handleRegister(ctx.engine, namespace, identity ?? null, registry, conn, frame).catch(() => {
510
- sendJson(conn, { error: "register failed" });
511
- });
512
- return;
513
- }
514
- if (type === "watch") {
515
- handleWatch(registry, conn);
516
- return;
517
- }
518
- if (type === "pong") return;
519
- sendJson(conn, { error: "unknown frame type" });
520
- });
521
- conn.onClose(() => {
522
- handleClose(ctx.engine, namespace, identity ?? null, registry, conn).catch(() => {});
406
+
407
+ //#endregion
408
+ //#region src/stream-routes.ts
409
+ /**
410
+ * The sentinel's frame-stream routes:
411
+ *
412
+ * - `POST /register` (the plugin router gates it on `mutate`) takes the
413
+ * register body `{ name, url, namespaces, version?, bridges? }`. A refusal is
414
+ * an HTTP status with `{ error }`. Otherwise the answer is a stream of
415
+ * length-prefixed JSON frames: first the register reply, then nothing but
416
+ * heartbeats. The registrant is online for as long as the response stays
417
+ * open, and closing it marks the registrant offline.
418
+ * - `GET /watch` (gated on `read`) streams `{ ok: true, watching: true }` and
419
+ * then every `{ event: 'online' | 'offline', … }` broadcast.
420
+ *
421
+ * A peer here is alive while its response is open: the liveness tick sends it
422
+ * zero-length heartbeat frames, and a dead socket surfaces as the response
423
+ * closing.
424
+ */
425
+ const HEADERS = {
426
+ "content-type": FRAMES_JSON_MIME,
427
+ "cache-control": "no-store",
428
+ "x-accel-buffering": "no"
429
+ };
430
+ const utf8 = new TextEncoder();
431
+ /** A JSON message as one length-prefixed frame. */
432
+ function frameOf(message) {
433
+ const payload = utf8.encode(message);
434
+ const out = new Uint8Array(4 + payload.length);
435
+ new DataView(out.buffer).setUint32(0, payload.length, false);
436
+ out.set(payload, 4);
437
+ return out;
438
+ }
439
+ /**
440
+ * A response body that is a liveness peer. `onEnd` runs once, whichever side
441
+ * ends it: the client disconnecting, the request aborting, or `close()` from
442
+ * the registry (a superseding registration, an eviction, shutdown).
443
+ */
444
+ function framePeer(onEnd) {
445
+ let controller;
446
+ let ended = false;
447
+ const end = () => {
448
+ if (ended) return;
449
+ ended = true;
450
+ onEnd(peer);
451
+ };
452
+ const enqueue = (bytes) => {
453
+ if (ended || controller === void 0) return;
454
+ if ((controller.desiredSize ?? 0) < -1048576) {
455
+ peer.close();
456
+ return;
457
+ }
458
+ try {
459
+ controller.enqueue(bytes);
460
+ } catch {
461
+ end();
462
+ }
463
+ };
464
+ const body = new ReadableStream({
465
+ start(c) {
466
+ controller = c;
467
+ },
468
+ cancel() {
469
+ controller = void 0;
470
+ end();
471
+ }
472
+ }, new ByteLengthQueuingStrategy({ highWaterMark: 65536 }));
473
+ const peer = {
474
+ send: (message) => enqueue(frameOf(message)),
475
+ heartbeat: () => enqueue(HEARTBEAT_FRAME),
476
+ close: () => {
477
+ if (!ended) try {
478
+ controller?.error(/* @__PURE__ */ new Error("sentinel feed closed"));
479
+ } catch {}
480
+ end();
481
+ }
482
+ };
483
+ return {
484
+ peer,
485
+ body,
486
+ ended: () => ended
487
+ };
488
+ }
489
+ function refuse(status, error) {
490
+ return jsonResponse(status, { error });
491
+ }
492
+ /** 401 without an identity, 403 without `capability` in `namespace`, else undefined. */
493
+ function gate(identity, namespace, capability) {
494
+ if (identity === void 0) return refuse(401, "unauthorized");
495
+ if (!grantsCapability(identity, namespace, capability)) return refuse(403, "forbidden");
496
+ }
497
+ /** Registers the routes; the returned function ends every open response. */
498
+ function registerSentinelStreamRoutes(router, ctx, namespace, registry) {
499
+ /** One peer per open response, so the route ends them all at shutdown. */
500
+ const open = /* @__PURE__ */ new Set();
501
+ /** Offline writes in flight, which shutdown waits for while the engine is still up. */
502
+ const closing = /* @__PURE__ */ new Set();
503
+ const track = (req, identity) => {
504
+ const close = (p) => {
505
+ const done = handleClose(ctx.engine, namespace, identity, registry, p).catch(() => {}).finally(() => closing.delete(done));
506
+ closing.add(done);
507
+ return done;
508
+ };
509
+ const fp = framePeer((p) => {
510
+ open.delete(p);
511
+ close(p);
523
512
  });
513
+ open.add(fp.peer);
514
+ if (req.signal?.aborted === true) fp.peer.close();
515
+ else req.signal?.addEventListener("abort", () => fp.peer.close(), { once: true });
516
+ return {
517
+ ...fp,
518
+ close
519
+ };
520
+ };
521
+ router.post("/register", async (req) => {
522
+ const refused = gate(req.identity, namespace, "mutate");
523
+ if (refused !== void 0) return refused;
524
+ const frame = parseFrame(req.body ?? Buffer.alloc(0));
525
+ if (frame === void 0) return refuse(400, "invalid JSON");
526
+ const identity = req.identity ?? null;
527
+ const { peer, body, ended, close } = track(req, identity);
528
+ if (ended()) return { status: 499 };
529
+ try {
530
+ const refusal = await handleRegister(ctx.engine, namespace, identity, registry, peer, frame);
531
+ if (refusal !== void 0) {
532
+ open.delete(peer);
533
+ return refuse(refusal.status, refusal.error);
534
+ }
535
+ } catch {
536
+ peer.close();
537
+ return refuse(500, "register failed");
538
+ }
539
+ if (ended()) await close(peer);
540
+ return {
541
+ status: 200,
542
+ headers: HEADERS,
543
+ body
544
+ };
524
545
  });
546
+ router.get("/watch", async (req) => {
547
+ const refused = gate(req.identity, namespace, "read");
548
+ if (refused !== void 0) return refused;
549
+ const { peer, body, ended } = track(req, req.identity ?? null);
550
+ if (!ended()) handleWatch(registry, peer);
551
+ return {
552
+ status: 200,
553
+ headers: HEADERS,
554
+ body
555
+ };
556
+ });
557
+ return async () => {
558
+ for (const peer of [...open]) peer.close();
559
+ await Promise.all([...closing]);
560
+ };
525
561
  }
526
562
 
527
563
  //#endregion
528
564
  //#region src/index.ts
529
565
  function createSentinelPlugin(cfg) {
530
- const registry = createLivenessRegistry({ staleThresholdMs: cfg.staleThresholdMs });
566
+ const registry = createLivenessRegistry();
567
+ let endStreams = async () => {};
531
568
  return {
532
569
  name: "substrate-sentinel",
533
570
  contractVersion: ">=1.0.0-alpha.0 <2.0.0",
@@ -537,16 +574,16 @@ function createSentinelPlugin(cfg) {
537
574
  intervalMs: cfg.pingIntervalMs,
538
575
  runOnStart: false,
539
576
  handler: async (taskCtx) => {
540
- const result = await runLivenessTick(registry, taskCtx.engine, cfg.namespace);
541
- taskCtx.metric("sentinel_liveness_tick", result);
577
+ taskCtx.metric("sentinel_liveness_tick", runLivenessTick(registry));
542
578
  }
543
579
  }],
544
580
  routes: (router, routeCtx) => {
545
581
  registerSentinelStatusRoute(router, routeCtx, cfg.namespace);
546
- registerSentinelWsRoute(router, routeCtx, cfg.namespace, registry);
547
- }
582
+ endStreams = registerSentinelStreamRoutes(router, routeCtx, cfg.namespace, registry);
583
+ },
584
+ onStop: () => endStreams()
548
585
  };
549
586
  }
550
587
 
551
588
  //#endregion
552
- export { buildSentinelNamespace as a, SENTINEL_TYPE_NAMES as i, registerSentinelWsRoute as n, createLivenessRegistry as o, registerSentinelStatusRoute as r, runLivenessTick as s, createSentinelPlugin as t };
589
+ export { SENTINEL_TYPE_NAMES as a, runLivenessTick as c, registerSentinelStatusRoute as i, framePeer as n, buildSentinelNamespace as o, registerSentinelStreamRoutes as r, createLivenessRegistry as s, createSentinelPlugin as t };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The sentinel's frame-stream routes:
3
+ *
4
+ * - `POST /register` (the plugin router gates it on `mutate`) takes the
5
+ * register body `{ name, url, namespaces, version?, bridges? }`. A refusal is
6
+ * an HTTP status with `{ error }`. Otherwise the answer is a stream of
7
+ * length-prefixed JSON frames: first the register reply, then nothing but
8
+ * heartbeats. The registrant is online for as long as the response stays
9
+ * open, and closing it marks the registrant offline.
10
+ * - `GET /watch` (gated on `read`) streams `{ ok: true, watching: true }` and
11
+ * then every `{ event: 'online' | 'offline', … }` broadcast.
12
+ *
13
+ * A peer here is alive while its response is open: the liveness tick sends it
14
+ * zero-length heartbeat frames, and a dead socket surfaces as the response
15
+ * closing.
16
+ */
17
+ import type { PluginRouteContext, PluginRouter } from '@mnmal-ai/substrate/sdk';
18
+ import type { LivenessRegistry, PeerConnection } from './liveness.js';
19
+ /**
20
+ * A response body that is a liveness peer. `onEnd` runs once, whichever side
21
+ * ends it: the client disconnecting, the request aborting, or `close()` from
22
+ * the registry (a superseding registration, an eviction, shutdown).
23
+ */
24
+ export declare function framePeer(onEnd: (peer: PeerConnection) => unknown): {
25
+ peer: PeerConnection;
26
+ body: ReadableStream<Uint8Array>;
27
+ /** True once the response has ended, whichever side ended it. */
28
+ ended: () => boolean;
29
+ };
30
+ /** Registers the routes; the returned function ends every open response. */
31
+ export declare function registerSentinelStreamRoutes(router: PluginRouter, ctx: PluginRouteContext, namespace: string, registry: LivenessRegistry): () => Promise<void>;
32
+ //# sourceMappingURL=stream-routes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stream-routes.d.ts","sourceRoot":"","sources":["../src/stream-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAEV,kBAAkB,EAClB,YAAY,EAGb,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAsBtE;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG;IACnE,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACjC,iEAAiE;IACjE,KAAK,EAAE,MAAM,OAAO,CAAC;CACtB,CAiDA;AAiBD,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,kBAAkB,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,MAAM,OAAO,CAAC,IAAI,CAAC,CAiErB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mnmal-ai/substrate-sentinel",
3
- "version": "1.0.0-alpha.2",
3
+ "version": "1.0.0-alpha.21",
4
4
  "description": "Substrate coordinator plugin: registry for dynamic bridge discovery.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -29,21 +29,21 @@
29
29
  "access": "public"
30
30
  },
31
31
  "dependencies": {
32
- "zod": "^4.6.5"
32
+ "zod": "^4.6.7"
33
33
  },
34
34
  "devDependencies": {
35
- "@mnmal-ai/substrate": "1.0.0-alpha.2",
36
- "@mnmal-ai/substrate-config": "1.0.0-alpha.2",
35
+ "@mnmal-ai/substrate": "1.0.0-alpha.21",
36
+ "@mnmal-ai/substrate-config": "1.0.0-alpha.21",
37
37
  "@types/node": "^26.6.4",
38
38
  "tsdown": "^0.23.0",
39
39
  "typescript": "^7.0.2",
40
40
  "vitest": "^5.0.3"
41
41
  },
42
42
  "peerDependencies": {
43
- "@mnmal-ai/substrate": ">=1.0.0-alpha.0 <2.0.0"
43
+ "@mnmal-ai/substrate": ">=1.0.0-alpha.19 <2.0.0"
44
44
  },
45
45
  "engines": {
46
- "node": ">=26.2.0"
46
+ "node": ">=26.13.1"
47
47
  },
48
48
  "substrate": {
49
49
  "tier": "coordinator",
@@ -1,38 +0,0 @@
1
- /**
2
- * WS route — `/substrate/v1/plugins/substrate-sentinel/ws`.
3
- *
4
- * Built on `PluginRouter.websocket`, a framework-agnostic primitive (§4.8) with
5
- * no native ping/pong and no raw `terminate()`; `./liveness.ts` supplies an
6
- * application-level heartbeat.
7
- *
8
- * Frame protocol (JSON, UTF-8):
9
- * - client → server
10
- * - `{ type: 'register', name, url, namespaces: string[], version?, bridges?: [...] }` (requires 'mutate')
11
- * - `{ type: 'watch' }` (requires 'read')
12
- * - `{ type: 'pong' }` (application heartbeat ack, unauthenticated)
13
- * - server → client
14
- * - `{ ok: true, registered, updated, coordinator }` (register reply)
15
- * - `{ ok: true, watching: true }` (watch reply)
16
- * - `{ event: 'online' | 'offline', name, url, ... }` (watcher broadcast)
17
- * - `{ type: 'ping' }` (liveness tick)
18
- * - `{ error: 'unknown frame type' }` (parser errors)
19
- * - `{ error: 'unauthorized' }` (register/watch, no identity)
20
- * - `{ error: 'forbidden' }` (register/watch, identity lacks the capability)
21
- *
22
- * Auth: `register` requires the 'mutate' capability (it mutates the
23
- * coordinator table) and `watch` requires 'read' (it subscribes to the
24
- * topology broadcast) — mirroring `withAuth`'s method-based capability map
25
- * for the HTTP routes (`substrate-compose`'s `compose.ts`). Both require
26
- * `req.identity` to be populated at all, resolved once at upgrade by
27
- * `wrapWsHandler`: missing identity is 'unauthorized', an
28
- * identity present but lacking the capability is 'forbidden'. `pong` carries
29
- * no capability requirement of its own — it is liveness only — but that is
30
- * not the same as being open to anonymous callers: under the default
31
- * `required` auth mode an unauthenticated connection is closed at upgrade and
32
- * never reaches this frame handler at all. Anonymous `pong` is reachable only
33
- * where the transport admits anonymous connections (attribute mode).
34
- */
35
- import type { PluginRouteContext, PluginRouter } from '@mnmal-ai/substrate/sdk';
36
- import type { LivenessRegistry } from './liveness.js';
37
- export declare function registerSentinelWsRoute(router: PluginRouter, ctx: PluginRouteContext, namespace: string, registry: LivenessRegistry): void;
38
- //# sourceMappingURL=ws-route.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"ws-route.d.ts","sourceRoot":"","sources":["../src/ws-route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAIV,kBAAkB,EAClB,YAAY,EAGb,MAAM,yBAAyB,CAAC;AASjC,OAAO,KAAK,EAAyB,gBAAgB,EAAE,MAAM,eAAe,CAAC;AA8e7E,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,kBAAkB,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CA4DN"}