@scp-dev/hub 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _scp_dev_core from '@scp-dev/core';
-import { Envelope, RelayCore, CoreOptions, EndpointRow, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, EndpointView, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Verdict, JudgeModelConfig, JudgeClient, Sql, JudgePolicy, CrossAccountLink, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
+import { Envelope, RelayCore, CoreOptions, EndpointRow, PolicySubject, ScopeSubject, ScopeNode, ScopeDirection, Admission, MessageRow, EndpointView, ScopeCap, ScopeEntry, Claim, SendParams, SendResult, EndpointKind, Presence, StatusState, Verdict, JudgeModelConfig, JudgeClient, Sql, JudgePolicy, Wake, CrossAccountLink, XDelivered, XListed, ActivityRow, XRelease } from '@scp-dev/core';
 
 type RelayAuth = Envelope["from"]["auth"];
 /** a machine name: one relay host of an account */
@@ -59,6 +59,8 @@ interface MirrorView extends MirrorScope {
     presence?: Presence;
     last_seen?: string | null;
     title?: string | null;
+    /** an agent's {@link Wake}; a value this hub does not know is kept as none */
+    wake?: string | null;
     /** the handle the endpoint had before a rename: its mirror is renamed in place */
     was?: string;
 }
@@ -567,7 +569,7 @@ interface GraphNode {
     status: EndpointView["status"];
     last_seen: string | null;
     parent: string | null;
-    wake?: string | null;
+    wake?: Wake | null;
 }
 /** `spawn`: parent to child; `message`: sender to recipient, with the count and newest send in the graph's window */
 type GraphEdge = {
@@ -591,6 +593,26 @@ interface HubGraph {
 /** the default and widest window of message edges; the core keeps an hour of sender and recipient pairs */
 declare const GRAPH_MINUTES = 15;
 declare const GRAPH_MINUTES_MAX = 60;
+/** what a read-only dashboard stream sees as it happens: addresses, kinds and presence, never a body, note, summary or label */
+type DashboardEvent = {
+    type: "presence";
+    at: string;
+    machine: string | null;
+    endpoint: string;
+    presence: Presence;
+} | {
+    type: "message";
+    at: string;
+    kind: string;
+    from: string;
+    to: string[];
+} | {
+    type: "endpoints";
+    at: string;
+    machine: string;
+};
+/** a watcher's fleet event as a dashboard sees it, field by field; null for the kinds a dashboard does not stream */
+declare function dashboardEvent(event: Record<string, unknown>, at: string): DashboardEvent | null;
 interface HubSocket {
     conn: HubConn;
     send(text: string): void;
@@ -609,6 +631,8 @@ interface HubDeps {
     save(socket: HubSocket): void;
     /** structured log line, e.g. relay_action; never bodies or tokens */
     log?: (event: string, fields: Record<string, unknown>) => void;
+    /** live presence, endpoint and message metadata for a read-only dashboard; never a body */
+    dashboard?: (event: DashboardEvent) => void;
     /** overrides of {@link HUB_LIMITS}; `Infinity` disables a cap, count or byte limit, durations stay finite */
     limits?: Partial<HubLimits>;
     /** the link to other accounts' relays; without it an address of another account is not found */
@@ -791,6 +815,7 @@ declare class RelayHub {
     /** the machines of other members than the grant's, which a bridge shows under the account handle */
     private othersOf;
     private fleet;
+    private dash;
     private write;
     private save;
     private waitMs;
@@ -840,4 +865,4 @@ declare class RelayHub {
     xnotice(endpoint: string, text: string): void;
 }
 
-export { type Deliver, type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphNode, HUB_LIMITS, type HoldView, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubGraph, type HubJudgeOptions, type HubLimits, type HubRole, type HubSocket, JUDGE_LIMITS, type JudgeClientFactory, JudgeGate, type JudgeGateOptions, type JudgeLimits, type Origin as JudgeOrigin, MACHINE_NAME, type MachineRow, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint };
+export { type DashboardEvent, type Deliver, type Delivery, FederatedCore, type FederatedOptions, GRAPH_MINUTES, GRAPH_MINUTES_MAX, type GraphEdge, type GraphNode, HUB_LIMITS, type HoldView, type HubAuth, type HubConn, type HubDeps, type HubGrant, type HubGraph, type HubJudgeOptions, type HubLimits, type HubRole, type HubSocket, JUDGE_LIMITS, type JudgeClientFactory, JudgeGate, type JudgeGateOptions, type JudgeLimits, type Origin as JudgeOrigin, MACHINE_NAME, type MachineRow, type MirrorCaps, type MirrorChange, type MirrorRules, type MirrorScope, type MirrorView, type RelayAuth, RelayHub, type RemoteView, type XEndpoint, dashboardEvent };

package/dist/index.js

@@ -22,7 +22,8 @@ import {
   unreachable,
   validHandle,
   validHarness,
-  validSelector
+  validSelector,
+  WAKES
 } from "@scp-dev/core";
 var MACHINE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 var REMOTE = /^[a-z0-9][a-z0-9._-]{0,63}\/([a-z0-9][a-z0-9._-]{0,62})?$/;
@@ -1283,7 +1284,7 @@ var FederatedCore = class extends RelayCore {
     const was = this.view(before);
     const presence = was.presence !== view.presence;
     const status = before.status_state !== after.status_state || before.status_note !== after.status_note;
-    const other = ["kind", "harness", "model", "cwd", "labels", "title", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"].some(
+    const other = ["kind", "harness", "model", "cwd", "labels", "title", "wake", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"].some(
       (field) => before[field] !== after[field]
     );
     return presence || status || other ? { view, added: false, presence, status } : null;
@@ -1351,6 +1352,7 @@ var FederatedCore = class extends RelayCore {
       rules: rules === void 0 ? row.rules : rules && (rules.in || rules.out) ? JSON.stringify(rules) : null,
       caps,
       title: scope.title !== void 0 ? scope.title : fresh ? null : row.title,
+      wake: scope.wake !== void 0 ? scope.wake : fresh ? null : row.wake,
       incarnation: scope.incarnation ?? row.incarnation
     };
   }
@@ -1504,6 +1506,7 @@ function parseScope(view) {
     throw new RelayError("too_large", `an endpoint's rules and caps are more than ${SCOPE_BYTES} bytes`);
   if (given("title"))
     out.title = view.title === null ? null : cleanText(typeof view.title === "string" ? view.title.replace(/\s+/g, " ") : view.title, "title", 64) || null;
+  if (given("wake")) out.wake = typeof view.wake === "string" && view.wake !== "none" && WAKES.includes(view.wake) ? view.wake : null;
   if (given("incarnation")) {
     if (view.incarnation !== null && (typeof view.incarnation !== "string" || !INCARNATION.test(view.incarnation))) throw bad("incarnation");
     out.incarnation = view.incarnation ?? null;
@@ -2009,6 +2012,20 @@ function heldResult(id, params) {
 // src/hub.ts
 var GRAPH_MINUTES = 15;
 var GRAPH_MINUTES_MAX = 60;
+var str = (v) => typeof v === "string" ? v : null;
+function dashboardEvent(event, at) {
+  if (event.type === "message") {
+    const from = str(event.from);
+    const to = Array.isArray(event.to) ? event.to.filter((a) => typeof a === "string") : [];
+    return from && to.length ? { type: "message", at, kind: str(event.kind) ?? "message", from, to } : null;
+  }
+  if (event.type === "presence") {
+    const endpoint = str(event.endpoint);
+    const presence = event.presence === "online" || event.presence === "idle" || event.presence === "offline" ? event.presence : null;
+    return endpoint && presence ? { type: "presence", at, machine: str(event.machine), endpoint, presence } : null;
+  }
+  return null;
+}
 var HUB_LIMITS = {
   machines: 16,
   endpoints: 512,
@@ -3167,6 +3184,7 @@ var RelayHub = class _RelayHub {
         this.fleet({ type: "presence", machine, endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels });
       if (change.status && !change.added) this.fleet({ type: "status", machine, endpoint: view.address, status: view.status });
     }
+    if (full || changes.some((c) => c.added || c.was !== void 0)) this.dash({ type: "endpoints", at: new Date(this.now()).toISOString(), machine });
   }
   /** a direct client's endpoint changed: the other bridges mirror it */
   announceEndpoint(endpoint) {
@@ -3191,6 +3209,15 @@ var RelayHub = class _RelayHub {
   fleet(event) {
     const at = new Date(this.now()).toISOString();
     for (const socket of this.deps.sockets()) if (socket.conn.watching) this.write(socket, { jsonrpc: "2.0", method: "fleet", params: { at, ...event } });
+    const dash = this.deps.dashboard ? dashboardEvent(event, at) : null;
+    if (dash) this.dash(dash);
+  }
+  dash(event) {
+    try {
+      this.deps.dashboard?.(event);
+    } catch {
+      this.deps.log?.("relay_dashboard_failed", { account: this.account });
+    }
   }
   write(socket, value) {
     if (this.gone.has(socket.conn.id)) return;
@@ -3383,6 +3410,7 @@ var RelayHub = class _RelayHub {
     });
     this.stored = null;
     this.toBridges(name, { machine: name, endpoints: [], full: true });
+    this.dash({ type: "endpoints", at: new Date(this.now()).toISOString(), machine: name });
     this.deps.log?.("relay_action", { account: this.account, machine: name, method: "machine_release", code: "ok" });
     return { removed: name, endpoints: dropped };
   }
@@ -3495,5 +3523,6 @@ export {
   JUDGE_LIMITS,
   JudgeGate,
   MACHINE_NAME,
-  RelayHub
+  RelayHub,
+  dashboardEvent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scp-dev/hub",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Swarm Communication Protocol federation and account hub: mirrored endpoints across machines, bridges, direct clients and cross-account delivery.",
   "license": "Apache-2.0",
   "homepage": "https://scp.dev",
@@ -29,7 +29,7 @@
     "typecheck": "tsc -p ."
   },
   "dependencies": {
-    "@scp-dev/core": "0.1.3"
+    "@scp-dev/core": "0.1.4"
   },
   "devDependencies": {
     "tsup": "^8.5.1"

package/src/federation.ts

@@ -43,6 +43,8 @@ import {
   validHandle,
   validHarness,
   validSelector,
+  type Wake,
+  WAKES,
 } from "@scp-dev/core"
 
 export type RelayAuth = Envelope["from"]["auth"]
@@ -121,6 +123,8 @@ export interface MirrorView extends MirrorScope {
   presence?: Presence
   last_seen?: string | null
   title?: string | null
+  /** an agent's {@link Wake}; a value this hub does not know is kept as none */
+  wake?: string | null
   /** the handle the endpoint had before a rename: its mirror is renamed in place */
   was?: string
 }
@@ -142,6 +146,7 @@ interface ParsedScope {
   rules?: MirrorRules | null
   caps?: ScopeCaps | null
   title?: string | null
+  wake?: Wake | null
   incarnation?: string | null
 }
 
@@ -1609,7 +1614,7 @@ export class FederatedCore extends RelayCore {
     const was = this.view(before)
     const presence = was.presence !== view.presence
     const status = before.status_state !== after.status_state || before.status_note !== after.status_note
-    const other = (["kind", "harness", "model", "cwd", "labels", "title", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"] as const).some(
+    const other = (["kind", "harness", "model", "cwd", "labels", "title", "wake", "tree", "parent_ep", "depth", "rules", "caps", "incarnation"] as const).some(
       (field) => before[field] !== (after as FederatedRow)[field],
     )
     return presence || status || other ? { view, added: false, presence, status } : null
@@ -1682,6 +1687,7 @@ export class FederatedCore extends RelayCore {
       rules: rules === undefined ? row.rules : rules && (rules.in || rules.out) ? JSON.stringify(rules) : null,
       caps,
       title: scope.title !== undefined ? scope.title : fresh ? null : row.title,
+      wake: scope.wake !== undefined ? scope.wake : fresh ? null : row.wake,
       incarnation: scope.incarnation ?? row.incarnation,
     }
   }
@@ -1860,6 +1866,7 @@ function parseScope(view: Partial<MirrorView>): ParsedScope {
     throw new RelayError("too_large", `an endpoint's rules and caps are more than ${SCOPE_BYTES} bytes`)
   if (given("title"))
     out.title = view.title === null ? null : cleanText(typeof view.title === "string" ? view.title.replace(/\s+/g, " ") : view.title, "title", 64) || null
+  if (given("wake")) out.wake = typeof view.wake === "string" && view.wake !== "none" && WAKES.includes(view.wake as Wake) ? (view.wake as Wake) : null
   if (given("incarnation")) {
     if (view.incarnation !== null && (typeof view.incarnation !== "string" || !INCARNATION.test(view.incarnation))) throw bad("incarnation")
     out.incarnation = view.incarnation ?? null

package/src/hub.ts

@@ -38,6 +38,7 @@ import {
   SYSTEM_HANDLE,
   sameSecret,
   untilTomorrow,
+  type Wake,
   type XContact,
   XCounters,
   type XDelivered,
@@ -104,7 +105,7 @@ export interface GraphNode {
   status: EndpointView["status"]
   last_seen: string | null
   parent: string | null
-  wake?: string | null
+  wake?: Wake | null
 }
 
 /** `spawn`: parent to child; `message`: sender to recipient, with the count and newest send in the graph's window */
@@ -122,6 +123,29 @@ export interface HubGraph {
 export const GRAPH_MINUTES = 15
 export const GRAPH_MINUTES_MAX = 60
 
+/** what a read-only dashboard stream sees as it happens: addresses, kinds and presence, never a body, note, summary or label */
+export type DashboardEvent =
+  | { type: "presence"; at: string; machine: string | null; endpoint: string; presence: Presence }
+  | { type: "message"; at: string; kind: string; from: string; to: string[] }
+  | { type: "endpoints"; at: string; machine: string }
+
+const str = (v: unknown): string | null => (typeof v === "string" ? v : null)
+
+/** a watcher's fleet event as a dashboard sees it, field by field; null for the kinds a dashboard does not stream */
+export function dashboardEvent(event: Record<string, unknown>, at: string): DashboardEvent | null {
+  if (event.type === "message") {
+    const from = str(event.from)
+    const to = Array.isArray(event.to) ? event.to.filter((a): a is string => typeof a === "string") : []
+    return from && to.length ? { type: "message", at, kind: str(event.kind) ?? "message", from, to } : null
+  }
+  if (event.type === "presence") {
+    const endpoint = str(event.endpoint)
+    const presence = event.presence === "online" || event.presence === "idle" || event.presence === "offline" ? event.presence : null
+    return endpoint && presence ? { type: "presence", at, machine: str(event.machine), endpoint, presence } : null
+  }
+  return null
+}
+
 export interface HubSocket {
   conn: HubConn
   send(text: string): void
@@ -141,6 +165,8 @@ export interface HubDeps {
   save(socket: HubSocket): void
   /** structured log line, e.g. relay_action; never bodies or tokens */
   log?: (event: string, fields: Record<string, unknown>) => void
+  /** live presence, endpoint and message metadata for a read-only dashboard; never a body */
+  dashboard?: (event: DashboardEvent) => void
   /** overrides of {@link HUB_LIMITS}; `Infinity` disables a cap, count or byte limit, durations stay finite */
   limits?: Partial<HubLimits>
   /** the link to other accounts' relays; without it an address of another account is not found */
@@ -1430,6 +1456,7 @@ export class RelayHub {
         this.fleet({ type: "presence", machine, endpoint: view.address, presence: view.presence, harness: view.harness, labels: view.labels })
       if (change.status && !change.added) this.fleet({ type: "status", machine, endpoint: view.address, status: view.status })
     }
+    if (full || changes.some((c) => c.added || c.was !== undefined)) this.dash({ type: "endpoints", at: new Date(this.now()).toISOString(), machine })
   }
 
   /** a direct client's endpoint changed: the other bridges mirror it */
@@ -1460,6 +1487,16 @@ export class RelayHub {
   private fleet(event: Record<string, unknown>): void {
     const at = new Date(this.now()).toISOString()
     for (const socket of this.deps.sockets()) if (socket.conn.watching) this.write(socket, { jsonrpc: "2.0", method: "fleet", params: { at, ...event } })
+    const dash = this.deps.dashboard ? dashboardEvent(event, at) : null
+    if (dash) this.dash(dash)
+  }
+
+  private dash(event: DashboardEvent): void {
+    try {
+      this.deps.dashboard?.(event)
+    } catch {
+      this.deps.log?.("relay_dashboard_failed", { account: this.account })
+    }
   }
 
   private write(socket: HubSocket, value: unknown): void {
@@ -1593,7 +1630,7 @@ export class RelayHub {
   /** a read-only graph for a dashboard: listed endpoints, spawn edges among them, and message counts per sender and recipient; never a body */
   graph(minutes = GRAPH_MINUTES): HubGraph {
     const window = Math.min(Math.max(1, Math.floor(Number.isFinite(minutes) ? minutes : GRAPH_MINUTES)), GRAPH_MINUTES_MAX)
-    const endpoints = this.relay.list() as (EndpointView & { wake?: string | null })[]
+    const endpoints = this.relay.list()
     const byId = new Map(endpoints.map((e) => [e.id, e.address]))
     const listed = new Set(byId.values())
     const nodes: GraphNode[] = endpoints.map((e) => ({
@@ -1672,6 +1709,7 @@ export class RelayHub {
     })
     this.stored = null
     this.toBridges(name, { machine: name, endpoints: [], full: true })
+    this.dash({ type: "endpoints", at: new Date(this.now()).toISOString(), machine: name })
     this.deps.log?.("relay_action", { account: this.account, machine: name, method: "machine_release", code: "ok" })
     return { removed: name, endpoints: dropped }
   }

package/src/index.ts

@@ -13,6 +13,8 @@ export {
   type XEndpoint,
 } from "./federation"
 export {
+  type DashboardEvent,
+  dashboardEvent,
   GRAPH_MINUTES,
   GRAPH_MINUTES_MAX,
   type GraphEdge,