@onlyne/node-host 3.0.0 → 3.1.0

package/README.md

@@ -20,6 +20,28 @@ library is not allowed to do.
 30 seconds, and on a terminal hands the operator the trust screen. Discovery only adds
 candidates: a key exchange still needs both fingerprints confirmed.
 
+`startNodeHost({ status })` accepts an async callback that returns gateway-specific display lines.
+The terminal refreshes these lines with its trust view once per second. Hosts use them for connection
+state, server tool counts, scheduled tasks, and delivery queues. `ONLYNE_NO_TUI=1` keeps JSON logging
+and skips terminal startup.
+
+## Log levels
+
+`createLogger` returns one callable line writer plus the other three levels: calling it, and
+`logger.log`, write `info`, so every existing host line keeps its level. `ONLYNE_LOG_LEVEL` selects
+the threshold, default `info`; a fourth argument overrides it for one process. Every level that
+passes goes to the ring the TUI renders and to the file sink, and each JSON line names its `level`.
+
+| Level | Meaning | Examples |
+|---|---|---|
+| `debug` | Per-pass work and protocol internals, off by default | reconcile pulls, replays, injected-context details |
+| `info` | State transitions and business milestones, one line each | `onlyne.tui.ready`, `connector.state`, a committed send |
+| `warn` | Degraded but running | reconnects, retries, an unconfirmed delivery, a rate-limit hit, a failed reconcile pull |
+| `error` | The operation failed and the caller lost something | a received event that could not be stored |
+
+A sink that is a plain function rather than a `createLogger` result records every line it is
+handed: it has no threshold of its own, so filtering belongs to the host that built it.
+
 ## Language
 
 `resolveLocale` reads an explicit value first, then `ONLYNE_LANG`, then `LC_ALL` or `LANG`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlyne/node-host",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Shared Onlyne node host pieces: identity keys, DNS-SD discovery, the gateway trust terminal, and message catalogs",
   "type": "module",
   "main": "./src/index.ts",
@@ -25,7 +25,7 @@
   "files": ["src", "README.md", "LICENSE"],
   "scripts": { "check": "tsc --noEmit" },
   "dependencies": {
-    "@onlyne/lib": "^3.0.0",
+    "@onlyne/lib": "^3.1.0",
     "bonjour-service": "^1.4.4"
   },
   "devDependencies": { "@types/bun": "^1.3.0", "typescript": "^5.9.0" }

package/src/index.ts

@@ -1,13 +1,13 @@
 import type { OnlyneNode, ServiceDescription } from '@onlyne/lib';
-import { NetworkDiscovery } from './network.js';
-import type { LogRing } from './log.js';
-import { GatewayTui } from './tui.js';
+import { NetworkDiscovery } from './network.ts';
+import type { LogRing } from './log.ts';
+import { GatewayTui } from './tui.ts';
 
