Transport Layer Abstract Base

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
• examples/01_basic_usage.py
• src/README.md
• pyproject.toml

The Transport Layer Abstract Base provides the foundation for HTTP communication within the FLEXT API framework. It defines the core protocols and mixins responsible for request parameter extraction, payload construction, and the dispatch of requests to underlying HTTP clients. This layer acts as a behavior-preserving MRO (Method Resolution Order) shard, ensuring consistent request normalization and model validation across different transport implementations.

The primary goal of this layer is to abstract the complexities of raw HTTP interactions into a structured, type-safe interface. It facilitates the conversion of domain-specific data into validated m.Api.HttpRequest models and handles the subsequent transformation of client responses into unified m.Api.HttpResponse objects.

Architecture and Components

The architecture relies on a mixin-based approach to separate concerns within the transport pipeline. The FlextApiTransportsRequestMixin serves as the central logic hub for the request lifecycle, while external constants and type definitions provide the necessary constraints and validation rules.

Request Pipeline Mixin

The FlextApiTransportsRequestMixin is responsible for the synchronous execution of HTTP requests using httpx. It manages the internal lifecycle from raw data input to the final model-validated response.

The diagram shows the internal data flow of the Request Mixin, starting from raw input and resulting in a validated API response model.
Sources: src/flext_api/_protocols/_transports_request.py:20-116

Key Methods and Logic

Method	Purpose	Key Logic
_extract_request_params	Validates input data against request models	Calls _request_payload and performs Pydantic validation.
_request_payload	Normalizes input types	Matches input as dict, str, or bytes to build a standardized payload.
_httpx_response	Routes request to specific body handlers	Dispatches based on whether the body is JSON, text, or binary.
_response_model	Unifies external response	Converts httpx.Response into m.Api.HttpResponse.

Sources: src/flext_api/_protocols/_transports_request.py:25-116

Protocol Standards and Constants

The transport layer is governed by a strict set of constants defined in the FlextApiConstants (aliased as c). These constants ensure that all transport implementations adhere to the same HTTP methods, status codes, and timeouts.

HTTP Methods and Statuses

The transport layer supports standard HTTP methods and pseudo-methods for specialized routing (e.g., WebSockets, SSE).

• Active Methods: GET, POST, PUT, DELETE.
• Safe Methods: GET, HEAD, OPTIONS, TRACE.
• Success Range: 200 - 300.
• Error Range: 400 - 599.

Sources: src/flext_api/history.json:constants.py (multiple lines)

Supported Protocols

The transport layer defines support for various versions of the HTTP protocol:

• HTTP/1.1
• HTTP/2
• HTTP/3 (included in SUPPORTED_PROTOCOLS_WITH_HTTP3)

Sources: src/flext_api/history.json:constants.py (Protocol class)

Data Normalization and Validation

Before a request is dispatched, it undergoes normalization through utility facades. This ensures that parameters like timeouts are coerced into the correct types and that URL structures are valid.

Request Normalization Flow

The sequence shows how utilities and mixins collaborate to normalize, validate, and execute an HTTP request.
Sources: examples/01_basic_usage.py:25-60, src/flext_api/_protocols/_transports_request.py:25-50

Type Definitions

The transport layer utilizes PEP 695 type aliases for strict enforcement. Key types include:

• WebHeaders: Mapping for HTTP headers.
• RequestBody: Union of JsonMapping, str, or StrictBytes.
• HttpResponseDict: Standardized dictionary structure for responses containing status codes, headers, and body.

Sources: src/flext_api/history.json:typings.py

Implementation Example: Basic Usage

The transport layer is typically accessed through public facades like FlextApi. The example usage demonstrates how request normalization and model validation are applied before the transport executes.

# Normalized request construction via u.Api.RequestUtils
payload_result = u.Api.RequestUtils.build_request_payload(
    method=c.Api.Method.GET,
    url=f"{self.settings.base_url.rstrip('/')}/resources",
    headers={"accept": c.Api.ContentType.JSON.value},
    request_kwargs={"params": {"page": 1}},
    timeout=timeout_result.value,
)

# Execution via transport mixin logic
request_result = u.parse_model(payload_result.value.root, m.Api.HttpRequest)

Sources: examples/01_basic_usage.py:38-51

Conclusion

The Transport Layer Abstract Base serves as the critical bridge between domain logic and the physical network layer. By utilizing MRO mixins and strict Pydantic model validation, it ensures that all outgoing requests are normalized and all incoming responses are unified. This abstraction allows the FLEXT API to maintain high performance and type safety while remaining agnostic of specific client implementations.