mycelia-kernel-plugin 1.0.0

package/src/contract/contracts/server.contract.js

@@ -0,0 +1,88 @@
+/**
+ * Server Facet Contract
+ * 
+ * Defines the contract that server facets must satisfy.
+ * Ensures all required HTTP server methods are implemented and validates
+ * internal structure for compatibility with different server implementations (Fastify, Express).
+ * 
+ * @example
+ * import { serverContract } from './server.contract.js';
+ * 
+ * // Enforce contract on a server facet
+ * serverContract.enforce(ctx, api, subsystem, serverFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Server Facet Contract
+ * 
+ * Required methods:
+ * - Lifecycle: start, stop, isRunning
+ * - Route Registration (Single): get, post, put, patch, delete, all
+ * - Route Registration (Batch): registerRoutes, registerMyceliaRoutes
+ * - Middleware: use, useRoute
+ * - Error Handling: setErrorHandler
+ * - Server Info: getAddress, getPort
+ * - Mycelia Integration: registerMyceliaRoute, registerMyceliaCommand, registerMyceliaQuery
+ * 
+ * Required properties:
+ * - _server: Internal server instance (Fastify/Express)
+ * - _isRunning: Running state flag
+ * 
+ * Custom validation:
+ * - Validates _server is an object (not null or primitive)
+ * - Validates _isRunning is a boolean
+ */
+export const serverContract = createFacetContract({
+  name: 'server',
+  requiredMethods: [
+    // Lifecycle
+    'start',
+    'stop',
+    'isRunning',
+    
+    // Route Registration (Single)
+    'get',
+    'post',
+    'put',
+    'patch',
+    'delete',
+    'all',  // All HTTP methods
+    
+    // Route Registration (Batch)
+    'registerRoutes',  // Register multiple routes at once
+    'registerMyceliaRoutes',  // Register multiple Mycelia routes at once
+    
+    // Middleware
+    'use',  // Global middleware
+    'useRoute',  // Route-specific middleware
+    
+    // Error Handling
+    'setErrorHandler',
+    
+    // Server Info
+    'getAddress',
+    'getPort',
+    
+    // Integration
+    'registerMyceliaRoute',  // Register Mycelia route as HTTP endpoint
+    'registerMyceliaCommand', // Register Mycelia command as HTTP endpoint
+    'registerMyceliaQuery'    // Register Mycelia query as HTTP endpoint
+  ],
+  requiredProperties: [
+    '_server',  // Internal server instance (Fastify/Express)
+    '_isRunning'  // Running state flag
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate _server is an object
+    if (typeof facet._server !== 'object' || facet._server === null) {
+      throw new Error('Server facet _server must be an object');
+    }
+    
+    // Validate _isRunning is a boolean
+    if (typeof facet._isRunning !== 'boolean') {
+      throw new Error('Server facet _isRunning must be a boolean');
+    }
+  }
+});
+

package/src/contract/contracts/speak.contract.js

