Base Classes & MRO

Relevant source files

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

• src/flext_grpc/models.py
• src/flext_grpc/README.md
• src/README.md
• pyproject.toml
• AGENTS.md
• src/flext_grpc/init.py

The FLEXT gRPC platform utilizes a structured hierarchy of base classes to enforce Clean Architecture and Domain-Driven Design (DDD) principles. The architecture is built upon core foundations provided by the flext-core library, specifically leveraging immutable domain entities and validated value objects. This approach ensures that business logic remains decoupled from infrastructure concerns while maintaining a strict Method Resolution Order (MRO) that prioritizes domain integrity and functional state transitions.

The primary objective of these base classes is to provide a unified framework for gRPC components—such as servers, clients, and channels—that incorporates built-in validation, state machine logic, and railway-oriented programming (using the r result pattern). By adhering to these standards, the system achieves high testability and predictable behavior across all gRPC operations.

Sources: src/README.md:15-30, src/flext_grpc/README.md:112-125, src/flext_grpc/models.py:20-28

Core Inheritance Architecture

The FLEXT gRPC model hierarchy is rooted in the flext_core.m namespace, which provides the foundational Pydantic-based models for the entire ecosystem. The architecture distinguishes between pure value objects (m.Value) and rich domain entities (m.Entity).

Hierarchy Overview

The following diagram illustrates the relationship between core library base classes and gRPC-specific implementations:

The diagram shows how FlextGrpcModels.Grpc.Entity integrates both value object immutability and entity identity, while stateful components like Server and Channel utilize multiple inheritance to gain state machine capabilities.

Sources: src/flext_grpc/models.py:32-40, src/flext_grpc/models.py:377-385, src/flext_grpc/models.py:402-408

Primary Base Components

FlextGrpcModels.Grpc.Entity

This is the foundational class for all gRPC domain objects. It inherits from m.Entity to provide identity management and m.Value for immutability.

• Key Logic: Implements functional patterns like copy_with(), allowing for state updates while maintaining immutability.
• Validation: Provides the validate_business_rules() hook, which is overridden by specific entities to enforce domain constraints.

Sources: src/flext_grpc/models.py:377-391, src/flext_grpc/README.md:27-30

FlextGrpcModels.Grpc.StateMachine

A mixin-style base class that handles lifecycle management for gRPC components. It defines the logic for valid state transitions (e.g., STOPPED to STARTING).

• Transition Logic: Uses a transition() method that validates the current state against a map of allowed target states.
• MRO Note: It is typically inherited alongside Entity in classes like Server and Channel to provide state management without violating Pydantic's frozen model constraints during initialization.

Sources: src/flext_grpc/models.py:330-360, src/flext_grpc/README.md:32-35

Derived Domain Components

The following table summarizes how specific gRPC entities leverage the base class hierarchy:

Entity	Base Classes	Key Fields	Purpose
Server	Entity, StateMachine	host, port, state	Manages gRPC server lifecycle (starting/running/stopped).
Channel	Entity, StateMachine	target, state, options	Tracks connection states between client and server.
Client	Entity	channel, grpc_stub	Orchestrates RPC calls via a managed channel.
Service	Entity	name, methods	Defines a gRPC service contract and its RPC methods.
GrpcStream	Entity	method_name, stream_type	Manages streaming communication patterns.

Sources: src/flext_grpc/models.py:402, src/flext_grpc/models.py:449, src/flext_grpc/models.py:539, src/flext_grpc/models.py:601, src/flext_grpc/README.md:30-40

Functional Implementation Patterns

The base classes enforce a "Functional Entity" pattern where state changes do not mutate the object but return a new instance wrapped in a Result object (r).

# Example of Functional Copying from the Entity Base Class
def copy_with(self, **kwargs: t.Scalar | None) -> p.Result[Self]:
    """Functional copy using r pattern."""
    return r[Self].create_from_callable(
        lambda: self.model_copy(update=kwargs),
    )

Sources: src/flext_grpc/models.py:382-386

State Transition Sequence

The following sequence diagram demonstrates how the StateMachine base logic interacts with a derived Server entity to transition states:

This flow ensures that state transitions are always validated at the base level before a new entity instance is created.

Sources: src/flext_grpc/models.py:340-355, src/flext_grpc/models.py:494-498

External Dependencies and MRO

The MRO is heavily influenced by the flext-core and pydantic libraries. As defined in pyproject.toml, the project depends on pydantic>=2.13.3 and flext-core, which establish the following inheritance constraints:

1. Pydantic BaseModel: Provides the underlying data validation and serialization.
2. Flext Core Entity/Value: Adds identity (id) and immutability settings.
3. FLEXT gRPC Facade: The FlextGrpc class in src/flext_grpc/__init__.py acts as a high-level facade, but the internal logic relies on the MRO of the models defined in models.py.

Sources: pyproject.toml:29-35, src/flext_grpc/init.py:60-80, AGENTS.md:120-125

Conclusion

The use of specialized base classes like Entity and StateMachine within the flext-grpc project provides a robust foundation for building complex gRPC services. By consolidating domain logic into immutable, validated models, the architecture ensures that all gRPC components follow a consistent lifecycle and state management protocol, significantly reducing the risk of side effects in highly concurrent communication environments.