navcore_signalk_client/

discovery.rs

//! Finding the server on the local network.
//!
//! A Signal K server announces itself over mDNS, and the announcement
//! carries more than an address: its TXT record names the vessel and gives
//! the identifier that own-ship deltas will arrive under. A client
//! therefore knows which boat it is looking at before it has connected to
//! anything, and nothing about the server has to be typed in.

use std::net::IpAddr;
use std::time::Duration;

use mdns_sd::{ServiceDaemon, ServiceEvent};

use crate::ClientError;

/// The service a Signal K server announces its data stream under.
const WEBSOCKET_SERVICE: &str = "_signalk-ws._tcp.local.";

/// And the same stream on a server with TLS switched on.
///
/// A different service name, not a flag in the TXT record: the server
/// renames the whole announcement (`interfaces/ws.js`: `ssl ? '_signalk-wss'
/// : '_signalk-ws'`). A client that browses only for the plain name finds
/// nothing at all once TLS is switched on, not just an unset flag.
const WEBSOCKET_SERVICE_TLS: &str = "_signalk-wss._tcp.local.";

/// A server that answered.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Server {
    /// What it calls itself on the network.
    pub host: String,
    /// Address to connect to. Preferred over the host name: a boat network
    /// with no working name resolution is the normal case, not the odd one.
    ///
    /// Kept as an address rather than a string because the two families do
    /// not go into a URL the same way, and a string invites forgetting that.
    pub address: IpAddr,
    /// The stream's port.
    pub port: u16,
    /// The vessel's own identifier, straight out of the TXT record. Deltas
    /// about own ship arrive under this, in full, rather than under
    /// "vessels.self" -- confirmed against a real server.
    pub self_id: Option<String>,
    /// The vessel's name, if the server states one. For telling two boats
    /// apart in a marina, where several servers answer.
    pub vessel_name: Option<String>,
    /// Whether this server speaks TLS, taken from which service it
    /// announced itself under rather than guessed or attempted.
    pub secure: bool,
}

impl Server {
    /// Host and port as a URL states them.
    ///
    /// An IPv6 address has to be bracketed here: without the brackets its
    /// own colons are indistinguishable from the one before the port, and
    /// the result is not a URL that anything will parse.
    fn authority(&self) -> String {
        match self.address {
            IpAddr::V4(address) => format!("{address}:{}", self.port),
            IpAddr::V6(address) => format!("[{address}]:{}", self.port),
        }
    }

    /// Where the data stream is.
    #[must_use]
    pub fn stream_url(&self) -> String {
        let scheme = if self.secure { "wss" } else { "ws" };
        format!("{scheme}://{}/signalk/v1/stream", self.authority())
    }

    /// Where the REST interface is. Same host and port; Signal K puts both
    /// on one server.
    #[must_use]
    pub fn http_base(&self) -> String {
        let scheme = if self.secure { "https" } else { "http" };
        format!("{scheme}://{}", self.authority())
    }
}

/// How usable an announced address is, best first.
///
/// A server announces every address it has, and they are not equally good
/// to dial. IPv4 first because it is what a boat network reliably routes.
/// A link-local IPv6 address comes last: it is only usable together with
/// the scope of the interface that received the announcement, which the
/// announcement itself does not carry -- so it works by luck on a machine
/// with one interface and fails on the cockpit computer, which will have
/// wifi and ethernet both.
fn address_rank(address: &IpAddr) -> u8 {
    match address {
        IpAddr::V4(address) if address.is_loopback() => 3,
        IpAddr::V4(_) => 0,
        IpAddr::V6(address) if address.is_loopback() => 3,
        IpAddr::V6(address) if (address.segments()[0] & 0xffc0) == 0xfe80 => 2,
        IpAddr::V6(_) => 1,
    }
}