@@ -0,0 +1,50 @@
+/**
+ * Speak Contract
+ * 
+ * Defines the interface for facets that provide speaking/printing functionality.
+ * This is a simple example contract for demonstration purposes.
+ * 
+ * @example
+ * // Create a speak contract
+ * const speakContract = createFacetContract({
+ *   name: 'speak',
+ *   requiredMethods: ['say', 'sayLine'],
+ *   requiredProperties: []
+ * });
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+export const speakContract = createFacetContract({
+  name: 'speak',
+  requiredMethods: ['say', 'sayLine'],
+  requiredProperties: [],
+  validate: (ctx, api, subsystem, facet) => {
+    const errors = [];
+    
+    // Validate say method
+    if (typeof facet.say !== 'function') {
+      errors.push('speak facet must have a say() method');
+    } else {
+      // Check method signature (should accept at least one argument)
+      if (facet.say.length < 1) {
+        errors.push('speak.say() method must accept at least one argument (message)');
+      }
+    }
+    
+    // Validate sayLine method
+    if (typeof facet.sayLine !== 'function') {
+      errors.push('speak facet must have a sayLine() method');
+    } else {
+      // Check method signature (should accept at least one argument)
+      if (facet.sayLine.length < 1) {
+        errors.push('speak.sayLine() method must accept at least one argument (message)');
+      }
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+});
+

package/src/contract/contracts/storage.contract.js

@@ -0,0 +1,107 @@
+/**
+ * Storage Facet Contract
+ * 
+ * Defines the contract that storage facets must satisfy.
+ * Ensures all required storage methods are implemented and validates
+ * internal structure for compatibility with other hooks.
+ * 
+ * @example
+ * import { storageContract } from './storage.contract.js';
+ * 
+ * // Enforce contract on a storage facet
+ * storageContract.enforce(ctx, api, subsystem, storageFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * Storage Facet Contract
+ * 
+ * Required methods:
+ * - get: Retrieve a value by key
+ * - set: Store a value by key
+ * - delete: Delete a value by key
+ * - has: Check if a key exists
+ * - getMany: Retrieve multiple values by keys
+ * - setMany: Store multiple key-value pairs
+ * - deleteMany: Delete multiple keys
+ * - list: List all keys (or keys matching pattern)
+ * - query: Query values by filter criteria
+ * - count: Count keys/entries
+ * - createNamespace: Create a new namespace/collection
+ * - deleteNamespace: Delete a namespace/collection
+ * - listNamespaces: List all namespaces
+ * - beginTransaction: Begin a transaction (optional)
+ * - commit: Commit a transaction (optional)
+ * - rollback: Rollback a transaction (optional)
+ * - getMetadata: Get metadata for a key
+ * - setMetadata: Set metadata for a key
+ * - clear: Clear all data (or data in namespace)
+ * - getStatus: Get storage status/health
+ * 
+ * Required properties:
+ * - _storageBackend: Internal storage backend instance
+ * - _config: Storage configuration
+ * 
+ * Optional properties:
+ * - supportsTransactions: Whether backend supports transactions
+ * - supportsQuery: Whether backend supports query operations
+ * - supportsMetadata: Whether backend supports metadata
+ * 
+ * Custom validation:
+ * - Validates _storageBackend is an object (not null or primitive)
+ * - Validates _config is an object
+ */
+export const storageContract = createFacetContract({
+  name: 'storage',
+  requiredMethods: [
+    'get',
+    'set',
+    'delete',
+    'has',
+    'getMany',
+    'setMany',
+    'deleteMany',
+    'list',
+    'query',
+    'count',
+    'createNamespace',
+    'deleteNamespace',
+    'listNamespaces',
+    'getMetadata',
+    'setMetadata',
+    'clear',
+    'getStatus'
+  ],
+  requiredProperties: [
+    '_storageBackend',
+    '_config'
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate that _storageBackend is an object (not null or primitive)
+    if (typeof facet._storageBackend !== 'object' || facet._storageBackend === null) {
+      throw new Error('Storage facet _storageBackend must be an object');
+    }
+    
+    // Validate _config is an object
+    if (typeof facet._config !== 'object' || facet._config === null) {
+      throw new Error('Storage facet _config must be an object');
+    }
+    
+    // Validate optional properties have correct types if present
+    if ('supportsTransactions' in facet && typeof facet.supportsTransactions !== 'boolean') {
+      throw new Error('Storage facet supportsTransactions must be a boolean');
+    }
+    
+    if ('supportsQuery' in facet && typeof facet.supportsQuery !== 'boolean') {
+      throw new Error('Storage facet supportsQuery must be a boolean');
+    }
+    
+    if ('supportsMetadata' in facet && typeof facet.supportsMetadata !== 'boolean') {
+      throw new Error('Storage facet supportsMetadata must be a boolean');
+    }
+  }
+});
+
+
+
+

package/src/contract/contracts/websocket.contract.js

