fix(bootstrap): bind HTTP and sync listeners before any accept loop starts

Previously HTTP and sync sockets were bound lazily inside their own
spawned tasks, so a port conflict on either surfaced late (or, for
HTTP, only as a task failure) after the node had already started
serving other protocols. Move both binds into bind_listeners alongside
the native and pgwire sockets so every protocol's port conflict is
boot-fatal before anything is exposed, then hand the pre-bound sockets
to serve_sync_listener/run via new BoundListeners/ProtocolListeners
fields.

Also introduce DEFAULT_SYNC_PORT as the single source of truth shared
between ServerConfig and SyncListenerConfig::default(), fix the wasm
docs example to reference the real default sync port, and give the
shutdown/crash-harness integration tests their own unique sync ports
so concurrent server processes never collide on the default.

Author: farhan-syah

docs/getting-started.md

@@ -237,6 +237,10 @@ resp = true
 ilp = false                       # Example: disable TLS for ILP ingest
 ```
 
+Every listener binds during startup, before the server accepts any
+connection. If a configured port is already in use, startup fails with that
+port named — the server never comes up missing a protocol.
+
 **Server settings:**
 
 | Config field       | Environment variable      | Default                                               |

docs/wasm.md

@@ -173,7 +173,7 @@ const db = new NodeDbLite();
 
 // Configure sync to Origin
 await db.sync_config({
-  server_url: "ws://localhost:6433",
+  server_url: "ws://localhost:9090",
   auth_token: "your-token",
   auto_sync: true,
   sync_interval_ms: 5000,

nodedb/src/bootstrap/listeners.rs

@@ -5,6 +5,7 @@
 use std::sync::Arc;
 
 use anyhow::Context;
+use tokio::net::TcpListener;
 use tracing::info;
 
 use crate::ServerConfig;
@@ -17,9 +18,14 @@ use crate::control::shutdown::ShutdownBus;
 use crate::control::startup::StartupGate;
 use crate::control::state::SharedState;
 
-/// The three protocol listeners passed to [`spawn_protocol_listeners`].
+/// The pre-bound protocol listeners passed to [`spawn_protocol_listeners`].
+///
+/// Every socket here is already bound by [`bind_listeners`], so spawning
+/// cannot fail on a port conflict.
 pub struct ProtocolListeners {
     pub pg_listener: PgListener,
+    pub http_listener: TcpListener,
+    pub sync_listener: TcpListener,
     pub ilp_listener: Option<IlpListener>,
     pub resp_listener: Option<RespListener>,
 }
@@ -36,20 +42,21 @@ 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.
+/// Infallible by construction: every socket was bound by [`bind_listeners`]
+/// before this point, so a port conflict has already aborted boot while
+/// nothing was exposed. Nothing here may silently swallow a bind failure.
 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,
+        http_listener,
+        sync_listener,
         ilp_listener,
         resp_listener,
     } = listeners;
@@ -90,10 +97,9 @@ pub async fn spawn_protocol_listeners(
         }
     });
 
-    // HTTP API server.
+    // HTTP API server (on the socket bound by `bind_listeners`).
     let shared_http = Arc::clone(&shared);
     let http_auth_mode = config.auth.mode.clone();
-    let http_listen = config.http_addr();
     let http_tls = if http_tls_enabled {
         config.server.tls.clone()
     } else {
@@ -102,7 +108,7 @@ pub async fn spawn_protocol_listeners(
     let bus_http = shutdown_bus.clone();
     tokio::spawn(async move {
         if let Err(e) = crate::control::server::http::server::run(
-            http_listen,
+            http_listener,
             shared_http,
             http_auth_mode,
             http_tls.as_ref(),
@@ -162,51 +168,59 @@ pub async fn spawn_protocol_listeners(
         });
     }
 
-    // Sync WebSocket listener for NodeDB-Lite clients.
+    // Sync WebSocket listener for NodeDB-Lite clients (socket already bound).
     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(
+    let sync_state = crate::control::server::sync::listener::serve_sync_listener(
+        sync_listener,
         sync_config,
         Some(Arc::clone(&shared)),
     )
-    .await
-    {
-        Ok(sync_state) => {
-            info!(
-                addr = %sync_state.config.listen_addr,
-                max_sessions = sync_state.config.max_sessions,
-                "sync WebSocket listener started"
-            );
-        }
-        Err(e) => {
-            return Err(e).context("sync listener failed to bind");
-        }
-    }
+    .await;
+    info!(
+        addr = %sync_state.config.listen_addr,
+        max_sessions = sync_state.config.max_sessions,
+        "sync WebSocket listener started"
+    );
 
     // Signal readiness to systemd and cluster lifecycle.
     if let Some(handle) = cluster_handle {
         let nodes = handle.topology.read().map(|t| t.node_count()).unwrap_or(1);
         handle.lifecycle.to_ready(nodes);
     }
     nodedb_cluster::readiness::notify_ready();
+}
 
-    Ok(())
+/// Every protocol socket, bound before any accept loop starts.
+pub struct BoundListeners {
+    pub native: Listener,
+    pub pgwire: PgListener,
+    pub http: TcpListener,
+    pub sync: TcpListener,
+    pub ilp: Option<IlpListener>,
+    pub resp: Option<RespListener>,
 }
 
 /// Bind all protocol listeners to their configured addresses.
-pub async fn bind_listeners(
-    config: &ServerConfig,
-) -> anyhow::Result<(
-    Listener,
-    PgListener,
-    Option<IlpListener>,
-    Option<RespListener>,
-)> {
+///
+/// This is the single fail-fast point for listener setup: it runs before the
+/// node waits on cluster readiness and before any accept loop is spawned, so
+/// a port conflict on *any* protocol — including HTTP and sync, which serve
+/// from detached tasks — aborts boot while nothing is exposed yet. Never
+/// move a bind out of here into a spawned task; that is how a server ends up
+/// running for days missing a listener behind one warning line.
+pub async fn bind_listeners(config: &ServerConfig) -> anyhow::Result<BoundListeners> {
     let native = crate::control::server::listener::Listener::bind(config.native_addr()).await?;
     let pgwire =
         crate::control::server::pgwire::listener::PgListener::bind(config.pgwire_addr()).await?;
+    let http = TcpListener::bind(config.http_addr())
+        .await
+        .with_context(|| format!("bind HTTP API listener to {}", config.http_addr()))?;
+    let sync = crate::control::server::sync::listener::bind_sync_listener(config.sync_addr())
+        .await
+        .context("sync listener failed to bind")?;
     let ilp = if let Some(ilp_addr) = config.ilp_addr() {
         Some(crate::control::server::ilp_listener::IlpListener::bind(ilp_addr).await?)
     } else {
@@ -217,5 +231,12 @@ pub async fn bind_listeners(
     } else {
         None
     };
-    Ok((native, pgwire, ilp, resp))
+    Ok(BoundListeners {
+        native,
+        pgwire,
+        http,
+        sync,
+        ilp,
+        resp,
+    })
 }

nodedb/src/config/server/mod.rs

@@ -25,7 +25,7 @@ pub use observability::{
     ObservabilityConfig, OtlpConfig, OtlpExportConfig, OtlpReceiverConfig, PromqlConfig,
     apply_observability_env, validate_feature_availability,
 };
-pub use ports::PortsConfig;
+pub use ports::{DEFAULT_SYNC_PORT, PortsConfig};
 pub use retention::RetentionSettings;
 pub use scheduler::{CronTimezone, SchedulerConfig};
 pub use section::ServerSection;

nodedb/src/config/server/ports.rs

@@ -4,6 +4,13 @@
 
 use serde::{Deserialize, Serialize};
 
+/// Default sync WebSocket port.
+///
+/// Exported because the sync listener's own `SyncListenerConfig::default()`
+/// must agree with the config default — one constant, not two literals that
+/// can drift apart.
+pub const DEFAULT_SYNC_PORT: u16 = 9090;
+
 /// Port configuration for all protocol listeners.
 ///
 /// Always-on protocols have a default port. Optional protocols (RESP, ILP)
@@ -54,7 +61,7 @@ fn default_http_port() -> u16 {
     6480
 }
 fn default_sync_port() -> u16 {
-    9090
+    DEFAULT_SYNC_PORT
 }
 
 #[cfg(test)]

nodedb/src/control/server/http/server.rs

@@ -37,7 +37,6 @@
 //! middleware (auth, startup-gate, tracing) must apply uniformly across
 //! versions.
 
-use std::net::SocketAddr;
 use std::sync::Arc;
 
 use axum::Router;
@@ -213,61 +212,26 @@ async fn startup_gate_middleware(
 
 /// Start the HTTP API server from an already-bound [`tokio::net::TcpListener`].
 ///
-/// Useful in tests where an ephemeral-port listener is bound before the server
-/// task is spawned, making the port available to the test without a race.
+/// Alias of [`run`], kept for call sites (tests, harnesses) that bind an
+/// ephemeral-port listener first so the port is known without a race.
 pub async fn run_with_listener(
     listener: tokio::net::TcpListener,
     shared: Arc<SharedState>,
     auth_mode: AuthMode,
     tls_settings: Option<&crate::config::server::TlsSettings>,
     bus: crate::control::shutdown::ShutdownBus,
 ) -> crate::Result<()> {
-    if tls_settings.is_some() {
-        return Err(crate::Error::Config {
-            detail: "run_with_listener does not support TLS; use run() instead".into(),
-        });
-    }
-    let drain_guard = bus.register_task(
-        crate::control::shutdown::ShutdownPhase::DrainingListeners,
-        "http",
-        None,
-    );
-    let mut shutdown_rx = bus.handle().flat_watch().raw_receiver();
-
-    let query_ctx = Arc::new(crate::control::planner::context::QueryContext::for_state(
-        &shared,
-    ));
-    let state = AppState {
-        shared,
-        auth_mode,
-        query_ctx,
-    };
-    let router = build_router(state);
-    let local_addr = listener.local_addr()?;
-    info!(%local_addr, "HTTP API server listening (pre-bound listener)");
-    // `with_connect_info` is required so routes that take
-    // `ConnectInfo<SocketAddr>` (e.g. `/api/auth/session` for the
-    // fingerprint-bound session handle path) resolve the peer address.
-    // Without it, axum rejects those requests with 500.
-    axum::serve(
-        listener,
-        router.into_make_service_with_connect_info::<std::net::SocketAddr>(),
-    )
-    .with_graceful_shutdown(async move {
-        let _ = shutdown_rx.changed().await;
-    })
-    .await
-    .map_err(crate::Error::Io)?;
-    drain_guard.report_drained();
-    Ok(())
+    run(listener, shared, auth_mode, tls_settings, bus).await
 }
 
-/// Start the HTTP API server (plain HTTP or HTTPS).
+/// Start the HTTP API server (plain HTTP or HTTPS) on a pre-bound listener.
 ///
-/// If `tls_settings` is provided, serves HTTPS via axum-server + rustls.
-/// Otherwise serves plain HTTP via axum::serve.
+/// The socket is bound by `bootstrap::listeners::bind_listeners` before any
+/// accept loop starts, so a port conflict is boot-fatal rather than an error
+/// logged from inside an already-detached task. If `tls_settings` is provided,
+/// serves HTTPS via axum-server + rustls; otherwise plain HTTP via axum::serve.
 pub async fn run(
-    listen: SocketAddr,
+    listener: tokio::net::TcpListener,
     shared: Arc<SharedState>,
     auth_mode: AuthMode,
     tls_settings: Option<&crate::config::server::TlsSettings>,
@@ -289,17 +253,18 @@ pub async fn run(
         query_ctx,
     };
     let router = build_router(state);
+    let local_addr = listener.local_addr()?;
 
     if let Some(tls) = tls_settings {
-        // HTTPS via axum-server + rustls.
+        // HTTPS via axum-server + rustls, on the pre-bound socket.
         let rustls_config =
             axum_server::tls_rustls::RustlsConfig::from_pem_file(&tls.cert_path, &tls.key_path)
                 .await
                 .map_err(|e| crate::Error::Config {
                     detail: format!("HTTP TLS config error: {e}"),
                 })?;
 
-        info!(%listen, tls = true, "HTTPS API server listening");
+        info!(%local_addr, tls = true, "HTTPS API server listening");
 
         let handle = axum_server::Handle::new();
         let shutdown_handle = handle.clone();
@@ -308,17 +273,22 @@ pub async fn run(
             shutdown_handle.graceful_shutdown(Some(std::time::Duration::from_secs(5)));
         });
 
-        axum_server::bind_rustls(listen, rustls_config)
+        // `into_std` keeps the socket in nonblocking mode, which is what
+        // axum-server needs to hand it back to Tokio.
+        axum_server::from_tcp_rustls(listener.into_std()?, rustls_config)
+            .map_err(crate::Error::Io)?
             .handle(handle)
             .serve(router.into_make_service_with_connect_info::<std::net::SocketAddr>())
             .await
             .map_err(crate::Error::Io)?;
     } else {
         // Plain HTTP.
-        let listener = tokio::net::TcpListener::bind(listen).await?;
-        let local_addr = listener.local_addr()?;
         info!(%local_addr, "HTTP API server listening");
 
+        // `with_connect_info` is required so routes that take
+        // `ConnectInfo<SocketAddr>` (e.g. `/api/auth/session` for the
+        // fingerprint-bound session handle path) resolve the peer address.
+        // Without it, axum rejects those requests with 500.
         axum::serve(
             listener,
             router.into_make_service_with_connect_info::<std::net::SocketAddr>(),