@scp-dev/hub 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -593,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;
@@ -611,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 */
@@ -793,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;
@@ -842,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

@@ -2012,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,
@@ -3170,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) {
@@ -3194,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;
@@ -3386,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 };
   }
@@ -3498,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.1",
+  "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",

package/src/hub.ts

@@ -123,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
@@ -142,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 */
@@ -1431,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 */
@@ -1461,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 {
@@ -1673,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,