Skip to main content

Crate chateau

Crate chateau 

Source
Expand description

§Chateau: Protocol-agnostic client and server primitives for Tower

Chateau provides a flexible framework for building network clients and servers on top of Tower’s service abstractions. It offers protocol-agnostic primitives that can work with any transport layer and wire protocol, making it easy to build robust networked applications.

§Architecture Overview

Chateau is designed around Tower’s Service trait, extending it with networking-specific abstractions that separate concerns between transport, protocol, and business logic layers. The library provides two main components: clients and servers, both built on similar architectural principles.

§Core Abstractions

The library introduces several key traits that work together:

  • Transport: Handles establishing connections to remote endpoints (client-side)
  • Accept: Handles accepting incoming connections (server-side)
  • Protocol: Transforms raw I/O streams into request/response connections
  • Connection: Manages the lifecycle of a single client/server connection

§Client Architecture

The client module provides connection pooling and management for Tower services. Clients are built using a fluent builder API that configures:

  1. Resolver: Translates logical addresses to network endpoints
  2. Transport: Establishes connections (TCP, TLS, or custom)
  3. Protocol: Handles wire protocol framing and serialization
  4. Service: The Tower service that processes requests

The client automatically manages connection pooling, reconnection, and load balancing across multiple endpoints. It integrates seamlessly with Tower middleware for concerns like timeouts, retries, and circuit breaking.

§Server Architecture

The server module provides a generic serving framework that accepts connections and processes them using Tower services. Servers are configured with:

  1. Acceptor: Listens for and accepts incoming connections
  2. Protocol: Converts connections into request/response streams
  3. MakeService: Creates a new service instance for each connection
  4. Executor: Manages concurrent connection handling

Servers support graceful shutdown, where existing connections can complete processing before the server terminates. The modular design allows easy composition of features like TLS termination, protocol upgrades, and connection limits.

§Usage with Tower

Chateau extends Tower’s service model to network I/O by providing the glue between raw sockets and Tower services. This allows you to:

  • Use any Tower middleware with network services
  • Compose complex request processing pipelines
  • Share service implementations between different protocols
  • Test services independently of network concerns

The library handles the complexity of connection management, allowing you to focus on implementing your service logic as standard Tower services.

§Protocol Flexibility

While Chateau provides built-in support for framed protocols (using codecs), it’s designed to work with any protocol implementation. You can integrate:

  • HTTP/1.1 and HTTP/2 (via integration with hyper)
  • Custom binary protocols using the codec framework
  • Text-based protocols like Redis or SMTP
  • Multiplexed protocols with stream management

The Protocol trait is the key abstraction that adapts between raw I/O streams and Tower’s request/response model, making it straightforward to add support for new protocols.

§Feature Flags

  • client: Enables client functionality with connection pooling
  • server: Enables server functionality
  • codec: Provides framed protocol support using tokio-util codecs
  • tls: Enables TLS support using rustls
  • tls-ring: Use ring as the crypto backend for TLS
  • tls-aws-lc: Use AWS-LC as the crypto backend for TLS

§Example Patterns

Chateau is particularly well-suited for:

  • Building RPC systems with custom protocols
  • Creating protocol gateways and proxies
  • Implementing microservices with standardized communication
  • Testing distributed systems with mock transports
  • Building multi-protocol servers that share business logic

Modules§

client
Client implementations
framed
Helpers for working with sinks and streams
info
Connection Information
rt
Defines runtime traits for spawning futures
server
Serving components
services
General tower services used for composition in this module.
stream
Network stream abstractions and implementations.