browsermesh-kernel 0.1.0

package/src/rng.mjs

@@ -0,0 +1,76 @@
+/**
+ * RNG — cryptographic and deterministic random number generation.
+ *
+ * Provides crypto-quality randomness by default, with a seeded mode using
+ * xorshift128+ for deterministic replay in tests and chaos engineering.
+ *
+ * @module rng
+ */
+
+/**
+ * Random number generator with crypto and seeded modes.
+ */
+export class RNG {
+  #getFn;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {function(number): Uint8Array} [opts.getFn] - Custom byte source.
+   */
+  constructor({ getFn } = {}) {
+    this.#getFn = getFn || ((n) => {
+      const buf = new Uint8Array(n);
+      crypto.getRandomValues(buf);
+      return buf;
+    });
+  }
+
+  /**
+   * Get `n` random bytes.
+   *
+   * @param {number} n - Number of bytes to generate.
+   * @returns {Uint8Array} Random bytes.
+   */
+  get(n) {
+    return this.#getFn(n);
+  }
+
+  /**
+   * Create a deterministic seeded RNG using xorshift128+.
+   * The same seed always produces the same sequence of bytes.
+   *
+   * @param {number} seed - The seed value (integer).
+   * @returns {RNG}
+   */
+  static seeded(seed) {
+    // xorshift128+ state
+    let s0 = seed >>> 0 || 1;
+    let s1 = (seed * 2654435761) >>> 0 || 1;
+
+    function next() {
+      let x = s0;
+      const y = s1;
+      s0 = y;
+      x ^= (x << 23) >>> 0;
+      x ^= x >>> 17;
+      x ^= y;
+      x ^= y >>> 26;
+      s1 = x >>> 0;
+      return (s0 + s1) >>> 0;
+    }
+
+    return new RNG({
+      getFn(n) {
+        const buf = new Uint8Array(n);
+        for (let i = 0; i < n; i += 4) {
+          const val = next();
+          buf[i] = val & 0xff;
+          if (i + 1 < n) buf[i + 1] = (val >>> 8) & 0xff;
+          if (i + 2 < n) buf[i + 2] = (val >>> 16) & 0xff;
+          if (i + 3 < n) buf[i + 3] = (val >>> 24) & 0xff;
+        }
+        return buf;
+      },
+    });
+  }
+}

package/src/service-registry.mjs