/// Listens for servers for as long as it is given.
///
/// Always waits the whole time rather than returning on the first answer:
/// in a marina there may be several, and a client that grabbed whichever
/// replied first would attach to the neighbour's boat.
///
/// # Errors
///
/// If the mDNS responder cannot be started or the browse cannot begin.
pub fn discover(listen_for: Duration) -> Result<Vec<Server>, ClientError> {
    let daemon = ServiceDaemon::new().map_err(|error| ClientError::Discovery(error.to_string()))?;
    // Both names are browsed because a server announces itself under one or
    // the other, never both, and which one it picks is exactly the fact
    // worth learning. Each browse has its own channel, so the loop below
    // drains them in turn rather than blocking on either.
    let receiver = daemon
        .browse(WEBSOCKET_SERVICE)
        .map_err(|error| ClientError::Discovery(error.to_string()))?;
    let secure_receiver = daemon
        .browse(WEBSOCKET_SERVICE_TLS)
        .map_err(|error| ClientError::Discovery(error.to_string()))?;

    let mut found: Vec<Server> = Vec::new();
    let deadline = std::time::Instant::now() + listen_for;

    while std::time::Instant::now() < deadline {
        let mut heard = false;
        for receiver in [&receiver, &secure_receiver] {
            while let Ok(event) = receiver.try_recv() {
                heard = true;
                let ServiceEvent::ServiceResolved(info) = event else {
                    continue;
                };
                if let Some(server) = read_server(&info) {
                    // The same server answers on every interface it has. One
                    // entry per machine, not one per network card.
                    if !found.iter().any(|seen| seen.self_id == server.self_id) {
                        found.push(server);
                    }
                }
            }
        }
        if !heard {
            std::thread::sleep(Duration::from_millis(50));
        }
    }

    let _ = daemon.shutdown();
    Ok(found)
}

/// Reads one resolved announcement into a server, if it carries an address.
///
/// Whether the server speaks TLS is read from the service it answered
/// under, not attempted and not inferred from the port. An announcement is
/// the server stating what it is; anything else here would be this client
/// guessing on its behalf.
fn read_server(info: &mdns_sd::ResolvedService) -> Option<Server> {
    // Every address the server has, ranked -- and ties broken by the
    // address itself, because the announcement arrives as a set and
    // "whichever came out first" would differ between two runs on the
    // same network.
    let address = info
        .addresses
        .iter()
        .map(mdns_sd::ScopedIp::to_ip_addr)
        .min_by(|left, right| {
            address_rank(left)
                .cmp(&address_rank(right))
                .then_with(|| left.cmp(right))
        })?;

    Some(Server {
        host: info.host.trim_end_matches('.').to_owned(),
        address,
        port: info.port,
        self_id: text_value(info, "self"),
        vessel_name: text_value(info, "vname"),
        secure: info.ty_domain == WEBSOCKET_SERVICE_TLS,
    })
}

/// One entry of the TXT record.
fn text_value(info: &mdns_sd::ResolvedService, key: &str) -> Option<String> {
    info.get_property_val_str(key)
        .map(str::to_owned)
        .filter(|value| !value.is_empty())
}

/// How a client should look for the server -- read from a settings store
/// by the caller, plain string in, plain enum out.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Discovery {
    /// Listen for the server announcing itself over mDNS ([`discover`]).
    /// The normal case: a boat network hands out addresses that change,
    /// and a mariner should not have to know one.
    Mdns,
    /// Use an address stated by hand ([`resolve_stated_server`]). For a
    /// server that does not announce itself -- one behind a router, or
    /// with mDNS switched off.
    Manual,
}

impl Discovery {
    /// The string a settings store names, in the order a dialog would
    /// list them.
    const NAMES: [&'static str; 2] = ["mdns", "manual"];

    /// The variant a stored wire string names -- `"mdns"` for anything it
    /// does not recognise, listening being the fail-safe default: it asks
    /// nothing of a mariner who never typed an address at all.
    #[must_use]
    pub fn from_key(value: &str) -> Self {
        match value {
            "manual" => Self::Manual,
            _ => Self::Mdns,
        }
    }

    /// The wire string a settings store should keep, the inverse of
    /// [`Discovery::from_key`].
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Mdns => Self::NAMES[0],
            Self::Manual => Self::NAMES[1],
        }
    }

    /// Position in a dialog's list.
    #[must_use]
    pub fn position(self) -> u32 {
        match self {
            Self::Mdns => 0,
            Self::Manual => 1,
        }
    }

    /// Back from a position in that list.
    #[must_use]
    pub fn from_position(position: u32) -> Self {
        if position == 1 { Self::Manual } else { Self::Mdns }
    }
}

