A modern TypeScript library for synchronizing Redux stores across multiple processes and machines using TCP, Unix Domain Sockets, and IPC.
🌐 Need WebSocket support for browsers? Check out redux-cluster-ws - our companion package that extends Redux Cluster with WebSocket transport for browser clients.
- 🔄 Real-time State Synchronization across multiple processes/machines
- 🌐 Multiple Transport Options: TCP, Unix Domain Sockets, IPC
- 🌍 WebSocket Support: Available via redux-cluster-ws
- 📡 Bidirectional Communication - any node can dispatch actions
- 🔒 Built-in Security with authentication and IP banning
- ⚡ High Performance with optimized networking and compression
- 🏗️ Master-Slave Architecture with automatic leader election
- 🔧 TypeScript First with comprehensive type definitions
- 🎯 Redux Compatible - works with existing Redux ecosystem
Redux Cluster implements a master-slave architecture where one server manages the authoritative state and distributes updates to all connected clients:
┌─────────────────────────────────────────────────────────────────┐
│ Redux Cluster Network │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ TCP/Socket ┌─────────────┐ │
│ │ Client A │◄───────────────────────────►│ Server │ │
│ │ (Worker) │ │ (Master) │ │
│ └─────────────┘ │ │ │
│ │ │ │
│ ┌─────────────┐ TCP/Socket │ │ │
│ │ Client B │◄───────────────────────────►│ │ │
│ │ (Worker) │ │ │ │
│ └─────────────┘ └─────────────┘ │
│ │ │
│ ┌─────────────┐ TCP/Socket │ │
│ │ Client C │◄─────────────────────────────────────┘ │
│ │ (Worker) │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────┐ 1. Action ┌─────────────┐ 2. Process ┌─────────────┐
│ Client │─────────────────►│ Server │────────────────►│ Redux │
│ │ │ (Master) │ │ Store │
└─────────────┘ └─────────────┘ └─────────────┘
▲ │ │
│ ▼ │
│ 4. State Update ┌─────────────┐ 3. State Changed │
└──────────────────────────│ Broadcast │◄──────────────────────┘
│ Engine │
└─────────────┘
│
▼
┌─────────────────────┐
│ All Clients │
│ (Auto-sync) │
└─────────────────────┘
npm install redux-cluster reduxServer (Master):
const { createStore } = require('redux-cluster');
// Simple counter reducer
const counterReducer = (state = { counter: 0 }, action) => {
switch (action.type) {
case 'INCREMENT': return { counter: state.counter + 1 };
case 'DECREMENT': return { counter: state.counter - 1 };
default: return state;
}
};
// Create store and server
const store = createStore(counterReducer);
const server = store.createServer({ port: 8080 });
console.log('Server started on port 8080');
// Server can dispatch actions
store.dispatch({ type: 'INCREMENT' });Client (Worker):
const { createStore } = require('redux-cluster');
const store = createStore(counterReducer);
const client = store.createClient({
host: 'localhost',
port: 8080
});
// Client receives all state updates automatically
store.subscribe(() => {
console.log('New state:', store.getState());
});
// Client can also dispatch actions
store.dispatch({ type: 'INCREMENT' });Redux Cluster supports multiple transport mechanisms:
// Server
const server = store.createServer({
host: 'localhost',
port: 8080
});
// Client
const client = store.createClient({
host: 'localhost',
port: 8080
});// Server
const server = store.createServer({
path: '/tmp/redux-cluster.sock'
});
// Client
const client = store.createClient({
path: '/tmp/redux-cluster.sock'
});import cluster from 'cluster';
if (cluster.isMaster) {
const store = createStore(reducer);
cluster.fork(); // Start worker
} else {
const store = createStore(reducer);
// IPC automatically enabled in cluster workers
}const server = store.createServer({
host: 'localhost', // TCP host
port: 8080, // TCP port
path: '/tmp/app.sock', // Unix socket path
logins: { // Authentication
'user1': 'password1',
'user2': 'password2'
}
});const client = store.createClient({
host: 'localhost', // TCP host
port: 8080, // TCP port
path: '/tmp/app.sock', // Unix socket path
login: 'user1', // Authentication
password: 'password1'
});const store = createStore(reducer, {
mode: 'action', // 'action' | 'snapshot'
serializationMode: 'json', // 'json' | 'protoobject'
debug: false, // Enable debug logging
resync: 30000 // Resync interval (ms)
});Actions are distributed and replayed on all nodes:
Client A: dispatch(ACTION) ──► Server ──► broadcast(ACTION) ──► All Clients
│
▼
Apply ACTION to master state
Complete state snapshots are distributed:
Client A: dispatch(ACTION) ──► Server ──► calculate new state ──► broadcast(STATE) ──► All Clients
const server = store.createServer({
logins: {
'api-service': 'secret-key-123',
'worker-pool': 'another-secret'
}
});
const client = store.createClient({
login: 'api-service',
password: 'secret-key-123'
});Automatic IP banning after failed authentication attempts:
- 5+ failed attempts = 3 hour ban
- Automatic cleanup of expired bans
- Configurable ban policies
See the examples/ directory for complete working examples:
- TCP Transport - Network communication
- File Socket - Local IPC via Unix sockets
- Basic Store - Local Redux store without networking
🌐 WebSocket Examples: For browser integration examples with WebSocket transport, visit the redux-cluster-ws examples.
Each example includes a README with step-by-step instructions.
WebSocket transport layer for Redux Cluster, enabling browser client support:
npm install redux-cluster-wsFeatures:
- 🌐 WebSocket server and client
- 🔗 Seamless integration with Redux Cluster
- 🖥️ Browser support for web applications
- 📱 Real-time state synchronization to browsers
- 🔒 Same security features as core package
Links:
- 📋 NPM Package
- 📖 Documentation
- 🎯 Examples
# Run all tests
npm test
# Run specific test suites
npm run test:unit # Unit tests
npm run test:transport # Transport integration tests
# Build and test
npm run build
npm run lint
# Run full integration tests (includes Docker)
npm run test:integration-fullRedux Cluster is optimized for high-throughput scenarios:
- Compression: gzip compression for all network traffic
- Binary Protocol: Efficient binary serialization options
- Connection Pooling: Reuse connections where possible
- Minimal Overhead: < 1ms latency for local sockets
Benchmark results:
- TCP: ~10,000 actions/sec
- Unix Sockets: ~50,000 actions/sec
- IPC: ~100,000 actions/sec
- [ ] Redis Transport - Redis pub/sub for clustering
- [x] WebSocket Transport - Available in redux-cluster-ws
- [ ] Conflict Resolution - CRDT-based conflict resolution
- [ ] Persistence Layer - Automatic state persistence
- [ ] Monitoring Dashboard - Real-time cluster monitoring
- [ ] Load Balancing - Multiple master support
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
git clone https://github.com/siarheidudko/redux-cluster.git
cd redux-cluster
npm install
npm run build
npm testMIT License - see LICENSE file for details.
- 📝 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: siarhei@dudko.dev
If Redux Cluster helps you build amazing applications, consider supporting its development:
- ☕ Buy me a coffee
- 💳 PayPal
- 🎯 Patreon
- 🌐 More options
Your support helps maintain and improve Redux Cluster for the entire community!
Made with ❤️ by Siarhei Dudko