{"id":18597827,"url":"https://github.com/siarheidudko/redux-cluster","last_synced_at":"2026-05-02T03:10:09.706Z","repository":{"id":52067352,"uuid":"152054488","full_name":"siarheidudko/redux-cluster","owner":"siarheidudko","description":"A modern TypeScript library for synchronizing Redux stores across multiple processes and machines using TCP, Unix Domain Sockets, and IPC.","archived":false,"fork":false,"pushed_at":"2026-03-31T01:33:26.000Z","size":9473,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T08:38:24.772Z","etag":null,"topics":["cluster","ipc","node-cluster","nodejs","nodejs-server","redux"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/redux-cluster","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/siarheidudko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":"FUNDING.yml","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"dudko_dev","custom":["http://dudko.dev/donate","https://paypal.me/dudkodev","https://www.buymeacoffee.com/dudko.dev"]}},"created_at":"2018-10-08T09:37:40.000Z","updated_at":"2026-03-31T01:33:29.000Z","dependencies_parsed_at":"2025-09-26T04:14:21.988Z","dependency_job_id":"b5652384-eb47-4c4d-b74c-bbde516e40ce","html_url":"https://github.com/siarheidudko/redux-cluster","commit_stats":null,"previous_names":[],"tags_count":106,"template":false,"template_full_name":null,"purl":"pkg:github/siarheidudko/redux-cluster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siarheidudko%2Fredux-cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siarheidudko%2Fredux-cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siarheidudko%2Fredux-cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siarheidudko%2Fredux-cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/siarheidudko","download_url":"https://codeload.github.com/siarheidudko/redux-cluster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/siarheidudko%2Fredux-cluster/sbom","scorecard":{"id":822118,"data":{"date":"2025-08-11","repo":{"name":"github.com/siarheidudko/redux-cluster","commit":"0e71321bbd3f2913c3acb5be7e3f5a84c4970c0f"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.7,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"project is archived","details":["Warn: Repository is archived."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw","Warn: Project is vulnerable to: GHSA-29mw-wpgm-hmr9","Warn: Project is vulnerable to: GHSA-35jh-r3h4-6jhm"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-23T15:51:58.213Z","repository_id":52067352,"created_at":"2025-08-23T15:51:58.213Z","updated_at":"2025-08-23T15:51:58.213Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32521171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cluster","ipc","node-cluster","nodejs","nodejs-server","redux"],"created_at":"2024-11-07T01:29:34.919Z","updated_at":"2026-05-02T03:10:09.269Z","avatar_url":"https://github.com/siarheidudko.png","language":"TypeScript","funding_links":["https://patreon.com/dudko_dev","http://dudko.dev/donate","https://paypal.me/dudkodev","https://www.buymeacoffee.com/dudko.dev"],"categories":[],"sub_categories":[],"readme":"# Redux Cluster 2.0\n\n[![npm](https://img.shields.io/npm/v/redux-cluster.svg)](https://www.npmjs.com/package/redux-cluster)\n[![npm](https://img.shields.io/npm/dy/redux-cluster.svg)](https://www.npmjs.com/package/redux-cluster)\n[![NpmLicense](https://img.shields.io/npm/l/redux-cluster.svg)](https://www.npmjs.com/package/redux-cluster)\n![GitHub last commit](https://img.shields.io/github/last-commit/siarheidudko/redux-cluster.svg)\n![GitHub release](https://img.shields.io/github/release/siarheidudko/redux-cluster.svg)\n\nA modern TypeScript library for synchronizing Redux stores across multiple processes and machines using TCP, Unix Domain Sockets, and IPC.\n\n\u003e 🌐 **Need WebSocket support for browsers?** Check out [redux-cluster-ws](https://www.npmjs.com/package/redux-cluster-ws) - our companion package that extends Redux Cluster with WebSocket transport for browser clients.\n\n## 🌟 Key Features\n\n- 🔄 **Real-time State Synchronization** across multiple processes/machines\n- 🌐 **Multiple Transport Options**: TCP, Unix Domain Sockets, IPC\n- 🌍 **WebSocket Support**: Available via [redux-cluster-ws](https://www.npmjs.com/package/redux-cluster-ws)\n- 📡 **Bidirectional Communication** - any node can dispatch actions\n- 🔒 **Built-in Security** with authentication and IP banning\n- ⚡ **High Performance** with optimized networking and compression\n- 🏗️ **Master-Slave Architecture** with automatic leader election\n- 🔧 **TypeScript First** with comprehensive type definitions\n- 🎯 **Redux Compatible** - works with existing Redux ecosystem\n\n## 🏛️ Architecture Overview\n\nRedux Cluster implements a master-slave architecture where one server manages the authoritative state and distributes updates to all connected clients:\n\n```ascii\n┌─────────────────────────────────────────────────────────────────┐\n│                        Redux Cluster Network                    │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                 │\n│  ┌─────────────┐         TCP/Socket          ┌─────────────┐    │\n│  │   Client A  │◄───────────────────────────►│   Server    │    │\n│  │  (Worker)   │                             │  (Master)   │    │\n│  └─────────────┘                             │             │    │\n│                                              │             │    │\n│  ┌─────────────┐         TCP/Socket          │             │    │\n│  │   Client B  │◄───────────────────────────►│             │    │\n│  │  (Worker)   │                             │             │    │\n│  └─────────────┘                             └─────────────┘    │\n│                                                       │         │\n│  ┌─────────────┐         TCP/Socket                   │         │\n│  │   Client C  │◄─────────────────────────────────────┘         │\n│  │  (Worker)   │                                                │\n│  └─────────────┘                                                │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Data Flow\n\n```ascii\n┌─────────────┐    1. Action     ┌─────────────┐    2. Process   ┌─────────────┐\n│   Client    │─────────────────►│   Server    │────────────────►│    Redux    │\n│             │                  │  (Master)   │                 │   Store     │\n└─────────────┘                  └─────────────┘                 └─────────────┘\n       ▲                                │                               │\n       │                                ▼                               │\n       │         4. State Update  ┌─────────────┐    3. State Changed   │\n       └──────────────────────────│  Broadcast  │◄──────────────────────┘\n                                  │   Engine    │\n                                  └─────────────┘\n                                         │\n                                         ▼\n                              ┌─────────────────────┐\n                              │    All Clients      │\n                              │   (Auto-sync)       │\n                              └─────────────────────┘\n```\n\n## 🚀 Quick Start\n\n### 1. Installation\n\n```bash\nnpm install redux-cluster redux\n```\n\n### 2. Basic TCP Example\n\n**Server (Master):**\n\n```javascript\nconst { createStore } = require('redux-cluster');\n\n// Simple counter reducer\nconst counterReducer = (state = { counter: 0 }, action) =\u003e {\n  switch (action.type) {\n    case 'INCREMENT': return { counter: state.counter + 1 };\n    case 'DECREMENT': return { counter: state.counter - 1 };\n    default: return state;\n  }\n};\n\n// Create store and server\nconst store = createStore(counterReducer);\nconst server = store.createServer({ port: 8080 });\n\nconsole.log('Server started on port 8080');\n\n// Server can dispatch actions\nstore.dispatch({ type: 'INCREMENT' });\n```\n\n**Client (Worker):**\n\n```javascript\nconst { createStore } = require('redux-cluster');\n\nconst store = createStore(counterReducer);\nconst client = store.createClient({ \n  host: 'localhost', \n  port: 8080 \n});\n\n// Client receives all state updates automatically\nstore.subscribe(() =\u003e {\n  console.log('New state:', store.getState());\n});\n\n// Client can also dispatch actions\nstore.dispatch({ type: 'INCREMENT' });\n```\n\n## 🌐 Transport Options\n\nRedux Cluster supports multiple transport mechanisms:\n\n### TCP (Network)\n\n```javascript\n// Server\nconst server = store.createServer({ \n  host: 'localhost',\n  port: 8080 \n});\n\n// Client  \nconst client = store.createClient({ \n  host: 'localhost',\n  port: 8080 \n});\n```\n\n### Unix Domain Sockets (Local)\n\n```javascript\n// Server\nconst server = store.createServer({ \n  path: '/tmp/redux-cluster.sock' \n});\n\n// Client\nconst client = store.createClient({ \n  path: '/tmp/redux-cluster.sock' \n});\n```\n\n### IPC (Node.js Cluster)\n\n```javascript\nimport cluster from 'cluster';\n\nif (cluster.isMaster) {\n  const store = createStore(reducer);\n  cluster.fork(); // Start worker\n} else {\n  const store = createStore(reducer);\n  // IPC automatically enabled in cluster workers\n}\n```\n\n## 🔧 Configuration Options\n\n### Server Configuration\n\n```typescript\nconst server = store.createServer({\n  host: 'localhost',     // TCP host\n  port: 8080,           // TCP port  \n  path: '/tmp/app.sock', // Unix socket path\n  logins: {             // Authentication\n    'user1': 'password1',\n    'user2': 'password2'\n  }\n});\n```\n\n### Client Configuration\n\n```typescript\nconst client = store.createClient({\n  host: 'localhost',     // TCP host\n  port: 8080,           // TCP port\n  path: '/tmp/app.sock', // Unix socket path\n  login: 'user1',       // Authentication\n  password: 'password1'\n});\n```\n\n### Store Configuration\n\n```typescript\nconst store = createStore(reducer, {\n  mode: 'action',           // 'action' | 'snapshot'\n  serializationMode: 'json', // 'json' | 'protoobject'\n  debug: false,             // Enable debug logging\n  resync: 30000            // Resync interval (ms)\n});\n```\n\n## 📊 Synchronization Modes\n\n### Action Mode (Default)\n\nActions are distributed and replayed on all nodes:\n\n```ascii\nClient A: dispatch(ACTION) ──► Server ──► broadcast(ACTION) ──► All Clients\n                                  │\n                                  ▼\n                              Apply ACTION to master state\n```\n\n### Snapshot Mode\n\nComplete state snapshots are distributed:\n\n```ascii\nClient A: dispatch(ACTION) ──► Server ──► calculate new state ──► broadcast(STATE) ──► All Clients\n```\n\n## 🔒 Security Features\n\n### Authentication\n\n```javascript\nconst server = store.createServer({\n  logins: {\n    'api-service': 'secret-key-123',\n    'worker-pool': 'another-secret'\n  }\n});\n\nconst client = store.createClient({\n  login: 'api-service',\n  password: 'secret-key-123'\n});\n```\n\n### IP Banning\n\nAutomatic IP banning after failed authentication attempts:\n\n- 5+ failed attempts = 3 hour ban\n- Automatic cleanup of expired bans\n- Configurable ban policies\n\n## 🎮 Examples\n\nSee the [examples/](./examples/) directory for complete working examples:\n\n- **[TCP Transport](./examples/tcp/)** - Network communication\n- **[File Socket](./examples/file-socket/)** - Local IPC via Unix sockets\n- **[Basic Store](./examples/basic/)** - Local Redux store without networking\n\n\u003e 🌐 **WebSocket Examples**: For browser integration examples with WebSocket transport, visit the [redux-cluster-ws examples](https://github.com/siarheidudko/redux-cluster-ws/tree/main/examples).\n\nEach example includes a README with step-by-step instructions.\n\n## 📦 Related Packages\n\n### redux-cluster-ws\n\nWebSocket transport layer for Redux Cluster, enabling browser client support:\n\n```bash\nnpm install redux-cluster-ws\n```\n\n**Features:**\n\n- 🌐 WebSocket server and client\n- 🔗 Seamless integration with Redux Cluster\n- 🖥️ Browser support for web applications  \n- 📱 Real-time state synchronization to browsers\n- 🔒 Same security features as core package\n\n**Links:**\n\n- 📋 [NPM Package](https://www.npmjs.com/package/redux-cluster-ws)\n- 📖 [Documentation](https://github.com/siarheidudko/redux-cluster-ws)\n- 🎯 [Examples](https://github.com/siarheidudko/redux-cluster-ws/tree/main/examples)\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test suites\nnpm run test:unit       # Unit tests\nnpm run test:transport  # Transport integration tests\n\n# Build and test\nnpm run build\nnpm run lint\n\n# Run full integration tests (includes Docker)\nnpm run test:integration-full\n```\n\n## 📈 Performance\n\nRedux Cluster is optimized for high-throughput scenarios:\n\n- **Compression**: gzip compression for all network traffic\n- **Binary Protocol**: Efficient binary serialization options\n- **Connection Pooling**: Reuse connections where possible\n- **Minimal Overhead**: \u003c 1ms latency for local sockets\n\nBenchmark results:\n\n- TCP: ~10,000 actions/sec\n- Unix Sockets: ~50,000 actions/sec\n- IPC: ~100,000 actions/sec\n\n## 🗺️ Roadmap\n\n- [ ] **Redis Transport** - Redis pub/sub for clustering\n- [x] **WebSocket Transport** - Available in [redux-cluster-ws](https://www.npmjs.com/package/redux-cluster-ws)\n- [ ] **Conflict Resolution** - CRDT-based conflict resolution\n- [ ] **Persistence Layer** - Automatic state persistence\n- [ ] **Monitoring Dashboard** - Real-time cluster monitoring\n- [ ] **Load Balancing** - Multiple master support\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/siarheidudko/redux-cluster.git\ncd redux-cluster\nnpm install\nnpm run build\nnpm test\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) file for details.\n\n## 🆘 Support\n\n- 📝 **Issues**: [GitHub Issues](https://github.com/siarheidudko/redux-cluster/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/siarheidudko/redux-cluster/discussions)\n- 📧 **Email**: [siarhei@dudko.dev](mailto:siarhei@dudko.dev)\n\n## 💝 Support This Project\n\nIf Redux Cluster helps you build amazing applications, consider supporting its development:\n\n- ☕ **[Buy me a coffee](https://www.buymeacoffee.com/dudko.dev)**\n- 💳 **[PayPal](https://paypal.me/dudkodev)**\n- 🎯 **[Patreon](https://patreon.com/dudko_dev)**\n- 🌐 **[More options](http://dudko.dev/donate)**\n\nYour support helps maintain and improve Redux Cluster for the entire community!\n\n---\n\n**Made with ❤️ by [Siarhei Dudko](https://github.com/siarheidudko)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiarheidudko%2Fredux-cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiarheidudko%2Fredux-cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiarheidudko%2Fredux-cluster/lists"}