Type Definitions

Type Definitions in the flext-grpc project provide the foundation for type safety, protocol compliance, and domain integrity across the platform. By leveraging Python's typing system and NewType definitions, the project ensures compile-time type checking with mypy and runtime validation, which is critical for enterprise gRPC operations.

The type system is organized into semantic categories, including domain types (targets, service names), state types (lifecycle states for channels and servers), and configuration types (ports, timeouts). These definitions are centralized to maintain a single source of truth, facilitating IDE support and clear semantic meaning throughout the codebase.

Sources: src/flext_grpc/README.md:104-120, src/flext_grpc/typings.py:1-21

Core Domain Types

The core domain types define the fundamental primitives used to describe gRPC entities and their relationships. These types are primarily housed within the FlextGrpcTypes.Grpc namespace to ensure a flat and accessible member structure.

Entity Kinds

The EntityKind type is a literal definition that constrains gRPC-related objects to a specific set of recognized domain entities. This ensures that operations performed by the platform facade or domain services are targeting valid architectural components.

Sources: src/flext_grpc/typings.py:18, tests/unit/test_api.py:108-112

Domain Namespace Relationships

The following diagram illustrates how the type system categorizes gRPC-specific definitions within the broader flext-grpc architecture:

The diagram shows the hierarchy of the FlextGrpcTypes class and its Grpc namespace.
Sources: src/flext_grpc/typings.py:14-21

Protocol and State Types

The platform utilizes specific types to manage the state machine transitions of gRPC resources and ensure protocol compliance when integrating with external libraries.

State Transitions

Entities such as the FlextGrpcServer and FlextGrpcChannel use state types to track lifecycle progress. For instance, a server transitions through states like stopped, starting, running, and stopping.

Sources: src/flext_grpc/README.md:107-112, src/flext_grpc/README.md:28-30

Stream Classifications

Streaming operations are categorized by the TGrpcStreamType definition, supporting the four standard gRPC communication patterns.

Configuration and Validation Types

Configuration types ensure that network settings and performance parameters adhere to valid ranges and formats.

Network and Performance Constraints

Types such as TGrpcHost, TGrpcPort, and TGrpcTimeout are used within the FlextGrpcSettings model to enforce business rules during configuration initialization.

• TGrpcPort: Validates that ports are within the compliant range (1024-65535).
• TGrpcHost: Ensures host strings are properly formatted network addresses.
• ConfigDict: A specialized mapping for gRPC configuration values, defined as t.MappingKV[str, t.Scalar | t.JsonValue | None].

Sources: src/flext_grpc/README.md:88-93, src/flext_grpc/typings.py:20, tests/unit/test_api.py:72-82

Implementation Example

The following snippet demonstrates the usage of gRPC types within the public API facade:

# src/flext_grpc/typings.py:14-21

class FlextGrpcTypes(t):
    """gRPC-specific type definitions extending t via MRO."""

    class Grpc:
        """gRPC domain namespace."""

        type EntityKind = Literal["server", "client", "channel", "service", "stream"]
        type Headers = t.StrMapping
        type ConfigDict = t.MappingKV[str, t.Scalar | t.JsonValue | None]

Sources: src/flext_grpc/typings.py:14-21

Integration with FlextCore

The FlextGrpcTypes class inherits from flext_cli.t (or flext_core.t), participating in the broader FLEXT ecosystem's Method Resolution Order (MRO). This allows the gRPC module to reuse foundational types while providing domain-specific extensions.

Summary

The type system in flext-grpc is a critical infrastructure component that enforces domain boundaries and protocol correctness. By centralizing EntityKind, Headers, and ConfigDict within FlextGrpcTypes, the project achieves a high degree of technical accuracy and developer productivity through enhanced static analysis and runtime validation.