HTTP Transport Implementation

Relevant source files

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

• src/flext_api/constants.py
• src/flext_api/typings.py
• src/README.md
• README.md
• pyproject.toml
• examples/README.md

Introduction

The HTTP Transport Implementation in flext-api provides a high-performance REST API foundation utilizing FastAPI and httpx. It is designed as a structured communication layer that enforces type safety through Pydantic 2 validation and PEP 695 type aliases. The system manages the lifecycle of HTTP requests, including normalization, protocol-specific handling (REST, WebSocket, SSE, GraphQL), and resilient retry logic.

This implementation serves as the primary communication gateway for the flext-api platform, orchestrating data flow between core services and infrastructure layers. It utilizes a plugin architecture for its HTTP client to allow for extensible request/response processing while maintaining a zero-debt baseline for high-performance enterprise applications.

Sources: README.md, src/README.md, pyproject.toml:23-35

Core Architecture and Components

The HTTP transport layer is organized into specific architectural layers, separating domain logic from infrastructure concerns. The src/flext_api/client.py module serves as the primary HTTP client implementation, featuring a plugin architecture for extensible behavior.

System Layering

The following diagram illustrates the relationship between the various components involved in the transport implementation:

The architecture separates public service facades from underlying transport mechanisms and data validation models.
Sources: src/README.md:20-55

Key Component Definitions

Component	File Path	Description
FlextApiClient	src/flext_api/api.py	Main service class with HTTP client composition.
FastAPI Factory	src/flext_api/app.py	Factory for generating the FastAPI application instance.
HTTP Client	src/flext_api/client.py	Client implementation supporting plugins and standard methods.
Builders	src/flext_api/builder.py	Fluent interfaces for constructing queries and responses.

Sources: src/README.md:41-55

Protocols and Methods

The transport implementation supports standard HTTP methods alongside specialized protocol handlers for real-time and query-based communication. These are defined using StrEnum to ensure type safety and automatic Pydantic validation.

Supported HTTP Methods

The system validates requests against a strict set of HTTP methods. Standard methods include GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, and TRACE.

Sources: src/flext_api/constants.py:53-75

Protocol-Specific Handlers

In addition to standard REST, the implementation provides pseudo-HTTP methods for routing to specialized protocol handlers:

• WS: WebSocket protocol for full-duplex communication.
• SSE: Server-Sent Events for uni-directional streaming.
• GRAPHQL: Dedicated handler for GraphQL queries.

Sources: src/flext_api/constants.py:80-92

The flow demonstrates how requests are dispatched to specific protocol handlers based on the method type.
Sources: src/flext_api/constants.py:97-106, src/flext_api/constants.py:385-395

Configuration and Defaults

The transport layer utilizes centralized constants and validation limits to maintain consistency across the API.

Connection and Timeout Settings

The system defines default pool sizes and timeout thresholds to optimize performance:

• Default Timeout: Inherited from FlextWebConstants.DEFAULT_TIMEOUT_SECONDS.
• Max Connections: 100 connections in the pool.
• Keepalive: 20 maximum keepalive connections.
• Max URL Length: 2048 characters.

Sources: src/flext_api/constants.py:221-222, src/flext_api/constants.py:400-405, src/flext_api/constants.py:230

Retry Policy

The implementation includes an automatic retry mechanism for specific failure modes.

Status Code	Description
408	Request Timeout
429	Too Many Requests (Rate Limit)
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable
504	Gateway Timeout

Sources: src/flext_api/constants.py:385-396

Data Serialization and Type Safety

The transport layer relies on strict type definitions and Pydantic-based adapters to handle request and response payloads.

Type Aliases

The project uses PEP 695 type aliases for clear interface definitions:

• WebHeaders: Mapping of scalars or string sequences.
• RequestBody: Union of JsonMapping, str, or StrictBytes.
• HttpResponseDict: Structured dictionary containing status_code, headers, body, and request_id.

Sources: src/flext_api/typings.py:41-55

Type Adapters

Pydantic TypeAdapter instances are used for runtime validation of transport data:

# Type Adapter Examples
BINARY_CONTENT_ADAPTER: u.TypeAdapter[t.StrictBytes] = u.TypeAdapter(t.StrictBytes)
HOSTNAME_ADAPTER: u.TypeAdapter[t.HostnameStr] = u.TypeAdapter(t.HostnameStr)
PORT_NUMBER_ADAPTER: u.TypeAdapter[t.PortNumber] = u.TypeAdapter(t.PortNumber)
REQUEST_BODY_ADAPTER: u.TypeAdapter[RequestBody] = u.TypeAdapter(RequestBody)

Sources: src/flext_api/typings.py:80-120

Usage Pattern

The implementation is typically accessed through the FlextApi facade, which handles request normalization and model validation.

class FlextApiExamplesDemo(s[t.JsonMapping]):
    @override
    def execute(self) -> p.Result[t.JsonMapping]:
        api = FlextApi(settings=self.settings)
        return api.execute().map(
            lambda ready: {
                "ready": ready,
                "base_url": self.settings.base_url,
            }
        )

Sources: examples/README.md:21-33

Summary

The HTTP Transport Implementation in flext-api provides a robust, type-safe foundation for RESTful and real-time communication. By centralizing protocol constants, enforcing strict Pydantic validation, and utilizing a plugin-based HTTP client, the system ensures high-performance connectivity with built-in resilience for enterprise-scale FastAPI applications.