holosphere 2.0.0-alpha1 → 2.0.0-alpha2

package/docs/storage-backends.md

@@ -0,0 +1,326 @@
+# HoloSphere Storage Backends
+
+HoloSphere supports multiple storage backends, allowing you to choose the best option for your deployment requirements. All backends expose the same API, ensuring your application code works identically regardless of which backend you use.
+
+## Available Backends
+
+| Backend | Description | Best For |
+|---------|-------------|----------|
+| **Nostr** (default) | Decentralized relay network | Censorship-resistant, public data |
+| **GunDB** | Real-time P2P database | Offline-first, real-time sync |
+| **ActivityPub** | Fediverse federation | Integration with Mastodon, Pleroma |
+
+---
+
+## Nostr Backend (Default)
+
+The Nostr backend uses the Nostr protocol for decentralized data storage across relay servers.
+
+### Configuration
+
+```javascript
+import HoloSphere from 'holosphere';
+
+const hs = new HoloSphere({
+  appName: 'myapp',
+  backend: 'nostr',  // Optional - this is the default
+  relays: [
+    'wss://relay.damus.io',
+    'wss://relay.nostr.band',
+    'wss://nos.lol'
+  ],
+  privateKey: 'hex-encoded-private-key',  // Optional - auto-generated if not provided
+  persistence: true,  // Enable local caching (default: true)
+  dataDir: './data'   // Custom data directory
+});
+```
+
+### Features
+- Decentralized storage across multiple relays
+- Cryptographic identity via secp256k1 keys
+- Built-in event caching for performance
+- Offline support with guaranteed delivery queue
+- NIP-09 compliant deletion
+
+### When to Use
+- Public, censorship-resistant applications
+- Applications requiring cryptographic verification
+- Social features compatible with Nostr ecosystem
+
+---
+
+## GunDB Backend
+
+The GunDB backend provides real-time P2P synchronization with offline-first capabilities.
+
+### Installation
+
+GunDB is an optional dependency. Install it before using this backend:
+
+```bash
+npm install gun
+```
+
+### Configuration
+
+```javascript
+import HoloSphere from 'holosphere';
+
+const hs = new HoloSphere({
+  appName: 'myapp',
+  backend: 'gundb',
+  gundb: {
+    peers: [
+      'https://gun-us.example.com/gun',
+      'https://gun-eu.example.com/gun'
+    ],
+    radisk: true,       // Persistent storage (default: true)
+    localStorage: true  // Browser localStorage (default: true)
+  },
+  dataDir: './gun-data'
+});
+
+// Wait for backend initialization
+await hs.ready();
+```
+
+### Features
+- Real-time P2P synchronization
+- Offline-first with automatic sync
+- Built-in conflict resolution (CRDT)
+- Works without central server
+
+### When to Use
+- Real-time collaborative applications
+- Offline-first mobile/desktop apps
+- Applications requiring P2P sync without relays
+
+---
+
+## ActivityPub Backend
+
+The ActivityPub backend enables federation with the Fediverse (Mastodon, Pleroma, etc.).
+
+### Architecture
+
+The ActivityPub backend requires a separate server process:
+
+```
+┌─────────────────┐     HTTP      ┌─────────────────────┐
+│  Your App       │◄────────────►│ ActivityPub Server  │
+│  (HoloSphere)   │               │ (holosphere-ap)     │
+└─────────────────┘               └─────────────────────┘
+                                           │
+                                           │ ActivityPub
+                                           ▼
+                                  ┌─────────────────┐
+                                  │  Mastodon/      │
+                                  │  Pleroma/etc    │
+                                  └─────────────────┘
+```
+
+### Starting the Server
+
+```bash
+# Start with default settings
+holosphere-activitypub
+
+# Start with custom configuration
+holosphere-activitypub \
+  --port 3000 \
+  --domain myholosphere.example.com \
+  --data-dir ./ap-data \
+  --protocol https
+
+# Or use environment variables
+export HOLOSPHERE_AP_PORT=3000
+export HOLOSPHERE_AP_DOMAIN=myholosphere.example.com
+export HOLOSPHERE_AP_DATADIR=./ap-data
+export HOLOSPHERE_AP_PROTOCOL=https
+holosphere-activitypub
+```
+
+### Server Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/.well-known/webfinger` | Actor discovery (required for federation) |
+| `/actor/:name` | Actor profile |
+| `/actor/:name/inbox` | Receive activities from federated servers |
+| `/actor/:name/outbox` | Published activities |
+| `/api/data` | HoloSphere data API |
+| `/subscribe` | Server-Sent Events for real-time updates |
+| `/health` | Health check |
+
+### Client Configuration
+
+```javascript
+import HoloSphere from 'holosphere';
+
+const hs = new HoloSphere({
+  appName: 'myapp',
+  backend: 'activitypub',
+  activitypub: {
+    serverUrl: 'http://localhost:3000',
+    apiKey: 'optional-api-key'  // For authentication
+  }
+});
+
+// Wait for connection to server
+await hs.ready();
+```
+
+### Federation with Mastodon
+
+1. Deploy your ActivityPub server with a public domain
+2. Configure HTTPS (required for federation)
+3. Set up DNS records
+4. Users can follow your actors from Mastodon: `@myapp@myholosphere.example.com`
+
+### When to Use
+- Integration with existing Fediverse communities
+- Building social features compatible with Mastodon
+- Applications requiring W3C ActivityPub compliance
+
+---
+
+## Data Migration
+
+HoloSphere provides tools to migrate data between backends.
+
+### Using the Migration Tool
+
+```javascript
+import { MigrationTool, quickMigrate } from 'holosphere/storage/migration';
+
+// Option 1: Full control
+const migration = new MigrationTool();
+
+// Configure source
+await migration.setSource('nostr', {
+  appName: 'myapp',
+  relays: ['wss://relay.damus.io']
+});
+
+// Configure target
+await migration.setTarget('gundb', {
+  appName: 'myapp',
+  gundb: { peers: [] }
+});
+
+// Run migration
+const results = await migration.migrate('myapp/');
+console.log(`Migrated ${results.success} records`);
+
+// Validate
+const validation = await migration.validate('myapp/');
+if (!validation.valid) {
+  console.error('Missing records:', validation.missing);
+}
+
+migration.close();
+
+// Option 2: Quick migrate
+await quickMigrate(
+  { type: 'nostr', appName: 'myapp', relays: ['wss://relay.damus.io'] },
+  { type: 'activitypub', appName: 'myapp', activitypub: { serverUrl: 'http://localhost:3000' } }
+);
+```
+
+### Export/Import for Backup
+
+```javascript
+const migration = new MigrationTool();
+await migration.setSource('nostr', { appName: 'myapp', relays: [] });
+
+// Export to file
+const bundle = await migration.export();
+await migration.exportToFile(bundle, './backup.json');
+
+// Later: Import from file
+const loadedBundle = await migration.importFromFile('./backup.json');
+await migration.setTarget('gundb', { appName: 'myapp', gundb: {} });
+await migration.import(loadedBundle);
+```
+
+---
+
+## Choosing a Backend
+
+| Requirement | Recommended Backend |
+|-------------|---------------------|
+| Censorship resistance | Nostr |
+| Real-time collaboration | GunDB |
+| Fediverse integration | ActivityPub |
+| Offline-first | GunDB or Nostr |
+| Cryptographic identity | Nostr |
+| Self-hosted | Any (Nostr relays, Gun peers, or AP server) |
+
+---
+
+## Custom Backends
+
+You can implement custom storage backends by extending the `StorageBackend` interface:
+
+```javascript
+import { StorageBackend, BackendFactory } from 'holosphere/storage';
+
+class MyCustomBackend extends StorageBackend {
+  async init() { /* ... */ }
+  buildPath(appName, holonId, lensName, key) { /* ... */ }
+  async write(path, data, options) { /* ... */ }
+  async read(path, options) { /* ... */ }
+  async readAll(path, options) { /* ... */ }
+  async update(path, updates) { /* ... */ }
+  async delete(path) { /* ... */ }
+  async deleteAll(path) { /* ... */ }
+  async subscribe(path, callback, options) { /* ... */ }
+  async exportData(pathPrefix) { /* ... */ }
+  async importData(records, options) { /* ... */ }
+  close() { /* ... */ }
+  getStatus() { /* ... */ }
+}
+
+// Register custom backend
+BackendFactory.register('custom', MyCustomBackend);
+
+// Use it
+const hs = new HoloSphere({
+  appName: 'myapp',
+  backend: 'custom',
+  // ... custom config
+});
+```
+
+---
+
+## Backend API Reference
+
+All backends implement the `StorageBackend` interface:
+
+```typescript
+interface StorageBackend {
+  // Initialization
+  init(): Promise<void>;
+  close(): void;
+  getStatus(): BackendStatus;
+
+  // Path building
+  buildPath(appName: string, holonId: string, lensName: string, key?: string): string;
+
+  // CRUD operations
+  write(path: string, data: object, options?: WriteOptions): Promise<boolean>;
+  read(path: string, options?: ReadOptions): Promise<object | null>;
+  readAll(path: string, options?: ReadOptions): Promise<object[]>;
+  update(path: string, updates: object): Promise<boolean>;
+  delete(path: string): Promise<boolean>;
+  deleteAll(path: string): Promise<{ success: boolean; count: number }>;
+
+  // Subscriptions
+  subscribe(path: string, callback: Function, options?: SubOptions): Promise<Subscription>;
+
+  // Migration
+  exportData(pathPrefix?: string): Promise<ExportRecord[]>;
+  importData(records: ExportRecord[], options?: ImportOptions): Promise<ImportResults>;
+}
+```