Protocol Interfaces

Relevant source files

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

• src/flext_api/_protocols/init.py
• src/flext_api/history.json (contains constants.py and typings.py content)
• src/README.md
• README.md
• pyproject.toml

The Protocol Interfaces in the FLEXT API project define the rigid structure for multi-protocol communication, including standard REST (HTTP), WebSockets (WS), Server-Sent Events (SSE), and GraphQL. This system utilizes high-performance Python 3.13+ features such as StrEnum for type safety and lazy loading to maintain a low memory footprint while providing a comprehensive suite of interfaces for transport, serialization, and storage.

The architecture is built on the principle of Dependency Inversion, where core services depend on abstractions (protocols) rather than concrete implementations. This allows the FlextApiClient to support various communication methods through a unified interface layer.

Sources: README.md:1-25, src/README.md:1-40, src/flext_api/history.json:constants.py:1-20

Architecture and Design Patterns

The protocol system is organized into a modular structure where each concern—transport, serialization, and resources—is represented by a dedicated protocol mixin or base class. These are consolidated and exposed via a lazy-loading mechanism to optimize application startup time.

Lazy Loading and Package Structure

The _protocols package uses build_lazy_import_map and install_lazy_exports to manage circular dependencies and performance. It exposes various mixins including FlextApiTransportsRequestMixin, FlextApiProtocolsSerializer, and FlextApiProtocolsStorage.

Sources: src/flext_api/_protocols/init.py:1-65

Protocol Hierarchy

The following diagram illustrates the relationship between the core protocol interfaces and their functional domains.

This hierarchy demonstrates how specialized protocols like HttpClient and Grpc inherit from the base transport layer.

Sources: src/flext_api/_protocols/init.py:10-50

Protocol Methods and Constants

The system defines specific pseudo-HTTP methods to route requests to protocol-specific handlers. These are distinct from standard HTTP methods and require specialized processing within the dispatching logic.

Enumerated Protocol Methods

Protocol Method	Enum Value	Description
WS	WS	WebSocket protocol handler for bi-directional streaming.
SSE	SSE	Server-Sent Events for uni-directional server pushes.
GRAPHQL	GRAPHQL	GraphQL-specific execution and query handling.

Sources: src/flext_api/history.json:constants.py:80-100

HTTP Standards Integration

The protocols adhere to strict HTTP method definitions for RESTful communication, using StrEnum for automatic validation.

@unique
class Method(StrEnum):
    GET = "GET"
    POST = "POST"
    PUT = "PUT"
    DELETE = "DELETE"
    PATCH = "PATCH"
    HEAD = "HEAD"
    OPTIONS = "OPTIONS"

Sources: src/flext_api/history.json:constants.py:50-75

Domain-Specific Protocols

WebSocket Protocol (WS)

The WebSocket protocol interface defines constants for robust connectivity, including ping intervals and reconnection logic. It supports both TEXT and BINARY message types.

Configuration	Default Value	Description
DEFAULT_PING_INTERVAL	20.0s	Frequency of heartbeat signals.
DEFAULT_MAX_SIZE	1 MiB	Maximum message size in bytes.
DEFAULT_RECONNECT_MAX_ATTEMPTS	5	Max retries before failure.

Sources: src/flext_api/history.json:constants.py:410-450

Server-Sent Events Protocol (SSE)

SSE interfaces manage uni-directional streaming with specific timeout controls.

• Retry Timeout: 3000ms
• Connect Timeout: 10.0s
• Read Timeout: 60.0s

Sources: src/flext_api/history.json:constants.py:465-485

Type-Safe Data Contracts

The protocols use PEP 695 type aliases and Pydantic 2 patterns to ensure data integrity across the interface boundaries. The RouteData type is a critical structure used for registering endpoints within protocol handlers.

type RouteData = t.MappingKV[
    str,
    t.JsonValue
    | t.ConfigurationMapping
    | t.JsonMapping
    | t.ResourceCallable
    | Callable[..., FlextApiTypes.Api.HttpResponseDict | str | None]
    | None,
]

Sources: src/flext_api/history.json:typings.py:40-60

Conclusion

Protocol Interfaces in FLEXT API provide a high-performance, type-safe foundation for multi-transport communication. By abstracting the complexities of HTTP, WebSockets, and GraphQL into standardized interfaces and utilizing lazy-loading for efficiency, the system ensures that the application remains scalable and maintainable while adhering to strict Clean Architecture principles.

Sources: README.md:5-15, src/flext_api/history.json:constants.py:10-30