Giao diện
@digiforce-nc/plugin-lock-adapter-redis
Plugin distributed lock qua Redis — đảm bảo chỉ một process xử lý tài nguyên tại một thời điểm trong môi trường multi-instance.
Plugin này làm gì?
Khi chạy nhiều instance (cluster, horizontal scaling), các tác vụ như migration, cron job, hoặc xử lý queue có thể bị chạy đồng thời trên nhiều instance. Plugin sử dụng Redis SET NX (Redlock algorithm) để cung cấp distributed locking — chỉ instance nào acquire được lock mới được thực thi.
Cơ chế hoạt động
Tính năng chính
| # | Tính năng | Mô tả |
|---|---|---|
| 1 | Distributed lock | Khoá phân tán qua Redis SET NX |
| 2 | Auto-expire (TTL) | Tự giải phóng lock sau TTL, tránh deadlock khi crash |
| 3 | Retry with backoff | Tự retry với exponential backoff khi lock bị chiếm |
| 4 | Drop-in adapter | Thay thế lock adapter mặc định (in-memory), zero code change |
| 5 | Lock extension | Gia hạn lock nếu task chạy lâu hơn TTL |
| 6 | Namespace | Prefix key tránh xung đột giữa các ứng dụng |
Cấu hình
| Tham số | Mặc định | Mô tả |
|---|---|---|
redis.url | redis://localhost:6379 | URL kết nối Redis |
ttl | 30000 | Thời gian lock tối đa (ms) |
retryCount | 3 | Số lần retry khi lock bị chiếm |
retryDelay | 200 | Delay giữa các lần retry (ms) |
prefix | lock: | Prefix cho key trong Redis |
Kiến trúc nội bộ
| Thành phần | Vai trò |
|---|---|
| RedisLockAdapter | Implement LockManager interface |
| acquire | Lấy lock bằng SET NX + TTL |
| release | Giải phóng lock bằng DEL (với owner check) |
| extend | Gia hạn TTL cho lock đang giữ |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/server | Server framework — LockManager interface |
@digiforce-nc/database | Lock interface contract |
ioredis | Redis client |
Lưu ý triển khai
- Redis phải accessible từ tất cả instance trong cluster
- TTL nên đủ dài cho task hoàn thành, đủ ngắn để recovery nhanh
- Nếu Redis restart, tất cả lock bị mất — các task sẽ tự retry
- Với Redis Cluster/Sentinel, cấu hình URL tương ứng