Client Request Management
Relevant source files
The following files were used as context for generating this wiki page:
Client Request Management in the FLEXT API ecosystem provides a high-performance, type-safe infrastructure for constructing, normalizing, and validating HTTP requests. It acts as a bridge between high-level service calls and the underlying HTTP client, ensuring that all outgoing communication adheres to strict domain models and validation rules. Sources: src/README.md, examples/01_basic_usage.py:17-20
The system leverages Pydantic 2 for runtime validation, specialized utility shards for payload normalization, and comprehensive constants to manage HTTP methods, status codes, and content types. This architecture ensures that request components like headers, query parameters, and body content are consistently handled across the platform. Sources: src/flext_api/constants.py:1-15, src/flext_api/_utilities/request_utils.py:16-18
Request Architecture and Flow
The request management lifecycle follows a structured path from initialization through normalization to final validation. The process begins with raw input data and configuration settings, which are processed by utility namespaces to produce a validated request model.
Request Execution Flow
The following diagram illustrates the lifecycle of a client request from the initial facade call to the generation of a validated model.
The flow ensures that any failures in normalization or validation are captured as Result objects, preventing silent errors during execution. Sources: src/flext_api/_utilities/request_utils.py:127-165, examples/01_basic_usage.py:27-55
Core Components
Request Utilities (u.Api.RequestUtils)
The FlextApiUtilitiesRequestUtils provides a namespace for static methods that handle the "dirty" work of HTTP preparation. This includes coercing types, merging dictionaries, and extracting data from keyword arguments. Sources: src/flext_api/_utilities/request_utils.py:13-18
| Method | Purpose | Return Type |
|---|---|---|
coerce_positive_timeout | Validates and converts input to a positive float. | p.Result[float] |
extract_body_from_kwargs | Resolves body content from specific keys (data, json). | p.Result[t.Api.RequestBody] |
merge_headers | Combines explicit headers with those found in kwargs. | p.Result[t.StrMapping] |
extract_query_params | Normalizes various types into a string-based mapping. | p.Result[t.Api.WebParams] |
build_request_payload | Orchestrates all extractions into a ConfigMap. | p.Result[m.ConfigMap] |
Sources: src/flext_api/_utilities/request_utils.py:21-125
Domain Constants
The system relies on FlextApiConstants for type-safe enums and safe method lists. These are used during validation to reject unsupported protocols or unsafe HTTP methods. Sources: src/flext_api/constants.py:21-25
class Method(StrEnum):
GET = "GET"
POST = "POST"
PUT = "PUT"
DELETE = "DELETE"
# ... other standard methods
Sources: src/flext_api/constants.py:40-61
Type Definitions and Validation
Request management is governed by strict PEP 695 type aliases and Pydantic TypeAdapters found in FlextApiTypes. This ensures that every piece of data in a request has a single, authoritative definition. Sources: src/flext_api/typings.py:21-30
Key Request Types
| Type Alias | Definition |
|---|---|
WebHeaders | t.ScalarOrStrSequenceMapping |
WebParams | `t.MappingKV[str, str |
RequestBody | `t.JsonMapping |
RequestKwargs | Mapping of strings to mappings or primitives for request configuration. |
Sources: src/flext_api/typings.py:36-61
Data Adapters
Adapters are used to enforce constraints during the normalization phase before a full model is instantiated.
- REQUEST_BODY_ADAPTER: Validates the payload structure.
- STR_MAPPING_ADAPTER: Ensures headers are valid string-to-string mappings.
- API_JSON_VALUE_ADAPTER: General purpose validation for arbitrary JSON values.
Sources: src/flext_api/typings.py:80-115
Implementation Example: Building a Request
The following sequence diagram demonstrates how the public facade interacts with the utility shard to produce a validated request object.
Conclusion
Client Request Management provides the necessary rigor for high-performance API interactions. By combining the RequestUtils shard for normalization with the FlextApiTypes for strict validation, the system ensures that every outgoing request is well-formed, safe, and compliant with the project's architectural standards. Sources: src/README.md, examples/01_basic_usage.py:133-145