Extending Transports

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_api/_protocols/_transports_request.py
• src/flext_api/history.json
• src/README.md
• examples/01_basic_usage.py
• AGENTS.md

The transport system in the FLEXT API project provides a high-performance, modular framework for handling various communication protocols, including standard HTTP, WebSockets (WS), Server-Sent Events (SSE), and GraphQL. Extending transports allows developers to implement custom request/response logic while maintaining strict type safety and adherence to the project's Clean Architecture principles.

The core of the transport extension mechanism involves leveraging MRO (Method Resolution Order) shards, such as the FlextApiTransportsRequestMixin, and utilizing the unified constant and type definitions. This ensure that all custom transports follow the "railway" result contract for explicit success and failure handling.

Sources: src/flext_api/_protocols/_transports_request.py:1-15, src/flext_api/history.json:Lines 30-100, examples/01_basic_usage.py:1-15

Transport Architecture and Mixins

The transport layer is organized as a series of behavior-preserving MRO shards. The primary mixin for request handling is FlextApiTransportsRequestMixin, which encapsulates the logic for parameter extraction, payload construction, and dispatching via httpx.

Request Pipeline Flow

The following diagram illustrates how the FlextApiTransportsRequestMixin processes raw data into a validated response.

The request pipeline is designed to handle multiple body types (JSON, String, or Bytes) and transform them into a unified m.Api.HttpRequest model before execution.

Sources: src/flext_api/_protocols/_transports_request.py:18-80

Protocol Methods and Constants

FLEXT API supports several protocols beyond standard REST. These are defined as ProtocolMethod constants, which act as pseudo-HTTP methods used to route requests to specific handlers.

Protocol Method	Description
WS	WebSocket communication
SSE	Server-Sent Events
GRAPHQL	GraphQL query/mutation handling

Sources: src/flext_api/history.json:Lines 50-70

Supported HTTP Protocols

The system supports a range of HTTP versions, which can be configured within the transport settings:

• http/1.1
• http/2
• http/3 (Experimental/Optional)

Sources: src/flext_api/history.json:Lines 200-220

Implementation Details

Request Normalization

When extending a transport, developers should use u.Api.RequestUtils (referenced in examples) to ensure that parameters like timeouts and payloads are normalized before they reach the model validation stage.

# Normalization pattern from FlextApiTransportsRequestMixin
def _request_payload(
    self,
    data: t.JsonMapping | t.Api.RequestBody,
    *,
    connection_url: str,
) -> p.Result[t.MappingKV[str, t.Api.RequestBody | t.JsonValue]]:
    match data:
        case dict() as payload:
            request_payload = {"url": connection_url, **payload}
        case str() | bytes():
            request_payload = {"url": connection_url, "body": data}
        case _:
            return r.fail("Unsupported HTTP request payload type")
    return r.ok(request_payload)

Sources: src/flext_api/_protocols/_transports_request.py:38-56, examples/01_basic_usage.py:23-45

Result Contract

All transport operations must return a p.Result object. This enforces a strict error-handling pattern where failures must be explicitly handled rather than relying on raised exceptions.

Data Models for Transports

The transport system relies on Pydantic 2 models defined in the m.Api namespace.

Model	Usage
HttpRequest	Contains URL, Method, Headers, Query Params, Body, and Timeout.
HttpResponse	Contains Status Code, Body, Headers, and Request ID.
WebHeaders	Typed mapping for HTTP headers.
WebParams	Typed mapping for URL query parameters.

Sources: src/flext_api/history.json:Lines 300-350, src/flext_api/_protocols/_transports_request.py:28-35

Governance and Quality Gates

All extensions to the transport layer must adhere to the Universal Agent Law and project quality gates:

• Zero-Debt Baseline: New transports must not introduce technical debt.
• Root Cause Only: Failures must be fixed at the source, not via workarounds.
• Strict Typing: All transport methods must use PEP 695 type aliases and strict Literal types where applicable.
• Contract Verification: Every new transport must be validated against the make test suite and flext-quality-gates.

Sources: AGENTS.md:Lines 15-60, README.md:Lines 40-50

Extending transports in FLEXT API is a structured process of implementing protocol-specific dispatch logic while utilizing shared mixins for request normalization and model validation. By adhering to the FlextApiTransportsRequestMixin patterns and the p.Result contract, developers ensure that new communication methods remain robust, testable, and consistent with the core API architecture.