holosphere 2.0.0-alpha0 → 2.0.0-alpha10

package/src/storage/gun-references.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview GunDB Reference Handler.
+ *
+ * Handles creation and resolution of data references for federation.
+ * References use a "soul" pattern: appname/holon/lens/key
+ * This allows lightweight propagation without data duplication.
+ *
+ * @module storage/gun-references
+ */
+
+import { read } from './gun-wrapper.js';
+
+/**
+ * Reference handler for GunDB backend.
+ *
+ * Manages creation, detection, and resolution of data references.
+ *
+ * @class GunReferenceHandler
+ * @example
+ * const handler = new GunReferenceHandler('myapp');
+ * const ref = handler.createReference('holon1', 'items', { id: '123', name: 'Test' });
+ * const resolved = await handler.resolveReference(gun, ref);
+ */
+export class GunReferenceHandler {
+  /**
+   * Create a new reference handler.
+   *
+   * @param {string} appname - Application namespace
+   */
+  constructor(appname) {
+    this.appname = appname;
+  }
+
+  /**
+   * 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) {
+    if (!data || !data.id) {
+      throw new Error('createReference: data must have an id field');
+    }
+    return {
+      id: data.id,
+      soul: `${this.appname}/${holon}/${lens}/${data.id}`
+    };
+  }
+
+  /**
+   * Check if data is a reference
+   * @param {Object} data - Data to check
+   * @returns {boolean} True if data is a reference
+   */
+  isReference(data) {
+    if (!data) return false;
+
+    // Simple reference format: { id, soul }
+    if (data.soul && data.id && Object.keys(data).filter(k => !k.startsWith('_')).length <= 2) {
+      return true;
+    }
+
+    // Legacy reference format: { _federation: { isReference: true } }
+    if (data._federation && data._federation.isReference) {
+      return true;
+    }
+
+    // Gun internal reference format: { _: { "#": "path/to/data" } }
+    if (data._ && data._['#']) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Parse a soul path into its components
+   * @param {string} soul - Soul path (appname/holon/lens/key)
+   * @returns {Object|null} Parsed components or null if invalid
+   */
+  parseSoulPath(soul) {
+    if (!soul || typeof soul !== 'string') {
+      return null;
+    }
+
+    const parts = soul.split('/');
+    if (parts.length < 4) {
+      return null;
+    }
+
+    return {
+      appname: parts[0],
+      holon: parts[1],
+      lens: parts[2],
+      key: parts.slice(3).join('/') // Handle keys with slashes
+    };
+  }
+
+  /**
+   * Resolve a reference to get the actual data
+   * @param {Object} gun - Gun instance
+   * @param {Object} reference - Reference object
+   * @param {Object} options - Resolution options
+   * @param {boolean} options.followReferences - Whether to recursively resolve nested references (default: true)
+   * @returns {Promise<Object|null>} Resolved data or null if not found
+   */
+  async resolveReference(gun, reference, options = {}) {
+    const { followReferences = true } = options;
+
+    if (!reference) {
+      return null;
+    }
+
+    let soul = null;
+    let originInfo = null;
+
+    // Handle simple reference format { id, soul }
+    if (reference.soul) {
+      soul = reference.soul;
+    }
+    // Handle legacy reference format { _federation: { isReference: true, origin, lens } }
+    else if (reference._federation && reference._federation.isReference) {
+      const fed = reference._federation;
+      if (fed.origin && fed.lens && reference.id) {
+        soul = `${this.appname}/${fed.origin}/${fed.lens}/${reference.id}`;
+        originInfo = fed;
+      }
+    }
+    // Handle Gun internal reference format { _: { "#": "path/to/data" } }
+    else if (reference._ && reference._['#']) {
+      soul = reference._['#'];
+    }
+
+    if (!soul) {
+      return null;
+    }
+
+    // Parse soul to get path components
+    const parsed = this.parseSoulPath(soul);
+    if (!parsed) {
+      return null;
+    }
+
+    try {
+      // Build path and read data
+      const path = `${parsed.appname}/${parsed.holon}/${parsed.lens}/${parsed.key}`;
+      const data = await read(gun, path);
+
+      if (!data) {
+        return null;
+      }
+
+      // Check if resolved data is also a reference and we should follow
+      if (followReferences && this.isReference(data)) {
+        const nested = await this.resolveReference(gun, data, { followReferences: true });
+        if (nested) {
+          return {
+            ...nested,
+            _federation: {
+              resolved: true,
+              soul: soul,
+              origin: parsed.holon,
+              lens: parsed.lens,
+              timestamp: Date.now()
+            }
+          };
+        }
+      }
+
+      // Add federation metadata to resolved data
+      return {
+        ...data,
+        _federation: {
+          resolved: true,
+          soul: soul,
+          origin: originInfo?.origin || parsed.holon,
+          lens: originInfo?.lens || parsed.lens,
+          timestamp: Date.now()
+        }
+      };
+    } catch (error) {
+      console.warn('Error resolving reference:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Get the soul path for data
+   * @param {string} holon - Holon ID
+   * @param {string} lens - Lens name
+   * @param {string} key - Data key
+   * @returns {string} Soul path
+   */
+  getSoul(holon, lens, key) {
+    return `${this.appname}/${holon}/${lens}/${key}`;
+  }
+}
+
+/**
+ * Create a reference handler instance
+ * @param {string} appname - Application namespace
+ * @returns {GunReferenceHandler} Reference handler instance
+ */
+export function createReferenceHandler(appname) {
+  return new GunReferenceHandler(appname);
+}
+
+export default GunReferenceHandler;

package/src/storage/gun-schema.js

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview GunDB Schema Validator.
+ *
+ * Handles JSON Schema validation for data stored in GunDB.
+ * Schemas are stored in the global 'schemas' table.
+ * Validation uses AJV (Another JSON Schema Validator) with JSON Schema 2019.
+ *
+ * @module storage/gun-schema
+ */
+
+import { writeGlobal, readGlobal, readAllGlobal, deleteGlobal } from './gun-wrapper.js';
+
+/**
+ * Default meta-schema for validating schema definitions.
+ * @private
+ * @constant {Object}
+ */
+const META_SCHEMA = {
+  type: 'object',
+  required: ['type'],
+  properties: {
+    $schema: { type: 'string' },
+    $id: { type: 'string' },
+    type: { type: 'string' },
+    properties: { type: 'object' },
+    required: { type: 'array', items: { type: 'string' } },
+    additionalProperties: { type: 'boolean' }
+  }
+};
+
+/**
+ * Schema validator for GunDB backend.
+ *
+ * Provides JSON Schema validation with caching and lazy-loaded AJV.
+ *
+ * @class GunSchemaValidator
+ * @example
+ * const validator = new GunSchemaValidator({ strict: true });
+ * await validator.init();
+ * await validator.setSchema(gun, 'myapp', 'user', { type: 'object', properties: { name: { type: 'string' } } });
+ */
+export class GunSchemaValidator {
+  /**
+   * Create a new schema validator.
+   *
+   * @param {Object} [options={}] - Validator options
+   * @param {boolean} [options.strict=false] - Whether to enforce strict validation
+   * @param {number} [options.cacheMaxAge=3600000] - Schema cache TTL in ms (1 hour)
+   */
+  constructor(options = {}) {
+    this.strict = options.strict || false;
+    this.cacheMaxAge = options.cacheMaxAge || 3600000; // 1 hour
+    this.schemaCache = new Map();
+    this.validator = null;
+    this.Ajv = null;
+  }
+
+  /**
+   * Initialize the validator (lazy load AJV)
+   * @returns {Promise<boolean>} True if initialized successfully
+   */
+  async init() {
+    if (this.validator) {
+      return true;
+    }
+
+    try {
+      // Dynamically import AJV to avoid requiring it if not needed
+      const AjvModule = await import('ajv/dist/2019.js');
+      this.Ajv = AjvModule.default || AjvModule;
+
+      this.validator = new this.Ajv({
+        allErrors: true,
+        strict: false,
+        validateSchema: true
+      });
+
+      return true;
+    } catch (error) {
+      console.warn('AJV not available, schema validation disabled:', error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Set a schema for a lens
+   * @param {Object} gun - Gun instance
+   * @param {string} appname - Application namespace
+   * @param {string} lens - Lens name
+   * @param {Object} schema - JSON Schema definition
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async setSchema(gun, appname, lens, schema) {
+    if (!schema || typeof schema !== 'object') {
+      throw new Error('setSchema: schema must be an object');
+    }
+
+    // Validate the schema against meta-schema
+    if (this.strict && this.validator) {
+      const isValid = this.validateSchema(META_SCHEMA, schema);
+      if (!isValid) {
+        throw new Error('setSchema: Invalid schema definition');
+      }
+    }
+
+    // Store schema in global 'schemas' table
+    const schemaRecord = {
+      id: lens,
+      lens: lens,
+      schema: schema,
+      timestamp: Date.now()
+    };
+
+    await writeGlobal(gun, appname, 'schemas', schemaRecord);
+
+    // Update cache
+    this.schemaCache.set(lens, {
+      schema: schema,
+      timestamp: Date.now()
+    });
+
+    return true;
+  }
+
+  /**
+   * Get a schema for a lens
+   * @param {Object} gun - Gun instance
+   * @param {string} appname - Application namespace
+   * @param {string} lens - Lens name
+   * @param {Object} options - Options
+   * @param {boolean} options.useCache - Whether to use cache (default: true)
+   * @returns {Promise<Object|null>} Schema or null if not found
+   */
+  async getSchema(gun, appname, lens, options = {}) {
+    const { useCache = true } = options;
+
+    // Check cache first
+    if (useCache) {
+      const cached = this.schemaCache.get(lens);
+      if (cached && (Date.now() - cached.timestamp) < this.cacheMaxAge) {
+        return cached.schema;
+      }
+    }
+
+    // Fetch from storage
+    const schemaRecord = await readGlobal(gun, appname, 'schemas', lens);
+
+    if (schemaRecord && schemaRecord.schema) {
+      // Update cache
+      this.schemaCache.set(lens, {
+        schema: schemaRecord.schema,
+        timestamp: Date.now()
+      });
+      return schemaRecord.schema;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get all schemas
+   * @param {Object} gun - Gun instance
+   * @param {string} appname - Application namespace
+   * @returns {Promise<Object[]>} Array of schema records
+   */
+  async getAllSchemas(gun, appname) {
+    return readAllGlobal(gun, appname, 'schemas');
+  }
+
+  /**
+   * Delete a schema
+   * @param {Object} gun - Gun instance
+   * @param {string} appname - Application namespace
+   * @param {string} lens - Lens name
+   * @returns {Promise<boolean>} Success indicator
+   */
+  async deleteSchema(gun, appname, lens) {
+    // Remove from cache
+    this.schemaCache.delete(lens);
+
+    // Delete from storage
+    return deleteGlobal(gun, appname, 'schemas', lens);
+  }
+
+  /**
+   * Validate data against a schema
+   * @param {Object} schema - JSON Schema definition
+   * @param {Object} data - Data to validate
+   * @returns {Object} Validation result { valid: boolean, errors: Array }
+   */
+  validate(schema, data) {
+    if (!this.validator) {
+      // If validator not available, skip validation
+      return { valid: true, errors: [] };
+    }
+
+    try {
+      const validate = this.validator.compile(schema);
+      const valid = validate(data);
+
+      return {
+        valid: valid,
+        errors: valid ? [] : this.formatErrors(validate.errors)
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        errors: [{ message: error.message, path: '' }]
+      };
+    }
+  }
+
+  /**
+   * Validate data against a lens schema (fetch schema from storage)
+   * @param {Object} gun - Gun instance
+   * @param {string} appname - Application namespace
+   * @param {string} lens - Lens name
+   * @param {Object} data - Data to validate
+   * @returns {Promise<Object>} Validation result { valid: boolean, errors: Array }
+   */
+  async validateData(gun, appname, lens, data) {
+    const schema = await this.getSchema(gun, appname, lens);
+
+    if (!schema) {
+      // No schema defined, validation passes
+      return { valid: true, errors: [] };
+    }
+
+    return this.validate(schema, data);
+  }
+
+  /**
+   * Validate a schema definition against meta-schema
+   * @param {Object} metaSchema - Meta schema to validate against
+   * @param {Object} schema - Schema to validate
+   * @returns {boolean} True if valid
+   */
+  validateSchema(metaSchema, schema) {
+    if (!this.validator) {
+      return true;
+    }
+
+    try {
+      const validate = this.validator.compile(metaSchema);
+      return validate(schema);
+    } catch (error) {
+      return false;
+    }
+  }
+
+  /**
+   * Format validation errors into a consistent structure
+   * @private
+   * @param {Array} errors - AJV error objects
+   * @returns {Array} Formatted errors
+   */
+  formatErrors(errors) {
+    if (!errors) return [];
+
+    return errors.map(err => ({
+      message: err.message || 'Validation error',
+      path: err.instancePath || err.dataPath || '',
+      keyword: err.keyword,
+      params: err.params
+    }));
+  }
+
+  /**
+   * Clear the schema cache
+   * @param {string} lens - Specific lens to clear, or null for all
+   */
+  clearCache(lens = null) {
+    if (lens) {
+      this.schemaCache.delete(lens);
+    } else {
+      this.schemaCache.clear();
+    }
+  }
+
+  /**
+   * Check if strict mode is enabled
+   * @returns {boolean} True if strict mode enabled
+   */
+  isStrict() {
+    return this.strict;
+  }
+
+  /**
+   * Enable or disable strict mode
+   * @param {boolean} strict - Whether to enable strict mode
+   */
+  setStrict(strict) {
+    this.strict = strict;
+  }
+}
+
+/**
+ * Create a schema validator instance
+ * @param {Object} options - Validator options
+ * @returns {GunSchemaValidator} Validator instance
+ */
+export function createSchemaValidator(options = {}) {
+  return new GunSchemaValidator(options);
+}
+
+export default GunSchemaValidator;