HieraChain đẩy thông báo khối mới và sự kiện mới tới client đang kết nối qua WebSocket. Client có thể đăng ký theo chuỗi cụ thể hoặc theo loại sự kiện. Vòng lặp ping nền giám sát kết nối chết và tự giải phóng.
WebSocketManager là singleton (ws_manager) dùng chung cho mọi route API để quản lý đăng ký tập trung.
Biểu đồ luồng: vòng đời kết nối và broadcast
sequenceDiagram
autonumber
participant Client as 🖥️ Trình duyệt / SDK Client
participant WS as 🔌 WebSocket Endpoint
participant WSM as 📡 WebSocketManager
participant SC as 📦 SubChain
Client->>WS: Nâng cấp giao thức WebSocket (GET /ws/{chain_name})
WS->>WSM: connect(connection_id, websocket, chain_name)
WSM->>WSM: Kiểm tra max_connections (mặc định 1000)
WSM->>WSM: Registry.add(connection_id, conn)
WSM->>WSM: SubscriptionManager.subscribe_to_chain(connection_id, chain_name)
WS-->>Client: Kết nối thành công ✅
opt Client lọc theo loại sự kiện cụ thể
Client->>WS: { "action": "subscribe", "event_types": ["quality_check", ...] }
WS->>WSM: subscribe(connection_id, chain_name, event_types)
WSM->>WSM: SubscriptionManager.subscribe_to_event_type(...)
end
Note over SC: Khối đã được hoàn tất (Gửi Sự kiện - bước 8)
SC->>WSM: broadcast_new_block(chain_name, block_data)
WSM->>WSM: get_chain_subscribers(chain_name)
loop Với từng người đăng ký
WSM->>Client: send_text(JSON { type: "block_added", data: block_data })
end
Biểu đồ luồng: vòng lặp ping và dọn dẹp
sequenceDiagram
autonumber
participant BG as 🔄 PingLoopRunner (chạy nền)
participant WSM as 📡 WebSocketManager
participant Client as 🖥️ Client
Note over BG: Chạy định kỳ mỗi 30 giây
loop Trên từng kết nối đang hoạt động
BG->>Client: Gửi gói tin ping
alt Nhận lại Pong trong vòng 10 giây
Client-->>BG: pong ✅
else Quá thời gian phản hồi (10 giây)
BG->>WSM: disconnect(connection_id)
WSM->>WSM: Registry.remove(connection_id)
WSM->>WSM: SubscriptionManager.unsubscribe_all(connection_id)
end
end
Định dạng thông điệp
// Thông báo khi có khối mới{"type":"block_added","chain":"supply_chain","data":{"index":42,"hash":"a3f8b2c1...","previous_hash":"9d1e4f...","timestamp":1714000000.0,"event_count":5}}// Thông báo sự kiện (nếu đăng ký lọc theo event_types){"type":"event","chain":"supply_chain","event_type":"quality_check","data":{"entity_id":"product-SKU-001","event":"quality_check","details":{"result":"passed"}}}
Các bước chi tiết
Bước
Mô tả
1. Nâng cấp giao thức
Gửi HTTP GET kèm header Upgrade: websocket.
2. Kiểm tra giới hạn
Từ chối nếu active_connections >= max_connections (mặc định 1000).
3. Đăng ký
ConnectionRegistry.add() lưu kết nối theo connection_id.
4. Đăng ký chuỗi
SubscriptionManager.subscribe_to_chain() liên kết kết nối với chuỗi.
5. Bộ lọc tùy chọn
Client có thể gửi danh sách event_types để lọc.
6. Broadcast
Khi Gửi Sự kiện hoàn tất khối mới, broadcast_new_block() gửi tới mọi subscriber.