browsermesh-kernel 0.1.0

package/src/constants.mjs

@@ -0,0 +1,85 @@
+/**
+ * Kernel constants — frozen defaults, capability tags, and error codes.
+ *
+ * Defines shared configuration values, capability tags for tenant access
+ * control, and machine-readable error codes used throughout the kernel.
+ * All objects are frozen to prevent runtime mutation.
+ *
+ * @module constants
+ */
+
+/**
+ * Default configuration values used across the kernel.
+ *
+ * @property {number} MAX_RESOURCE_TABLE_SIZE - Maximum entries in a ResourceTable.
+ * @property {number} DEFAULT_STREAM_BUFFER_SIZE - Default highWaterMark for ByteStream pipes.
+ * @property {number} DEFAULT_TRACER_CAPACITY - Default ring buffer size for Tracer events.
+ * @property {number} DEFAULT_LOGGER_CAPACITY - Default ring buffer size for Logger entries.
+ */
+export const KERNEL_DEFAULTS = Object.freeze({
+  MAX_RESOURCE_TABLE_SIZE: 4096,
+  DEFAULT_STREAM_BUFFER_SIZE: 1024,
+  DEFAULT_TRACER_CAPACITY: 1024,
+  DEFAULT_LOGGER_CAPACITY: 1024,
+});
+
+/**
+ * Capability tags for tenant access control.
+ *
+ * Each tag grants access to a kernel subsystem. Pass these to
+ * {@link Kernel#createTenant} in the `capabilities` array.
+ *
+ * @property {string} NET - Access to networking subsystems (`'net'`).
+ * @property {string} FS - Access to filesystem operations (`'fs'`).
+ * @property {string} CLOCK - Access to clock/time primitives (`'clock'`).
+ * @property {string} RNG - Access to random number generation (`'rng'`).
+ * @property {string} IPC - Access to inter-process communication (`'ipc'`).
+ * @property {string} STDIO - Access to standard I/O streams (`'stdio'`).
+ * @property {string} TRACE - Access to the tracing subsystem (`'trace'`).
+ * @property {string} CHAOS - Access to chaos engineering controls (`'chaos'`).
+ * @property {string} ENV - Access to environment variables (`'env'`).
+ * @property {string} SIGNAL - Access to signal handling (`'signal'`).
+ * @property {string} MESH - Access to mesh networking and P2P operations (`'mesh'`).
+ * @property {string} PAYMENT - Access to payment channels and credit ledgers (`'payment'`).
+ * @property {string} CONSENSUS - Access to voting and consensus protocols (`'consensus'`).
+ * @property {string} ALL - Wildcard granting all capabilities (`'*'`).
+ */
+export const KERNEL_CAP = Object.freeze({
+  NET: 'net',
+  FS: 'fs',
+  CLOCK: 'clock',
+  RNG: 'rng',
+  IPC: 'ipc',
+  STDIO: 'stdio',
+  TRACE: 'trace',
+  CHAOS: 'chaos',
+  ENV: 'env',
+  SIGNAL: 'signal',
+  MESH: 'mesh',
+  PAYMENT: 'payment',
+  CONSENSUS: 'consensus',
+  ALL: '*',
+});
+
+/**
+ * Machine-readable error codes used by kernel error classes.
+ *
+ * @property {string} ENOHANDLE - Resource handle not found in table.
+ * @property {string} EHANDLETYPE - Resource handle exists but type mismatch.
+ * @property {string} ETABLEFULL - Resource table at maximum capacity.
+ * @property {string} ESTREAMCLOSED - Operation on a closed ByteStream.
+ * @property {string} ECAPDENIED - Capability not granted to tenant.
+ * @property {string} EALREADY - Name or resource already registered.
+ * @property {string} ENOTFOUND - Named resource not found.
+ * @property {string} ESIGNAL - Operation interrupted by signal.
+ */
+export const KERNEL_ERROR = Object.freeze({
+  ENOHANDLE: 'ENOHANDLE',
+  EHANDLETYPE: 'EHANDLETYPE',
+  ETABLEFULL: 'ETABLEFULL',
+  ESTREAMCLOSED: 'ESTREAMCLOSED',
+  ECAPDENIED: 'ECAPDENIED',
+  EALREADY: 'EALREADY',
+  ENOTFOUND: 'ENOTFOUND',
+  ESIGNAL: 'ESIGNAL',
+});

package/src/env.mjs

