One connected client session of a UnixServer control socket. More...

#include <dfx-server/UnixSession.hpp>

Inheritance diagram for dfx::Server::UnixSession:

Collaboration diagram for dfx::Server::UnixSession:

Classes
struct	PeerCreds
	Peer credentials associated with the Unix socket. More...

Public Member Functions
	UnixSession (UnixServer &server, UnixRouter &router, std::chrono::milliseconds timeout)
	Create a session descriptor (not yet bound to a socket FD).
	DFX_DISABLE_COPY_AND_MOVE (UnixSession)
	UnixSessions are neither copyable nor movable.
Utils::BorrowedFd	socket () const noexcept
	Borrowed socket FD for this session.
PeerCreds	peerCredentials () const noexcept
	Peer credentials attached to the socket.
uint64_t	inMsgCount () const noexcept
	Total number of received request messages.
uint64_t	outMsgCount () const noexcept
	Total number of sent response messages (success + error).
uint64_t	outErrMsgCount () const noexcept
	Total number of sent error responses.
uint64_t	outConsecutiveErrMsgCount () const noexcept
	Number of consecutive error responses sent.
bool	subtractTimeAndCheckTimeout (std::chrono::milliseconds time)
	Decrease the remaining time before timeout and report expiration.
std::chrono::milliseconds	initialTimeout () const noexcept
	Current configured initial timeout value.
void	setInitialTimeout (std::chrono::milliseconds timeout)
	Update the initial timeout value.
void	init (Utils::OwnedFd socket, FdWatch::Poller &poller, PeerCreds creds)
	Bind an accepted socket to this session and register it into a poller.
void	reply (nlohmann::json response, std::string_view id)
	Send a JSON response associated with a request id.
void	replyError (std::string message, std::string_view id, nlohmann::json baseJson={})
	Convenience overload to reply with a single error message.
void	replyError (std::vector< std::string > const &messages, std::string_view id, nlohmann::json baseJson={})
	Reply with an error response containing one or more messages.
void	terminate ()
	Terminate the session.

Detailed Description

One connected client session of a UnixServer control socket.

UnixSession represents a single accepted Unix domain socket connection managed by UnixServer.

The session is:

poller-driven via a FdWatch::PollerFd registered for readability,
message-oriented (the surrounding server uses SOCK_SEQPACKET), so each read corresponds to a discrete request frame,
responsible for parsing incoming requests, routing them through a UnixRouter, and writing JSON responses back to the client.

Request / response model

Requests and responses are JSON objects. The session provides helpers to:

reply with a normal JSON response via reply(),
reply with an error response via replyError().

Both reply helpers take an explicit request identifier (id), which is echoed back in the response so clients can match replies to requests (including when multiple requests are in flight).

Timeout model: The server periodically calls subtractTimeAndCheckTimeout() (usually from a timer). If the session has been inactive for longer than the configured timeout, the server will close the connection.

Error tracking (server policy support)

UnixSession maintains counters that the server can use to enforce policies such as:

closing a session after too many total error replies,
closing a session after too many consecutive error replies.

The counters are:

inMsgCount(): total number of received requests,
outMsgCount(): total number of sent responses (success + error),
outErrMsgCount(): total number of sent error responses,
outConsecutiveErrMsgCount(): number of consecutive error responses.

Note: UnixSession is held by UnixServer as a UnixSessionPtr and derives from std::enable_shared_from_this to allow safe capture in poller callbacks.

Constructor & Destructor Documentation

◆ UnixSession()

dfx::Server::UnixSession::UnixSession	(	UnixServer &	server,
		UnixRouter &	router,
		std::chrono::milliseconds	timeout )

Create a session descriptor (not yet bound to a socket FD).

The accepted socket FD is provided later via init(). init() is called right after the constructor and this is done this way because shared_from_this and weak_from_this function only returns a valid value after the instance is stored in a std::shared_ptr.

Parameters

server	Owning server responsible for lifecycle and termination.
router	Router used to dispatch decoded requests to command handlers.
timeout	Initial inactivity timeout value for this session.

Member Function Documentation

◆ DFX_DISABLE_COPY_AND_MOVE()

dfx::Server::UnixSession::DFX_DISABLE_COPY_AND_MOVE ( UnixSession )

UnixSessions are neither copyable nor movable.

◆ init()

