fix(sync): make sync listener bind fatal and address configurable

The sync WebSocket listener always bound to its hardcoded default
address and, if the bind failed, logged a warning and continued
booting. That left the server up with no reachable sync listener and
no clear indication anything was wrong, silently stranding
NodeDB-Lite clients.

Add a `sync` port to `PortsConfig` (default 9090, overridable via
config file or `NODEDB_PORT_SYNC`) and a `ServerConfig::sync_addr()`
accessor, and wire `spawn_protocol_listeners` to use it instead of
`SyncListenerConfig::default()`. A sync-listener bind failure now
propagates as an `Err` instead of a non-fatal warning, so boot fails
loudly.

Closes #209

Author: emanzx

nodedb/src/bootstrap/listeners.rs

@@ -4,6 +4,7 @@
 
 use std::sync::Arc;
 
+use anyhow::Context;
 use tracing::info;
 
 use crate::ServerConfig;
@@ -34,14 +35,19 @@ pub struct ListenerInfra {
 ///
 /// The native listener is not spawned here — it is run on the main task
 /// by the caller after this returns.
+///
+/// Returns `Err` if the sync WebSocket listener fails to bind — that
+/// failure is boot-fatal rather than a silent warning, since a server
+/// that comes up without a reachable sync listener leaves NodeDB-Lite
+/// clients unable to connect with no indication anything is wrong.
 pub async fn spawn_protocol_listeners(
     listeners: ProtocolListeners,
     shared: Arc<SharedState>,
     config: &ServerConfig,
     infra: ListenerInfra,
     base_acceptor: Option<tokio_rustls::TlsAcceptor>,
     cluster_handle: &Option<Arc<ClusterHandle>>,
-) {
+) -> anyhow::Result<()> {
     let ProtocolListeners {
         pg_listener,
         ilp_listener,
@@ -157,7 +163,10 @@ pub async fn spawn_protocol_listeners(
     }
 
     // Sync WebSocket listener for NodeDB-Lite clients.
-    let sync_config = crate::control::server::sync::listener::SyncListenerConfig::default();
+    let sync_config = crate::control::server::sync::listener::SyncListenerConfig {
+        listen_addr: config.sync_addr(),
+        ..Default::default()
+    };
     match crate::control::server::sync::listener::start_sync_listener(
         sync_config,
         Some(Arc::clone(&shared)),
@@ -172,7 +181,7 @@ pub async fn spawn_protocol_listeners(
             );
         }
         Err(e) => {
-            tracing::warn!(error = %e, "sync listener failed to start (non-fatal)");
+            return Err(e).context("sync listener failed to bind");
         }
     }
 
@@ -182,6 +191,8 @@ pub async fn spawn_protocol_listeners(
         handle.lifecycle.to_ready(nodes);
     }
     nodedb_cluster::readiness::notify_ready();
+
+    Ok(())
 }
 
 /// Bind all protocol listeners to their configured addresses.

nodedb/src/config/server/config.rs

@@ -39,6 +39,7 @@ use crate::config::EngineConfig;
 /// pgwire = 6432
 /// native = 6433
 /// http   = 6480
+/// sync   = 9090
 ///
 /// [auth]
 /// # ...
@@ -161,6 +162,11 @@ impl ServerConfig {
         self.addr(self.server.ports.http)
     }
 
+    /// Sync WebSocket listen address (NodeDB-Lite clients).
+    pub fn sync_addr(&self) -> SocketAddr {
+        self.addr(self.server.ports.sync)
+    }
+
     /// RESP listen address (None if disabled).
     pub fn resp_addr(&self) -> Option<SocketAddr> {
         self.server.ports.resp.map(|p| self.addr(p))
@@ -200,6 +206,7 @@ mod tests {
         assert_eq!(cfg.server.ports.native, 6433);
         assert_eq!(cfg.server.ports.pgwire, 6432);
         assert_eq!(cfg.server.ports.http, 6480);
+        assert_eq!(cfg.server.ports.sync, 9090);
         assert!(cfg.server.ports.resp.is_none());
         assert!(cfg.server.ports.ilp.is_none());
         assert!(cfg.server.data_plane_cores >= 1);

nodedb/src/config/server/env.rs

@@ -180,6 +180,7 @@ fn apply_bool_env(var: &str, target: &mut bool) {
 /// - `NODEDB_PORT_NATIVE`      — overrides `config.ports.native` (default 6433)
 /// - `NODEDB_PORT_PGWIRE`      — overrides `config.ports.pgwire` (default 6432)
 /// - `NODEDB_PORT_HTTP`        — overrides `config.ports.http` (default 6480)
+/// - `NODEDB_PORT_SYNC`        — overrides `config.ports.sync` (default 9090)
 /// - `NODEDB_PORT_RESP`        — overrides `config.ports.resp` (set to enable RESP)
 /// - `NODEDB_PORT_ILP`         — overrides `config.ports.ilp` (set to enable ILP)
 /// - `NODEDB_DATA_DIR`         — overrides `config.data_dir`
@@ -235,6 +236,7 @@ pub fn apply_env_overrides(config: &mut ServerConfig) {
     apply_port_env("NODEDB_PORT_NATIVE", &mut config.server.ports.native);
     apply_port_env("NODEDB_PORT_PGWIRE", &mut config.server.ports.pgwire);
     apply_port_env("NODEDB_PORT_HTTP", &mut config.server.ports.http);
+    apply_port_env("NODEDB_PORT_SYNC", &mut config.server.ports.sync);
     apply_optional_port_env("NODEDB_PORT_RESP", &mut config.server.ports.resp);
     apply_optional_port_env("NODEDB_PORT_ILP", &mut config.server.ports.ilp);
 
@@ -679,6 +681,29 @@ mod tests {
         unsafe { std::env::remove_var("NODEDB_MEMORY_LIMIT") };
     }
 
+    /// Tests valid and malformed `NODEDB_PORT_SYNC` sequentially to avoid
+    /// env-var races (env vars are process-global, Rust tests run in parallel).
+    #[test]
+    fn env_sync_port_overrides() {
+        // ── Valid value → overrides ports.sync ──
+        unsafe { std::env::set_var("NODEDB_PORT_SYNC", "19090") };
+        let mut cfg = ServerConfig::default();
+        apply_env_overrides(&mut cfg);
+        assert_eq!(cfg.server.ports.sync, 19090);
+
+        // ── Malformed value → ports.sync unchanged ──
+        unsafe { std::env::set_var("NODEDB_PORT_SYNC", "notaport") };
+        let mut cfg = ServerConfig::default();
+        let before = cfg.server.ports.sync;
+        apply_env_overrides(&mut cfg);
+        assert_eq!(
+            cfg.server.ports.sync, before,
+            "malformed value must not change config"
+        );
+
+        unsafe { std::env::remove_var("NODEDB_PORT_SYNC") };
+    }
+
     #[test]
     fn env_cluster_overrides() {
         // Always start clean.

nodedb/src/config/server/ports.rs

@@ -20,6 +20,9 @@ pub struct PortsConfig {
     /// HTTP API port (REST, SSE, WebSocket). Default: 6480.
     #[serde(default = "default_http_port")]
     pub http: u16,
+    /// Sync WebSocket port (NodeDB-Lite clients). Default: 9090.
+    #[serde(default = "default_sync_port")]
+    pub sync: u16,
     /// RESP (Redis-compatible) port. Disabled by default. Set to enable.
     #[serde(default)]
     pub resp: Option<u16>,
@@ -34,6 +37,7 @@ impl Default for PortsConfig {
             native: default_native_port(),
             pgwire: default_pgwire_port(),
             http: default_http_port(),
+            sync: default_sync_port(),
             resp: None,
             ilp: None,
         }
@@ -49,6 +53,9 @@ fn default_pgwire_port() -> u16 {
 fn default_http_port() -> u16 {
     6480
 }
+fn default_sync_port() -> u16 {
+    9090
+}
 
 #[cfg(test)]
 mod tests {
@@ -60,6 +67,7 @@ mod tests {
         assert_eq!(p.native, 6433);
         assert_eq!(p.pgwire, 6432);
         assert_eq!(p.http, 6480);
+        assert_eq!(p.sync, 9090);
         assert!(p.resp.is_none());
         assert!(p.ilp.is_none());
     }

nodedb/src/control/server/sync/listener.rs

@@ -163,3 +163,36 @@ async fn accept_loop(
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Binding to an address that's already occupied must surface as `Err`,
+    /// not panic or silently succeed — this is the behavior
+    /// `spawn_protocol_listeners` relies on to treat a sync-listener bind
+    /// failure as boot-fatal instead of a silent non-fatal warning.
+    #[tokio::test]
+    async fn start_sync_listener_returns_err_on_occupied_port() {
+        // Reserve an ephemeral port via a real listener so we know it's taken.
+        let occupied = TcpListener::bind(SocketAddr::from(([127, 0, 0, 1], 0)))
+            .await
+            .expect("bind ephemeral listener to reserve a port");
+        let addr = occupied
+            .local_addr()
+            .expect("local addr of reserved listener");
+
+        let cfg = SyncListenerConfig {
+            listen_addr: addr,
+            ..Default::default()
+        };
+        let result = start_sync_listener(cfg, None).await;
+
+        assert!(
+            result.is_err(),
+            "expected start_sync_listener to return Err when the address is already bound"
+        );
+
+        drop(occupied);
+    }
+}

nodedb/src/main.rs

@@ -224,7 +224,7 @@ async fn main() -> anyhow::Result<()> {
         base_acceptor.clone(),
         &cluster_handle,
     )
-    .await;
+    .await?;
 
     // Native protocol TLS.
     let native_tls = tls_for(native_tls_enabled);