Crate subduction_http_longpoll 

Subduction HTTP Long-Poll Transport

An HTTP long-poll transport layer for the Subduction sync protocol, providing an alternative to WebSocket for environments where WebSocket connections are unreliable or unavailable (e.g., restrictive proxies, corporate firewalls, some serverless platforms).

Protocol

The transport maps Subduction’s bidirectional message stream onto HTTP request-response pairs:

┌────────┐                                ┌────────┐
│ Client │                                │ Server │
└───┬────┘                                └───┬────┘
    │                                         │
    │  POST /lp/handshake                     │
    │  Body: Signed<Challenge> (157 B)        │
    │ ──────────────────────────────────────► │
    │  200 + Signed<Response> (140 B)         │
    │  X-Session-Id: <session_id>             │
    │ ◄────────────────────────────────────── │
    │                                         │
    │  POST /lp/send                          │
    │  X-Session-Id: <id>                     │
    │  Body: Message (binary)                 │
    │ ──────────────────────────────────────► │
    │  204 No Content                         │
    │ ◄────────────────────────────────────── │
    │                                         │
    │  POST /lp/recv                          │
    │  X-Session-Id: <id>                     │
    │ ──────────────────────────────────────► │
    │            ... (blocks) ...             │
    │  200 + Message (binary)                 │
    │ ◄────────────────────────────────────── │
    │                                         │
    │  POST /lp/disconnect                    │
    │  X-Session-Id: <id>                     │
    │ ──────────────────────────────────────► │
    │  204 No Content                         │
    │ ◄────────────────────────────────────── │

Architecture

The server maintains per-session state with async channels that mirror the WebSocket transport’s internal architecture:

┌─────────────────────────────────────────────────┐
│            HttpLongPollConnection               │
│                                                 │
│  outbound_tx ──► [bounded channel] ──► /recv    │
│  /send ──► [bounded channel] ──► inbound_reader │
│  pending: Map<RequestId, oneshot::Tx>           │
└─────────────────────────────────────────────────┘

Modules

client

Generic HTTP long-poll client.

connection

HTTP long-poll connection implementing Connection<K>.

error

Error types for the HTTP long-poll transport.

http_client

Generic HTTP client trait for portable long-poll transport.

server

Hyper-based HTTP server for long-poll transport.

session

Session management for HTTP long-poll connections.

Enums

Sendable

Abstraction over Send futures.

Constants

DEFAULT_MAX_BODY_SIZE

Default maximum HTTP request body size (50 MB).

DEFAULT_POLL_TIMEOUT_SECS

Default long-poll timeout in seconds.

SESSION_ID_HEADER

Session ID header name.