@@ -0,0 +1,167 @@
+/**
+ * ServiceRegistry — convention-based svc:// service registry.
+ *
+ * Manages named services with registration, lookup, and lifecycle callbacks.
+ * Services are identified by string names (convention: `svc://name`).
+ *
+ * @module service-registry
+ */
+
+import { AlreadyRegisteredError, NotFoundError } from './errors.mjs';
+
+/**
+ * Registry for named services with lifecycle event callbacks.
+ */
+export class ServiceRegistry {
+  #services = new Map();
+  #onRegisterCbs = [];
+  #onUnregisterCbs = [];
+  #onLookupMissCbs = [];
+
+  /**
+   * Register a named service.
+   *
+   * @param {string} name - Service name.
+   * @param {*} listener - The service listener/handler.
+   * @param {Object} [opts={}]
+   * @param {Object} [opts.metadata] - Arbitrary metadata about the service.
+   * @param {string} [opts.owner] - Owner identifier.
+   * @throws {AlreadyRegisteredError} If the name is already registered.
+   */
+  register(name, listener, { metadata, owner } = {}) {
+    if (this.#services.has(name)) {
+      throw new AlreadyRegisteredError(name);
+    }
+    const entry = { name, listener, metadata: metadata || {}, owner: owner || null };
+    this.#services.set(name, entry);
+    for (const cb of this.#onRegisterCbs) {
+      try { cb(entry); } catch (_) {}
+    }
+  }
+
+  /**
+   * Unregister a named service.
+   *
+   * @param {string} name - Service name.
+   * @throws {NotFoundError} If the name is not registered.
+   */
+  unregister(name) {
+    const entry = this.#services.get(name);
+    if (!entry) throw new NotFoundError(name);
+    this.#services.delete(name);
+    for (const cb of this.#onUnregisterCbs) {
+      try { cb(entry); } catch (_) {}
+    }
+  }
+
+  /**
+   * Look up a service by name. If not found locally, calls onLookupMiss hooks
+   * which may resolve the service from remote sources.
+   *
+   * @param {string} name - Service name.
+   * @returns {Promise<{ name: string, listener: *, metadata: Object, owner: string|null }>}
+   * @throws {NotFoundError} If the service is not found (locally or via hooks).
+   */
+  async lookup(name) {
+    const entry = this.#services.get(name);
+    if (entry) return entry;
+
+    // Try lookup miss hooks (e.g., distributed service resolution)
+    for (const cb of this.#onLookupMissCbs) {
+      try {
+        const result = await cb(name);
+        if (result) return result;
+      } catch (_) {}
+    }
+
+    throw new NotFoundError(name);
+  }
+
+  /**
+   * Check whether a service is registered.
+   *
+   * @param {string} name - Service name.
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.#services.has(name);
+  }
+
+  /**
+   * List all registered service names.
+   *
+   * @returns {string[]}
+   */
+  list() {
+    return [...this.#services.keys()];
+  }
+
+  /**
+   * Register a callback for service registration events.
+   *
+   * @param {function(Object): void} cb - Callback receiving the service entry.
+   * @returns {function(): void} Unsubscribe function.
+   */
+  onRegister(cb) {
+    this.#onRegisterCbs.push(cb);
+    return () => {
+      const idx = this.#onRegisterCbs.indexOf(cb);
+      if (idx >= 0) this.#onRegisterCbs.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Register a callback for service unregistration events.
+   *
+   * @param {function(Object): void} cb - Callback receiving the service entry.
+   * @returns {function(): void} Unsubscribe function.
+   */
+  onUnregister(cb) {
+    this.#onUnregisterCbs.push(cb);
+    return () => {
+      const idx = this.#onUnregisterCbs.indexOf(cb);
+      if (idx >= 0) this.#onUnregisterCbs.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Register a hook called when lookup() misses locally.
+   * Hook receives the service name and may return a service entry
+   * or null to let the next hook try.
+   *
+   * @param {function(string): Promise<Object|null>} cb - Lookup miss handler.
+   * @returns {function(): void} Unsubscribe function.
+   */
+  onLookupMiss(cb) {
+    this.#onLookupMissCbs.push(cb);
+    return () => {
+      const idx = this.#onLookupMissCbs.indexOf(cb);
+      if (idx >= 0) this.#onLookupMissCbs.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Register a remote service entry (for distributed service awareness).
+   *
+   * @param {string} name - Service name.
+   * @param {string} nodeId - Remote node identifier.
+   * @param {Object} [metadata={}] - Metadata about the remote service.
+   * @throws {AlreadyRegisteredError} If the name is already registered.
+   */
+  registerRemote(name, nodeId, metadata = {}) {
+    this.register(name, null, {
+      metadata: { ...metadata, remote: true, nodeId },
+      owner: nodeId,
+    });
+  }
+
+  /**
+   * Remove all registered services and callbacks.
+   */
+  clear() {
+    this.#services.clear();
+    this.#onRegisterCbs.length = 0;
+    this.#onUnregisterCbs.length = 0;
+    this.#onLookupMissCbs.length = 0;
+  }
+}

package/src/signal.mjs

@@ -0,0 +1,122 @@
+/**
+ * Signal — cancellation and shutdown via AbortController.
+ *
+ * Provides named signals (TERM, INT, HUP) with AbortSignal integration
+ * for cooperative cancellation of long-running operations.
+ *
+ * @module signal
+ */
+
+/**
+ * Signal name constants.
+ */
+export const SIGNAL = Object.freeze({
+  TERM: 'TERM',
+  INT: 'INT',
+  HUP: 'HUP',
+});
+
+/**
+ * Signal controller providing named signal dispatch and AbortSignal integration.
+ */
+export class SignalController {
+  #controllers = new Map();
+  #listeners = new Map();
+  #fired = new Set();
+
+  /**
+   * Fire a named signal. All registered callbacks and AbortSignals for
+   * this signal name are triggered.
+   *
+   * @param {string} name - Signal name (e.g. SIGNAL.TERM).
+   */
+  signal(name) {
+    this.#fired.add(name);
+
+    // Fire listeners
+    const cbs = this.#listeners.get(name);
+    if (cbs) {
+      for (const cb of [...cbs]) {
+        try { cb(); } catch (_) {}
+      }
+    }
+
+    // Abort the associated controller
+    const ctrl = this.#controllers.get(name);
+    if (ctrl && !ctrl.signal.aborted) {
+      ctrl.abort();
+    }
+  }
+
+  /**
+   * Register a callback for a named signal.
+   *
+   * @param {string} name - Signal name.
+   * @param {function(): void} cb - Callback.
+   * @returns {function(): void} Unsubscribe function.
+   */
+  onSignal(name, cb) {
+    if (!this.#listeners.has(name)) {
+      this.#listeners.set(name, []);
+    }
+    this.#listeners.get(name).push(cb);
+    return () => {
+      const arr = this.#listeners.get(name);
+      if (!arr) return;
+      const idx = arr.indexOf(cb);
+      if (idx >= 0) arr.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Get an AbortSignal that aborts when the named signal fires.
+   *
+   * @param {string} name - Signal name.
+   * @returns {AbortSignal}
+   */
+  abortSignal(name) {
+    if (!this.#controllers.has(name)) {
+      this.#controllers.set(name, new AbortController());
+    }
+    const ctrl = this.#controllers.get(name);
+    // If already fired, abort immediately
+    if (this.#fired.has(name) && !ctrl.signal.aborted) {
+      ctrl.abort();
+    }
+    return ctrl.signal;
+  }
+
+  /**
+   * Check whether a signal has been fired.
+   *
+   * @param {string} name - Signal name.
+   * @returns {boolean}
+   */
+  hasFired(name) {
+    return this.#fired.has(name);
+  }
+
+  /**
+   * Reset a signal so it can be fired again.
+   *
+   * @param {string} name - Signal name.
+   */
+  reset(name) {
+    this.#fired.delete(name);
+    // Replace the AbortController so a fresh signal can be obtained
+    this.#controllers.delete(name);
+  }
+
+  /**
+   * Get a composite AbortSignal that aborts on either TERM or INT.
+   * Useful for graceful shutdown scenarios.
+   *
+   * @returns {AbortSignal}
+   */
+  get shutdownSignal() {
+    return AbortSignal.any([
+      this.abortSignal(SIGNAL.TERM),
+      this.abortSignal(SIGNAL.INT),
+    ]);
+  }
+}

package/src/stdio.mjs

@@ -0,0 +1,62 @@
+/**
+ * Stdio — standard I/O streams as ByteStreams.
+ *
+ * Provides stdin, stdout, stderr as ByteStream-compatible objects with
+ * convenience methods for text output.
+ *
+ * @module stdio
+ */
+
+import { devNull } from './byte-stream.mjs';
+
+const encoder = new TextEncoder();
+
+/**
+ * Standard I/O container wrapping ByteStream-compatible streams.
+ */
+export class Stdio {
+  #stdin;
+  #stdout;
+  #stderr;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {Object} [opts.stdin] - Input ByteStream (defaults to devNull).
+   * @param {Object} [opts.stdout] - Output ByteStream (defaults to devNull).
+   * @param {Object} [opts.stderr] - Error ByteStream (defaults to devNull).
+   */
+  constructor({ stdin, stdout, stderr } = {}) {
+    this.#stdin = stdin || devNull();
+    this.#stdout = stdout || devNull();
+    this.#stderr = stderr || devNull();
+  }
+
+  /** Standard input stream. */
+  get stdin() { return this.#stdin; }
+
+  /** Standard output stream. */
+  get stdout() { return this.#stdout; }
+
+  /** Standard error stream. */
+  get stderr() { return this.#stderr; }
+
+  /**
+   * Write text to stdout (without trailing newline).
+   *
+   * @param {string} text - Text to write.
+   * @returns {Promise<void>}
+   */
+  async print(text) {
+    await this.#stdout.write(encoder.encode(text));
+  }
+
+  /**
+   * Write text to stdout with a trailing newline.
+   *
+   * @param {string} text - Text to write.
+   * @returns {Promise<void>}
+   */
+  async println(text) {
+    await this.#stdout.write(encoder.encode(text + '\n'));
+  }
+}

package/src/tracer.mjs

@@ -0,0 +1,117 @@
+/**
+ * Tracer — structured event tracing with ring buffer and async iteration.
+ *
+ * Events are auto-stamped with ID and timestamp. A ring buffer with
+ * evict-half strategy provides smooth degradation when capacity is exceeded.
+ * Multiple consumers each get independent AsyncIterables.
+ *
+ * @module tracer
+ */
+
+import { KERNEL_DEFAULTS } from './constants.mjs';
+
+/**
+ * Structured event tracer with ring buffer storage and async iteration.
+ */
+export class Tracer {
+  #events = [];
+  #counter = 0;
+  #capacity;
+  #clock;
+  #waiters = [];
+  #enabled = true;
+
+  /**
+   * @param {Object} [opts={}]
+   * @param {number} [opts.capacity=1024] - Maximum events in the ring buffer.
+   * @param {Object} [opts.clock] - Clock instance with `nowMonotonic()`. Falls back to performance.now().
+   */
+  constructor({ capacity = KERNEL_DEFAULTS.DEFAULT_TRACER_CAPACITY, clock } = {}) {
+    this.#capacity = capacity;
+    this.#clock = clock || null;
+  }
+
+  /** Whether emit() records events. Toggled via enable()/disable() (e.g. /sys/kernel/trace). */
+  get enabled() { return this.#enabled; }
+
+  /** Resume recording trace events. */
+  enable() { this.#enabled = true; }
+
+  /** Stop recording trace events. Buffered events remain readable. */
+  disable() { this.#enabled = false; }
+
+  /**
+   * Emit a trace event. The event is auto-stamped with `id` and `timestamp`.
+   * No-op while the tracer is disabled.
+   *
+   * @param {Object} event - Event data (must include `type` string).
+   */
+  emit(event) {
+    if (!this.#enabled) return;
+    const stamped = {
+      id: ++this.#counter,
+      timestamp: this.#clock ? this.#clock.nowMonotonic() : performance.now(),
+      ...event,
+    };
+
+    this.#events.push(stamped);
+
+    // Evict-half strategy when at capacity
+    if (this.#events.length > this.#capacity) {
+      const half = Math.floor(this.#capacity / 2);
+      this.#events = this.#events.slice(-half);
+    }
+
+    // Notify waiting consumers
+    for (const w of this.#waiters) {
+      w.resolve(stamped);
+    }
+    this.#waiters.length = 0;
+  }
+
+  /**
+   * Get an AsyncIterable of trace events. Each consumer gets an independent
+   * iterator that yields events as they are emitted. Does not replay past events.
+   *
+   * @returns {AsyncIterable<Object>}
+   */
+  events() {
+    const self = this;
+    let done = false;
+
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            if (done) return Promise.resolve({ value: undefined, done: true });
+            return new Promise(resolve => {
+              self.#waiters.push({
+                resolve: (event) => resolve({ value: event, done: false }),
+              });
+            });
+          },
+          return() {
+            done = true;
+            return Promise.resolve({ value: undefined, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  /**
+   * Get a snapshot of all currently buffered events.
+   *
+   * @returns {Object[]} Array of trace events.
+   */
+  snapshot() {
+    return [...this.#events];
+  }
+
+  /**
+   * Clear all buffered events.
+   */
+  clear() {
+    this.#events.length = 0;
+  }
+}