Basic Usage Tutorial

Relevant source files

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

• examples/01_basic_usage.py
• examples/README.md
• src/README.md
• src/flext_grpc/README.md
• examples/03_error_handling_patterns.py
• tests/README.md

Introduction

The FLEXT gRPC platform provides a high-performance communication framework built on Clean Architecture and Domain-Driven Design (DDD) principles. This tutorial covers the fundamental operations required to manage gRPC lifecycles, including server creation, client connection management, and service registration using the unified FlextGrpc facade.

The project emphasizes a "Result Pattern" for error handling (using the r pattern), ensuring that all operations return explicit success or failure states rather than throwing unhandled exceptions. This approach facilitates railway-oriented programming and robust state management for gRPC entities.

Sources: src/README.md:15-20, src/flext_grpc/README.md:12-15, examples/01_basic_usage.py:1-8

Core Architecture and Entities

The platform is organized into distinct layers: Domain, Application, and Infrastructure. The Domain layer contains rich entities that encapsulate business rules and state machines.

Primary Entities

Entity	Responsibility	Key Attributes
FlextGrpcServer	Manages server lifecycle and worker pool.	host, port, max_workers, state
FlextGrpcClient	Manages client connections and SSL/TLS.	target, channel, options
FlextGrpcChannel	Abstraction for gRPC channel state.	target, state
FlextGrpcService	Defines service methods and registration.	name, methods
FlextGrpcStream	Handles streaming operation patterns.	method_name, stream_type

Sources: src/README.md:28-40, src/flext_grpc/README.md:22-35, examples/01_basic_usage.py:32-58

Entity Lifecycle Flow

Entities follow a strict state machine, particularly for servers and channels. A server transitions from stopped to starting, running, and eventually stopping.

Server and Client Management

The FlextGrpc facade simplifies the creation and management of these entities.

Server Lifecycle

To start a server, you first create the server entity and then execute the start command through the facade. All steps should include validation checks using the Result (r) pattern.

grpc = FlextGrpc()
server_result = grpc.create_server(host="localhost", port=7070)

if server_result.success:
    server = server_result.value
    start_result = grpc.start_server(server)
    if start_result.success:
        print(f"Server is now: {start_result.value.state}")

Sources: examples/01_basic_usage.py:80-95, examples/README.md:323-338

Client Connections

Clients are created by specifying a target address. The platform manages the underlying FlextGrpcChannel state.

Validation and Business Rules

A core feature of FLEXT gRPC is the requirement to validate domain rules before operation. Entities provide a validate_business_rules() or validate_domain_rules() method that returns an r object.

Validation Aspect	Description
Host/Target	Must be a valid network address (e.g., non-empty, correct format).
Port	Must be within the range 1024-65535 for non-privileged usage.
Workers	Must be a positive integer within operational limits.

Sources: src/flext_grpc/README.md:78-83, examples/01_basic_usage.py:118-132

Error Handling Patterns

The platform uses specialized error classes to provide context for failures.

Error Hierarchy

• FlextGrpcError: Base class for all gRPC exceptions.
• GrpcValidationError: Used for field-level validation failures (includes a field attribute).
• FlextGrpcConfigurationError: Used for invalid settings (includes a config_key).
• FlextGrpcConnectionError: Used for network-level failures.

Sources: src/flext_grpc/README.md:104-115, examples/03_error_handling_patterns.py:35-50

Handling Results

The r pattern allows for clean error propagation:

validation = server.validate_business_rules()
if validation.failure:
    print(f"Error: {validation.error}")
    # Handle failure appropriately

Sources: examples/README.md:330-335, examples/03_error_handling_patterns.py:53-62

Conclusion

Basic usage of the FLEXT gRPC platform centers on the FlextGrpc facade and the immutable entity model. By following the Result pattern and enforcing domain validation at every step, developers can ensure that gRPC servers and clients maintain valid states throughout their lifecycle, from initial configuration to teardown.

Sources: src/README.md:65-75, src/flext_grpc/README.md:185-195