LibCurl Consumer

The LibCurl consumer is a synchronous transport implementation that utilizes the PHP curl extension to transmit event batches to the RudderStack Data Plane. It is designed for environments where reliable, synchronous delivery is preferred over the "fire-and-forget" nature of other consumers.

Implementation Overview

The LibCurl class extends QueueConsumer and implements the flushBatch method to handle the actual HTTP transmission. Unlike asynchronous consumers, LibCurl blocks execution until the request completes or the timeout is reached.

Data Flow and Request Lifecycle

When the internal queue reaches the flush_at threshold or flush() is called manually, the following sequence occurs:

1. Payload Preparation: The batch of messages is wrapped in a standard RudderStack payload object via payload($messages) lib/Consumer/LibCurl.php20
2. Compression: If compress_request is enabled, the JSON-encoded payload is compressed using gzencode lib/Consumer/LibCurl.php25-27
3. Header Construction: Standard headers are set, including Content-Type: application/json and User-Agent based on the SDK version lib/Consumer/LibCurl.php45-57
4. Ordering Preservation: If the batch contains exactly one event, the consumer extracts the userId or anonymousId and adds it as a Base64-encoded AnonymousId HTTP header to help the server maintain event ordering lib/Consumer/LibCurl.php59-71
5. Execution: The request is dispatched via curl_exec lib/Consumer/LibCurl.php78

Code Entity Map: Request Construction

The following diagram maps the logical HTTP request components to the specific PHP code entities responsible for generating them.

Title: LibCurl Request Construction Map

Sources: lib/Consumer/LibCurl.php18-75

---

Retry Logic and Backoff

The LibCurl consumer implements an exponential backoff strategy to handle transient network issues or server-side rate limiting.

Exponential Backoff Mechanism

The consumer starts with an initial backoff of 100ms lib/Consumer/LibCurl.php32 If a retriable error occurs, it waits for the current backoff duration using usleep and then doubles the duration for the next attempt lib/Consumer/LibCurl.php107-108 This continues until the duration exceeds maximum_backoff_duration lib/Consumer/LibCurl.php34

Status Code Handling

The consumer distinguishes between retriable and non-retriable HTTP status codes:

Status Code(s)	Classification	Action
200	Success	Terminate loop, return true lib/Consumer/LibCurl.php112-114
429	Retriable (Rate Limited)	Apply backoff and retry lib/Consumer/LibCurl.php103-108
500 - 600	Retriable (Server Error)	Apply backoff and retry lib/Consumer/LibCurl.php103-108
400 - 499 (excl. 429)	Non-Retriable (Client Error)	Log error and abort batch lib/Consumer/LibCurl.php109-110

Logic Flow: Retry Loop

Title: LibCurl Retry and Error Handling Logic

Sources: lib/Consumer/LibCurl.php34-118

---

Configuration Options

The LibCurl consumer respects several configuration options passed during the initialization of the Rudder client.

Option	Type	Description
compress_request	bool	If true, the payload is compressed using gzencode and the Content-Encoding: gzip header is added lib/Consumer/LibCurl.php25-27
curl_timeout	int	The maximum number of seconds to allow cURL functions to execute lib/Consumer/LibCurl.php41
curl_connecttimeout	int	The number of seconds to wait while trying to connect lib/Consumer/LibCurl.php42
maximum_backoff_duration	int	The ceiling for the exponential backoff (in milliseconds) lib/Consumer/LibCurl.php34

Error Handling

If a cURL error occurs (e.g., DNS failure, connection refused), the consumer captures the error code and message via curl_errno and curl_error and passes them to the handleError method inherited from the base class lib/Consumer/LibCurl.php80-84

Sources: lib/Consumer/LibCurl.php7-120