void dfx::Server::UnixSession::init	(	Utils::OwnedFd	socket,
		FdWatch::Poller &	poller,
		PeerCreds	creds )

Bind an accepted socket to this session and register it into a poller.

Stores the FD in a FdWatch::PollerFd and registers a readiness callback that reads incoming request messages.

Parameters

socket	Accepted socket FD (ownership transferred to the session).
poller	Poller that will drive readability notifications.
creds	The peer credentials associated with the socket.

◆ initialTimeout()

std::chrono::milliseconds dfx::Server::UnixSession::initialTimeout ( ) const

inlinenoexcept

Current configured initial timeout value.

◆ inMsgCount()

uint64_t dfx::Server::UnixSession::inMsgCount ( ) const

inlinenoexcept

Total number of received request messages.

◆ outConsecutiveErrMsgCount()

uint64_t dfx::Server::UnixSession::outConsecutiveErrMsgCount ( ) const

inlinenoexcept

Number of consecutive error responses sent.

This counter is intended for server-side policies such as "close a client after N consecutive errors".

It is reset back to 0 when a non-error response is sent (implementation detail in reply()).

◆ outErrMsgCount()

uint64_t dfx::Server::UnixSession::outErrMsgCount ( ) const

inlinenoexcept

Total number of sent error responses.

◆ outMsgCount()

uint64_t dfx::Server::UnixSession::outMsgCount ( ) const

inlinenoexcept

Total number of sent response messages (success + error).

◆ peerCredentials()

PeerCreds dfx::Server::UnixSession::peerCredentials ( ) const

inlinenoexcept

Peer credentials attached to the socket.

◆ reply()

void dfx::Server::UnixSession::reply	(	nlohmann::json	response,
		std::string_view	id )

Send a JSON response associated with a request id.

Serializes response and sends it to the client. This increments the outgoing counters and resets the consecutive-error counter.

Parameters

response	JSON response body.
id	Request identifier to echo back in the response.

◆ replyError() [1/2]

void dfx::Server::UnixSession::replyError	(	std::string	message,
		std::string_view	id,
		nlohmann::json	baseJson = {} )

inline

Convenience overload to reply with a single error message.

Parameters

message	Error message.
id	Request identifier to echo back in the response.
baseJson	Optional JSON object to merge into the error response.

◆ replyError() [2/2]

void dfx::Server::UnixSession::replyError	(	std::vector< std::string > const &	messages,
		std::string_view	id,
		nlohmann::json	baseJson = {} )

Reply with an error response containing one or more messages.

Builds a standardized error JSON payload and sends it to the client. Updates outgoing counters:

increments total outgoing message count,
increments total error message count,
increments consecutive error count.

Parameters

messages	List of error messages.
id	Request identifier to echo back in the response.
baseJson	Optional JSON object to merge into the error response.

◆ setInitialTimeout()

void dfx::Server::UnixSession::setInitialTimeout ( std::chrono::milliseconds timeout )

Update the initial timeout value.

Parameters

timeout New timeout value.

◆ socket()

Utils::BorrowedFd dfx::Server::UnixSession::socket ( ) const

inlinenoexcept

Borrowed socket FD for this session.

Returns: The session socket FD once initialized, otherwise an invalid FD.

◆ subtractTimeAndCheckTimeout()

bool dfx::Server::UnixSession::subtractTimeAndCheckTimeout ( std::chrono::milliseconds time )

Decrease the remaining time before timeout and report expiration.

Typically called periodically by UnixServer. The countdown is reset on successful I/O activity.

Parameters

time	Amount of time to subtract.

Returns: True if the session timed out, false otherwise.

◆ terminate()

void dfx::Server::UnixSession::terminate ( )

Terminate the session.

Requests shutdown of this session. Actual removal from the server registry is performed by UnixServer but this function takes care of this.

The documentation for this class was generated from the following file:

lib/dfx-server/UnixSession.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ UnixSession()

Member Function Documentation

◆ DFX_DISABLE_COPY_AND_MOVE()

◆ init()

◆ initialTimeout()

◆ inMsgCount()

◆ outConsecutiveErrMsgCount()

◆ outErrMsgCount()

◆ outMsgCount()

◆ peerCredentials()

◆ reply()

◆ replyError() [1/2]

◆ replyError() [2/2]

◆ setInitialTimeout()

◆ socket()

◆ subtractTimeAndCheckTimeout()

◆ terminate()