{"_id":"@ahmedbanihani/ahmed-rivet","name":"@ahmedbanihani/ahmed-rivet","dist-tags":{"latest":"0.2.7"},"versions":{"0.2.7":{"name":"@ahmedbanihani/ahmed-rivet","version":"0.2.7","description":"Zero Cache with binary protocol support (MessagePack + Gzip compression) and optimized performance","main":"index.js","types":"index.d.ts","repository":{"type":"git","url":"git+https://github.com/ahmedbanihani/ahmed-rivet.git"},"keywords":["zero-cache","replication","sync","binary-protocol","messagepack","real-time","database-sync","supabase","neon"],"author":{"name":"Ahmed Banihani","email":"ahmedbanihani@example.com"},"license":"MIT","peerDependencies":{"@msgpack/msgpack":"^3.0.0","pako":"^2.1.0"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"_id":"@ahmedbanihani/ahmed-rivet@0.2.7","bugs":{"url":"https://github.com/ahmedbanihani/ahmed-rivet/issues"},"homepage":"https://github.com/ahmedbanihani/ahmed-rivet#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-7ktb5NOr6Co7eoMzvl/zreMlN+LYE9ZdqoTMT6Y7UXuLgsx7k/fE1uSJWybbD7nqJRx2cHOqEToJLTO85iA3Kg==","shasum":"7e791e87b44af66b388e417a420599423e60be9a","tarball":"https://registry.npmjs.org/@ahmedbanihani/ahmed-rivet/-/ahmed-rivet-0.2.7.tgz","fileCount":5,"unpackedSize":7020,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDdobFsYcfJyACd65VKUnZVxEA7w2EfyjNWJcCfF99mvgIhANJ6wswpyIqd5LLEIcZZTkI2YhRD+HU0qu8832uZceMj"}]},"_npmUser":{"name":"ahmedbanihani","email":"awsahmedbanihani@mail.com"},"directories":{},"maintainers":[{"name":"ahmedbanihani","email":"awsahmedbanihani@mail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ahmed-rivet_0.2.7_1762278953663_0.9065227509971592"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-04T17:55:53.526Z","0.2.7":"2025-11-04T17:55:53.865Z","modified":"2025-11-04T17:55:54.247Z"},"maintainers":[{"name":"ahmedbanihani","email":"awsahmedbanihani@mail.com"}],"description":"Zero Cache with binary protocol support (MessagePack + Gzip compression) and optimized performance","homepage":"https://github.com/ahmedbanihani/ahmed-rivet#readme","keywords":["zero-cache","replication","sync","binary-protocol","messagepack","real-time","database-sync","supabase","neon"],"repository":{"type":"git","url":"git+https://github.com/ahmedbanihani/ahmed-rivet.git"},"author":{"name":"Ahmed Banihani","email":"ahmedbanihani@example.com"},"bugs":{"url":"https://github.com/ahmedbanihani/ahmed-rivet/issues"},"license":"MIT","readme":"# @ahmedbanihani/ahmed-rivet\n\nZero Cache with binary protocol support (MessagePack + Gzip compression) and optimized performance for real-time data synchronization.\n\n## Features\n\n- **Binary Protocol**: MessagePack encoding with Gzip compression\n- **Smart Compression**: Only compresses payloads larger than 1KB\n- **Fast Compression**: Level 1 Gzip for optimal speed\n- **Database Separation**: Supports Supabase + Neon architecture\n- **Connection Pooling**: Neon pooler support for CVR/CHANGE databases\n- **Production Ready**: Stable deployment with persistent replica storage\n\n## Docker Image\n\n```bash\ndocker pull awsahmedbanihani/ahmed-rivet:latest\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\n# Database Configuration\nZERO_UPSTREAM_DB=postgresql://...\nZERO_CVR_DB=postgresql://...  # Supports Neon pooler\nZERO_CHANGE_DB=postgresql://... # Supports Neon pooler\n\n# Connection Limits\nZERO_UPSTREAM_MAX_CONNS=5\nZERO_CVR_MAX_CONNS=5\nZERO_CHANGE_MAX_CONNS=2\n\n# Worker Configuration\nZERO_NUM_SYNC_WORKERS=5\n\n# Stability Settings\nZERO_AUTO_RESET=false\nZERO_REPLICA_FILE=/data/replica.db\n\n# Core Settings\nZERO_APP_ID=your-app-id\nZERO_PORT=4848\n```\n\n### Docker Deployment\n\n```bash\n# Create persistent volume\nmkdir -p /data/zero-replica\n\n# Run container\ndocker run -d \\\n  --name zero-cache \\\n  -p 4848:4848 \\\n  -v /data/zero-replica:/data \\\n  --env-file .env \\\n  -e ZERO_LOG_FORMAT=text \\\n  -e ZERO_REPLICA_FILE=/data/replica.db \\\n  -e ZERO_UPSTREAM_MAX_CONNS=5 \\\n  -e ZERO_CVR_MAX_CONNS=5 \\\n  -e ZERO_CHANGE_MAX_CONNS=2 \\\n  -e ZERO_NUM_SYNC_WORKERS=5 \\\n  --health-cmd='curl -f http://localhost:4848/ || exit 1' \\\n  --health-interval=30s \\\n  --health-timeout=5s \\\n  --health-retries=3 \\\n  --health-start-period=15s \\\n  --restart unless-stopped \\\n  awsahmedbanihani/ahmed-rivet:latest\n```\n\n## Performance\n\n### Binary Protocol Compression\n\n- **MessagePack**: 60-70% size reduction vs JSON\n- **MessagePack + Gzip**: 85-95% size reduction vs JSON\n- **Compression Level**: 1 (fastest)\n- **Compression Threshold**: 1KB (smart compression)\n\n### Database Latency\n\n- Supabase: ~193-198ms average ping\n- Neon Pooler: ~192-202ms average ping\n\n## Architecture\n\n### Database Separation\n\n- **Upstream DB**: Supabase Direct (port 5432) - application data\n- **CVR DB**: Neon Pooler - client view records metadata\n- **CHANGE DB**: Neon Pooler - change tracking metadata\n\n### Why Neon Pooler?\n\nSupabase's transaction pooler (port 6543) does NOT support `statement_timeout` parameter. Neon's pooler supports full PostgreSQL compatibility including `statement_timeout`.\n\n## Health Check\n\n```bash\ncurl http://localhost:4848/\n# Response: OK\n```\n\n## Monitoring\n\n```bash\n# Check restart count\ndocker inspect zero-cache --format='Restarts: {{.RestartCount}}'\n\n# Monitor query performance\ndocker logs zero-cache -f | grep \"processing queries\"\n\n# Check worker count\ndocker logs zero-cache | grep \"worker=syncer.*telemetry\" | wc -l\n```\n\n## Troubleshooting\n\n### Container Restarts\n\nIf container restarts frequently:\n\n1. Check `ZERO_AUTO_RESET` is set to `false`\n2. Verify persistent volume is mounted\n3. Check Supabase replication slots:\n   ```sql\n   SELECT * FROM pg_replication_slots WHERE slot_name LIKE 'your-app%';\n   ```\n\n### Connection Issues\n\nIf experiencing connection errors:\n\n1. Increase connection limits:\n   ```bash\n   ZERO_UPSTREAM_MAX_CONNS=20\n   ZERO_CVR_MAX_CONNS=20\n   ```\n\n2. Reduce worker count:\n   ```bash\n   ZERO_NUM_SYNC_WORKERS=2\n   ```\n\n## License\n\nMIT\n\n## Author\n\nAhmed Banihani\n\n## Version\n\n0.2.7-optimized\n","readmeFilename":"README.md","_rev":"1-ceab3c328a28822c9622c4fef3abd64c"}