Cluster Management

Tổng quan

Cluster là nhóm các cache nodes làm việc cùng nhau. ClusterManager xử lý vòng đời node, theo dõi sức khỏe, và failover tự động.

┌─────────────────────────────────────────┐
│           ClusterManager                │
│  ┌─────┐  ┌─────┐  ┌─────┐           │
│  │Node0│  │Node1│  │Node2│           │
│  │ ✅  │  │ ✅  │  │ ❌  │ ← failed  │
│  └─────┘  └─────┘  └─────┘           │
│       ↓         ↓         ↓            │
│    primary   backup   (removed)        │
└─────────────────────────────────────────┘

Singleton Pattern

ClusterManager là singleton — chỉ có 1 instance per application:

import { ClusterManager } from "distributed-cache";

const cluster = ClusterManager.getInstance();

// Thêm nodes
cluster.addNode(new CacheNode("node-0", { maxSize: 10000 }));
cluster.addNode(new CacheNode("node-1", { maxSize: 10000 }));
cluster.addNode(new CacheNode("node-2", { maxSize: 10000 }));

Theo dõi sức khỏe

Bật heartbeat để phát hiện node bị lỗi:

// Kiểm tra mỗi 5 giây, đánh dấu unhealthy sau 3 lần miss heartbeat
cluster.startHeartbeat(5000, 3);

// Callback khi node gặp sự cố
cluster.setOnNodeFailed((nodeId) => {
  console.log(`Node ${nodeId} gặp sự cố!`);
  // Tùy chọn: promote backup lên primary
});

Thao tác với Node

// Lấy node cho một key (qua consistent hashing)
const node = cluster.getNode("user:123");

// Lấy node cụ thể theo ID
const specific = cluster.getNodeById("node-0");

// Lấy tất cả healthy nodes
const healthy = cluster.getHealthyNodes();

// Lấy/đặt primary node
cluster.setPrimary(node0);
const primary = cluster.getPrimary();

// Đánh dấu trạng thái sức khỏe
cluster.markUnhealthy("node-0");
cluster.markHealthy("node-0");

// Xóa node bị lỗi
cluster.removeNode("node-0");

Cluster Flush

Xóa tất cả nodes cùng lúc:

const freed = cluster.flushAll();
console.log(`Đã giải phóng ${(freed / 1024 / 1024).toFixed(2)} MB`);

Thống kê

const stats = cluster.getStats();
console.log(stats);
// {
//   totalNodes: 3,
//   healthyNodes: 2,
//   unhealthyNodes: 1,
//   primary: "node-0",
//   totalKeys: 15000
// }

Leader Election

Khi primary node gặp sự cố, cluster elect leader mới:

1. Primary node ngừng phản hồi heartbeat
2. ClusterManager đánh dấu unhealthy
3. Healthy node tiếp theo trở thành primary
4. Clients redirect sang primary mới

Thực hành tốt nhất

Thực hành	Tại sao
Luôn thiết lập heartbeat	Phát hiện sự cố nhanh
Dùng callback setOnNodeFailed	Phản ứng real-time với sự cố
Theo dõi cluster stats	Theo dõi sức khỏe theo thời gian
Đặt timeout phù hợp	Quá ngắn = false positives, quá dài = phát hiện chậm