Client API Reference

Relevant source files

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

• src/relpclt.h
• src/librelp.h
• src/relp.h
• src/relp.c
• tests/send.c
• doc/relp.html
• src/scrsp.c

The librelp Client API provides a structured interface for applications to implement the Reliable Event Logging Protocol (RELP). It handles connection management, session establishment through feature negotiation (offers), and the reliable transmission of syslog messages with application-level acknowledgments. The client architecture is designed to be integrated into event-driven or multi-threaded environments, such as rsyslog output plugins.

Sources: doc/relp.html:14-25, src/relp.h:103-114

Architecture Overview

The librelp client operates within a relpEngine instance, which manages global states, memory, and background I/O processing. A relpClt (Client) object represents a specific connection endpoint, which is tied to exactly one relpSess (Session). The session handles the actual protocol state machine, including transaction numbering (TXNR) and window management for unacknowledged frames.

The following diagram illustrates the relationship between the primary client-side objects:

Life Cycle Management

A librelp client follows a strict life cycle: engine construction, client instantiation, configuration, connection, message transmission, and finally destruction.

Engine and Client Initialization

Before creating a client, a relpEngine must be constructed. This engine serves as the factory for client objects.

Function	Description
relpEngineConstruct	Initializes a new engine instance.
relpEngineCltConstruct	Creates a relpClt object within the context of an engine.
relpCltSetUsrPtr	Sets an opaque pointer for user data used in callbacks.

Sources: src/librelp.h:145-148, src/librelp.h:155, src/librelp.h:193

Establishing Connections

Connection establishment involves setting the target host and port, followed by the protocol-level "open" handshake where features (offers) are negotiated.

Message Transmission

The primary function for sending data is relpCltSendSyslog. This function encapsulates the data into a RELP frame with a unique transaction number (TXNR).

Reliability Mechanism

1. Command: The client sends a syslog command with a TXNR.
2. Acknowledgment: The server must respond with a rsp command containing the same TXNR and a status code (e.g., 200 OK).
3. Windowing: librelp maintains a window of unacknowledged frames. If the window is full, subsequent sends will block or fail until acks are received.

Sources: doc/relp.html:84-93, src/scrsp.c:116-129, src/librelp.h:196

Transmission API

Function	Parameters	Description
relpCltSendSyslog	pClt, pMsg, lenMsg	Sends a syslog message reliably.
relpCltHintBurstBegin	pClt	Hints that a high-volume burst of messages is starting (enables TCP optimizations like CORK).
relpCltHintBurstEnd	pClt	Hints the end of a message burst.

Sources: src/librelp.h:196-204, src/tcp.c:1203-1215

TLS and Security Configuration

Client security is managed through TLS settings applied to the client object before connection. librelp supports both GnuTLS and OpenSSL backends.

Security Parameters

Setting	Function	Description
Enable TLS	relpCltEnableTLS	Activates TLS for the connection.
Auth Mode	relpCltSetAuthMode	Sets mode: none, fingerprint, name, or certvalid.
CA Certificate	relpCltSetCACert	Path to the CA bundle for peer verification.
Peer Names	relpCltAddPermittedPeer	Adds a hostname or fingerprint to the ACL.

Sources: src/librelp.h:198-202, src/relpclt.h:46-53

Authentication Workflow

When authmode is set to name or fingerprint, the client performs post-handshake verification.

• Name: Matches the Subject Alternative Name (SAN) or Common Name (CN) of the server certificate against the permitted peer list.
• Fingerprint: Matches the SHA1 hash of the certificate against the permitted peer list.

Sources: src/tcp.c:1280-1322, src/tcp.c:380-410

Error Handling

Librelp uses integer return codes (relpRetVal) to indicate status. Successful operations return RELP_RET_OK (0).

Common Return Codes

• RELP_RET_OK: Success.
• RELP_RET_TIMED_OUT: Connection or I/O timeout.
• RELP_RET_IO_ERR: Underlying TCP error.
• RELP_RET_AUTH_ERR_NAME: Server certificate name did not match permitted peers.
• RELP_RET_SESSION_BROKEN: The session was terminated due to a protocol error.

Sources: src/librelp.h:97-135

Event Callbacks

The application can register callback functions on the relpEngine to handle errors asynchronously:

• relpEngineSetOnErr: General error handler.
• relpEngineSetOnAuthErr: Specific handler for TLS authentication failures.
• relpEngineSetOnGenericErr: Handler for errors not tied to a specific session.

Sources: src/librelp.h:162-167, src/relp.c:26-44

Summary

The librelp Client API offers a robust mechanism for reliable logging. By utilizing the relpClt and relpEngine abstractions, developers can implement high-performance logging clients that ensure data integrity through application-level acknowledgments and secure transport via TLS. Proper management of the engine's execution loop (relpEngineRun) is critical for processing the asynchronous responses required for the protocol's reliability guarantees.

Sources: tests/send.c:258-278, doc/relp.html:252-265