Support socket activation for mdbook serve

Add a `--socket-activate` flag that adopts a pre-bound TCP listener
from `LISTEN_FDS` instead of binding a new one. This allows process
managers like foreman (with Socketfile support) or systemd to own the
socket, so it survives server restarts.

Three modes:
- `--socket-activate`: require a passed-in socket, fail if absent
- `--port N` / `--hostname H`: always bind, ignore `LISTEN_FDS`
- Neither: try `LISTEN_FDS` first, fall back to binding the default

The listener is now bound in the main thread before spawning the
server, so the actual address is always known for logging and
`--open`.

Also parse `--port` as `u16` at arg-parse time instead of leaving
it as a string.

Socket activation is normally associated with systemd. And indeed, it
would be peculiar to wire up this development command with systemd, but
it is also used in other contexts more appropriate to this command, like
https://github.com/mitsuhiko/systemfd, a development tool. From a
Capsicum/WASI perspective, it also is generally better when tools can
consume resources provided by a more privileged caller, rather than
having to open them themselves. For these reasons, I think everything
should support socket-activation.

Author: Ericson2314

Cargo.lock

@@ -108,6 +108,7 @@ walkdir = { workspace = true, optional = true }
 # Serve feature
 axum = { workspace = true, features = ["ws"], optional = true }
 futures-util = { workspace = true, optional = true }
+listenfd = { version = "1", optional = true }
 tokio = { workspace = true, features = ["macros", "rt-multi-thread"], optional = true }
 tower-http = { workspace = true, features = ["fs", "trace"], optional = true }
 
@@ -126,7 +127,7 @@ walkdir.workspace = true
 [features]
 default = ["watch", "serve", "search"]
 watch = ["dep:notify", "dep:notify-debouncer-mini", "dep:ignore", "dep:pathdiff", "dep:walkdir"]
-serve = ["dep:futures-util", "dep:tokio", "dep:axum", "dep:tower-http"]
+serve = ["dep:futures-util", "dep:listenfd", "dep:tokio", "dep:axum", "dep:tower-http"]
 search = ["mdbook-html/search"]
 
 [[bin]]

Cargo.toml

@@ -40,9 +40,15 @@ pub fn make_subcommand() -> Command {
                 .long("port")
                 .num_args(1)
                 .default_value("3000")
-                .value_parser(NonEmptyStringValueParser::new())
+                .value_parser(clap::value_parser!(u16))
                 .help("Port to use for HTTP connections"),
         )
+        .arg(
+            Arg::new("socket-activate")
+                .long("socket-activate")
+                .num_args(0)
+                .help("Use a pre-bound socket from LISTEN_FDS (systemd/foreman socket activation)"),
+        )
         .arg_open()
         .arg_watcher()
 }
@@ -52,11 +58,18 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
     let book_dir = get_book_dir(args);
     let mut book = MDBook::load(&book_dir)?;
 
-    let port = args.get_one::<String>("port").unwrap();
+    let port = *args.get_one::<u16>("port").unwrap();
     let hostname = args.get_one::<String>("hostname").unwrap();
     let open_browser = args.get_flag("open");
-
-    let address = format!("{hostname}:{port}");
+    let port_explicitly_set =
+        args.value_source("port") == Some(clap::parser::ValueSource::CommandLine);
+    let hostname_explicitly_set =
+        args.value_source("hostname") == Some(clap::parser::ValueSource::CommandLine);
+    let socket_activate = args.get_flag("socket-activate");
+
+    if socket_activate && (port_explicitly_set || hostname_explicitly_set) {
+        anyhow::bail!("--socket-activate cannot be used with --port or --hostname");
+    }
 
     let update_config = |book: &mut MDBook| {
         book.config
@@ -69,10 +82,31 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
     update_config(&mut book);
     book.build()?;
 
-    let sockaddr: SocketAddr = address
-        .to_socket_addrs()?
-        .next()
-        .ok_or_else(|| anyhow::anyhow!("no address found for {}", address))?;
+    // Bind or adopt the listener in the parent thread so we can log
+    // the actual address before spawning the server.
+    let listener = if socket_activate {
+        take_listenfd().ok_or_else(|| {
+            anyhow::anyhow!(
+                "LISTEN_FDS not set or no TCP listener at fd 3; \
+                 --socket-activate requires exactly one pre-bound TCP socket"
+            )
+        })?
+    } else if let Some(l) = (!port_explicitly_set && !hostname_explicitly_set)
+        .then(take_listenfd)
+        .flatten()
+    {
+        l
+    } else {
+        let address = format!("{hostname}:{port}");
+        let sockaddr: SocketAddr = address
+            .to_socket_addrs()?
+            .next()
+            .ok_or_else(|| anyhow::anyhow!("no address found for {}", address))?;
+        std::net::TcpListener::bind(sockaddr)?
+    };
+
+    let local_addr = listener.local_addr()?;
+
     let build_dir = book.build_dir_for("html");
     let html_config = book.config.html_config().unwrap_or_default();
     let file_404 = html_config.get_404_output_file();
@@ -82,11 +116,11 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
 
     let reload_tx = tx.clone();
     let thread_handle = std::thread::spawn(move || {
-        serve(build_dir, sockaddr, reload_tx, &file_404);
+        serve(build_dir, listener, reload_tx, &file_404);
     });
 
-    let serving_url = format!("http://{address}");
-    info!("Serving on: {}", serving_url);
+    let serving_url = format!("http://{local_addr}");
+    info!("Serving on: {serving_url}");
 
     if open_browser {
         open(serving_url);
@@ -108,7 +142,7 @@ pub fn execute(args: &ArgMatches) -> Result<()> {
 #[tokio::main]
 async fn serve(
     build_dir: PathBuf,
-    address: SocketAddr,
+    std_listener: std::net::TcpListener,
     reload_tx: broadcast::Sender<Message>,
     file_404: &str,
 ) {
@@ -132,13 +166,23 @@ async fn serve(
         std::process::exit(1);
     }));
 
-    let listener = tokio::net::TcpListener::bind(&address)
-        .await
-        .unwrap_or_else(|e| panic!("Unable to bind to {address}: {e}"));
+    std_listener
+        .set_nonblocking(true)
+        .expect("failed to set nonblocking");
+    let listener = tokio::net::TcpListener::from_std(std_listener)
+        .expect("failed to convert listener to tokio");
 
     axum::serve(listener, app).await.unwrap();
 }
 
+/// Try to adopt a TCP listener from LISTEN_FDS.
+fn take_listenfd() -> Option<std::net::TcpListener> {
+    let mut listenfd = listenfd::ListenFd::from_env();
+    listenfd
+        .take_tcp_listener(0)
+        .expect("failed to take listenfd TCP listener")
+}
+
 async fn websocket_connection(ws: WebSocket, reload_tx: broadcast::Sender<Message>) {
     let (mut user_ws_tx, _user_ws_rx) = ws.split();
     let mut rx = reload_tx.subscribe();