Asynchronous Unix domain socket control server driven by a FdWatch::Poller. More...

#include <dfx-server/UnixServer.hpp>

Classes
struct	Options
	Server configuration values (mostly controlled via Utils::SystemConfig). More...

Public Member Functions
	UnixServer (Utils::SystemConfig &sysConfig, FdWatch::Poller &poller, UnixRouter &router, std::string const &defaultSocketPath="/var/run/dfx.sock")
	Construct a Unix control server and register SystemConfig entries.
	DISABLE_COPY_AND_MOVE (UnixServer)
	UnixServer are not copyable and not movable.
	~UnixServer ()
	Stop listening and release resources.
void	listen ()
	Start listening on the configured unix socket path.
void	stop () noexcept
	Stop listening and remove the socket file from the filesystem.
bool	isListening () const noexcept
	Whether the server socket is currently registered and listening.
void	terminateSession (UnixSessionPtr session)
	Terminate and forget a session.

Detailed Description

Asynchronous Unix domain socket control server driven by a FdWatch::Poller.

UnixServer implements the local control-plane server used by dfx components. It listens on an AF_UNIX socket using SOCK_SEQPACKET (message oriented) and accepts client connections in non-blocking mode.

Each accepted client is represented by a UnixSession instance. Incoming requests are routed through a UnixRouter.

Poller integration

The server does not create its own thread. It is entirely driven by the provided FdWatch::Poller :

the listening socket is registered through a FdWatch::PollerFd,
a periodic FdWatch::Timer is enabled while at least one session is active.

Runtime configuration (SystemConfig): The constructor registers several entries into the provided Utils::SystemConfig. These settings can be changed at runtime, and the implementation carefully preserves existing client connections where possible:

Socket permissions: changing permissions uses chmod(2) on the socket path. Existing clients are not disconnected.
Socket path: changing the socket path stops listening on the previous path and starts listening on the new path. Already connected clients are not disconnected, because sessions are tracked independently of the listening socket.
Backlog: changing backlog calls listen(2) again on the existing server socket. Pending clients are not forcibly disconnected.
Inactivity timeout / timer accuracy: affects how sessions are checked for timeouts.
Error limits: the server can automatically close clients that receive too many error responses (total or consecutive).

Inactivity and error-based auto-close

While sessions exist, a periodic timer runs at Options::timeoutAccuracy. On each tick:

sessions that timed out are closed (and an error reply is sent),
sessions that exceeded error message limits are closed:
- total error replies limit (Options::errCountBeforeClose),
- consecutive error replies limit (Options::consecutiveErrCountBeforeClose).

Socket behavior and filesystem side-effects

On listen():

the socket is created as AF_UNIX, SOCK_SEQPACKET | SOCK_NONBLOCK | SOCK_CLOEXEC,
an existing socket file at the same path is removed,
parent directories are created if needed,
the socket is bound, chmod(2) is applied, then listen(2) is called.

On stop():

the listening FD is deregistered,
the timer is stopped,
the socket path is removed from the filesystem,

Warning: There can only by 1 UnixServer per Utils::SystemConfig since it registers entries into it and the SystemConfig doesn't allow 2 entries to have the same name.

Constructor & Destructor Documentation

◆ UnixServer()

dfx::Server::UnixServer::UnixServer	(	Utils::SystemConfig &	sysConfig,
		FdWatch::Poller &	poller,
		UnixRouter &	router,
		std::string const &	defaultSocketPath = "/var/run/dfx.sock" )

Construct a Unix control server and register SystemConfig entries.

The constructor registers configuration entries (permissions, socket path, backlog, session timeouts, error limits, enabled flag). Once initialization is complete, the server may start automatically depending on the configured "enabled" value (true by default).

Parameters

sysConfig	System configuration registry used to expose and update server settings.
poller	Poller driving socket accept and session I/O.
router	Router used to dispatch decoded requests.
defaultSocketPath	Default socket path if not overridden by configuration.

◆ ~UnixServer()

dfx::Server::UnixServer::~UnixServer ( )

Stop listening and release resources.

Member Function Documentation

◆ DISABLE_COPY_AND_MOVE()

dfx::Server::UnixServer::DISABLE_COPY_AND_MOVE ( UnixServer )

UnixServer are not copyable and not movable.

◆ isListening()

bool dfx::Server::UnixServer::isListening ( ) const

inlinenoexcept

Whether the server socket is currently registered and listening.

◆ listen()

void dfx::Server::UnixServer::listen ( )

Start listening on the configured unix socket path.

Creates/binds/listens on the socket and registers it to the poller for read events. Any existing socket file at the same path is removed first.

◆ stop()

void dfx::Server::UnixServer::stop ( )

noexcept

Stop listening and remove the socket file from the filesystem.

Stops the periodic timer.
Deregisters the server socket from the poller.
Removes the socket file path (best effort).

This function is safe to call multiple times.

◆ terminateSession()

void dfx::Server::UnixServer::terminateSession ( UnixSessionPtr session )

Terminate and forget a session.

Removes the session from the internal registry. If it was the last active session, the periodic timer is stopped.