@@ -0,0 +1,56 @@
+/**
+ * Environment — per-tenant immutable key-value environment.
+ *
+ * Once constructed, the environment is frozen and cannot be modified.
+ * Provides a read-only interface similar to process.env.
+ *
+ * @module env
+ */
+
+/**
+ * Immutable environment variable store.
+ */
+export class Environment {
+  #vars;
+
+  /**
+   * @param {Record<string, string>} [vars={}] - Initial environment variables.
+   */
+  constructor(vars = {}) {
+    this.#vars = Object.freeze({ ...vars });
+  }
+
+  /**
+   * Get an environment variable by key.
+   *
+   * @param {string} key - Variable name.
+   * @returns {string|undefined} The value, or undefined if not set.
+   */
+  get(key) {
+    return this.#vars[key];
+  }
+
+  /**
+   * Check whether an environment variable exists.
+   *
+   * @param {string} key - Variable name.
+   * @returns {boolean}
+   */
+  has(key) {
+    return key in this.#vars;
+  }
+
+  /**
+   * Get a frozen copy of all environment variables.
+   *
+   * @returns {Readonly<Record<string, string>>}
+   */
+  all() {
+    return this.#vars;
+  }
+
+  /** Number of environment variables. */
+  get size() {
+    return Object.keys(this.#vars).length;
+  }
+}

package/src/errors.mjs

@@ -0,0 +1,148 @@
+/**
+ * Kernel error hierarchy.
+ *
+ * All kernel errors extend {@link KernelError}, which itself extends the native
+ * `Error`. Each subclass carries a POSIX-style `.code` string (e.g. `'ENOHANDLE'`)
+ * and additional contextual properties describing the failure.
+ *
+ * @module errors
+ */
+
+import { KERNEL_ERROR } from './constants.mjs';
+
+/**
+ * Base error class for all kernel errors.
+ *
+ * @property {string} code - Machine-readable error code.
+ */
+export class KernelError extends Error {
+  /**
+   * @param {string} message - Human-readable error description.
+   * @param {string} code - Machine-readable error code.
+   */
+  constructor(message, code) {
+    super(message);
+    this.name = 'KernelError';
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown when a resource handle is not found in the ResourceTable.
+ *
+ * @property {string} handle - The handle that was not found.
+ * @property {string} code - Always `'ENOHANDLE'`.
+ */
+export class HandleNotFoundError extends KernelError {
+  /**
+   * @param {string} handle - The handle that was not found.
+   */
+  constructor(handle) {
+    super(`Handle not found: ${handle}`, KERNEL_ERROR.ENOHANDLE);
+    this.name = 'HandleNotFoundError';
+    this.handle = handle;
+  }
+}
+
+/**
+ * Thrown when a resource handle exists but its type does not match the expected type.
+ *
+ * @property {string} handle - The handle that was accessed.
+ * @property {string} expected - The expected resource type.
+ * @property {string} actual - The actual resource type.
+ * @property {string} code - Always `'EHANDLETYPE'`.
+ */
+export class HandleTypeMismatchError extends KernelError {
+  /**
+   * @param {string} handle - The handle accessed.
+   * @param {string} expected - Expected type.
+   * @param {string} actual - Actual type.
+   */
+  constructor(handle, expected, actual) {
+    super(`Handle type mismatch: ${handle} expected ${expected}, got ${actual}`, KERNEL_ERROR.EHANDLETYPE);
+    this.name = 'HandleTypeMismatchError';
+    this.handle = handle;
+    this.expected = expected;
+    this.actual = actual;
+  }
+}
+
+/**
+ * Thrown when the ResourceTable has reached its maximum capacity.
+ *
+ * @property {number} maxSize - The table's maximum capacity.
+ * @property {string} code - Always `'ETABLEFULL'`.
+ */
+export class TableFullError extends KernelError {
+  /**
+   * @param {number} maxSize - Maximum table capacity.
+   */
+  constructor(maxSize) {
+    super(`Resource table full: max ${maxSize} entries`, KERNEL_ERROR.ETABLEFULL);
+    this.name = 'TableFullError';
+    this.maxSize = maxSize;
+  }
+}
+
+/**
+ * Thrown when attempting to read from, write to, or operate on a closed ByteStream.
+ *
+ * @property {string} code - Always `'ESTREAMCLOSED'`.
+ */
+export class StreamClosedError extends KernelError {
+  constructor() {
+    super('Stream is closed', KERNEL_ERROR.ESTREAMCLOSED);
+    this.name = 'StreamClosedError';
+  }
+}
+
+/**
+ * Thrown when a tenant lacks the required capability for an operation.
+ *
+ * @property {string} capability - The capability that was required but not granted.
+ * @property {string} code - Always `'ECAPDENIED'`.
+ */
+export class CapabilityDeniedError extends KernelError {
+  /**
+   * @param {string} capability - The required capability tag.
+   */
+  constructor(capability) {
+    super(`Capability denied: ${capability}`, KERNEL_ERROR.ECAPDENIED);
+    this.name = 'CapabilityDeniedError';
+    this.capability = capability;
+  }
+}
+
+/**
+ * Thrown when attempting to register a name or resource that already exists.
+ *
+ * @property {string} identifier - The name that was already registered.
+ * @property {string} code - Always `'EALREADY'`.
+ */
+export class AlreadyRegisteredError extends KernelError {
+  /**
+   * @param {string} identifier - The duplicate name.
+   */
+  constructor(identifier) {
+    super(`Already registered: ${identifier}`, KERNEL_ERROR.EALREADY);
+    this.name = 'AlreadyRegisteredError';
+    this.identifier = identifier;
+  }
+}
+
+/**
+ * Thrown when a named resource is not found in a registry or lookup.
+ *
+ * @property {string} identifier - The name that was not found.
+ * @property {string} code - Always `'ENOTFOUND'`.
+ */
+export class NotFoundError extends KernelError {
+  /**
+   * @param {string} identifier - The name that was not found.
+   */
+  constructor(identifier) {
+    super(`Not found: ${identifier}`, KERNEL_ERROR.ENOTFOUND);
+    this.name = 'NotFoundError';
+    this.identifier = identifier;
+  }
+}