@mnmal-ai/substrate-sentinel 1.0.0-alpha.9 → 1.0.0-beta.1
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 +3 -3
- package/config.schema.json +1 -2
- package/default-config.json +1 -2
- package/dist/bootstrap.d.ts +1 -1
- package/dist/bootstrap.d.ts.map +1 -1
- package/dist/bootstrap.js +7 -8
- package/dist/config.d.ts +1 -6
- package/dist/config.d.ts.map +1 -1
- package/dist/coordinators.d.ts +34 -0
- package/dist/coordinators.d.ts.map +1 -0
- package/dist/index.d.ts +7 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -2
- package/dist/liveness.d.ts +29 -49
- package/dist/liveness.d.ts.map +1 -1
- package/dist/namespace.d.ts +1 -1
- package/dist/{src-DSiwjCeD.js → src-CfscT6sX.js} +203 -166
- package/dist/stream-routes.d.ts +32 -0
- package/dist/stream-routes.d.ts.map +1 -0
- package/package.json +6 -6
- package/dist/ws-route.d.ts +0 -38
- package/dist/ws-route.d.ts.map +0 -1
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
|
|
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` (
|
|
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
|
|
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
|
|
package/config.schema.json
CHANGED
package/default-config.json
CHANGED
package/dist/bootstrap.d.ts
CHANGED
|
@@ -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.
|
|
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;
|
package/dist/bootstrap.d.ts.map
CHANGED
|
@@ -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,
|
|
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-
|
|
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
|
-
*
|
|
19
|
-
*
|
|
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
|
-
|
|
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
|
|
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
|
package/dist/config.d.ts.map
CHANGED
|
@@ -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,
|
|
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
|
|
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)
|
|
10
|
-
*
|
|
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)
|
|
13
|
-
*
|
|
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
|
|
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 {
|
|
26
|
+
export { framePeer, registerSentinelStreamRoutes } from './stream-routes.js';
|
|
27
27
|
export declare function createSentinelPlugin(cfg: SentinelPluginConfig): CoordinatorPlugin;
|
|
28
28
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -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,
|
|
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
|
|
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,
|
|
3
|
+
export { SENTINEL_TYPE_NAMES, buildSentinelNamespace, createLivenessRegistry, createSentinelPlugin, framePeer, registerSentinelStatusRoute, registerSentinelStreamRoutes, runLivenessTick };
|
package/dist/liveness.d.ts
CHANGED
|
@@ -1,76 +1,56 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* The sentinel's open peers and the heartbeat that keeps them honest.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
-
|
|
23
|
-
|
|
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:
|
|
41
|
-
/** Remove a coordinator (on close
|
|
42
|
-
removeCoordinator(conn:
|
|
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:
|
|
36
|
+
addWatcher(conn: PeerConnection): void;
|
|
45
37
|
/** Drop a watcher (on close). */
|
|
46
|
-
removeWatcher(conn:
|
|
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:
|
|
43
|
+
conn: PeerConnection;
|
|
59
44
|
meta: CoordinatorConnection;
|
|
60
45
|
}>;
|
|
61
46
|
/** Introspection for tests. */
|
|
62
|
-
watchers(): Array<
|
|
47
|
+
watchers(): Array<PeerConnection>;
|
|
63
48
|
}
|
|
64
|
-
export declare function createLivenessRegistry(
|
|
49
|
+
export declare function createLivenessRegistry(): LivenessRegistry;
|
|
65
50
|
/** Result snapshot returned from a tick. Metric payload shape. */
|
|
66
51
|
export interface LivenessTickResult {
|
|
67
|
-
|
|
68
|
-
markedOffline: number;
|
|
52
|
+
heartbeats: number;
|
|
69
53
|
}
|
|
70
|
-
/**
|
|
71
|
-
|
|
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
|
package/dist/liveness.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../src/liveness.ts"],"names":[],"mappings":"AAAA
|
|
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"}
|
package/dist/namespace.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* substrate-sentinel namespace definition.
|
|
3
3
|
*
|
|
4
4
|
* Three autoCRUD types: Coordinator, CoordinatorNamespace, CoordinatorBridge.
|
|
5
|
-
*
|
|
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(
|
|
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
|
|
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.
|
|
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
|
|
26
|
-
if (entry === void 0) return void 0;
|
|
20
|
+
const meta = coords.get(conn);
|
|
27
21
|
coords.delete(conn);
|
|
28
|
-
return
|
|
22
|
+
return meta;
|
|
29
23
|
},
|
|
30
24
|
addWatcher(conn) {
|
|
31
|
-
|
|
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
|
|
50
|
-
|
|
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
|
|
61
|
-
conn
|
|
62
|
-
meta
|
|
37
|
+
return [...coords].map(([conn, meta]) => ({
|
|
38
|
+
conn,
|
|
39
|
+
meta
|
|
63
40
|
}));
|
|
64
41
|
},
|
|
65
42
|
watchers() {
|
|
66
|
-
return [...watchers
|
|
43
|
+
return [...watchers];
|
|
67
44
|
}
|
|
68
45
|
};
|
|
69
46
|
}
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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/
|
|
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
|
-
|
|
404
|
-
|
|
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
|
-
|
|
417
|
-
|
|
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
|
-
|
|
422
|
-
|
|
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
|
-
|
|
427
|
-
|
|
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
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
547
|
-
}
|
|
582
|
+
endStreams = registerSentinelStreamRoutes(router, routeCtx, cfg.namespace, registry);
|
|
583
|
+
},
|
|
584
|
+
onStop: () => endStreams()
|
|
548
585
|
};
|
|
549
586
|
}
|
|
550
587
|
|
|
551
588
|
//#endregion
|
|
552
|
-
export {
|
|
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-
|
|
3
|
+
"version": "1.0.0-beta.1",
|
|
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.
|
|
32
|
+
"zod": "^4.6.7"
|
|
33
33
|
},
|
|
34
34
|
"devDependencies": {
|
|
35
|
-
"@mnmal-ai/substrate": "1.0.0-
|
|
36
|
-
"@mnmal-ai/substrate-config": "1.0.0-
|
|
35
|
+
"@mnmal-ai/substrate": "1.0.0-beta.1",
|
|
36
|
+
"@mnmal-ai/substrate-config": "1.0.0-beta.1",
|
|
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.
|
|
43
|
+
"@mnmal-ai/substrate": ">=1.0.0-alpha.19 <2.0.0"
|
|
44
44
|
},
|
|
45
45
|
"engines": {
|
|
46
|
-
"node": ">=26.
|
|
46
|
+
"node": ">=26.13.1"
|
|
47
47
|
},
|
|
48
48
|
"substrate": {
|
|
49
49
|
"tier": "coordinator",
|
package/dist/ws-route.d.ts
DELETED
|
@@ -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
|
package/dist/ws-route.d.ts.map
DELETED
|
@@ -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"}
|