Luồng dữ liệu WebSocket Thời gian thực (WebSocket Real-Time Streaming)

Overview

HieraChain tự động đẩy các thông báo về khối mới và sự kiện mới phát sinh tới các máy khách (clients) đang kết nối trong thời gian thực thông qua kết nối WebSocket. Các máy khách có thể chọn đăng ký theo dõi toàn bộ chuỗi cụ thể hoặc theo các loại sự kiện nhất định. Một quy trình vòng lặp ping chạy nền (background ping loop) sẽ giám sát để phát hiện các kết nối rác, mất mạng và tự động giải phóng chúng.

WebSocketManager được triển khai dưới dạng mẫu thiết kế Singleton (ws_manager) dùng chung cho toàn bộ các định tuyến API để quản lý đăng ký kết nối tập trung tại một nơi duy nhất.

Biểu đồ luồng — Vòng đời Kết nối & Phát tin (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 / Dọn dẹp kết nối rác

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 (Message Format)

// Thông báo khi có khối dữ liệu mới được thêm vào chuỗ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 cụ thể 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 thực hiện chi tiết

Xử lý lỗi

Các Class & Method quan trọng

Liên quan

• Gửi Sự kiện — Kích hoạt broadcast_new_block() sau khi khối mới được cam kết thành công
• Cảnh báo Rủi ro — Các thông báo cảnh báo cũng được đẩy thời gian thực qua kênh WebSocket này