|
| 1 | +// SPDX-License-Identifier: AGPL-3.0-or-later |
| 2 | + |
| 3 | +//! Transport endpoint abstraction for launcher-injected transport. |
| 4 | +//! |
| 5 | +//! Wire-compatible with `sourdough_core::TransportEndpoint` (same serde |
| 6 | +//! tagged JSON format). Primals accept a `TRANSPORT_ENDPOINT` env var and |
| 7 | +//! let the launcher or Songbird decide the transport — not the primal. |
| 8 | +//! |
| 9 | +//! # Wire Format |
| 10 | +//! |
| 11 | +//! ```json |
| 12 | +//! { "transport": "uds", "path": "/run/membrane/loamspine.sock" } |
| 13 | +//! { "transport": "tcp", "host": "127.0.0.1", "port": 8080 } |
| 14 | +//! { "transport": "mesh_relay", "peer_id": "strand-gate", "capability": "ledger" } |
| 15 | +//! ``` |
| 16 | +
|
| 17 | +use serde::{Deserialize, Serialize}; |
| 18 | +use std::fmt; |
| 19 | + |
| 20 | +/// Structured transport endpoint — describes how to reach a service. |
| 21 | +/// |
| 22 | +/// Wire-compatible with `sourdough_core::TransportEndpoint` and |
| 23 | +/// `songbird_types::TransportEndpoint`. No cross-primal dependency — |
| 24 | +/// the wire format is the contract. |
| 25 | +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)] |
| 26 | +#[serde(tag = "transport")] |
| 27 | +pub enum TransportEndpoint { |
| 28 | + /// Unix Domain Socket — local primal on same host. |
| 29 | + #[serde(rename = "uds")] |
| 30 | + Uds { |
| 31 | + /// Filesystem path to the socket. |
| 32 | + path: String, |
| 33 | + }, |
| 34 | + |
| 35 | + /// TCP — direct network connection. |
| 36 | + #[serde(rename = "tcp")] |
| 37 | + Tcp { |
| 38 | + /// Host address (IPv4, IPv6, or hostname). |
| 39 | + host: String, |
| 40 | + /// TCP port number. |
| 41 | + port: u16, |
| 42 | + }, |
| 43 | + |
| 44 | + /// Mesh relay — reachable via Songbird's mesh network. |
| 45 | + #[serde(rename = "mesh_relay")] |
| 46 | + MeshRelay { |
| 47 | + /// Mesh peer identifier (e.g. `"strand-gate"`). |
| 48 | + peer_id: String, |
| 49 | + /// Capability being resolved on the remote peer. |
| 50 | + capability: String, |
| 51 | + }, |
| 52 | +} |
| 53 | + |
| 54 | +impl TransportEndpoint { |
| 55 | + /// Construct a UDS endpoint. |
| 56 | + #[must_use] |
| 57 | + pub fn uds(path: impl Into<String>) -> Self { |
| 58 | + Self::Uds { path: path.into() } |
| 59 | + } |
| 60 | + |
| 61 | + /// Construct a TCP endpoint. |
| 62 | + #[must_use] |
| 63 | + pub fn tcp(host: impl Into<String>, port: u16) -> Self { |
| 64 | + Self::Tcp { |
| 65 | + host: host.into(), |
| 66 | + port, |
| 67 | + } |
| 68 | + } |
| 69 | + |
| 70 | + /// Construct a mesh relay endpoint. |
| 71 | + #[must_use] |
| 72 | + pub fn mesh_relay(peer_id: impl Into<String>, capability: impl Into<String>) -> Self { |
| 73 | + Self::MeshRelay { |
| 74 | + peer_id: peer_id.into(), |
| 75 | + capability: capability.into(), |
| 76 | + } |
| 77 | + } |
| 78 | + |
| 79 | + /// Whether this endpoint is local (same host, no network hop). |
| 80 | + #[must_use] |
| 81 | + pub fn is_local(&self) -> bool { |
| 82 | + match self { |
| 83 | + Self::Uds { .. } => true, |
| 84 | + Self::Tcp { host, .. } => host == "127.0.0.1" || host == "::1" || host == "localhost", |
| 85 | + Self::MeshRelay { .. } => false, |
| 86 | + } |
| 87 | + } |
| 88 | + |
| 89 | + /// Transport name as it appears in the wire format. |
| 90 | + #[must_use] |
| 91 | + pub const fn transport_name(&self) -> &'static str { |
| 92 | + match self { |
| 93 | + Self::Uds { .. } => "uds", |
| 94 | + Self::Tcp { .. } => "tcp", |
| 95 | + Self::MeshRelay { .. } => "mesh_relay", |
| 96 | + } |
| 97 | + } |
| 98 | +} |
| 99 | + |
| 100 | +impl fmt::Display for TransportEndpoint { |
| 101 | + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| 102 | + match self { |
| 103 | + Self::Uds { path } => write!(f, "unix://{path}"), |
| 104 | + Self::Tcp { host, port } => { |
| 105 | + if host.contains(':') { |
| 106 | + write!(f, "tcp://[{host}]:{port}") |
| 107 | + } else { |
| 108 | + write!(f, "tcp://{host}:{port}") |
| 109 | + } |
| 110 | + } |
| 111 | + Self::MeshRelay { |
| 112 | + peer_id, |
| 113 | + capability, |
| 114 | + } => write!(f, "mesh://{peer_id}/{capability}"), |
| 115 | + } |
| 116 | + } |
| 117 | +} |
| 118 | + |
| 119 | +/// Parse a `TRANSPORT_ENDPOINT` env var value into a [`TransportEndpoint`]. |
| 120 | +/// |
| 121 | +/// The value must be a JSON string matching the tagged serde format. |
| 122 | +/// |
| 123 | +/// # Errors |
| 124 | +/// |
| 125 | +/// Returns an error if the value is not valid JSON or doesn't match the |
| 126 | +/// expected wire format. |
| 127 | +pub fn parse_transport_endpoint(json: &str) -> Result<TransportEndpoint, serde_json::Error> { |
| 128 | + serde_json::from_str(json) |
| 129 | +} |
| 130 | + |
| 131 | +/// The env var name for transport endpoint injection. |
| 132 | +pub const TRANSPORT_ENDPOINT_ENV: &str = "TRANSPORT_ENDPOINT"; |
| 133 | + |
| 134 | +#[cfg(test)] |
| 135 | +#[expect(clippy::unwrap_used, reason = "tests use unwrap for conciseness")] |
| 136 | +mod tests { |
| 137 | + use super::*; |
| 138 | + |
| 139 | + #[test] |
| 140 | + fn uds_roundtrip() { |
| 141 | + let ep = TransportEndpoint::uds("/run/membrane/loamspine.sock"); |
| 142 | + let json = serde_json::to_string(&ep).unwrap(); |
| 143 | + assert!(json.contains(r#""transport":"uds"#)); |
| 144 | + assert!(json.contains("loamspine.sock")); |
| 145 | + let parsed: TransportEndpoint = serde_json::from_str(&json).unwrap(); |
| 146 | + assert_eq!(ep, parsed); |
| 147 | + } |
| 148 | + |
| 149 | + #[test] |
| 150 | + fn tcp_roundtrip() { |
| 151 | + let ep = TransportEndpoint::tcp("192.168.1.132", 8080); |
| 152 | + let json = serde_json::to_string(&ep).unwrap(); |
| 153 | + assert!(json.contains(r#""transport":"tcp"#)); |
| 154 | + let parsed: TransportEndpoint = serde_json::from_str(&json).unwrap(); |
| 155 | + assert_eq!(ep, parsed); |
| 156 | + } |
| 157 | + |
| 158 | + #[test] |
| 159 | + fn mesh_relay_roundtrip() { |
| 160 | + let ep = TransportEndpoint::mesh_relay("strand-gate", "ledger"); |
| 161 | + let json = serde_json::to_string(&ep).unwrap(); |
| 162 | + assert!(json.contains(r#""transport":"mesh_relay"#)); |
| 163 | + let parsed: TransportEndpoint = serde_json::from_str(&json).unwrap(); |
| 164 | + assert_eq!(ep, parsed); |
| 165 | + } |
| 166 | + |
| 167 | + #[test] |
| 168 | + fn wire_compat_sourdough_uds() { |
| 169 | + let json = r#"{"transport":"uds","path":"/run/user/1000/biomeos/beardog.sock"}"#; |
| 170 | + let ep: TransportEndpoint = serde_json::from_str(json).unwrap(); |
| 171 | + assert_eq!( |
| 172 | + ep, |
| 173 | + TransportEndpoint::uds("/run/user/1000/biomeos/beardog.sock") |
| 174 | + ); |
| 175 | + } |
| 176 | + |
| 177 | + #[test] |
| 178 | + fn wire_compat_sourdough_tcp() { |
| 179 | + let json = r#"{"transport":"tcp","host":"127.0.0.1","port":9100}"#; |
| 180 | + let ep: TransportEndpoint = serde_json::from_str(json).unwrap(); |
| 181 | + assert_eq!(ep, TransportEndpoint::tcp("127.0.0.1", 9100)); |
| 182 | + } |
| 183 | + |
| 184 | + #[test] |
| 185 | + fn wire_compat_sourdough_mesh() { |
| 186 | + let json = r#"{"transport":"mesh_relay","peer_id":"strand-gate","capability":"security"}"#; |
| 187 | + let ep: TransportEndpoint = serde_json::from_str(json).unwrap(); |
| 188 | + assert_eq!( |
| 189 | + ep, |
| 190 | + TransportEndpoint::mesh_relay("strand-gate", "security") |
| 191 | + ); |
| 192 | + } |
| 193 | + |
| 194 | + #[test] |
| 195 | + fn is_local_uds() { |
| 196 | + assert!(TransportEndpoint::uds("/tmp/test.sock").is_local()); |
| 197 | + } |
| 198 | + |
| 199 | + #[test] |
| 200 | + fn is_local_tcp_localhost() { |
| 201 | + assert!(TransportEndpoint::tcp("127.0.0.1", 8080).is_local()); |
| 202 | + assert!(TransportEndpoint::tcp("::1", 8080).is_local()); |
| 203 | + assert!(TransportEndpoint::tcp("localhost", 8080).is_local()); |
| 204 | + } |
| 205 | + |
| 206 | + #[test] |
| 207 | + fn is_not_local_tcp_remote() { |
| 208 | + assert!(!TransportEndpoint::tcp("192.168.1.100", 8080).is_local()); |
| 209 | + } |
| 210 | + |
| 211 | + #[test] |
| 212 | + fn is_not_local_mesh_relay() { |
| 213 | + assert!(!TransportEndpoint::mesh_relay("peer", "cap").is_local()); |
| 214 | + } |
| 215 | + |
| 216 | + #[test] |
| 217 | + fn display_format() { |
| 218 | + assert_eq!( |
| 219 | + TransportEndpoint::uds("/tmp/test.sock").to_string(), |
| 220 | + "unix:///tmp/test.sock" |
| 221 | + ); |
| 222 | + assert_eq!( |
| 223 | + TransportEndpoint::tcp("127.0.0.1", 9100).to_string(), |
| 224 | + "tcp://127.0.0.1:9100" |
| 225 | + ); |
| 226 | + assert_eq!( |
| 227 | + TransportEndpoint::tcp("::1", 9100).to_string(), |
| 228 | + "tcp://[::1]:9100" |
| 229 | + ); |
| 230 | + assert_eq!( |
| 231 | + TransportEndpoint::mesh_relay("gate", "ledger").to_string(), |
| 232 | + "mesh://gate/ledger" |
| 233 | + ); |
| 234 | + } |
| 235 | + |
| 236 | + #[test] |
| 237 | + fn parse_env_var_value() { |
| 238 | + let json = r#"{"transport":"uds","path":"/run/membrane/loamspine.sock"}"#; |
| 239 | + let ep = parse_transport_endpoint(json).unwrap(); |
| 240 | + assert_eq!( |
| 241 | + ep, |
| 242 | + TransportEndpoint::uds("/run/membrane/loamspine.sock") |
| 243 | + ); |
| 244 | + } |
| 245 | + |
| 246 | + #[test] |
| 247 | + fn parse_invalid_json_fails() { |
| 248 | + assert!(parse_transport_endpoint("not json").is_err()); |
| 249 | + } |
| 250 | + |
| 251 | + #[test] |
| 252 | + fn transport_name_values() { |
| 253 | + assert_eq!(TransportEndpoint::uds("/tmp/x").transport_name(), "uds"); |
| 254 | + assert_eq!(TransportEndpoint::tcp("h", 1).transport_name(), "tcp"); |
| 255 | + assert_eq!( |
| 256 | + TransportEndpoint::mesh_relay("p", "c").transport_name(), |
| 257 | + "mesh_relay" |
| 258 | + ); |
| 259 | + } |
| 260 | +} |
0 commit comments