-export { createNodeKey } from './keys.js';
-export { NetworkDiscovery } from './network.js';
-export { createLogger } from './log.js';
-export type { GatewayLogger, LogRing } from './log.js';
-export { GatewayTui } from './tui.js';
+export { createNodeKey } from './keys.ts';
+export { NetworkDiscovery } from './network.ts';
+export { createLogger, leveled, resolveLogLevel } from './log.ts';
+export type { GatewayLogger, LeveledLog, LogLevel, LogLine, LogRing, LogSink } from './log.ts';
+export { GatewayTui } from './tui.ts';
 
 export interface NodeHostOptions {
   node: OnlyneNode;
@@ -18,6 +18,8 @@ export interface NodeHostOptions {
   ring?: LogRing;
   /** Defaults to the terminal surface when both ends of the process are a TTY. */
   interactive?: boolean;
+  /** Gateway-specific state rendered with the trust terminal. */
+  status?: () => Promise<string[]>;
   log(message: string, fields?: Record<string, unknown>): void;
 }
 
@@ -58,7 +60,7 @@ export async function startNodeHost(options: NodeHostOptions): Promise<{ close()
   // `ONLYNE_NO_TUI=1` keeps the plain JSON log on stdout, for a pipe or a screen a TUI would spoil.
   const interactive = (options.interactive ?? true) && process.env.ONLYNE_NO_TUI !== '1';
   if (interactive && options.ring !== undefined && process.stdin.isTTY && process.stdout.isTTY) {
-    const surface = new GatewayTui(node, options.ring, options.endpoint);
+    const surface = new GatewayTui(node, options.ring, options.endpoint, undefined, options.status);
     try {
       log('onlyne.tui.starting');
       await surface.start();

package/src/log.ts

@@ -6,16 +6,61 @@ export interface LogRing {
   tail(count: number): string[];
 }
 
-export interface GatewayLogger {
-  log(message: string, fields?: Record<string, unknown>): void;
-  readonly ring: LogRing;
+/** The four levels of the convention: `debug` loops, `info` milestones, `warn` degradation, `error` loss. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/** One JSON line about to be written. */
+export type LogLine = (message: string, fields?: Record<string, unknown>) => void;
+
+/**
+ * A host's log sink. Calling it writes `info`, the level every existing call site uses; a sink
+ * that also carries `debug`/`warn`/`error` records those levels where the host put them.
+ */
+export type LogSink = LogLine & {
+  readonly debug?: LogLine;
+  readonly warn?: LogLine;
+  readonly error?: LogLine;
+};
+
+export type LeveledLog = LogLine & {
+  log: LogLine;
+  debug: LogLine;
+  warn: LogLine;
+  error: LogLine;
+};
+
+export type GatewayLogger = LeveledLog & { readonly level: LogLevel; readonly ring: LogRing };
+
+const ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/** `ONLYNE_LOG_LEVEL` selects a level; anything unrecognised (and unset) keeps `info`. */
+export function resolveLogLevel(value: string | undefined): LogLevel {
+  return value === 'debug' || value === 'warn' || value === 'error' ? value : 'info';
+}
+
+/**
+ * Normalizes a sink to the four entry points. A sink without level methods records every line
+ * it is handed: it cannot filter, so the host's own store decides what the level means.
+ */
+export function leveled(sink?: LogSink): LeveledLog {
+  const call: LogLine = (message, fields) => { if (typeof sink === 'function') sink(message, fields); };
+  return Object.assign(call, {
+    log: call,
+    debug: sink?.debug ?? call,
+    warn: sink?.warn ?? call,
+    error: sink?.error ?? call,
+  });
 }
 
 /**
  * The gateway logs JSON lines. Under the TUI those lines would corrupt the alternate
  * screen, so they go to a ring the TUI renders instead; without a TTY they stay on stdout.
+ * The returned function is the `info` line — `logger.log` is the same entry point — and
+ * `debug`, `warn`, `error` are the other levels of the same convention.
  */
-export function createLogger(toStdout: boolean, capacity = 200, file?: string): GatewayLogger {
+export function createLogger(toStdout: boolean, capacity = 200, file?: string, level?: LogLevel): GatewayLogger {
+  const selected = level ?? resolveLogLevel(process.env.ONLYNE_LOG_LEVEL);
+  const threshold = ORDER[selected];
   // One entry per distinct message: a gateway that retries every five seconds would otherwise
   // fill the pane with the same line and hide everything else.
   const lines: Array<{ key: string; line: string; count: number }> = [];
@@ -35,18 +80,24 @@ export function createLogger(toStdout: boolean, capacity = 200, file?: string):
         .map(entry => (entry.count === 1 ? entry.line : `${entry.line} ×${entry.count}`));
     },
   };
-  return {
-    ring,
-    log(message: string, fields?: Record<string, unknown>): void {
-      const line = JSON.stringify({ at: new Date().toISOString(), message, ...fields });
-      if (toStdout) console.log(line);
-      else ring.push(`${message}|${JSON.stringify(fields ?? {})}`, line);
-      // The TUI owns the screen, so the durable record is the file; without one the line would
-      // exist only in the ring and vanish with the process.
-      if (file !== undefined) {
-        try { appendFileSync(file, `${line}\n`); } catch { /* a full disk must not stop the gateway */ }
-      }
-    },
+  const emit = (at: LogLevel, message: string, fields?: Record<string, unknown>): void => {
+    if (ORDER[at] < threshold) return;
+    const line = JSON.stringify({ at: new Date().toISOString(), level: at, message, ...fields });
+    if (toStdout) console.log(line);
+    else ring.push(`${at}|${message}|${JSON.stringify(fields ?? {})}`, line);
+    // The TUI owns the screen, so the durable record is the file; without one the line would
+    // exist only in the ring and vanish with the process.
+    if (file !== undefined) {
+      try { appendFileSync(file, `${line}\n`); } catch { /* a full disk must not stop the gateway */ }
+    }
   };
+  const info: LogLine = (message, fields) => emit('info', message, fields);
+  return Object.assign(info, {
+    level: selected,
+    log: info,
+    debug: (message: string, fields?: Record<string, unknown>) => emit('debug', message, fields),
+    warn: (message: string, fields?: Record<string, unknown>) => emit('warn', message, fields),
+    error: (message: string, fields?: Record<string, unknown>) => emit('error', message, fields),
+    ring,
+  });
 }
-

package/src/tui-text.ts

@@ -1,4 +1,4 @@
-import { createTranslator } from './i18n.js';
+import { createTranslator } from './i18n.ts';
 
 const en = {
   'title': 'Onlyne gateway · {actor} · {endpoint}',

package/src/tui.ts

@@ -1,6 +1,6 @@
 import { trustPhase, type KeyExchange, type OnlyneNode, type TrustPhase } from '@onlyne/lib';
-import type { LogRing } from './log.js';
-import { t, type TuiTextKey } from './tui-text.js';
+import type { LogRing } from './log.ts';
+import { t, type TuiTextKey } from './tui-text.ts';
 
 /** One peer as the terminal shows it: a discovery address plus whatever the trust table knows. */
 interface Row {
@@ -46,12 +46,14 @@ export class GatewayTui {
   #busy = false;
   #closed = false;
   #refreshTimer?: ReturnType<typeof setInterval>;
+  #statusLines: string[] = [];
 
   constructor(
     private readonly node: OnlyneNode,
     private readonly ring: LogRing,
     private readonly endpoint: string,
     private readonly onChange: () => void = () => undefined,
+    private readonly status?: () => Promise<string[]>,
   ) {}
 
   async start(): Promise<void> {
@@ -119,10 +121,12 @@ export class GatewayTui {
   async #refresh(): Promise<void> {
     if (this.#closed) return;
     try {
-      const [trust, records] = await Promise.all([
+      const [trust, records, status] = await Promise.all([
         this.node.trust.list(this.node.auth),
         this.node.discovery.listRecords(),
+        this.status?.() ?? [],
       ]);
+      this.#statusLines = status;
       const handlers = new Map<string, string[]>();
       const resources = await this.node.resources.list(this.node.auth, { page_size: 100 });
       for (const resource of resources.items) {
@@ -231,6 +235,13 @@ export class GatewayTui {
     push(t('title', { actor: this.node.auth.actor, endpoint: this.endpoint }));
     push(rule(width));
 
+    if (this.#statusLines.length > 0) {
+      const budget = Math.max(3, Math.floor(height / 3));
+      for (const line of this.#statusLines.slice(0, budget)) push(line);
+      if (this.#statusLines.length > budget) push('…');
+      push(rule(width));
+    }
+
     const peerHeader = this.#rows.length === 0 ? t('peers.none') : t('peers.count', { count: this.#rows.length });
     push(peerHeader);
     for (const [index, row] of this.#rows.entries()) {