RFC Implementations
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
RFC Implementations within the flext-api project provide a structured, compliant foundation for various networking protocols. These implementations ensure that standard protocol patterns—such as HTTP, WebSocket, and Server-Sent Events (SSE)—adhere to specific Request for Comments (RFC) documentation. By extending a base RFC class, the project enforces consistent behavior across different communication layers.
The scope of this module includes the definition of protocol-specific constants, type-safe data structures, and the implementation of core protocol logic. It serves as a bridge between high-level API service classes and the underlying infrastructure required for RFC-compliant data exchange.
Sources: src/flext_api/protocol_impls/rfc.py:1-12, src/README.md:18-35
Core Architecture
The RFC implementation architecture is built on a hierarchy where protocol-specific handlers extend a base implementation. This ensures that all standard protocols (HTTP, WebSocket, etc.) inherit RFC-compliant behavior and common interfaces.
Protocol Implementation Hierarchy
The following diagram illustrates the relationship between the base RFC implementation and specific protocol handlers.
This hierarchy allows for shared logic regarding request/response lifecycle management while allowing specific protocols to handle their unique frames and headers.
Sources: src/flext_api/protocol_impls/rfc.py:3-7, src/flext_api/constants.py:44-70
Protocol Constants and Enumerations
To maintain RFC compliance, flext-api defines strict enumerations for HTTP methods, status codes, and protocol types. These are organized within the FlextApiConstants class.
HTTP Methods and Protocols
Standard HTTP methods are defined as StrEnum types to provide type-safety and automatic Pydantic validation.
| Category | Values | Description |
|---|---|---|
| Standard Methods | GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS | Standard HTTP/1.1 and HTTP/2 methods. |
| Protocol Methods | WS, SSE, GRAPHQL | Pseudo-methods for routing to specific protocol handlers. |
| Supported Protocols | http, https, http/1.1, http/2, http/3 | Versions of the HTTP protocol supported by the library. |
Sources: src/flext_api/constants.py:44-84, src/flext_api/constants.py:270-300
Content Types and Status Codes
RFC compliance requires proper handling of MIME types and status ranges.
@unique
class ContentType(StrEnum):
JSON = "application/json"
XML = "application/xml"
TEXT = "text/plain"
HTML = "text/html"
FORM = "application/x-www-form-urlencoded"
MULTIPART = "multipart/form-data"
OCTET_STREAM = "application/octet-stream"
Sources: src/flext_api/constants.py:157-175, src/flext_api/constants.py:220-250
Type Definitions for RFC Compliance
The typings.py module defines the data structures used by RFC implementations to ensure data integrity during transmission.
Request and Response Structures
RFC implementations utilize unified types for headers, parameters, and bodies:
- WebHeaders: Mapping of scalar or string sequence values for RFC-compliant header structures.
- WebParams: Mapping for query string parameters.
- RequestBody/ResponseBody: Union types supporting JSON, strings, or strict bytes.
Sources: src/flext_api/typings.py:38-48
Serialization Flow
The data flow within the RFC implementation involves strict validation using TypeAdapters before protocol-specific serialization (e.g., JSON, MsgPack, or CBOR).
Protocol Specific Implementation Details
WebSocket (RFC 6455)
The implementation supports standard WebSocket features including ping/pong intervals and specific close codes. It utilizes status code 101 (Switching Protocols) for the initial handshake.
- Default Ping Interval: 20.0 seconds
- Max Message Size: 1 MiB (Default)
- Status Code: 101 (Switching Protocols)
Sources: src/flext_api/constants.py:313-340
Server-Sent Events (SSE)
SSE implementations follow the EventSource standard, managing reconnection backoff and retry timeouts.
- Default Retry Timeout: 3000ms
- Default Read Timeout: 60.0 seconds
Sources: src/flext_api/constants.py:359-375
Usage in Examples
Example implementations demonstrate how to build RFC-compliant requests using normalized utilities.
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, "active": True}},
timeout=timeout_result.value,
)
Sources: examples/01_basic_usage.py:31-41
Conclusion
The RFC Implementations in flext-api establish a rigorous framework for network communication. By centralizing constants, strictly defining types, and providing a base implementation for protocols like HTTP, WebSocket, and SSE, the system ensures that all outbound and inbound traffic follows industry-standard patterns. This design facilitates interoperability and reduces errors in protocol-level handshakes and data serialization.