Architecture Overview

Relevant source files

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

• src/relp.c
• src/relp.h
• src/librelp.h
• doc/relp.html
• src/relpclt.h
• src/cmdif.h
• src/scrsp.c
• src/copen.c

The Reliable Event Logging Protocol (RELP) library is designed to provide guaranteed delivery for event messages, primarily syslog, by utilizing an application-level acknowledgment mechanism. It operates on a client-server model where the client initiates connections and issues commands, and the server responds to acknowledge or process these commands. This architecture ensures that message loss is detected even in the event of network interruptions or process crashes.

The library is structured around a central Engine object that manages multiple server listeners and client sessions, abstracting the complexities of socket multiplexing (via select or epoll), TLS encryption, and protocol-level framing.

Sources: doc/relp.html:12-45, src/relp.h:111-118

Core Components

The librelp architecture is comprised of several key objects, each identified by a unique relpObjID_t.

RELP Engine (relpEngine_t)

The Engine is the root object of the library. It maintains the state for all active listeners (servers) and sessions. It is designed to be thread-safe, allowing multiple plugins or applications to share a single engine instance. The engine handles the main event loop, dispatching I/O events to the appropriate sessions.

RELP Session (relpSess_t)

A session represents an established connection between a client and a server. It manages the transaction numbers (TXNR), application-level windows, and the state of commands currently in flight.

RELP Server (relpSrv_t) and Client (relpClt_t)

• Server: Manages listening sockets and accepts incoming connection requests, which are then promoted to sessions.
• Client: Represents the local initiator of a connection. It holds configuration for target hosts, ports, and security parameters.

Object ID	Name	Purpose
eRelpObj_Engine	Engine	Root management object and event dispatcher.
eRelpObj_Srv	Server	Listener for incoming RELP connections.
eRelpObj_Clt	Client	Initiator for outgoing RELP connections.
eRelpObj_Sess	Session	Active connection state and protocol handler.
eRelpObj_Frame	Frame	Unit of protocol communication (Command + Data).

Sources: src/librelp.h:61-75, src/relp.h:111-133, src/relpclt.h:35-55

Protocol Framing and Communication

All communication in RELP is encapsulated in a consistent frame format. This ensures reliable parsing and error detection at the application layer.

Frame Structure

A RELP frame consists of a Header (Transaction Number, Command, Data Length), the Data itself, and a Trailer (Line Feed).

RELP-FRAME = HEADER DATA TRAILER
HEADER = TXNR SP COMMAND SP DATALEN
TRAILER = LF

Sources: doc/relp.html:112-125

Command-Response Model

RELP follows a command-response model. Every regular command issued by a client must be acknowledged by the server with a rsp command containing the same Transaction Number (TXNR).

Internal Event Loop

The engine manages I/O through an event loop that supports both legacy select() and modern epoll() mechanisms.

Event Processing Flow

1. Initialization: The engine adds all server listening sockets to the monitoring set.
2. Wait: The engine blocks on epoll_wait() or select().
3. Dispatch:
   • If a listening socket is ready, handleConnectionRequest creates a new session.
   • If a session socket is ready for reading, doRecv processes incoming frames.
   • If a session socket is ready for writing, doSend flushes the outbound queue.

Command Dispatcher

When a frame is fully received, the relpEngineDispatchFrame function routes the frame to the appropriate command handler based on the COMMAND field in the header.

• open: Handled by relpSCInit to negotiate version and features.
• syslog: Handled by relpSCSyslog to process incoming logs.
• rsp: Handled by relpSCRsp to process acknowledgments for sent commands.
• close: Handled by relpSCClose for graceful termination.

Sources: src/relp.c:825-860, src/cmdif.h:51-60

Session Negotiation (Offers)

During the open command phase, the client and server exchange "offers" to agree on protocol versions and supported commands.

1. The client sends a list of features (e.g., relp_version=1, commands=syslog).
2. The server's selectOffers function compares these against engine capabilities.
3. A required feature (e.g., syslog) must be supported by both; otherwise, the connection is aborted with RELP_RET_RQD_FEAT_MISSING.

Sources: src/copen.c:45-80, doc/relp.html:150-165

Security and TLS

Librelp supports TLS for encrypted communication, supporting both GnuTLS and OpenSSL backends. Security is managed through:

• Authentication Modes: Fingerprint, Name, or Certificate Validation.
• Permitted Peers: ACL-like structures (relpPermittedPeers_t) to restrict connection to specific authorized hosts.
• Encryption: Configurable priority strings and Diffie-Hellman bits.

Sources: src/librelp.h:77-82, src/relp.h:61-64, src/relpclt.h:46-51

Summary

The librelp architecture provides a robust framework for reliable message transfer by combining a strict framing protocol with a flexible, object-oriented engine. By managing sessions, transactions, and I/O multiplexing centrally, it allows applications to implement reliable logging with minimal boilerplate while maintaining high performance and security through TLS integration.

Sources: doc/relp.html:11-15, src/relp.c:380-400