/ CASE_STUDY.md
CASE_STUDY.md
1 Feature: Flower-Iroh Funnel Integration 2 3 In order to enable federated learning across NAT boundaries 4 As a system operator 5 I want to route Flower gRPC communications through Iroh tunnels 6 7 Background: 8 Given Flower operates as a hub-and-spoke federated learning framework 9 And Flower nodes communicate via gRPC using protobuf messages 10 And Iroh provides P2P connections with NAT traversal and encryption 11 12 Scenario: Flower Framework Architecture 13 In order to coordinate distributed model training 14 As a Flower deployment 15 I want to understand the framework's component topology 16 17 Given Flower uses a hub-and-spoke topology centered on a SuperLink server 18 When organizing federated learning workloads 19 Then the framework consists of three primary components: 20 | Component | Role | 21 | SuperLink | Long-running server that forwards tasks | 22 | SuperNode | Client coordinating client training | 23 | ServerApp | Short-lived process with project code | 24 And communication flows through well-defined API ports 25 | API | Port | Purpose | 26 | Fleet API | 9092 | SuperNode to SuperLink messaging | 27 | ServerAppIo API | 9091 | ServerApp to SuperLink run management | 28 | ClientAppIo API | 9094 | ClientApp to SuperNode FAB retrieval | 29 | Control API | 9093 | CLI to SuperLink user interaction | 30 31 Scenario: Iroh Framework Architecture 32 In order to establish peer connections across NAT boundaries 33 As an Iroh deployment 34 I want to leverage QUIC-based hole-punching and relay fallback 35 36 Given Iroh dials by public key rather than IP address 37 When establishing connections 38 Then the framework uses a multi-tier connection strategy: 39 | Strategy | Condition | 40 | Direct P2P | When hole-punching succeeds | 41 | Home Relay | When both endpoints have relays | 42 | Public Relay | When NAT traversal fails | 43 And all traffic is encrypted via QUIC with TLS 44 And protocol negotiation uses ALPN for stream multiplexing 45 46 Scenario: Flower-Iroh Funnel Design 47 In order to route Flower gRPC through Iroh tunnels 48 As a system architect 49 I want to design a sidecar proxy architecture 50 51 Given Flower communicates via gRPC on HTTP/2 52 And Iroh provides QUIC-based transport with NAT traversal 53 When integrating the frameworks 54 Then the funnel package structure follows: 55 | Component | Responsibility | 56 | grpc_server.rs | gRPC server (Flower protocol terminator)| 57 | tunnel.rs | Iroh tunnel management | 58 | protocol.rs | Protocol translation layer | 59 | address_lookup/ | Address resolution service | 60 And the communication flow operates as: 61 | Step | Description | 62 | Flower Client | Initiates gRPC to funnel | 63 | Funnel (Iroh endpoint) | Terminates gRPC, publishes endpoint | 64 | Iroh tunnel | Encrypts, traverses NAT via QUIC | 65 | Peer Funnel | Terminates Iroh, forwards to Flower | 66 | Flower Server | Receives gRPC from peer funnel | 67 68 Scenario: Funnel API Design 69 In order to provide a clean library interface 70 As a Rust developer 71 I want to expose a typed API for tunnel management 72 73 Given the funnel is a Rust package named flower-iroh-funnel 74 When consuming the library 75 Then the public interface provides: 76 | Method | Returns | Purpose | 77 | Funnel::new() | Result<Self, Error> | Initialize with config | 78 | Funnel::serve() | Result<(), Error> | Start gRPC server | 79 | Funnel::connect_to_peer | Result<PeerConn, Err>| Connect to remote peer | 80 | Funnel::endpoint_id | EndpointId | Local iroh endpoint identity | 81 And configuration includes: 82 | Field | Type | Purpose | 83 | alpn | Vec<u8> | Protocol negotiation bytes | 84 | relay_mode | RelayMode | NAT traversal strategy | 85 | bind_addr | SocketAddr | Local bind address | 86 | flower_grpc_addr | SocketAddr | Flower gRPC listen address | 87 88 Scenario: Cross-Platform Support 89 In order to support deployment across major platforms 90 As an operator 91 I want the funnel to operate on macOS, Windows, and Linux 92 93 Given Iroh's QUIC transport is cross-platform 94 When deploying the funnel 95 Then full support is available on: 96 | Platform | Status | 97 | macOS | Full | 98 | Windows | Full | 99 | Linux | Full | 100 And platform detection uses cfg(target_os) conditionals 101 102 Scenario: Dependencies 103 In order to build the funnel package 104 As a Rust developer 105 I want to declare the correct dependencies 106 107 Given the funnel requires both gRPC and P2P capabilities 108 When configuring Cargo.toml 109 Then the dependencies are: 110 | Crate | Version | Purpose | 111 | iroh | 0.98 | P2P connectivity and NAT traversal| 112 | tokio | 1 | Async runtime with full features | 113 | tonic | 0.12 | gRPC server implementation | 114 | prost | 0.12 | Protocol buffer code generation | 115 | serde | 1 | Serialization with derive support |