Bỏ qua

SDK Module (hierachain/sdk/*)

Tổng quan

Module SDK cung cấp bộ công cụ phát triển (Software Development Kit) bằng ngôn ngữ Python, giúp các ứng dụng bên ngoài tương tác với HieraChain một cách an toàn và tin cậy. Khác với việc gọi REST API thuần túy, SDK được tích hợp sẵn các cơ chế chống lỗi (Resiliency patterns) để đảm bảo ứng dụng không bị treo khi mạng gặp sự cố hoặc node đang trong chế độ bảo trì/lockdown.

Các tính năng nổi bật

  • Dual Interface (Sync/Async)

    • Sync Client: Sử dụng requests, phù hợp cho các script đơn giản, worker xử lý tuần tự.
    • Async Client: Sử dụng aiohttp, tối ưu cho các ứng dụng web high-concurrency (như FastAPI).

  • Thông minh & Linh hoạt

    • Exponential Backoff: Tự động thử lại (Retry) với khoảng thời gian tăng dần khi gặp lỗi mạng tạm thời.
    • Circuit Breaker: Cơ chế "ngắt mạch" tự động để tránh làm quá tải hệ thống khi service đang lỗi.

  • Nhận biết Trạng thái Hệ thống

    • Lockdown Awareness: Tự động phát hiện và xử lý lỗi khi Node đang ở chế độ phong tỏa (X-Lockdown-Mode).
    • Connection Pooling: Tối ưu hóa việc tái sử dụng kết nối HTTP để giảm độ trễ.
    • Health Check: Kiểm tra route /api/ledger/health của API.

  • Truy vấn Nâng cao

    • Entity Tracing: Truy vết vòng đời thực thể xuyên suốt các chuỗi con.
    • CID Resolution: Truy vấn block mặc định dùng resolve_cid=False; với resolve_cid=True, SDK yêu cầu API giải quyết CID. API giải quyết và giải mã details khi IPFS được bật. trace_entity() cũng hỗ trợ tùy chọn này.

Entity ID được percent-encode thành một path segment khi truy vấn trace. Khi cấu hình api_key, cả hai client từ chối redirect đối với request đọc; phản hồi 3xx được trả về dưới dạng HieraChainAPIError để X-API-Key không bị chuyển tiếp sang origin redirect.

Kiến trúc Resiliency (Chống lỗi)

SDK sử dụng mô hình trạng thái (State Machine) để quản lý kết nối:

stateDiagram-v2
    [*] --> CLOSED: Normal Operation
    CLOSED --> OPEN: Failure Threshold Reached
    OPEN --> HALF_OPEN: Recovery Timeout Expired
    HALF_OPEN --> CLOSED: Success (Service Recovered)
    HALF_OPEN --> OPEN: Failure (Still Broken)

    note right of OPEN: Fails fast immediately\nwithout calling API

Hướng dẫn sử dụng

1. Cấu hình Client

from hierachain.sdk import HieraChainClientConfig, HieraChainClient

config = HieraChainClientConfig(
    base_url="https://api.hierachain.com",
    api_key="your_secret_key",
    max_retries=3,
    circuit_failure_threshold=5
)

2. Sử dụng Synchronous Client (Dành cho Script/CLI)

with HieraChainClient(config) as client:
    # Write event to supply chain
    result = client.submit_event(
        chain_name="supply_chain",
        event_data={
            "entity_id": "PRODUCT-123",
            "event_type": "quality_check",
            "details": {"status": "passed", "inspector": "QA-01"}
        }
    )
    print(f"Event ID: {result.event_id}")

3. Sử dụng Asynchronous Client (Dành cho Web/High-load)

from hierachain.sdk import HieraChainAsyncClient

async def track_product():
    async with HieraChainAsyncClient(config) as client:
        # Trace entity across chains
        trace = await client.trace_entity("PRODUCT-123")
        for event in trace.events:
            print(f"Timestamp: {event['timestamp']} - Action: {event['event']}")

Quản lý Lỗi (Exception Handling)

SDK định nghĩa các lớp lỗi cụ thể để ứng dụng có thể xử lý logic riêng biệt:

Exception Nguyên nhân Gợi ý xử lý
CircuitOpenError Hệ thống đang lỗi liên tục, SDK tạm ngừng gửi request. Đợi một khoảng thời gian trước khi thử lại.
LockdownError Node mục tiêu đang trong chế độ phong tỏa bảo mật. Kiểm tra thông báo từ quản trị viên hệ thống.
ServiceUnavailableError Server quá tải (503). GET có thể thử lại với backoff; POST chỉ gửi một lần.
HieraChainAPIError Lỗi logic từ phía API hoặc dữ liệu không hợp lệ. Kiểm tra lại payload và quyền truy cập.

Liên quan