/// The server the mariner stated by hand, resolved to something dialable.
///
/// `None` when the address is empty or names nothing this machine can
/// reach. A caller should report that the same way a silent mDNS browse
/// is reported ("no server answered"): from the chart's point of view it
/// is the same thing, nowhere to get a position from.
///
/// `assume_tls` is what a bare address (no `http(s)://`/`ws(s)://`
/// scheme) is taken to mean -- the mariner being explicit with a scheme
/// always wins over this. A caller with the boat's own certificate
/// authority installed should pass `true`: a mariner who has been through
/// installing one is running a secured server, and silently dialling
/// plain text would be the one guess with a cost.
#[must_use]
pub fn resolve_stated_server(stated: &str, assume_tls: bool) -> Option<Server> {
    let stated = stated.trim();
    if stated.is_empty() {
        return None;
    }

    // The scheme, when there is one, is the mariner being explicit and
    // wins over any assumption made here.
    let (secure, rest) = match stated.split_once("://") {
        Some(("https" | "wss", rest)) => (true, rest),
        Some(("http" | "ws", rest)) => (false, rest),
        Some((_, rest)) => (assume_tls, rest),
        None => (assume_tls, stated),
    };

    let authority = rest.split(['/', '?']).next().unwrap_or(rest);
    let default_port = if secure { 3443 } else { 3000 };

    // Bracketed IPv6 is parsed on its own terms first: a URL keeps the
    // brackets right up to the resolver, which wants them gone, and a
    // colon inside them is part of the address, not a host/port split --
    // the same split that produced an unparseable address the first time
    // this met a real server.
    let (host, port) = if let Some(rest) = authority.strip_prefix('[') {
        let (host, after) = rest.split_once(']').unwrap_or((rest, ""));
        let port = after.strip_prefix(':').and_then(|text| text.parse().ok()).unwrap_or(default_port);
        (host, port)
    } else {
        match authority.rsplit_once(':') {
            // More than one colon with no brackets is a bare IPv6
            // literal with no port, not a host:port pair -- splitting at
            // the last colon would otherwise cut it at the wrong one.
            Some((host, port)) if !host.is_empty() && !host.contains(':') => {
                (host, port.parse().ok()?)
            }
            // No port stated: the server's own defaults.
            _ => (authority, default_port),
        }
    };

    use std::net::ToSocketAddrs;
    let address = (host, port).to_socket_addrs().ok()?.next()?.ip();

    Some(Server {
        host: host.to_owned(),
        address,
        port,
        // Neither is known until the server greets us; discovery learns
        // them from the announcement, and there is no announcement here.
        self_id: None,
        vessel_name: None,
        secure,
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    fn server_at(address: &str) -> Server {
        // Documentation addresses from RFC 5737 and RFC 3849, and a made-up
        // boat. Nothing from whatever network this happens to be written on:
        // test data that names a real machine outlives the machine.
        Server {
            host: "boat-server.local".to_owned(),
            address: address.parse().expect("an address"),
            port: 3000,
            self_id: Some("urn:mrn:signalk:uuid:00000000-0000-4000-8000-000000000000".to_owned()),
            vessel_name: Some("Example Vessel".to_owned()),
            secure: false,
        }
    }

    /// The same server, but announced under the TLS service name.
    fn secure_server_at(address: &str) -> Server {
        Server {
            secure: true,
            ..server_at(address)
        }
    }

    #[test]
    fn a_tls_server_gets_tls_urls() {
        // Both halves have to move together: a client that upgraded the
        // stream but went on asking for its token over plain http would
        // send the one thing worth protecting in clear text.
        let server = secure_server_at("198.51.100.7");
        assert_eq!(
            server.stream_url(),
            "wss://198.51.100.7:3000/signalk/v1/stream"
        );
        assert_eq!(server.http_base(), "https://198.51.100.7:3000");
    }

    #[test]
    fn a_plain_server_is_left_plain() {
        // Never optimistically upgraded: a server that did not announce TLS
        // does not speak it, and trying would only fail more slowly.
        let server = server_at("198.51.100.7");
        assert_eq!(
            server.stream_url(),
            "ws://198.51.100.7:3000/signalk/v1/stream"
        );
        assert_eq!(server.http_base(), "http://198.51.100.7:3000");
    }

    #[test]
    fn an_ipv6_tls_server_keeps_its_brackets() {
        let server = secure_server_at("2001:db8::1");
        assert_eq!(
            server.stream_url(),
            "wss://[2001:db8::1]:3000/signalk/v1/stream"
        );
        assert_eq!(server.http_base(), "https://[2001:db8::1]:3000");
    }

    #[test]
    fn the_urls_are_built_from_the_address_and_not_the_name() {
        // Boat networks routinely have no working name resolution. The
        // announcement carries the address for exactly this reason.
        let server = server_at("198.51.100.7");
        assert_eq!(
            server.stream_url(),
            "ws://198.51.100.7:3000/signalk/v1/stream"
        );
        assert_eq!(server.http_base(), "http://198.51.100.7:3000");
    }

    #[test]
    fn an_ipv6_address_is_bracketed() {
        // Unbracketed, the address's own colons run into the one before the
        // port and nothing can parse the result.
        let server = server_at("2001:db8::1");
        assert_eq!(
            server.stream_url(),
            "ws://[2001:db8::1]:3000/signalk/v1/stream"
        );
        assert_eq!(server.http_base(), "http://[2001:db8::1]:3000");
    }

    #[test]
    fn a_routable_address_is_preferred_to_a_link_local_one() {
        // The order the announcement arrives in must not decide this: a
        // link-local address is unusable without the scope of the interface
        // that heard it, which is not in the announcement.
        let mut addresses: Vec<IpAddr> = vec![
            "fe80::1".parse().expect("an address"),
            "2001:db8::1".parse().expect("an address"),
            "198.51.100.7".parse().expect("an address"),
        ];
        addresses.sort_by_key(address_rank);
        assert_eq!(addresses[0].to_string(), "198.51.100.7");
        assert_eq!(addresses[2].to_string(), "fe80::1");
    }

    #[test]
    fn discovery_survives_a_round_trip_through_the_dialog() {
        for mode in [Discovery::Mdns, Discovery::Manual] {
            assert_eq!(Discovery::from_position(mode.position()), mode);
        }
    }

    #[test]
    fn a_stated_address_with_no_scheme_takes_the_assumption_it_is_given() {
        let plain = resolve_stated_server("198.51.100.7:3000", false).expect("a server");
        assert!(!plain.secure);
        let tls = resolve_stated_server("198.51.100.7:3000", true).expect("a server");
        assert!(tls.secure);
    }

    #[test]
    fn an_explicit_scheme_overrides_the_assumption() {
        let server = resolve_stated_server("wss://198.51.100.7:3000", false).expect("a server");
        assert!(server.secure);
        let server = resolve_stated_server("ws://198.51.100.7:3000", true).expect("a server");
        assert!(!server.secure);
    }

    #[test]
    fn a_stated_address_with_no_port_gets_the_schemes_own_default() {
        let plain = resolve_stated_server("198.51.100.7", false).expect("a server");
        assert_eq!(plain.port, 3000);
        let tls = resolve_stated_server("198.51.100.7", true).expect("a server");
        assert_eq!(tls.port, 3443);
    }

    #[test]
    fn a_bracketed_ipv6_address_keeps_its_brackets_off_the_host() {
        let server = resolve_stated_server("[2001:db8::1]:3000", false).expect("a server");
        assert_eq!(server.host, "2001:db8::1");
        assert_eq!(server.port, 3000);
    }

    #[test]
    fn an_empty_or_blank_address_resolves_to_nothing() {
        assert!(resolve_stated_server("", false).is_none());
        assert!(resolve_stated_server("   ", false).is_none());
    }
}