Frame Format & Parsing
Relevant source files
The following files were used as context for generating this wiki page:
The Reliable Event Logging Protocol (RELP) utilizes a consistent framing mechanism to ensure the reliable delivery and acknowledgement of commands and data over a TCP connection. Frame format and parsing are fundamental to the protocol's ability to maintain transaction integrity, handle application-level acknowledgements, and support full-duplex communication.
The framing structure is designed to be human-readable and easy to parse, consisting of a header, optional data, and a trailer. Every RELP transaction is encapsulated within these frames, where each command is assigned a monotonically increasing transaction number (TXNR).
Sources: doc/relp.html:86-101, src/relpframe.h:54-65
RELP Frame Structure
A RELP frame consists of three primary components: a Header, optional Data, and a Trailer. The structure is defined as: TXNR SP COMMAND SP DATALEN [SP DATA] TRAILER.
Frame Components
| Component | Description | Format/Constraints |
|---|---|---|
| TXNR | Transaction Number. Monotonically increasing ID starting at 1. TXNR 0 is reserved for hint commands. | 1 to 9 digits (max 999,999,999) |
| COMMAND | The action to be performed (e.g., open, syslog, close, rsp). | 1 to 32 Alpha characters |
| DATALEN | The number of octets in the DATA field. | 1 to 9 digits |
| DATA | Command-defined payload. Only present if DATALEN > 0. | Octet stream |
| TRAILER | A single Line Feed (LF) character to detect framing errors. | %d10 (LF) |
Sources: doc/relp.html:103-120, src/relpframe.c:115-160
Parsing Logic & State Machine
The library implements a state machine to process incoming octets and reconstruct RELP frames. The parser handles data stream-wise, transitioning through states as it validates each part of the frame.
Parser States
The relpFrameRcvState_t enumeration defines the following states for frame reception:
- eRelpFrameRcvState_BEGIN_FRAME: Initial state expecting the start of a TXNR.
- eRelpFrameRcvState_IN_TXNR: Accumulating digits for the transaction number.
- eRelpFrameRcvState_IN_CMD: Accumulating characters for the command string.
- eRelpFrameRcvState_IN_DATALEN: Accumulating digits for the data length.
- eRelpFrameRcvState_IN_DATA: Reading the number of octets specified by DATALEN.
- eRelpFrameRcvState_IN_TRAILER: Verifying the presence of the LF trailer.
- eRelpFrameRcvState_FINISHED: Frame is fully received and ready for dispatching.
Sources: src/relpframe.h:44-52, src/relpframe.c:115-207
Reception Flow Diagram
The following diagram illustrates the state transitions during the parsing of a single RELP frame.
This state machine ensures that frames are rejected immediately if they violate length constraints or character type requirements (e.g., non-digits in the TXNR field).
Sources: src/relpframe.c:115-231
Response Frame Parsing ("rsp")
The rsp command carries the status of a previous transaction. The data portion of a response frame has its own sub-format: RSP-CODE SP [HUMANMSG] LF [CMDDATA].
Response Header Parsing
The function readRspHdr is responsible for extracting the status code and human-readable message from the response data.
- RSP-CODE: Exactly three digits (e.g., 200 for OK, 500 for Error).
- HUMANMSG: Up to 80 characters of text terminated by an LF or end of data.
Sources: src/scrsp.c:50-100, doc/relp.html:125-131
Frame Construction & Transmission
Frames are constructed using the relpFrameBuildSendbuf function, which prepares a relpSendbuf_t for the network layer.
Construction Logic
To optimize performance and support session recovery, the builder reserves 9 bytes for the TXNR field regardless of the actual digit count. This allows relpFrameRewriteTxnr to patch in a new TXNR without reallocating or shifting the entire frame buffer when retransmitting unacknowledged frames.
Sources: src/relpframe.c:301-344, src/relpframe.c:266-291
Data Structures
The primary object representing a frame during reception is struct relpFrame_s.
rcvState: Tracks the current position in the parsing state machine.iRcv: A multi-purpose index used to track the number of processed octets for the current field.txnr: The sequence number assigned to the transaction.pData: A dynamically allocated buffer for the command payload.
Sources: src/relpframe.h:57-67
Error Handling during Parsing
The parser strictly enforces protocol constraints to prevent Denial of Service (DoS) attacks and data corruption.
- Field Length Limits: TXNR and DATALEN are capped at 9 digits. The COMMAND is capped at 32 characters.
- Oversize Frames: The behavior when
DATALENexceedsmaxDataSizeis configurable viaoversizeMode:- RELP_OVERSIZE_ABORT: Immediately terminates the session (Default).
- RELP_OVERSIZE_TRUNCATE: Accepts the frame but truncates the data to
maxDataSize. - RELP_OVERSIZE_ACCEPT: Accepts the frame regardless of length (Risky).
- Invalid Characters: Any non-digit character in a numeric field or non-alpha character in the command field results in
RELP_RET_INVALID_FRAME.
Sources: src/relpframe.c:127-130, src/relpframe.c:164-190, src/relp.h:176-178
Summary
Frame format and parsing in librelp provide the foundation for the protocol's reliability. By utilizing a robust state machine for reception and a flexible buffer system for transmission, the library ensures that every event is correctly framed, sequence-tracked via TXNRs, and validated against size and format constraints before being dispatched to command-specific handlers.
Sources: src/relpframe.c:115-231, doc/relp.html:86-120