@@ -0,0 +1,90 @@
+/**
+ * WebSocket Facet Contract
+ * 
+ * Defines the contract that WebSocket facets must satisfy.
+ * Ensures all required WebSocket server methods are implemented and validates
+ * internal structure for compatibility with different WebSocket implementations (ws, uWebSockets.js).
+ * 
+ * @example
+ * import { websocketContract } from './websocket.contract.js';
+ * 
+ * // Enforce contract on a WebSocket facet
+ * websocketContract.enforce(ctx, api, subsystem, websocketFacet);
+ */
+import { createFacetContract } from '../facet-contract.js';
+
+/**
+ * WebSocket Facet Contract
+ * 
+ * Required methods:
+ * - Lifecycle: start, stop, isRunning
+ * - Server Info: getAddress, getPort
+ * - Connection Management: getConnection, getAllConnections, getConnectionCount, closeConnection
+ * - Message Sending: send, broadcast
+ * - Connection Lifecycle Handlers: onConnection, onDisconnection, onError
+ * - Message Routing: registerMessageHandler, routeMessage
+ * 
+ * Required properties:
+ * - _server: Internal WebSocket server instance
+ * - _isRunning: Running state flag
+ * - _connections: Connection manager/registry
+ * 
+ * Custom validation:
+ * - Validates _server is an object (not null or primitive)
+ * - Validates _isRunning is a boolean
+ * - Validates _connections exists
+ */
+export const websocketContract = createFacetContract({
+  name: 'websocket',
+  requiredMethods: [
+    // Lifecycle
+    'start',
+    'stop',
+    'isRunning',
+    
+    // Server Info
+    'getAddress',
+    'getPort',
+    
+    // Connection Management
+    'getConnection',
+    'getAllConnections',
+    'getConnectionCount',
+    'closeConnection',
+    
+    // Message Sending
+    'send',
+    'broadcast',
+    
+    // Connection Lifecycle Handlers
+    'onConnection',
+    'onDisconnection',
+    'onError',
+    
+    // Message Routing
+    'registerMessageHandler',
+    'routeMessage'
+  ],
+  requiredProperties: [
+    '_server',      // Internal WebSocket server instance
+    '_isRunning',  // Running state flag
+    '_connections'  // Connection manager/registry
+  ],
+  validate: (ctx, api, subsystem, facet) => {
+    // Validate _server is an object
+    if (typeof facet._server !== 'object' || facet._server === null) {
+      throw new Error('WebSocket facet _server must be an object');
+    }
+    
+    // Validate _isRunning is a boolean
+    if (typeof facet._isRunning !== 'boolean') {
+      throw new Error('WebSocket facet _isRunning must be a boolean');
+    }
+    
+    // Validate _connections exists (could be Map, object, or manager instance)
+    if (!facet._connections) {
+      throw new Error('WebSocket facet _connections must be defined');
+    }
+  }
+});
+

package/src/contract/facet-contract-registry.js

