Railscale v1 Architecture

Reference for the original implementation at /Users/levander/coding/railscale.

Crate Structure

Crate	Purpose
train_track	Core pipeline, frames, routing, I/O
carriage	HTTP codec, TCP/Unix socket sources
conductor	Builder API with phantom type states
coupler	Protocol forwarding (TCP/TLS/Unix)
bogie	Testing harness, benchmarks, property tests
trezorcarriage	Hardware wallet integration

Key Patterns

Frame Phase Machine: Init -> Headers -> Body -> Complete

Service Trait:

trait Service {
    type Err;
    async fn run(self, cancel: CancellationToken) -> Result<(), Self::Err>;
}

Pipeline: Composes source, parser factory, pipeline transforms, router, error responder, hooks, response handling, and stabling config.

Conductor Builder: Conductor::tcp(addr).route_tcp(dest).max_request_bytes(n).run() Uses phantom type states: SockBuilder<NoRoute> → SockBuilder<HasRoute>.

Routing: DestinationRouter trait, Turnout/SimpleTurnout for switching, MatchingRouter for content-based routing.

Stabling: Buffering/caching layer with StablingConfig.

I/O: StreamSource/StreamDestination, Departure/Transload for cross-crate message transfer.

Feature Gates

• metrics-full / metrics-minimal — OpenTelemetry metrics
• capture — Traffic capture to files

Test Coverage

Property-based tests (proptest) for codec, derivation, TLS. Integration tests for HTTP methods, edge cases, security, keep-alive, HTTP smuggling, TLS passthrough.