Session Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/relpsess.c
• src/relpsess.h
• src/relp.h
• src/copen.c
• src/cclose.c
• src/cserverclose.c
• src/librelp.h
• doc/relp.html

Session Management in librelp governs the lifecycle, state, and reliable communication between RELP clients and servers. A session (relpSess_t) represents a distinct logical connection over a transport layer (typically TCP), providing application-level acknowledgments through transaction numbers (txnr) and windowing mechanisms to ensure message delivery.

The RELP protocol follows a command-response model where the client initiates commands and the server provides responses. Sessions handle protocol negotiation (offers), message queuing, and error recovery, maintaining a state machine that transitions from connection establishment to graceful or forced termination.
Sources: src/relpsess.h:61-105, doc/relp.html:15-30

Session Architecture and State

Sessions are represented by the relpSess_t structure, which contains pointers to the parent engine, TCP transport details, and state variables for both client and server operations.

Core Session States

The session state machine ensures that commands are only sent when the connection is ready and the acknowledgment window allows.

State	Description
eRelpSessState_DISCONNECTED	Session is closed and awaiting destruction.
eRelpSessState_PRE_INIT	Transport connection is established; protocol init not yet started.
eRelpSessState_INIT_CMD_SENT	Client has sent the "open" command.
eRelpSessState_INIT_RSP_RCVD	Server response to "open" has been received and processed.
eRelpSessState_READY_TO_SEND	Session is fully established and ready for data transmission.
eRelpSessState_WINDOW_FULL	App-level window is full; client must wait for acknowledgments.
eRelpSessState_BROKEN	An error occurred; session requires recovery or termination.

Sources: src/relpsess.h:48-59, src/relpsess.c:485-502

Session State Transitions

The following diagram illustrates the typical lifecycle of a client-side session from initialization to closure.

Protocol Negotiation (Offers)

During the "open" command phase, the client and server exchange "offers" to negotiate supported features such as protocol version and available commands (e.g., syslog).

Offer Selection Logic

1. Client Proposal: The client sends an "open" command containing its supported offers (e.g., relp_version=1, commands=syslog).
2. Server Selection: The server processes these offers using selectOffers(). It checks if required features are present and enables commands based on common support.
3. Finalization: The server responds with the accepted subset of offers. The client then validates this subset; if a required feature is missing, the session is marked as broken.

Sources: src/copen.c:42-105, src/relpsess.c:755-816

Reliable Data Transfer

RELP ensures reliability by assigning a unique, monotonically increasing Transaction Number (txnr) to every command.

Windowing and Unacknowledged Frames

The client maintains a list of unacknowledged frames (pUnackedLstRoot). When a command is sent, it is added to this list. When the server responds with a matching txnr, the entry is removed.

• Window Size: Defined by sizeWindow. If the number of unacknowledged frames reaches this limit, the session enters eRelpSessState_WINDOW_FULL.
• Wait Logic: relpSessWaitState() blocks sending until the session reaches the desired state (e.g., READY_TO_SEND) or a timeout occurs.

Error Handling and Recovery

Sessions handle various failure modes, including transport-level disconnects and application-level timeouts.

Session Recovery

If a session enters the eRelpSessState_BROKEN state, relpSessTryReestablish() is utilized:

1. The existing TCP connection is aborted and destructed.
2. A new TCP connection is established.
3. Resending: All frames remaining in the unacknowledged list are resent. Crucially, these frames are rewritten with new transaction numbers (relpFrameRewriteTxnr) to maintain protocol consistency in the new session.

Sources: src/relpsess.c:717-748, doc/relp.html:190-210

Server-Initiated Closure

Because the RELP protocol is client-driven, the server uses a "hint" command called serverclose (sent with txnr 0) to notify the client of an impending shutdown. This allows the client to quickly clean up resources rather than waiting for a TCP timeout.
Sources: src/cserverclose.c:48-56, src/relpsess.c:466-480

Key Data Structures

relpSess_t

The primary object managing a session's lifecycle.

Field	Type	Description
pTcp	relpTcp_t*	Transport layer handle.
sessState	relpSessState_t	Current protocol state.
txnr	relpTxnr_t	Next transaction number to use.
sizeWindow	int	Maximum outstanding unacknowledged frames.
pUnackedLstRoot	relpSessUnacked_t*	Head of the unacknowledged frames list.
timeout	unsigned	Seconds before a session is considered broken.

Sources: src/relpsess.h:70-105

Summary

Session Management in librelp provides the stateful glue between raw TCP connections and reliable message delivery. Through a strict state machine, transaction-based acknowledgments, and a robust re-establishment logic for broken sessions, it ensures that event logs are transferred without loss, even in unstable network conditions.
Sources: doc/relp.html:45-55, src/relpsess.c:717-748