Overview

• Introduces an additive extension point to run the cluster protocol over any reliable, ordered,
  bidirectional byte stream.
• Keeps current TCP/TLS defaults and APIs intact; no wire or behavioral changes to existing transports.
• Adds documentation and integration tests (in‑memory and Unix sockets) to demonstrate the new path.

Why

• Decouple transport from protocol/actors so downstreams can use QUIC, WebSocket, SSH tunnels, Unix
  domain sockets, named pipes, or in‑memory streams.
• Improve testability with in‑memory streams without sockets.
• Keep the change minimal and upstream‑friendly: no new dependencies and unchanged defaults.

What Changed

• Transport seam:
  • New ClusterBidiStream trait with split() -> (BoxRead, BoxWrite) and optional peer_label/
    local_label.
  • New aliases BoxRead/BoxWrite for boxed tokio::io halves.
  • New NodeServerMessage::ConnectionOpenedExternal { stream, is_server }.
  • New NetworkStream::External { reader, writer, peer_label, local_label }.
• Session IO:
  • net::Session extended to read/write the External halves alongside existing Raw/TLS branches.
  • Framing remains the same (length prefix + prost payload).
• Client helper:
  • client_connect_external(&node_server, Box).await.
• Diagnostics:
  • Manual Debug for NetworkStream to handle External (prints labels, not halves).
• Docs:
  • README “Bring Your Own Transport” section with a concise example.
• Tests (no new crates):
  • In‑memory (DuplexStream): external_transport_auth_and_ready
  • Unix Domain Sockets (Unix only): external_unix_auth_and_ready

Backwards Compatibility

• TCP/TLS connect/listen unchanged.
• On-the-wire format unchanged.
• Public API is additive; no removed or renamed items.
• NetworkStream now has a manual Debug impl.

API Summary

• New trait: ractor_cluster::ClusterBidiStream
• New types: ractor_cluster::{BoxRead, BoxWrite}
• New message: NodeServerMessage::ConnectionOpenedExternal { stream: Box,
  is_server: bool }
• New helper: ractor_cluster::client_connect_external(...)

Usage

• Implement ClusterBidiStream for your connected stream type and inject:
  • node_server.cast(NodeServerMessage::ConnectionOpenedExternal { stream: Box::new(MyStream),
    is_server: true/false })?;
  • Or: ractor_cluster::client_connect_external(&node_server, Box::new(MyStream)).await?;
• Framing/auth/control/RemoteActor/PG sync remain centralized and unchanged.

Tests

• Build: cargo check
• Integration tests:
  • All: cargo test -p ractor_cluster_integration_tests
  • Duplex: cargo test -p ractor_cluster_integration_tests -- tests::external_transport
  • UDS (Unix): cargo test -p ractor_cluster_integration_tests -- tests::external_unix

Implementation Notes

• NetworkStream::peer_addr()/local_addr() return 0.0.0.0:0 for External; NodeServer uses labels for
  NodeServerSessionInformation.peer_addr.
• Raw TCP retains .readable()/.writable() readiness; TLS and External use straightforward async reads/
  writes.
• No new dependencies added to ractor_cluster; the test crate only enables additional Tokio features
  (net, io-util).

Follow‑ups (Out of Scope Here)

• Optional acceptor/dialer traits for generic listeners/clients.
• Standardize writer length prefix to u64 (reader already reads u64); left unchanged to avoid any wire
  delta.

Checklist

• Additive API only; no breaking changes
• Docs updated (ractor_cluster/README.md)
• Manual Debug for NetworkStream
• Integration tests for external transports (Duplex, UDS)
• No new dependencies in ractor_cluster

Touched Files (high level)

• ractor_cluster/src/net.rs: trait/types, External variant, manual Debug
• ractor_cluster/src/net/session.rs: External halves support
• ractor_cluster/src/node.rs: ConnectionOpenedExternal handler
• ractor_cluster/src/node/client.rs: client_connect_external
• ractor_cluster/src/lib.rs: re-exports
• ractor_cluster/README.md: BYO Transport docs
• ractor_cluster_integration_tests/*: new tests and minimal tokio feature enablement