{"id":22838657,"url":"https://github.com/plancia/mogu","last_synced_at":"2026-05-19T04:03:03.319Z","repository":{"id":267526279,"uuid":"901243348","full_name":"plancia/mogu","owner":"plancia","description":"Decentralized backup system","archived":false,"fork":false,"pushed_at":"2024-12-23T22:53:15.000Z","size":1942,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-06T08:32:31.335Z","etag":null,"topics":["backup","evm","gundb","ipfs","pinata","storage"],"latest_commit_sha":null,"homepage":"https://mogu-docs.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plancia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-10T09:55:02.000Z","updated_at":"2024-12-23T22:53:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"e799a772-6de8-4477-aa68-1d0b94a93958","html_url":"https://github.com/plancia/mogu","commit_stats":null,"previous_names":["plancia/mogu"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plancia%2Fmogu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plancia%2Fmogu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plancia%2Fmogu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plancia%2Fmogu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plancia","download_url":"https://codeload.github.com/plancia/mogu/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246413244,"owners_count":20773053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","evm","gundb","ipfs","pinata","storage"],"created_at":"2024-12-13T00:07:49.279Z","updated_at":"2026-05-19T04:03:03.253Z","avatar_url":"https://github.com/plancia.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mogu\n\n\u003cimg src=\"https://github.com/scobru/mogu/raw/7588270975ff5f8b7e8c13db86b28ea5fc3fe7f8/mogu.png\" width=\"300\" height=\"auto\" alt=\"Mogu Logo\"\u003e\n\n🔐 Mogu is a modern backup system that solves data security and reliability challenges by combining end-to-end encryption with decentralized IPFS storage.\n\n🌐 Unlike traditional cloud backup services, Mogu ensures your data remains under your control, encrypted before leaving your system, and securely distributed across the IPFS network.\n\n🚀 With advanced features like automatic versioning, smart caching, and detailed version comparison, Mogu is the perfect choice for developers and teams who need a robust, secure, and easy-to-integrate backup system.\n\n## Features\n\n- 🚀 **Simple to Use**: Just a few lines of code to backup and restore\n- 🔒 **End-to-End Encryption**: Your data is always secure\n- 📦 **IPFS Storage**: Decentralized and reliable through Pinata\n- 🔄 **Automatic Versioning**: Track changes over time\n- 💾 **Smart Caching**: Fast operations with intelligent caching\n- 📝 **Structured Logging**: Detailed operation tracking\n- 🔍 **Version Comparison**: Compare backups with local files\n\n## Quick Start\n\n```bash\nyarn add @scobru/mogu\n```\n\nor\n\n```bash\nnpm install @scobru/mogu\n```\n\n\n```typescript\nimport { Mogu } from \"mogu\";\n\n// Initialize Mogu\nconst mogu = new Mogu({\n  storage: {\n    service: 'PINATA' as const,\n    config: {\n      pinataJwt: process.env.PINATA_JWT || '',\n      pinataGateway: process.env.PINATA_GATEWAY || ''\n    }\n  },\n  features: {\n    encryption: {\n      enabled: true,\n      algorithm: \"aes-256-gcm\",\n    },\n  },\n  performance: {\n    maxConcurrent: 3,\n    chunkSize: 1024 * 1024,\n    cacheEnabled: true,\n  },\n});\n\n// Create a backup\nconst backup = await mogu.backup(\"./data\");\nconsole.log(\"Backup created:\", backup.hash);\n\n// Compare changes\nconst comparison = await mogu.compare(backup.hash, \"./data\");\nif (!comparison.isEqual) {\n  console.log(\"Changes detected!\");\n  console.log(`Time since backup: ${comparison.formattedDiff}`);\n}\n\n// Get detailed changes\nconst details = await mogu.compareDetailed(backup.hash, \"./data\");\nconsole.log(`Files added: ${details.totalChanges.added}`);\nconsole.log(`Files modified: ${details.totalChanges.modified}`);\nconsole.log(`Files deleted: ${details.totalChanges.deleted}`);\n\n// Restore from backup\nawait mogu.restore(backup.hash, \"./restored\");\n\n// Delete a backup\nconst deleted = await mogu.delete(backup.hash);\nif (deleted) {\n  console.log(\"Backup deleted successfully\");\n} else {\n  console.log(\"Backup not found or deletion failed\");\n}\n```\n\n## Configuration\n\n```typescript\nconst baseConfig = {\n  storage: {\n    service: 'PINATA' as const,\n    config: {\n      pinataJwt: process.env.PINATA_JWT || '',\n      pinataGateway: process.env.PINATA_GATEWAY || ''\n    }\n  },\n  paths: {\n    backup: './backup',    // Source directory\n    restore: './restore',  // Restore directory\n    storage: './storage', // Local storage\n    logs: path.join(process.cwd(), 'logs')\n  },\n  features: {\n    encryption: {\n      enabled: true,\n      algorithm: 'aes-256-gcm'\n    }\n  }\n};\n\nconst mogu = new Mogu(baseConfig);\n```\n\n## Version Comparison\n\nMogu provides powerful comparison features to track changes between your local files and backups:\n\n```typescript\n// Basic comparison\nconst comparison = await mogu.compare(backup.hash, \"./data\");\nconsole.log(\"Files changed:\", !comparison.isEqual);\nconsole.log(\"Local version is newer:\", comparison.isNewer);\nconsole.log(\"Time difference:\", comparison.formattedDiff);\n\n// Detailed comparison\nconst details = await mogu.compareDetailed(backup.hash, \"./data\");\nconsole.log(\"Added files:\", details.totalChanges.added);\nconsole.log(\"Modified files:\", details.totalChanges.modified);\nconsole.log(\"Deleted files:\", details.totalChanges.deleted);\n\n// Inspect specific changes\ndetails.differences.forEach(diff =\u003e {\n  console.log(`File: ${diff.path}`);\n  console.log(`Change type: ${diff.type}`); // 'added', 'modified', or 'deleted'\n  if (diff.type === \"modified\") {\n    console.log(`Previous size: ${diff.size.old}`);\n    console.log(`New size: ${diff.size.new}`);\n    console.log(`Previous checksum: ${diff.oldChecksum}`);\n    console.log(`New checksum: ${diff.newChecksum}`);\n  }\n});\n```\n\nThe comparison system:\n\n- Supports recursive directory structures\n- Compares actual file contents\n- Provides detailed change information\n- Calculates checksums for each file\n- Tracks file sizes\n\n## Testing Versioning\n\nThe versioning tests verify Mogu's ability to handle different file versions and compare them accurately. The test suite includes:\n\n### Backup and Restore Testing\n- Verifies backup creation and restoration with automatic retries\n- Validates backup integrity through test restorations\n- Handles errors and multiple backup attempts\n\n### Version Testing\n1. **Version 1 (Initial)**\n   - Creates initial files with base content\n   - Verifies correct backup creation\n\n2. **Version 2 (Modifications)**\n   - Modifies existing files\n   - Verifies changes are tracked correctly\n\n3. **Version 3 (Additions and Deletions)**\n   - Adds new files\n   - Removes existing files\n   - Verifies all changes\n\n### Comparison Testing\n- Compares different versions to verify:\n  - Modified files\n  - Added files\n  - Deleted files\n  - Timestamps and time differences\n  - Checksums and data integrity\n\n### Restore Verification\n- Restores each version to separate directories\n- Verifies restored content against expected data\n- Validates restored file integrity\n\n## Storage Providers\n\nCurrently supported:\n\n- **PINATA**: Managed IPFS storage with automatic hash validation and error handling. Requires a Pinata JWT token.\n- **IPFS-CLIENT**: Direct IPFS node connection for decentralized storage. Requires a running IPFS node with its HTTP API endpoint.\n\n### PINATA Configuration\n```typescript\nconst config = {\n  storage: {\n    service: 'PINATA' as const,\n    config: {\n      pinataJwt: process.env.PINATA_JWT || '',\n      pinataGateway: process.env.PINATA_GATEWAY || ''\n    }\n  }\n};\n```\n\n### IPFS-CLIENT Configuration\n```typescript\nconst config = {\n  storage: {\n    service: 'IPFS-CLIENT' as const,\n    config: {\n      url: 'http://localhost:5001' // Your IPFS node HTTP API endpoint\n    }\n  }\n};\n```\n\n## Advanced Usage\n\n### Encrypted Backup\n\n```typescript\n// Backup with encryption\nconst backup = await mogu.backup(\"./data\", {\n  encryption: {\n    enabled: true,\n    key: \"your-encryption-key\",\n  },\n});\n\n// Restore encrypted backup\nawait mogu.restore(backup.hash, \"./restore\", {\n  encryption: {\n    enabled: true,\n    key: \"your-encryption-key\",\n  },\n});\n```\n\n### Direct Storage Operations\n\n```typescript\n// Upload JSON data directly\nconst jsonResult = await mogu.uploadJson({\n  name: \"test\",\n  data: { key: \"value\" }\n});\nconsole.log(\"JSON uploaded:\", jsonResult.id);\n\n// Upload a single file\nconst fileResult = await mogu.uploadFile(\"./path/to/file.txt\");\nconsole.log(\"File uploaded:\", fileResult.id);\n\n// Get data by hash\nconst data = await mogu.getData(\"QmHash...\");\nconsole.log(\"Retrieved data:\", data);\n\n// Get metadata\nconst metadata = await mogu.getMetadata(\"QmHash...\");\nconsole.log(\"Content metadata:\", metadata);\n\n// Check if content is pinned\nconst isPinned = await mogu.isPinned(\"QmHash...\");\nconsole.log(\"Is content pinned?\", isPinned);\n\n// Unpin content\nconst unpinned = await mogu.unpin(\"QmHash...\");\nif (unpinned) {\n  console.log(\"Content unpinned successfully\");\n}\n\n// Get storage service instance\nconst storage = mogu.getStorage();\n```\n\n### Storage Service Methods\n\nMogu fornisce accesso diretto ai metodi del servizio di storage sottostante:\n\n- `uploadJson(jsonData: Record\u003cstring, unknown\u003e)`: Carica dati JSON direttamente su IPFS\n- `uploadFile(path: string)`: Carica un singolo file su IPFS\n- `getData(hash: string)`: Recupera dati da un hash IPFS\n- `getMetadata(hash: string)`: Recupera i metadati associati a un hash\n- `isPinned(hash: string)`: Verifica se un contenuto è pinnato\n- `unpin(hash: string)`: Rimuove il pin di un contenuto\n- `getStorage()`: Ottiene l'istanza del servizio di storage\n\n### Backup Options\n\n```typescript\nconst backup = await mogu.backup(\"./data\", {\n  // Exclude patterns\n  excludePatterns: [\"*.log\", \".DS_Store\"],\n\n  // File size limits\n  maxFileSize: 100 * 1024 * 1024, // 100MB\n\n  // Recursive backup\n  recursive: true,\n\n  // Custom metadata\n  metadata: {\n    description: \"Daily backup\",\n    tags: [\"prod\", \"db\"],\n  },\n});\n```\n\n### General Operations\n\n\n\n\n## Development\n\n```bash\n# Install dependencies\nyarn install\n\n# Run tests\nyarn test\n\n# Build\nyarn build\n```\n\n## License\n\nMIT License\n\nCopyright (c) 2024 scobru\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplancia%2Fmogu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplancia%2Fmogu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplancia%2Fmogu/lists"}