holosphere 2.0.0-alpha1 → 2.0.0-alpha4

package/src/core/holosphere.js

@@ -1,7 +1,30 @@
 import { createClient } from '../storage/nostr-client.js';
 import { BackendFactory } from '../storage/backend-factory.js';
+import * as gunWrapper from '../storage/gun-wrapper.js';
+import * as gunFederation from '../storage/gun-federation.js';
+import { GunDBBackend } from '../storage/backends/gundb-backend.js';
 import pkg from '../../package.json' with { type: 'json' };
 
+// Gun will be loaded dynamically when needed
+let Gun = null;
+let gunLoadPromise = null;
+
+/**
+ * Load Gun module dynamically
+ * @returns {Promise<Function>} Gun constructor
+ */
+async function loadGun() {
+  if (Gun) return Gun;
+  if (gunLoadPromise) return gunLoadPromise;
+
+  gunLoadPromise = import('gun').then(module => {
+    Gun = module.default || module;
+    return Gun;
+  });
+
+  return gunLoadPromise;
+}
+
 /**
  * Get environment variable (works in Node.js, returns undefined in browser)
  * @param {string} name - Environment variable name
@@ -89,9 +112,12 @@ export class HoloSphere {
     this._backend = null;
 
     // For backward compatibility with Nostr, initialize synchronously
-    // Other backends use async initialization via _backendReady
+    // GunDB and other backends use async initialization via _backendReady
     if (this.config.backend === 'nostr') {
       this._initNostrSync(config);
+    } else if (this.config.backend === 'gundb') {
+      // GunDB uses async init due to dynamic import
+      this._backendReady = this._initGunDBAsync(config);
     } else {
       // Async initialization for other backends
       this._backendReady = this._initBackendAsync(config);
@@ -143,6 +169,68 @@ export class HoloSphere {
     }
   }
 
+  /**
+   * Initialize GunDB backend asynchronously (for browser compatibility with dynamic import)
+   * @private
+   */
+  async _initGunDBAsync(config) {
+    try {
+      const gundbConfig = config.gundb || {};
+
+      // Create the full-featured GunDB backend
+      this._backend = new GunDBBackend({
+        appName: this.config.appName,
+        peers: gundbConfig.peers || [],
+        radisk: gundbConfig.radisk !== false,
+        localStorage: gundbConfig.localStorage !== false,
+        dataDir: config.dataDir,
+        privateKey: this.config.privateKey,
+        strict: gundbConfig.strict || false,
+        schemaCacheMaxAge: gundbConfig.schemaCacheMaxAge || 3600000,
+      });
+
+      // Initialize the backend
+      await this._backend.init();
+
+      // Set public key from backend
+      this.publicKey = this._backend.publicKey;
+
+      // Store Gun instance for direct access
+      this._gun = this._backend.gun;
+
+      // Create a client-like interface for compatibility
+      this.client = {
+        publicKey: this.publicKey,
+        gun: this._gun,
+        write: (path, data) => this._backend.write(path, data),
+        read: (path, options) => this._backend.read(path, options),
+        readAll: (path, options) => this._backend.readAll(path, options),
+        update: (path, updates) => this._backend.update(path, updates),
+        delete: (path) => this._backend.delete(path),
+        subscribe: (path, callback, options) => this._backend.subscribe(path, callback, options),
+        buildPath: gunWrapper.buildPath,
+      };
+
+      // Store Gun wrapper functions for direct access
+      this._gunWrapper = gunWrapper;
+
+      // Log startup information
+      this._logStartup({
+        version: pkg.version,
+        appName: this.config.appName,
+        backend: 'gundb',
+        peers: gundbConfig.peers || [],
+        publicKey: this.publicKey,
+        logLevel: this.config.logLevel,
+        persistence: gundbConfig.radisk !== false,
+        dataDir: config.dataDir,
+      });
+    } catch (error) {
+      this._log('ERROR', 'GunDB client initialization failed', { error: error.message });
+      throw new Error(`GunDB client initialization failed: ${error.message}`);
+    }
+  }
+
   /**
    * Initialize non-Nostr backends asynchronously
    * @private
@@ -270,4 +358,368 @@ export class HoloSphere {
   metrics() {
     return { ...this._metrics };
   }
+
+  // ============================================================================
+  // GUNDB-SPECIFIC METHODS
+  // These methods are only available when using the 'gundb' backend
+  // ============================================================================
+
+  /**
+   * Check if using GunDB backend
+   * @private
+   */
+  _requireGunDB() {
+    if (this.config.backend !== 'gundb') {
+      throw new Error('This method requires the GunDB backend');
+    }
+    if (!this._backend) {
+      throw new Error('Backend not initialized. Call ready() first.');
+    }
+  }
+
+  // ============================================================================
+  // GLOBAL TABLE OPERATIONS
+  // ============================================================================
+
+  /**
+   * Write data to a global table
+   * @param {string} tableName - Global table name (e.g., 'federation', 'schemas')
+   * @param {Object} data - Data to write (must have 'id' field)
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async putGlobal(tableName, data) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.writeGlobal(tableName, data);
+  }
+
+  /**
+   * Read data from a global table
+   * @param {string} tableName - Global table name
+   * @param {string} key - Data key
+   * @returns {Promise<Object|null>} Data or null if not found
+   */
+  async getGlobal(tableName, key) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.readGlobal(tableName, key);
+  }
+
+  /**
+   * Read all data from a global table
+   * @param {string} tableName - Global table name
+   * @returns {Promise<Object[]>} Array of data objects
+   */
+  async getAllGlobal(tableName) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.readAllGlobal(tableName);
+  }
+
+  /**
+   * Delete data from a global table
+   * @param {string} tableName - Global table name
+   * @param {string} key - Data key
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async deleteGlobal(tableName, key) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.deleteGlobal(tableName, key);
+  }
+
+  // ============================================================================
+  // REFERENCE OPERATIONS
+  // ============================================================================
+
+  /**
+   * Create a reference to data
+   * @param {string} holon - Holon ID
+   * @param {string} lens - Lens name
+   * @param {Object} data - Data object (must have 'id' field)
+   * @returns {Object} Reference object with id and soul
+   */
+  createReference(holon, lens, data) {
+    this._requireGunDB();
+    return this._backend.createReference(holon, lens, data);
+  }
+
+  /**
+   * Check if data is a reference
+   * @param {Object} data - Data to check
+   * @returns {boolean} True if data is a reference
+   */
+  isReference(data) {
+    this._requireGunDB();
+    return this._backend.isReference(data);
+  }
+
+  /**
+   * Resolve a reference to get actual data
+   * @param {Object} reference - Reference object
+   * @param {Object} options - Resolution options
+   * @returns {Promise<Object|null>} Resolved data or null
+   */
+  async resolveReference(reference, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.resolveReference(reference, options);
+  }
+
+  // ============================================================================
+  // AUTHENTICATION OPERATIONS
+  // ============================================================================
+
+  /**
+   * Authenticate for a holon
+   * @param {string} holonId - Holon ID
+   * @param {string} password - Password
+   * @returns {Promise<Object>} Authenticated user object
+   */
+  async authenticate(holonId, password) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.authenticate(holonId, password);
+  }
+
+  /**
+   * Create a new user for a holon
+   * @param {string} holonId - Holon ID
+   * @param {string} password - Password
+   * @returns {Promise<Object>} Created user object
+   */
+  async createUser(holonId, password) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.createUser(holonId, password);
+  }
+
+  /**
+   * Logout current user
+   */
+  logout() {
+    this._requireGunDB();
+    this._backend.logout();
+  }
+
+  /**
+   * Check if authenticated
+   * @returns {boolean} True if authenticated
+   */
+  isAuthenticated() {
+    this._requireGunDB();
+    return this._backend.isAuthenticated();
+  }
+
+  /**
+   * Write to private storage (requires authentication)
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @param {Object} data - Data to write
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async writePrivate(lens, key, data) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.writePrivate(lens, key, data);
+  }
+
+  /**
+   * Read from private storage (requires authentication)
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @returns {Promise<Object|null>} Data or null
+   */
+  async readPrivate(lens, key) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.readPrivate(lens, key);
+  }
+
+  // ============================================================================
+  // SCHEMA OPERATIONS
+  // ============================================================================
+
+  /**
+   * Set a schema for a lens
+   * @param {string} lens - Lens name
+   * @param {Object} schema - JSON Schema definition
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async setSchema(lens, schema) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.setSchema(lens, schema);
+  }
+
+  /**
+   * Get a schema for a lens
+   * @param {string} lens - Lens name
+   * @returns {Promise<Object|null>} Schema or null
+   */
+  async getSchema(lens) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.getSchema(lens);
+  }
+
+  /**
+   * Validate data against a lens schema
+   * @param {string} lens - Lens name
+   * @param {Object} data - Data to validate
+   * @returns {Promise<Object>} Validation result { valid: boolean, errors: Array }
+   */
+  async validateData(lens, data) {
+    await this.ready();
+    this._requireGunDB();
+    return this._backend.validateData(lens, data);
+  }
+
+  // ============================================================================
+  // FEDERATION OPERATIONS
+  // ============================================================================
+
+  /**
+   * Create a federation relationship between two spaces
+   * @param {string} spaceId1 - First space ID
+   * @param {string} spaceId2 - Second space ID
+   * @param {boolean} bidirectional - Whether to set up bidirectional notifications (default: true)
+   * @returns {Promise<boolean>} True if federation was created
+   */
+  async federate(spaceId1, spaceId2, bidirectional = true) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.federate(this._backend, spaceId1, spaceId2, bidirectional);
+  }
+
+  /**
+   * Remove a federation relationship
+   * @param {string} spaceId1 - First space ID
+   * @param {string} spaceId2 - Second space ID
+   * @returns {Promise<boolean>} True if federation was removed
+   */
+  async unfederate(spaceId1, spaceId2) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.unfederate(this._backend, spaceId1, spaceId2);
+  }
+
+  /**
+   * Get federation info for a space
+   * @param {string} spaceId - Space ID
+   * @returns {Promise<Object|null>} Federation info or null
+   */
+  async getFederation(spaceId) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.getFederation(this._backend, spaceId);
+  }
+
+  /**
+   * Reset all federation relationships for a space
+   * @param {string} spaceId - Space ID
+   * @param {Object} options - Reset options
+   * @returns {Promise<Object>} Result object
+   */
+  async resetFederation(spaceId, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.resetFederation(this._backend, spaceId, options);
+  }
+
+  /**
+   * Propagate data to federated spaces
+   * @param {string} holon - Holon identifier
+   * @param {string} lens - Lens identifier
+   * @param {Object} data - Data to propagate
+   * @param {Object} options - Propagation options
+   * @returns {Promise<Object>} Result with success count and errors
+   */
+  async propagate(holon, lens, data, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.propagate(this._backend, holon, lens, data, options);
+  }
+
+  /**
+   * Get combined data from local and federated sources
+   * @param {string} holon - Local holon name
+   * @param {string} lens - Lens to query
+   * @param {Object} options - Options for data retrieval and aggregation
+   * @returns {Promise<Array>} Combined array of local and federated data
+   */
+  async getFederated(holon, lens, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.getFederated(this._backend, holon, lens, options);
+  }
+
+  /**
+   * Subscribe to federation notifications for a space
+   * @param {string} spaceId - Space ID to subscribe to
+   * @param {Function} callback - Callback to execute on notifications
+   * @param {Object} options - Subscription options
+   * @returns {Promise<Object>} Subscription object with unsubscribe() method
+   */
+  async subscribeFederation(spaceId, callback, options = {}) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.subscribeFederation(this._backend, spaceId, callback, options);
+  }
+
+  /**
+   * Track a federated message across different chats
+   * @param {string} originalChatId - Original chat ID
+   * @param {string} messageId - Original message ID
+   * @param {string} federatedChatId - Federated chat ID
+   * @param {string} federatedMessageId - Federated message ID
+   * @param {string} type - Message type
+   * @returns {Promise<void>}
+   */
+  async federateMessage(originalChatId, messageId, federatedChatId, federatedMessageId, type = 'generic') {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.federateMessage(this._backend, originalChatId, messageId, federatedChatId, federatedMessageId, type);
+  }
+
+  /**
+   * Get all federated messages for a given original message
+   * @param {string} originalChatId - Original chat ID
+   * @param {string} messageId - Original message ID
+   * @returns {Promise<Object|null>} Tracking information for the message
+   */
+  async getFederatedMessages(originalChatId, messageId) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.getFederatedMessages(this._backend, originalChatId, messageId);
+  }
+
+  /**
+   * Update a federated message across all federated chats
+   * @param {string} originalChatId - Original chat ID
+   * @param {string} messageId - Original message ID
+   * @param {Function} updateCallback - Function to update the message in each chat
+   * @returns {Promise<void>}
+   */
+  async updateFederatedMessages(originalChatId, messageId, updateCallback) {
+    await this.ready();
+    this._requireGunDB();
+    return gunFederation.updateFederatedMessages(this._backend, originalChatId, messageId, updateCallback);
+  }
+
+  // ============================================================================
+  // LIFECYCLE
+  // ============================================================================
+
+  /**
+   * Close the backend and clean up resources
+   */
+  close() {
+    if (this._backend) {
+      this._backend.close();
+    }
+    if (this.client && typeof this.client.close === 'function') {
+      this.client.close();
+    }
+  }
 }