Skip to main content

Module socket

Module socket 

Source
Expand description

Systemd socket activation for HTTP listeners

Provides transparent socket activation support - if systemd passes a pre-bound socket via LISTEN_FDS, we use it; otherwise we bind normally.

§How Socket Activation Works

  1. Systemd creates and binds the socket before starting the service
  2. Systemd sets LISTEN_FDS=1 and LISTEN_PID=<pid> environment variables
  3. The service receives the socket as file descriptor 3 (SD_LISTEN_FDS_START)
  4. The service uses the pre-bound socket instead of binding itself

§Benefits

  • Zero-downtime restarts (systemd holds the socket during restart)
  • Faster startup (socket already bound)
  • Privilege separation (systemd can bind privileged ports)

§Usage

ⓘ
use hyprstream_core::systemd::socket::get_listener;

// Get listener - uses systemd socket if available, otherwise binds normally
let listener = get_listener("0.0.0.0:3000").await?;

// Use with axum
axum::serve(listener, app).await?;

§Systemd Configuration

# hyprstream.socket
[Socket]
ListenStream=0.0.0.0:3000
ReusePort=yes

[Install]
WantedBy=sockets.target

Functions§

get_all_tcp_listeners
Get all TCP listeners passed by systemd
get_listener
Get a TCP listener, using systemd socket activation if available
get_listener_addr
Get a TCP listener for a specific socket address
has_socket
Check if running with systemd socket activation
listen_fd_count
Get the number of file descriptors passed by systemd