@@ -0,0 +1,155 @@
+/**
+ * FacetContractRegistry Class
+ * 
+ * Manages a collection of facet contracts, allowing registration and enforcement
+ * of contracts on facets by name.
+ * 
+ * @example
+ * import { FacetContractRegistry } from './facet-contract-registry.js';
+ * import { createFacetContract } from './facet-contract.js';
+ * 
+ * const registry = new FacetContractRegistry();
+ * 
+ * const routerContract = createFacetContract({
+ *   name: 'router',
+ *   requiredMethods: ['registerRoute', 'match']
+ * });
+ * 
+ * registry.register(routerContract);
+ * 
+ * // Later, enforce the contract
+ * registry.enforce('router', ctx, api, subsystem, routerFacet);
+ */
+import { FacetContract } from './facet-contract.js';
+
+export class FacetContractRegistry {
+  /**
+   * Map of contract name → FacetContract instance
+   * @private
+   * @type {Map<string, FacetContract>}
+   */
+  #contracts = new Map();
+
+  /**
+   * Creates a new FacetContractRegistry
+   */
+  constructor() {
+    // No initialization needed
+  }
+
+  /**
+   * Registers a facet contract in the registry
+   * 
+   * @param {FacetContract} contract - FacetContract instance to register
+   * @returns {FacetContract} The registered contract
+   * @throws {Error} If contract is invalid or a contract with the same name already exists
+   */
+  register(contract) {
+    if (!contract || typeof contract !== 'object') {
+      throw new Error('FacetContractRegistry.register: contract must be an object');
+    }
+    if (!(contract instanceof FacetContract)) {
+      throw new Error('FacetContractRegistry.register: contract must be a FacetContract instance');
+    }
+    if (!contract.name || typeof contract.name !== 'string') {
+      throw new Error('FacetContractRegistry.register: contract must have a string name property');
+    }
+
+    if (this.#contracts.has(contract.name)) {
+      throw new Error(`FacetContractRegistry.register: contract with name '${contract.name}' already exists`);
+    }
+
+    this.#contracts.set(contract.name, contract);
+    return contract;
+  }
+
+  /**
+   * Checks if a contract exists for the given name
+   * 
+   * @param {string} name - Contract name to check
+   * @returns {boolean} True if contract exists
+   */
+  has(name) {
+    if (typeof name !== 'string') {
+      return false;
+    }
+    return this.#contracts.has(name);
+  }
+
+  /**
+   * Gets a contract by name
+   * 
+   * @param {string} name - Contract name
+   * @returns {FacetContract|undefined} Contract instance or undefined if not found
+   */
+  get(name) {
+    if (typeof name !== 'string') {
+      return undefined;
+    }
+    return this.#contracts.get(name);
+  }
+
+  /**
+   * Enforces a contract on a facet
+   * 
+   * Looks up the contract by name and delegates to its enforce method.
+   * 
+   * @param {string} name - Name of the contract to enforce
+   * @param {Object} ctx - Context object
+   * @param {Object} api - Subsystem API object
+   * @param {BaseSubsystem} subsystem - Subsystem instance
+   * @param {Facet} facet - Facet to validate
+   * @throws {Error} If contract not found or validation fails
+   */
+  enforce(name, ctx, api, subsystem, facet) {
+    if (typeof name !== 'string' || !name) {
+      throw new Error('FacetContractRegistry.enforce: name must be a non-empty string');
+    }
+
+    const contract = this.#contracts.get(name);
+    if (!contract) {
+      throw new Error(`FacetContractRegistry.enforce: no contract found for name '${name}'`);
+    }
+
+    contract.enforce(ctx, api, subsystem, facet);
+  }
+
+  /**
+   * Removes a contract from the registry
+   * 
+   * @param {string} name - Contract name to remove
+   * @returns {boolean} True if contract was removed, false if not found
+   */
+  remove(name) {
+    if (typeof name !== 'string') {
+      return false;
+    }
+    return this.#contracts.delete(name);
+  }
+
+  /**
+   * Lists all registered contract names
+   * 
+   * @returns {Array<string>} Array of contract names
+   */
+  list() {
+    return Array.from(this.#contracts.keys());
+  }
+
+  /**
+   * Gets the number of registered contracts
+   * 
+   * @returns {number} Number of contracts
+   */
+  size() {
+    return this.#contracts.size;
+  }
+
+  /**
+   * Clears all contracts from the registry
+   */
+  clear() {
+    this.#contracts.clear();
+  }
+}
+

package/src/contract/facet-contract.js

@@ -0,0 +1,136 @@
+/**
+ * FacetContract Class
+ * 
+ * Defines a contract that facets must satisfy, including required methods,
+ * required properties, and optional custom validation logic.
+ * 
+ * @example
+ * const routerContract = new FacetContract('router', {
+ *   requiredMethods: ['registerRoute', 'match'],
+ *   requiredProperties: ['_routeRegistry']
+ * }, (ctx, api, subsystem, facet) => {
+ *   // Additional custom validation
+ * });
+ * 
+ * routerContract.enforce(ctx, api, subsystem, routerFacet);
+ */
+export class FacetContract {
+  #validate = null;
+
+  /**
+   * Create a new FacetContract
+   * 
+   * @param {string} name - Name of the contract (usually same as facet kind)
+   * @param {Object} requirements - Requirements object
+   * @param {Array<string>} [requirements.requiredMethods=[]] - Array of required method names that must be implemented
+   * @param {Array<string>} [requirements.requiredProperties=[]] - Array of required property names that must exist
+   * @param {Function} [validate] - Optional validation function with signature (ctx, api, subsystem, facet)
+   */
+  constructor(name, requirements = {}, validate = null) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('FacetContract: name must be a non-empty string');
+    }
+    if (!requirements || typeof requirements !== 'object' || Array.isArray(requirements)) {
+      throw new Error('FacetContract: requirements must be an object');
+    }
+    if (validate !== null && typeof validate !== 'function') {
+      throw new Error('FacetContract: validate must be a function or null');
+    }
+
+    this.name = name;
+    this.requiredMethods = Array.isArray(requirements.requiredMethods) 
+      ? [...requirements.requiredMethods] 
+      : [];
+    this.requiredProperties = Array.isArray(requirements.requiredProperties)
+      ? [...requirements.requiredProperties]
+      : [];
+    this.#validate = validate;
+  }
+
+  /**
+   * Enforce the contract on a facet
+   * 
+   * Checks that all required methods and properties exist on the facet,
+   * then runs the custom validation function if provided.
+   * 
+   * @param {Object} ctx - Context object
+   * @param {Object} api - Subsystem API object
+   * @param {BaseSubsystem} subsystem - Subsystem instance
+   * @param {Facet} facet - Facet to validate
+   * @throws {Error} If required methods or properties are missing or validation fails
+   */
+  enforce(ctx, api, subsystem, facet) {
+    if (!facet || typeof facet !== 'object') {
+      throw new Error(`FacetContract '${this.name}': facet must be an object`);
+    }
+
+    // Check that all required methods are implemented
+    const missingMethods = [];
+    for (const methodName of this.requiredMethods) {
+      if (typeof facet[methodName] !== 'function') {
+        missingMethods.push(methodName);
+      }
+    }
+
+    if (missingMethods.length > 0) {
+      throw new Error(
+        `FacetContract '${this.name}': facet is missing required methods: ${missingMethods.join(', ')}`
+      );
+    }
+
+    // Check that all required properties exist
+    const missingProperties = [];
+    for (const propertyName of this.requiredProperties) {
+      if (!(propertyName in facet) || facet[propertyName] === undefined) {
+        missingProperties.push(propertyName);
+      }
+    }
+
+    if (missingProperties.length > 0) {
+      throw new Error(
+        `FacetContract '${this.name}': facet is missing required properties: ${missingProperties.join(', ')}`
+      );
+    }
+
+    // Run custom validation if provided
+    if (this.#validate !== null) {
+      try {
+        this.#validate(ctx, api, subsystem, facet);
+      } catch (error) {
+        throw new Error(
+          `FacetContract '${this.name}': validation failed: ${error.message}`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * FacetContract Factory Function
+ * 
+ * Creates a FacetContract instance with validation and error handling.
+ * 
+ * @param {Object} options - Contract configuration
+ * @param {string} options.name - Name of the contract (usually same as facet kind)
+ * @param {Array<string>} [options.requiredMethods=[]] - Array of required method names that must be implemented
+ * @param {Array<string>} [options.requiredProperties=[]] - Array of required property names that must exist
+ * @param {Function} [options.validate] - Optional validation function with signature (ctx, api, subsystem, facet)
+ * @returns {FacetContract} New FacetContract instance
+ * 
+ * @example
+ * const routerContract = createFacetContract({
+ *   name: 'router',
+ *   requiredMethods: ['registerRoute', 'match', 'route'],
+ *   requiredProperties: ['_routeRegistry'],
+ *   validate: (ctx, api, subsystem, facet) => {
+ *     // Additional custom validation
+ *     if (typeof facet._routeRegistry !== 'object') {
+ *       throw new Error('Router facet _routeRegistry must be an object');
+ *     }
+ *   }
+ * });
+ */
+export function createFacetContract({ name, requiredMethods = [], requiredProperties = [], validate = null }) {
+  return new FacetContract(name, { requiredMethods, requiredProperties }, validate);
+}
+

package/src/contract/index.js

@@ -0,0 +1,63 @@
+/**
+ * Facet Contract Registry Index
+ * 
+ * Creates a default FacetContractRegistry instance and registers all available
+ * facet contracts. This provides a centralized registry for enforcing contracts
+ * on facets throughout the system.
+ * 
+ * @example
+ * import { defaultContractRegistry } from './index.js';
+ * 
+ * // Enforce a contract on a facet
+ * defaultContractRegistry.enforce('router', ctx, api, subsystem, routerFacet);
+ * 
+ * // Check if a contract exists
+ * if (defaultContractRegistry.has('queue')) {
+ *   // Contract is available
+ * }
+ */
+import { FacetContractRegistry } from './facet-contract-registry.js';
+import { routerContract } from './contracts/router.contract.js';
+import { queueContract } from './contracts/queue.contract.js';
+import { processorContract } from './contracts/processor.contract.js';
+import { listenersContract } from './contracts/listeners.contract.js';
+import { hierarchyContract } from './contracts/hierarchy.contract.js';
+import { schedulerContract } from './contracts/scheduler.contract.js';
+import { serverContract } from './contracts/server.contract.js';
+import { speakContract } from './contracts/speak.contract.js';
+import { websocketContract } from './contracts/websocket.contract.js';
+import { storageContract } from './contracts/storage.contract.js';
+
+/**
+ * Default Facet Contract Registry
+ * 
+ * Pre-configured registry with all standard facet contracts registered.
+ */
+export const defaultContractRegistry = new FacetContractRegistry();
+
+// Register all available contracts
+defaultContractRegistry.register(routerContract);
+defaultContractRegistry.register(queueContract);
+defaultContractRegistry.register(processorContract);
+defaultContractRegistry.register(listenersContract);
+defaultContractRegistry.register(hierarchyContract);
+defaultContractRegistry.register(schedulerContract);
+defaultContractRegistry.register(serverContract);
+defaultContractRegistry.register(speakContract);
+defaultContractRegistry.register(websocketContract);
+defaultContractRegistry.register(storageContract);
+
+// Also export the registry class and individual contracts for flexibility
+export { FacetContractRegistry } from './facet-contract-registry.js';
+export { FacetContract, createFacetContract } from './facet-contract.js';
+export { routerContract } from './contracts/router.contract.js';
+export { queueContract } from './contracts/queue.contract.js';
+export { processorContract } from './contracts/processor.contract.js';
+export { listenersContract } from './contracts/listeners.contract.js';
+export { hierarchyContract } from './contracts/hierarchy.contract.js';
+export { schedulerContract } from './contracts/scheduler.contract.js';
+export { serverContract } from './contracts/server.contract.js';
+export { speakContract } from './contracts/speak.contract.js';
+export { websocketContract } from './contracts/websocket.contract.js';
+export { storageContract } from './contracts/storage.contract.js';
+