fast_curl 0.3.1 → 0.5.0

data/ext/fast_curl/fast_curl.c

@@ -11,7 +11,10 @@
 #define FAST_CURL_HAVE_FIBER_SCHEDULER 1
 #endif
 #include <curl/curl.h>
+#include <ctype.h>
 #include <limits.h>
+#include <pthread.h>
+#include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 #include <strings.h>
@@ -23,20 +26,25 @@
 #define FAST_CURL_NORETURN
 #endif
 
-#define MAX_RESPONSE_SIZE     (100 * 1024 * 1024)
-#define MAX_REDIRECTS         5
-#define MAX_TIMEOUT           300
-#define MAX_RETRIES           10
-#define MAX_REQUESTS          10000
-#define MAX_CONNECTIONS       100
-#define MAX_RETRY_DELAY_MS    30000
-#define DEFAULT_RETRIES       1
-#define DEFAULT_RETRY_DELAY   0
-#define INITIAL_BUF_CAP       8192
-#define INITIAL_HEADER_CAP    16
-#define POLL_TIMEOUT_MS       50
-#define FIBER_POLL_TIMEOUT_MS 10
-#define HEADER_LINE_BUF_SIZE  512
+#define MAX_RESPONSE_SIZE          (100 * 1024 * 1024)
+#define MAX_REDIRECTS              5
+#define MAX_TIMEOUT                300
+#define MAX_RETRIES                10
+#define MAX_REQUESTS               10000
+#define MAX_CONNECTIONS            100
+#define MAX_BUFFER                 10000
+#define MAX_RETRY_DELAY_MS         30000
+#define DEFAULT_RETRIES            1
+#define DEFAULT_RETRY_DELAY        100
+#define DEFAULT_CONNECT_TIMEOUT_MS 10000L
+#define MAX_CONNECT_TIMEOUT_MS     300000L
+#define MAX_TOTAL_TIMEOUT_MS       3600000L
+#define INITIAL_BUF_CAP            8192
+#define INITIAL_HEADER_CAP         16
+#define POLL_TIMEOUT_MS            50
+#define POLL_SLICE_MS              2000
+#define FIBER_POLL_TIMEOUT_MS      10
+#define HEADER_LINE_BUF_SIZE       512
 
 static const CURLcode DEFAULT_RETRYABLE_CURLE[] = {
     CURLE_COULDNT_CONNECT, CURLE_OPERATION_TIMEDOUT, CURLE_SEND_ERROR,       CURLE_RECV_ERROR,
@@ -57,6 +65,16 @@ typedef enum {
     KEY_RETRIES,
     KEY_RETRY_DELAY,
     KEY_RETRY_CODES,
+    KEY_CONNECT_TIMEOUT,
+    KEY_TOTAL_TIMEOUT,
+    KEY_RETRY_NON_IDEMPOTENT,
+    KEY_FOLLOW_REDIRECTS,
+    KEY_MAX_REDIRECTS,
+    KEY_EFFECTIVE_URL,
+    KEY_ERROR,
+    KEY_ATTEMPTS,
+    KEY_BUFFER,
+    KEY_ACCEPT,
     KEY_LAST
 } key_id_t;
 
@@ -66,10 +84,113 @@ static VALUE fast_syms[KEY_LAST];
 #define SYM(key) fast_syms[key]
 
 static const char *const KEY_NAMES[KEY_LAST] = {
-    "status",  "headers",     "body",  "error_code", "url",         "method",
-    "timeout", "connections", "count", "retries",    "retry_delay", "retry_codes",
+    "status",
+    "headers",
+    "body",
+    "error_code",
+    "url",
+    "method",
+    "timeout",
+    "connections",
+    "count",
+    "retries",
+    "retry_delay",
+    "retry_codes",
+    "connect_timeout",
+    "total_timeout",
+    "retry_non_idempotent",
+    "follow_redirects",
+    "max_redirects",
+    "effective_url",
+    "error",
+    "attempts",
+    "buffer",
+    "accept",
 };
 
+typedef enum {
+    ERR_CURL,
+    ERR_INVALID_REQUEST,
+    ERR_NOT_COMPLETED,
+    ERR_DEADLINE,
+    ERR_LAST
+} error_kind_t;
+
+static VALUE error_syms[ERR_LAST];
+
+static const char *const ERROR_KIND_NAMES[ERR_LAST] = {
+    "curl_error",
+    "invalid_request",
+    "not_completed",
+    "deadline_exceeded",
+};
+
+static long long fast_now_ms(void) {
+    struct timespec ts;
+#ifdef CLOCK_MONOTONIC
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+#else
+    clock_gettime(CLOCK_REALTIME, &ts);
+#endif
+    return (long long)ts.tv_sec * 1000LL + ts.tv_nsec / 1000000LL;
+}
+
+static uint64_t fast_rand_state;
+
+/* Small xorshift PRNG; only used to jitter retry delays. */
+static uint32_t fast_rand(void) {
+    uint64_t x = fast_rand_state;
+    if (x == 0)
+        x = (uint64_t)fast_now_ms() | 1ULL;
+    x ^= x << 13;
+    x ^= x >> 7;
+    x ^= x << 17;
+    fast_rand_state = x;
+    return (uint32_t)(x >> 32);
+}
+
+/* Process-wide DNS and TLS session cache, so repeated calls to the same host
+   skip resolution and can resume TLS instead of doing a full handshake. */
+static CURLSH *fast_share = NULL;
+static pthread_mutex_t fast_share_locks[CURL_LOCK_DATA_LAST];
+
+static void fast_share_lock(CURL *handle, curl_lock_data data, curl_lock_access access,
+                            void *userptr) {
+    (void)handle;
+    (void)access;
+    (void)userptr;
+    if ((int)data > 0 && (int)data < CURL_LOCK_DATA_LAST)
+        pthread_mutex_lock(&fast_share_locks[data]);
+}
+
+static void fast_share_unlock(CURL *handle, curl_lock_data data, void *userptr) {
+    (void)handle;
+    (void)userptr;
+    if ((int)data > 0 && (int)data < CURL_LOCK_DATA_LAST)
+        pthread_mutex_unlock(&fast_share_locks[data]);
+}
+
+static void fast_share_init(void) {
+    for (int i = 0; i < CURL_LOCK_DATA_LAST; i++)
+        pthread_mutex_init(&fast_share_locks[i], NULL);
+
+    fast_share = curl_share_init();
+    if (!fast_share)
+        return;
+
+    curl_share_setopt(fast_share, CURLSHOPT_LOCKFUNC, fast_share_lock);
+    curl_share_setopt(fast_share, CURLSHOPT_UNLOCKFUNC, fast_share_unlock);
+    curl_share_setopt(fast_share, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
+    curl_share_setopt(fast_share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION);
+
+    /* CURL_LOCK_DATA_CONNECT is deliberately NOT shared. Sharing the connection
+       cache between multi handles running concurrently in different threads
+       deadlocks against CURLMOPT_MAX_TOTAL_CONNECTIONS, and removing that limit
+       turns the deadlock into a segfault inside curl_multi_perform (reproduced
+       on libcurl 8.5.0 with two threads x 25 requests). Cross-call TCP reuse
+       needs a persistent multi handle per thread, not a shared cache. */
+}
+
 typedef struct {
     char *data;
     size_t len;
@@ -204,7 +325,7 @@ static size_t header_callback(char *ptr, size_t size, size_t nmemb, void *userda
 
 typedef struct {
     CURL *easy;
-    int index;
+    long index;
     buffer_t body;
     header_list_t headers;
     struct curl_slist *req_headers;
@@ -212,9 +333,20 @@ typedef struct {
     int active;
     CURLcode curl_result;
     long http_status;
+    int idempotent;
+    int attempts;
+    const char *setup_error;
+    int setup_error_fatal;
 } request_ctx_t;
 
-static inline void request_ctx_init(request_ctx_t *ctx, int index) {
+static VALUE fast_validation_error = Qnil;
+#define SET_SETUP_ERROR(ctx, msg, fatal)    \
+    do {                                    \
+        (ctx)->setup_error = (msg);         \
+        (ctx)->setup_error_fatal = (fatal); \
+    } while (0)
+
+static inline void request_ctx_init(request_ctx_t *ctx, long index) {
     ctx->easy = NULL;
     ctx->index = index;
     buffer_init(&ctx->body);
@@ -224,6 +356,10 @@ static inline void request_ctx_init(request_ctx_t *ctx, int index) {
     ctx->active = 0;
     ctx->curl_result = CURLE_OK;
     ctx->http_status = 0;
+    ctx->idempotent = 1;
+    ctx->attempts = 0;
+    ctx->setup_error = NULL;
+    ctx->setup_error_fatal = 0;
 }
 
 static void request_ctx_free(request_ctx_t *ctx) {
@@ -267,6 +403,8 @@ static int request_ctx_reset_for_retry(request_ctx_t *ctx) {
     ctx->active = 0;
     ctx->curl_result = CURLE_OK;
     ctx->http_status = 0;
+    ctx->setup_error = NULL;
+    ctx->setup_error_fatal = 0;
     return 1;
 }
 
@@ -291,8 +429,18 @@ typedef struct {
     long retry_delay_ms;
     int *retry_http_codes;
     int retry_http_count;
+    int retry_non_idempotent;
 } retry_config_t;
 
+typedef struct {
+    long timeout_sec;
+    long connect_timeout_ms;
+    long total_timeout_ms;
+    long follow_redirects;
+    long max_redirects;
+    long long deadline_ms;
+} request_options_t;
+
 static int contains_header_injection(const char *str, long len) {
     for (long i = 0; i < len; i++) {
         if (str[i] == '\r' || str[i] == '\n' || str[i] == '\0')
@@ -392,24 +540,37 @@ static void run_via_fiber_worker(VALUE scheduler, void *(*func)(void *), void *a
 }
 #endif
 
-static void headers_hash_store(VALUE headers_hash, VALUE key, VALUE val) {
+static VALUE fast_cHeaders = Qnil;
+static VALUE new_headers_hash(void) {
+    if (!NIL_P(fast_cHeaders))
+        return rb_obj_alloc(fast_cHeaders);
+    return rb_hash_new();
+}
+
+static void headers_hash_store(VALUE headers_hash, VALUE key, VALUE val, int always_array) {
     VALUE existing = rb_hash_aref(headers_hash, key);
 
     if (NIL_P(existing)) {
-        rb_hash_aset(headers_hash, key, val);
-    } else if (RB_TYPE_P(existing, T_ARRAY)) {
+        rb_hash_aset(headers_hash, key, always_array ? rb_ary_new_from_args(1, val) : val);
+        return;
+    }
+
+    if (RB_TYPE_P(existing, T_ARRAY)) {
         rb_ary_push(existing, val);
-    } else {
-        VALUE values = rb_ary_new_from_args(2, existing, val);
-        rb_hash_aset(headers_hash, key, values);
+        return;
     }
+
+    VALUE joined = rb_str_dup(existing);
+    rb_str_cat_cstr(joined, ", ");
+    rb_str_append(joined, val);
+    rb_hash_aset(headers_hash, key, joined);
 }
 
 static VALUE build_response(request_ctx_t *ctx) {
     long status = 0;
     curl_easy_getinfo(ctx->easy, CURLINFO_RESPONSE_CODE, &status);
 
-    VALUE headers_hash = rb_hash_new();
+    VALUE headers_hash = new_headers_hash();
     for (int i = 0; i < ctx->headers.count; i++) {
         const char *hdr = ctx->headers.entries[i].str;
         size_t hdr_len = ctx->headers.entries[i].len;
@@ -418,6 +579,12 @@ static VALUE build_response(request_ctx_t *ctx) {
             continue;
 
         VALUE key = rb_str_new(hdr, colon - hdr);
+        char *kp = RSTRING_PTR(key);
+        long klen = RSTRING_LEN(key);
+        for (long k = 0; k < klen; k++)
+            kp[k] = (char)tolower((unsigned char)kp[k]);
+        int always_array = (klen == 10 && memcmp(kp, "set-cookie", 10) == 0);
+
         const char *vs = colon + 1;
         const char *ve = hdr + hdr_len;
 
@@ -427,7 +594,7 @@ static VALUE build_response(request_ctx_t *ctx) {
             ve--;
 
         VALUE val = rb_str_new(vs, ve - vs);
-        headers_hash_store(headers_hash, key, val);
+        headers_hash_store(headers_hash, key, val, always_array);
     }
 
     VALUE body_str =
@@ -437,19 +604,33 @@ static VALUE build_response(request_ctx_t *ctx) {
     rb_hash_aset(result, SYM(KEY_STATUS), LONG2NUM(status));
     rb_hash_aset(result, SYM(KEY_HEADERS), headers_hash);
     rb_hash_aset(result, SYM(KEY_BODY), body_str);
+    rb_hash_aset(result, SYM(KEY_ERROR), Qnil);
+    rb_hash_aset(result, SYM(KEY_ERROR_CODE), Qnil);
+    rb_hash_aset(result, SYM(KEY_ATTEMPTS), INT2NUM(ctx->attempts));
+
+    char *effective = NULL;
+    if (curl_easy_getinfo(ctx->easy, CURLINFO_EFFECTIVE_URL, &effective) == CURLE_OK && effective)
+        rb_hash_aset(result, SYM(KEY_EFFECTIVE_URL), rb_str_new_cstr(effective));
+    else
+        rb_hash_aset(result, SYM(KEY_EFFECTIVE_URL), Qnil);
+
     return result;
 }
 
-static VALUE build_error_response(const char *message) {
+static VALUE build_error_response(const char *message, error_kind_t kind, int attempts) {
     VALUE r = rb_hash_new();
     rb_hash_aset(r, SYM(KEY_STATUS), INT2NUM(0));
     rb_hash_aset(r, SYM(KEY_HEADERS), Qnil);
     rb_hash_aset(r, SYM(KEY_BODY), rb_str_new_cstr(message));
+    rb_hash_aset(r, SYM(KEY_ERROR), error_syms[kind]);
+    rb_hash_aset(r, SYM(KEY_ERROR_CODE), Qnil);
+    rb_hash_aset(r, SYM(KEY_EFFECTIVE_URL), Qnil);
+    rb_hash_aset(r, SYM(KEY_ATTEMPTS), INT2NUM(attempts));
     return r;
 }
 
-static VALUE build_error_response_with_code(const char *message, int error_code) {
-    VALUE r = build_error_response(message);
+static VALUE build_error_response_with_code(const char *message, int error_code, int attempts) {
+    VALUE r = build_error_response(message, ERR_CURL, attempts);
     rb_hash_aset(r, SYM(KEY_ERROR_CODE), INT2NUM(error_code));
     return r;
 }
@@ -474,20 +655,33 @@ static int is_valid_url(const char *url) {
             return _r;                                         \
     } while (0)
 
-static CURLcode setup_basic_options(CURL *easy, const char *url_str, long timeout_sec,
+static CURLcode setup_basic_options(CURL *easy, const char *url_str, const request_options_t *opts,
                                     request_ctx_t *ctx) {
+    long timeout_ms = opts->timeout_sec * 1000L;
+
+    if (opts->deadline_ms > 0) {
+        long long remaining = opts->deadline_ms - fast_now_ms();
+        if (remaining < 1)
+            remaining = 1;
+        if (remaining < (long long)timeout_ms)
+            timeout_ms = (long)remaining;
+    }
+
     CURL_SETOPT_CHECK(easy, CURLOPT_URL, url_str);
     CURL_SETOPT_CHECK(easy, CURLOPT_WRITEFUNCTION, write_callback);
     CURL_SETOPT_CHECK(easy, CURLOPT_WRITEDATA, &ctx->body);
     CURL_SETOPT_CHECK(easy, CURLOPT_HEADERFUNCTION, header_callback);
     CURL_SETOPT_CHECK(easy, CURLOPT_HEADERDATA, &ctx->headers);
-    CURL_SETOPT_CHECK(easy, CURLOPT_TIMEOUT, timeout_sec);
+    CURL_SETOPT_CHECK(easy, CURLOPT_TIMEOUT_MS, timeout_ms);
+    CURL_SETOPT_CHECK(easy, CURLOPT_CONNECTTIMEOUT_MS, opts->connect_timeout_ms);
     CURL_SETOPT_CHECK(easy, CURLOPT_NOSIGNAL, 1L);
-    CURL_SETOPT_CHECK(easy, CURLOPT_FOLLOWLOCATION, 1L);
-    CURL_SETOPT_CHECK(easy, CURLOPT_MAXREDIRS, MAX_REDIRECTS);
+    CURL_SETOPT_CHECK(easy, CURLOPT_FOLLOWLOCATION, opts->follow_redirects);
+    CURL_SETOPT_CHECK(easy, CURLOPT_MAXREDIRS, opts->max_redirects);
     CURL_SETOPT_CHECK(easy, CURLOPT_ACCEPT_ENCODING, "");
     CURL_SETOPT_CHECK(easy, CURLOPT_PRIVATE, (char *)ctx);
     CURL_SETOPT_CHECK(easy, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2TLS);
+    if (fast_share)
+        CURL_SETOPT_CHECK(easy, CURLOPT_SHARE, fast_share);
     return CURLE_OK;
 }
 
@@ -518,12 +712,13 @@ typedef struct {
     int post;
     int nobody;
     int allows_body;
+    int idempotent;
 } http_method_t;
 
 static const http_method_t HTTP_METHODS[] = {
-    {"GET", NULL, 0, 0, 0},          {"POST", NULL, 1, 0, 1},     {"PUT", "PUT", 0, 0, 1},
-    {"DELETE", "DELETE", 0, 0, 1},   {"PATCH", "PATCH", 0, 0, 1}, {"HEAD", NULL, 0, 1, 0},
-    {"OPTIONS", "OPTIONS", 0, 0, 0},
+    {"GET", NULL, 0, 0, 0, 1},          {"POST", NULL, 1, 0, 1, 0},     {"PUT", "PUT", 0, 0, 1, 1},
+    {"DELETE", "DELETE", 0, 0, 1, 1},   {"PATCH", "PATCH", 0, 0, 1, 0}, {"HEAD", NULL, 0, 1, 0, 1},
+    {"OPTIONS", "OPTIONS", 0, 0, 0, 1},
 };
 
 static const http_method_t *find_http_method(const char *name) {
@@ -544,29 +739,52 @@ static CURLcode apply_http_method(CURL *easy, const http_method_t *method) {
     return CURLE_OK;
 }
 
-static CURLcode setup_method_and_body(CURL *easy, VALUE method_value, VALUE body) {
-    const char *name = NIL_P(method_value) ? "GET" : StringValueCStr(method_value);
-    const http_method_t *method = find_http_method(name);
+static int setup_method_and_body(request_ctx_t *ctx, VALUE method_value, VALUE body) {
+    const http_method_t *method;
     int has_body = !NIL_P(body);
+    char name[32];
 
-    if (!method)
-        rb_raise(rb_eArgError, "Unsupported HTTP method: %s", name);
-    if (has_body && !method->allows_body)
-        rb_raise(rb_eArgError, "%s requests must not include a body", method->name);
+    if (NIL_P(method_value)) {
+        memcpy(name, "GET", 4);
+    } else {
+        if (!RB_TYPE_P(method_value, T_STRING)) {
+            SET_SETUP_ERROR(ctx, "Unsupported HTTP method", 1);
+            return 0;
+        }
+        long len = RSTRING_LEN(method_value);
+        if (len <= 0 || len >= (long)sizeof(name)) {
+            SET_SETUP_ERROR(ctx, "Unsupported HTTP method", 1);
+            return 0;
+        }
+        memcpy(name, RSTRING_PTR(method_value), (size_t)len);
+        name[len] = '\0';
+    }
+
+    method = find_http_method(name);
+    if (!method) {
+        SET_SETUP_ERROR(ctx, "Unsupported HTTP method", 1);
+        return 0;
+    }
+    if (has_body && !method->allows_body) {
+        SET_SETUP_ERROR(ctx, "This HTTP method must not include a body", 1);
+        return 0;
+    }
+
+    ctx->idempotent = method->idempotent;
 
-    CURLcode res = apply_http_method(easy, method);
-    if (res != CURLE_OK)
-        return res;
+    if (apply_http_method(ctx->easy, method) != CURLE_OK) {
+        SET_SETUP_ERROR(ctx, "Failed to configure HTTP method", 0);
+        return 0;
+    }
 
-    if (has_body) {
-        res = set_body(easy, body);
-        if (res != CURLE_OK)
-            return res;
+    if (has_body && set_body(ctx->easy, body) != CURLE_OK) {
+        SET_SETUP_ERROR(ctx, "Failed to configure request body", 0);
+        return 0;
     }
 
     RB_GC_GUARD(method_value);
     RB_GC_GUARD(body);
-    return CURLE_OK;
+    return 1;
 }
 
 static void append_request_header(request_ctx_t *ctx, const char *buf) {
@@ -608,23 +826,42 @@ static void append_formatted_header(request_ctx_t *ctx, const char *key, long ke
         free(line);
 }
 
+static VALUE header_part_to_str(VALUE v) {
+    if (RB_TYPE_P(v, T_STRING))
+        return v;
+    if (SYMBOL_P(v))
+        return rb_sym2str(v);
+    return rb_String(v);
+}
+
 static int header_iter_cb(VALUE key, VALUE val, VALUE arg) {
     request_ctx_t *ctx = (request_ctx_t *)arg;
-    VALUE key_str = rb_String(key);
-    VALUE val_str = NIL_P(val) ? Qnil : rb_String(val);
-    const char *k = RSTRING_PTR(key_str);
-    long klen = RSTRING_LEN(key_str);
+    VALUE key_str, val_str;
+    const char *k;
+    long klen;
     const char *v = NULL;
     long vlen = 0;
 
-    if (!is_valid_header_name(k, klen) || contains_header_injection(k, klen))
-        rb_raise(rb_eArgError, "Invalid HTTP header name");
+    if (ctx->setup_error)
+        return ST_STOP;
+
+    key_str = header_part_to_str(key);
+    val_str = NIL_P(val) ? Qnil : header_part_to_str(val);
+    k = RSTRING_PTR(key_str);
+    klen = RSTRING_LEN(key_str);
+
+    if (!is_valid_header_name(k, klen) || contains_header_injection(k, klen)) {
+        SET_SETUP_ERROR(ctx, "Invalid HTTP header name", 1);
+        return ST_STOP;
+    }
 
     if (!NIL_P(val_str) && RSTRING_LEN(val_str) > 0) {
         v = RSTRING_PTR(val_str);
         vlen = RSTRING_LEN(val_str);
-        if (contains_header_injection(v, vlen))
-            rb_raise(rb_eArgError, "Invalid HTTP header value");
+        if (contains_header_injection(v, vlen)) {
+            SET_SETUP_ERROR(ctx, "Invalid HTTP header value", 1);
+            return ST_STOP;
+        }
     }
 
     append_formatted_header(ctx, k, klen, v, vlen);
@@ -634,40 +871,58 @@ static int header_iter_cb(VALUE key, VALUE val, VALUE arg) {
     return ST_CONTINUE;
 }
 
-static int setup_easy_handle(request_ctx_t *ctx, VALUE request, long timeout_sec) {
-    Check_Type(request, T_HASH);
+static int setup_easy_handle(request_ctx_t *ctx, VALUE request, const request_options_t *opts) {
+    if (!RB_TYPE_P(request, T_HASH)) {
+        SET_SETUP_ERROR(ctx, "Request must be a Hash", 1);
+        return 0;
+    }
 
     VALUE url = hash_aref_key(request, KEY_URL);
     VALUE method = hash_aref_key(request, KEY_METHOD);
     VALUE headers = hash_aref_key(request, KEY_HEADERS);
     VALUE body = hash_aref_key(request, KEY_BODY);
 
-    if (NIL_P(url))
+    if (NIL_P(url)) {
+        SET_SETUP_ERROR(ctx, "Missing :url", 0);
+        return 0;
+    }
+    if (!RB_TYPE_P(url, T_STRING) || memchr(RSTRING_PTR(url), '\0', RSTRING_LEN(url))) {
+        SET_SETUP_ERROR(ctx, "Invalid URL", 1);
         return 0;
+    }
 
     const char *url_str = StringValueCStr(url);
-    if (!is_valid_url(url_str))
-        rb_raise(rb_eArgError, "Invalid URL: %s", url_str);
+    if (!is_valid_url(url_str)) {
+        SET_SETUP_ERROR(ctx, "Invalid URL (expected http:// or https://, max 2048 bytes)", 1);
+        return 0;
+    }
 
-    CURLcode res = setup_basic_options(ctx->easy, url_str, timeout_sec, ctx);
-    if (res != CURLE_OK)
+    if (setup_basic_options(ctx->easy, url_str, opts, ctx) != CURLE_OK) {
+        SET_SETUP_ERROR(ctx, "Failed to configure request", 0);
         return 0;
+    }
 
-    res = setup_security_options(ctx->easy);
-    if (res != CURLE_OK)
+    if (setup_security_options(ctx->easy) != CURLE_OK) {
+        SET_SETUP_ERROR(ctx, "Failed to configure TLS options", 0);
         return 0;
+    }
 
-    res = setup_method_and_body(ctx->easy, method, body);
-    if (res != CURLE_OK)
+    if (!setup_method_and_body(ctx, method, body))
         return 0;
 
     if (!NIL_P(headers)) {
-        Check_Type(headers, T_HASH);
+        if (!RB_TYPE_P(headers, T_HASH)) {
+            SET_SETUP_ERROR(ctx, ":headers must be a Hash", 1);
+            return 0;
+        }
         rb_hash_foreach(headers, header_iter_cb, (VALUE)ctx);
+        if (ctx->setup_error)
+            return 0;
         if (ctx->req_headers) {
-            res = curl_easy_setopt(ctx->easy, CURLOPT_HTTPHEADER, ctx->req_headers);
-            if (res != CURLE_OK)
+            if (curl_easy_setopt(ctx->easy, CURLOPT_HTTPHEADER, ctx->req_headers) != CURLE_OK) {
+                SET_SETUP_ERROR(ctx, "Failed to set request headers", 0);
                 return 0;
+            }
         }
     }
 
@@ -679,14 +934,25 @@ static int setup_easy_handle(request_ctx_t *ctx, VALUE request, long timeout_sec
     return 1;
 }
 
+/* Poll until something actually completes, or the slice budget expires.
+   Previously this returned after every single 50ms poll, which under a fiber
+   scheduler meant a fresh OS thread twenty times a second. Cancellation still
+   breaks out immediately via curl_multi_wakeup. */
 static void *poll_without_gvl(void *arg) {
     multi_session_t *s = (multi_session_t *)arg;
-    if (s->cancelled)
-        return NULL;
+    long long started = fast_now_ms();
+    int before = s->still_running;
+
+    while (!s->cancelled) {
+        int numfds = 0;
+        curl_multi_poll(s->multi, NULL, 0, POLL_TIMEOUT_MS, &numfds);
+        curl_multi_perform(s->multi, &s->still_running);
 
-    int numfds = 0;
-    curl_multi_poll(s->multi, NULL, 0, POLL_TIMEOUT_MS, &numfds);
-    curl_multi_perform(s->multi, &s->still_running);
+        if (s->still_running == 0 || s->still_running < before)
+            break;
+        if (fast_now_ms() - started >= POLL_SLICE_MS)
+            break;
+    }
     return NULL;
 }
 
@@ -700,28 +966,52 @@ static void unblock_perform(void *arg) {
 
 typedef struct {
     VALUE results;
+    VALUE accept;
     int completed;
     int target;
     int stream;
 } completion_ctx_t;
 
-static VALUE build_result_pair(int index, VALUE response) {
-    return rb_ary_new_from_args(2, INT2NUM(index), response);
+static VALUE build_result_pair(long index, VALUE response) {
+    return rb_ary_new_from_args(2, LONG2NUM(index), response);
 }
 
-static int record_immediate_error(completion_ctx_t *cctx, int index, const char *message) {
-    if (cctx->stream || cctx->target > 0) {
-        VALUE pair = build_result_pair(index, build_error_response(message));
+static int response_accepted(completion_ctx_t *cctx, VALUE response) {
+    if (cctx->target <= 0 || NIL_P(cctx->accept))
+        return 1;
 
-        if (cctx->stream)
-            rb_yield(pair);
-        else
-            rb_ary_push(cctx->results, pair);
+    return RTEST(rb_funcall(cctx->accept, rb_intern("call"), 1, response));
+}
+
+static int record_response(completion_ctx_t *cctx, long index, VALUE response) {
+    VALUE pair = build_result_pair(index, response);
 
+    if (cctx->stream) {
+        rb_yield(pair);
         cctx->completed++;
-        if (cctx->target > 0 && cctx->completed >= cctx->target)
-            return 1;
+        return 0;
+    }
+
+    if (cctx->target > 0) {
+        if (!response_accepted(cctx, response))
+            return 0;
+
+        rb_ary_push(cctx->results, pair);
+        cctx->completed++;
+        return cctx->completed >= cctx->target;
     }
+
+    rb_ary_store(cctx->results, index, pair);
+    cctx->completed++;
+    return 0;
+}
+
+static int record_immediate_error(completion_ctx_t *cctx, long index, const char *message,
+                                  int attempts) {
+    if (cctx->stream || cctx->target > 0)
+        return record_response(cctx, index,
+                               build_error_response(message, ERR_INVALID_REQUEST, attempts));
+
     return 0;
 }
 
@@ -751,21 +1041,16 @@ static int process_completed(multi_session_t *session, completion_ctx_t *cctx) {
             curl_easy_getinfo(ctx->easy, CURLINFO_RESPONSE_CODE, &ctx->http_status);
 
         if (cctx->stream || cctx->target > 0) {
-            VALUE response = (msg->data.result == CURLE_OK)
-                                 ? build_response(ctx)
-                                 : build_error_response_with_code(
-                                       curl_easy_strerror(msg->data.result), (int)msg->data.result);
-            VALUE pair = build_result_pair(ctx->index, response);
-
-            if (cctx->stream)
-                rb_yield(pair);
-            else
-                rb_ary_push(cctx->results, pair);
+            VALUE response =
+                (msg->data.result == CURLE_OK)
+                    ? build_response(ctx)
+                    : build_error_response_with_code(curl_easy_strerror(msg->data.result),
+                                                     (int)msg->data.result, ctx->attempts);
+            if (record_response(cctx, ctx->index, response))
+                return 1;
+        } else {
+            cctx->completed++;
         }
-
-        cctx->completed++;
-        if (cctx->target > 0 && cctx->completed >= cctx->target)
-            return 1;
     }
 
     return 0;
@@ -782,30 +1067,34 @@ static int next_pending_index(multi_session_t *session) {
 }
 
 static int activate_request(multi_session_t *session, VALUE requests, int idx, int *invalid,
-                            long timeout_sec) {
+                            const request_options_t *opts) {
     request_ctx_t *ctx = &session->requests[idx];
 
     if (invalid[idx] || ctx->done)
         return 0;
 
-    if (!request_ctx_prepare_easy(ctx))
+    if (!request_ctx_prepare_easy(ctx)) {
+        SET_SETUP_ERROR(ctx, "Failed to allocate a curl handle", 0);
         return 0;
+    }
 
-    if (!setup_easy_handle(ctx, rb_ary_entry(requests, idx), timeout_sec))
+    if (!setup_easy_handle(ctx, rb_ary_entry(requests, idx), opts))
         return 0;
 
-    CURLMcode mc = curl_multi_add_handle(session->multi, ctx->easy);
-    if (mc != CURLM_OK)
+    if (curl_multi_add_handle(session->multi, ctx->easy) != CURLM_OK) {
+        SET_SETUP_ERROR(ctx, "Failed to schedule the request", 0);
         return 0;
+    }
 
+    ctx->attempts++;
     ctx->active = 1;
     ctx->done = 0;
     session->active_count++;
     return 1;
 }
 
-static int fill_slots(multi_session_t *session, VALUE requests, int *invalid, long timeout_sec,
-                      completion_ctx_t *cctx) {
+static int fill_slots(multi_session_t *session, VALUE requests, int *invalid,
+                      const request_options_t *opts, completion_ctx_t *cctx) {
     while (session->active_count < session->max_connections) {
         int idx = next_pending_index(session);
         if (idx < 0)
@@ -813,11 +1102,14 @@ static int fill_slots(multi_session_t *session, VALUE requests, int *invalid, lo
 
         request_ctx_t *ctx = &session->requests[idx];
 
-        if (!activate_request(session, requests, idx, invalid, timeout_sec)) {
+        if (!activate_request(session, requests, idx, invalid, opts)) {
             invalid[idx] = 1;
             ctx->done = 1;
             ctx->active = 0;
-            if (record_immediate_error(cctx, idx, "Invalid request configuration"))
+            if (record_immediate_error(cctx, idx,
+                                       ctx->setup_error ? ctx->setup_error
+                                                        : "Invalid request configuration",
+                                       ctx->attempts))
                 return 1;
         }
     }
@@ -838,13 +1130,14 @@ static void prepare_pending(multi_session_t *session, int *indices, int count) {
 }
 
 static void run_multi_loop(multi_session_t *session, completion_ctx_t *cctx, VALUE requests,
-                           int *invalid, long timeout_sec, int *indices, int indices_count) {
+                           int *invalid, const request_options_t *opts, int *indices,
+                           int indices_count) {
 #ifdef FAST_CURL_HAVE_FIBER_SCHEDULER
     VALUE scheduler = current_fiber_scheduler();
 #endif
     prepare_pending(session, indices, indices_count);
 
-    if (fill_slots(session, requests, invalid, timeout_sec, cctx))
+    if (fill_slots(session, requests, invalid, opts, cctx))
         return;
 
     curl_multi_perform(session->multi, &session->still_running);
@@ -852,7 +1145,10 @@ static void run_multi_loop(multi_session_t *session, completion_ctx_t *cctx, VAL
         return;
 
     while (!session->cancelled && (session->active_count > 0 || pending_remaining(session))) {
-        if (fill_slots(session, requests, invalid, timeout_sec, cctx))
+        if (opts->deadline_ms > 0 && fast_now_ms() >= opts->deadline_ms)
+            break;
+
+        if (fill_slots(session, requests, invalid, opts, cctx))
             return;
 
         if (session->active_count == 0)
@@ -880,6 +1176,9 @@ static int is_default_retryable_curle(CURLcode code) {
 }
 
 static int should_retry(request_ctx_t *ctx, retry_config_t *rc) {
+    if (!ctx->idempotent && !rc->retry_non_idempotent)
+        return 0;
+
     if (ctx->curl_result != CURLE_OK)
         return is_default_retryable_curle(ctx->curl_result);
 
@@ -930,6 +1229,26 @@ static void retry_config_init(retry_config_t *retry_cfg) {
     retry_cfg->retry_delay_ms = DEFAULT_RETRY_DELAY;
     retry_cfg->retry_http_codes = NULL;
     retry_cfg->retry_http_count = 0;
+    retry_cfg->retry_non_idempotent = 0;
+}
+
+static long retry_backoff_ms(const retry_config_t *rc, int attempt) {
+    long delay = rc->retry_delay_ms;
+    long half;
+
+    if (delay <= 0)
+        return 0;
+
+    for (int i = 0; i < attempt && delay < MAX_RETRY_DELAY_MS; i++)
+        delay *= 2;
+    if (delay > MAX_RETRY_DELAY_MS)
+        delay = MAX_RETRY_DELAY_MS;
+
+    half = delay / 2;
+    if (half > 0)
+        delay = half + (long)(fast_rand() % (uint32_t)(half + 1));
+
+    return delay;
 }
 
 static long parse_long_option(VALUE options, key_id_t key, const char *name, long min, long max,
@@ -986,8 +1305,16 @@ static void parse_retry_codes(VALUE options, retry_config_t *retry_cfg) {
         retry_cfg->retry_http_codes[i] = NUM2INT(rb_ary_entry(codes, i));
 }
 
-static void parse_options(VALUE options, long *timeout, int *max_conn, retry_config_t *retry_cfg) {
-    *timeout = 30;
+static void parse_options(VALUE options, request_options_t *opts, int *max_conn,
+                          retry_config_t *retry_cfg) {
+    VALUE flag;
+
+    opts->timeout_sec = 30;
+    opts->connect_timeout_ms = DEFAULT_CONNECT_TIMEOUT_MS;
+    opts->total_timeout_ms = 0;
+    opts->follow_redirects = 1;
+    opts->max_redirects = MAX_REDIRECTS;
+    opts->deadline_ms = 0;
     *max_conn = 20;
     retry_config_init(retry_cfg);
 
@@ -995,7 +1322,24 @@ static void parse_options(VALUE options, long *timeout, int *max_conn, retry_con
         return;
 
     Check_Type(options, T_HASH);
-    *timeout = parse_long_option(options, KEY_TIMEOUT, "timeout", 1, MAX_TIMEOUT, *timeout, NULL);
+    opts->timeout_sec =
+        parse_long_option(options, KEY_TIMEOUT, "timeout", 1, MAX_TIMEOUT, opts->timeout_sec, NULL);
+    opts->connect_timeout_ms =
+        parse_long_option(options, KEY_CONNECT_TIMEOUT, "connect_timeout", 1,
+                          MAX_CONNECT_TIMEOUT_MS, opts->connect_timeout_ms, NULL);
+    opts->total_timeout_ms = parse_long_option(options, KEY_TOTAL_TIMEOUT, "total_timeout", 1,
+                                               MAX_TOTAL_TIMEOUT_MS, opts->total_timeout_ms, NULL);
+    opts->max_redirects = parse_long_option(options, KEY_MAX_REDIRECTS, "max_redirects", 0, 100,
+                                            opts->max_redirects, NULL);
+
+    flag = hash_aref_key(options, KEY_FOLLOW_REDIRECTS);
+    if (!NIL_P(flag))
+        opts->follow_redirects = RTEST(flag) ? 1L : 0L;
+
+    flag = hash_aref_key(options, KEY_RETRY_NON_IDEMPOTENT);
+    if (!NIL_P(flag))
+        retry_cfg->retry_non_idempotent = RTEST(flag) ? 1 : 0;
+
     *max_conn = parse_int_option(options, KEY_CONNECTIONS, "connections", 1, MAX_CONNECTIONS,
                                  *max_conn, NULL);
     retry_cfg->max_retries = parse_int_option(options, KEY_RETRIES, "retries", 0, MAX_RETRIES,
@@ -1074,7 +1418,7 @@ typedef struct {
     multi_session_t *session;
     int *invalid;
     retry_config_t *retry_cfg;
-    long timeout_sec;
+    request_options_t *opts;
 } execute_args_t;
 
 static VALUE internal_execute_body(VALUE arg) {
@@ -1083,7 +1427,8 @@ static VALUE internal_execute_body(VALUE arg) {
     multi_session_t *session = ea->session;
     int *invalid = ea->invalid;
     retry_config_t *retry_cfg = ea->retry_cfg;
-    long timeout_sec = ea->timeout_sec;
+    request_options_t *opts = ea->opts;
+    int deadline_hit = 0;
     int count = session->count;
     int target = ea->target;
     int stream = ea->stream;
@@ -1093,19 +1438,31 @@ static VALUE internal_execute_body(VALUE arg) {
 
     completion_ctx_t cctx;
     cctx.results = stream ? Qnil : ((target > 0) ? rb_ary_new2(target) : rb_ary_new2(count));
+    cctx.accept = target > 0 && !NIL_P(ea->options) ? hash_aref_key(ea->options, KEY_ACCEPT) : Qnil;
     cctx.completed = 0;
     cctx.target = target;
     cctx.stream = stream;
 
+    if (!NIL_P(cctx.accept) && !rb_respond_to(cctx.accept, rb_intern("call")))
+        rb_raise(rb_eArgError, "accept must respond to #call");
+
     if (!stream && target <= 0) {
         for (int i = 0; i < count; i++)
             rb_ary_store(cctx.results, i, Qnil);
     }
 
-    run_multi_loop(session, &cctx, requests, invalid, timeout_sec, NULL, count);
+    if (opts->total_timeout_ms > 0)
+        opts->deadline_ms = fast_now_ms() + opts->total_timeout_ms;
+
+    run_multi_loop(session, &cctx, requests, invalid, opts, NULL, count);
 
     if (!stream && target <= 0 && retry_cfg->max_retries > 0) {
         for (int attempt = 0; attempt < retry_cfg->max_retries; attempt++) {
+            if (opts->deadline_ms > 0 && fast_now_ms() >= opts->deadline_ms) {
+                deadline_hit = 1;
+                break;
+            }
+
             int *retry_indices = malloc(sizeof(int) * (size_t)count);
             if (!retry_indices)
                 rb_raise(rb_eNoMemError, "failed to allocate retry index array");
@@ -1123,7 +1480,18 @@ static VALUE internal_execute_body(VALUE arg) {
                 break;
             }
 
-            retry_delay_sleep(retry_cfg->retry_delay_ms);
+            long backoff = retry_backoff_ms(retry_cfg, attempt);
+            if (opts->deadline_ms > 0) {
+                long long left = opts->deadline_ms - fast_now_ms();
+                if (left <= 0) {
+                    deadline_hit = 1;
+                    free(retry_indices);
+                    break;
+                }
+                if (backoff > (long)left)
+                    backoff = (long)left;
+            }
+            retry_delay_sleep(backoff);
 
             int runnable_count = 0;
             for (int r = 0; r < retry_count; r++) {
@@ -1133,6 +1501,7 @@ static VALUE internal_execute_body(VALUE arg) {
                 if (!request_ctx_reset_for_retry(rc)) {
                     invalid[idx] = 1;
                     rc->done = 1;
+                    rc->setup_error = "Failed to allocate a curl handle for the retry";
                     continue;
                 }
 
@@ -1141,7 +1510,7 @@ static VALUE internal_execute_body(VALUE arg) {
 
             if (runnable_count > 0) {
                 cctx.completed = 0;
-                run_multi_loop(session, &cctx, requests, invalid, timeout_sec, retry_indices,
+                run_multi_loop(session, &cctx, requests, invalid, opts, retry_indices,
                                runnable_count);
             }
 
@@ -1155,14 +1524,20 @@ static VALUE internal_execute_body(VALUE arg) {
             VALUE response;
 
             if (invalid[i]) {
-                response = build_error_response("Invalid request configuration");
+                response = build_error_response(rc->setup_error ? rc->setup_error
+                                                                : "Invalid request configuration",
+                                                ERR_INVALID_REQUEST, rc->attempts);
             } else if (!rc->done) {
-                response = build_error_response("Request was not completed");
+                response =
+                    deadline_hit || (opts->deadline_ms > 0 && fast_now_ms() >= opts->deadline_ms)
+                        ? build_error_response("Total timeout exceeded", ERR_DEADLINE, rc->attempts)
+                        : build_error_response("Request was not completed", ERR_NOT_COMPLETED,
+                                               rc->attempts);
             } else if (rc->curl_result == CURLE_OK) {
                 response = build_response(rc);
             } else {
                 response = build_error_response_with_code(curl_easy_strerror(rc->curl_result),
-                                                          (int)rc->curl_result);
+                                                          (int)rc->curl_result, rc->attempts);
             }
 
             rb_ary_store(cctx.results, i, build_result_pair(i, response));
@@ -1172,6 +1547,482 @@ static VALUE internal_execute_body(VALUE arg) {
     return stream ? Qnil : cctx.results;
 }
 
+typedef enum {
+    LAZY_SLOT_FREE,
+    LAZY_SLOT_PENDING,
+    LAZY_SLOT_ACTIVE,
+    LAZY_SLOT_RETRY_WAIT
+} lazy_slot_state_t;
+
+typedef struct {
+    multi_session_t session;
+    request_options_t opts;
+    retry_config_t retry_cfg;
+    completion_ctx_t cctx;
+    VALUE source;
+    VALUE anchors;
+    int *states;
+    int *free_slots;
+    int free_count;
+    int *pending_slots;
+    int pending_head;
+    int pending_tail;
+    int pending_count;
+    long long *retry_at_ms;
+    int capacity;
+    int buffer_size;
+    int occupied_count;
+    long next_index;
+    int deadline_hit;
+    int stop;
+} lazy_execute_ctx_t;
+
+static int lazy_pending_push(lazy_execute_ctx_t *ctx, int slot) {
+    if (ctx->pending_count >= ctx->capacity)
+        return 0;
+
+    ctx->pending_slots[ctx->pending_tail] = slot;
+    ctx->pending_tail = (ctx->pending_tail + 1) % ctx->capacity;
+    ctx->pending_count++;
+    return 1;
+}
+
+static int lazy_pending_pop(lazy_execute_ctx_t *ctx) {
+    if (ctx->pending_count == 0)
+        return -1;
+
+    int slot = ctx->pending_slots[ctx->pending_head];
+    ctx->pending_head = (ctx->pending_head + 1) % ctx->capacity;
+    ctx->pending_count--;
+    return slot;
+}
+
+static void lazy_release_slot(lazy_execute_ctx_t *ctx, int slot) {
+    request_ctx_free(&ctx->session.requests[slot]);
+    rb_ary_store(ctx->anchors, slot, Qnil);
+    ctx->states[slot] = LAZY_SLOT_FREE;
+    ctx->retry_at_ms[slot] = 0;
+    ctx->free_slots[ctx->free_count++] = slot;
+    if (ctx->occupied_count > 0)
+        ctx->occupied_count--;
+}
+
+static FAST_CURL_NORETURN void lazy_raise_setup_error(request_ctx_t *request) {
+    VALUE klass = NIL_P(fast_validation_error) ? rb_eArgError : fast_validation_error;
+    rb_raise(klass, "%s (request %ld)",
+             request->setup_error ? request->setup_error : "Invalid request configuration",
+             request->index);
+}
+
+static int lazy_finalize_error(lazy_execute_ctx_t *ctx, int slot, const char *message) {
+    request_ctx_t *request = &ctx->session.requests[slot];
+    VALUE response = build_error_response(message, ERR_INVALID_REQUEST, request->attempts);
+    int stop = record_response(&ctx->cctx, request->index, response);
+    lazy_release_slot(ctx, slot);
+    return stop;
+}
+
+static int lazy_activate_pending(lazy_execute_ctx_t *ctx) {
+    while (ctx->session.active_count < ctx->session.max_connections && ctx->pending_count > 0) {
+        int slot = lazy_pending_pop(ctx);
+        request_ctx_t *request = &ctx->session.requests[slot];
+        VALUE request_value = rb_ary_entry(ctx->anchors, slot);
+
+        if (!request_ctx_prepare_easy(request)) {
+            if (lazy_finalize_error(ctx, slot, "Failed to allocate a curl handle"))
+                return 1;
+            continue;
+        }
+
+        if (!setup_easy_handle(request, request_value, &ctx->opts)) {
+            if (request->setup_error_fatal)
+                lazy_raise_setup_error(request);
+            if (lazy_finalize_error(ctx, slot,
+                                    request->setup_error ? request->setup_error
+                                                         : "Invalid request configuration"))
+                return 1;
+            continue;
+        }
+
+        if (curl_multi_add_handle(ctx->session.multi, request->easy) != CURLM_OK) {
+            if (lazy_finalize_error(ctx, slot, "Failed to schedule the request"))
+                return 1;
+            continue;
+        }
+
+        request->attempts++;
+        request->active = 1;
+        request->done = 0;
+        ctx->states[slot] = LAZY_SLOT_ACTIVE;
+        ctx->session.active_count++;
+    }
+
+    return 0;
+}
+
+static int lazy_activate_retries(lazy_execute_ctx_t *ctx) {
+    long long now = fast_now_ms();
+
+    for (int slot = 0;
+         slot < ctx->capacity && ctx->session.active_count < ctx->session.max_connections; slot++) {
+        if (ctx->states[slot] != LAZY_SLOT_RETRY_WAIT || ctx->retry_at_ms[slot] > now)
+            continue;
+
+        request_ctx_t *request = &ctx->session.requests[slot];
+        VALUE request_value = rb_ary_entry(ctx->anchors, slot);
+
+        if (!request_ctx_reset_for_retry(request)) {
+            if (lazy_finalize_error(ctx, slot, "Failed to allocate a curl handle for the retry"))
+                return 1;
+            continue;
+        }
+
+        if (!setup_easy_handle(request, request_value, &ctx->opts)) {
+            if (request->setup_error_fatal)
+                lazy_raise_setup_error(request);
+            if (lazy_finalize_error(ctx, slot,
+                                    request->setup_error ? request->setup_error
+                                                         : "Invalid request configuration"))
+                return 1;
+            continue;
+        }
+
+        if (curl_multi_add_handle(ctx->session.multi, request->easy) != CURLM_OK) {
+            if (lazy_finalize_error(ctx, slot, "Failed to schedule the retry"))
+                return 1;
+            continue;
+        }
+
+        request->attempts++;
+        request->active = 1;
+        request->done = 0;
+        ctx->states[slot] = LAZY_SLOT_ACTIVE;
+        ctx->retry_at_ms[slot] = 0;
+        ctx->session.active_count++;
+    }
+
+    return 0;
+}
+
+static long long lazy_next_retry_at(const lazy_execute_ctx_t *ctx) {
+    long long next = 0;
+    for (int slot = 0; slot < ctx->capacity; slot++) {
+        if (ctx->states[slot] != LAZY_SLOT_RETRY_WAIT)
+            continue;
+        if (next == 0 || ctx->retry_at_ms[slot] < next)
+            next = ctx->retry_at_ms[slot];
+    }
+    return next;
+}
+
+static int lazy_process_completed(lazy_execute_ctx_t *ctx) {
+    CURLMsg *msg;
+    int msgs_left;
+
+    while ((msg = curl_multi_info_read(ctx->session.multi, &msgs_left))) {
+        if (msg->msg != CURLMSG_DONE)
+            continue;
+
+        request_ctx_t *request = NULL;
+        curl_easy_getinfo(msg->easy_handle, CURLINFO_PRIVATE, (char **)&request);
+        if (!request || request->done)
+            continue;
+
+        int slot = (int)(request - ctx->session.requests);
+        if (slot < 0 || slot >= ctx->capacity)
+            continue;
+
+        if (request->active) {
+            curl_multi_remove_handle(ctx->session.multi, request->easy);
+            request->active = 0;
+            if (ctx->session.active_count > 0)
+                ctx->session.active_count--;
+        }
+
+        request->done = 1;
+        request->curl_result = msg->data.result;
+        if (msg->data.result == CURLE_OK)
+            curl_easy_getinfo(request->easy, CURLINFO_RESPONSE_CODE, &request->http_status);
+
+        if (request->attempts <= ctx->retry_cfg.max_retries &&
+            should_retry(request, &ctx->retry_cfg)) {
+            ctx->states[slot] = LAZY_SLOT_RETRY_WAIT;
+            ctx->retry_at_ms[slot] =
+                fast_now_ms() + retry_backoff_ms(&ctx->retry_cfg, request->attempts - 1);
+            continue;
+        }
+
+        VALUE response =
+            (msg->data.result == CURLE_OK)
+                ? build_response(request)
+                : build_error_response_with_code(curl_easy_strerror(msg->data.result),
+                                                 (int)msg->data.result, request->attempts);
+        int stop = record_response(&ctx->cctx, request->index, response);
+        lazy_release_slot(ctx, slot);
+        if (stop)
+            return 1;
+    }
+
+    return 0;
+}
+
+typedef struct {
+    multi_session_t *session;
+    long long wake_at_ms;
+} lazy_poll_args_t;
+
+static void *lazy_poll_without_gvl(void *arg) {
+    lazy_poll_args_t *poll = (lazy_poll_args_t *)arg;
+    multi_session_t *session = poll->session;
+    long long started = fast_now_ms();
+    int before = session->still_running;
+
+    while (!session->cancelled) {
+        int numfds = 0;
+        curl_multi_poll(session->multi, NULL, 0, POLL_TIMEOUT_MS, &numfds);
+        curl_multi_perform(session->multi, &session->still_running);
+
+        if (session->still_running == 0 || session->still_running < before)
+            break;
+        if (poll->wake_at_ms > 0 && fast_now_ms() >= poll->wake_at_ms)
+            break;
+        if (fast_now_ms() - started >= POLL_SLICE_MS)
+            break;
+    }
+
+    return NULL;
+}
+
+static void lazy_wait(lazy_execute_ctx_t *ctx) {
+    long long next_retry = lazy_next_retry_at(ctx);
+
+    if (ctx->session.active_count > 0) {
+        lazy_poll_args_t poll = {.session = &ctx->session, .wake_at_ms = next_retry};
+#ifdef FAST_CURL_HAVE_FIBER_SCHEDULER
+        VALUE scheduler = current_fiber_scheduler();
+        if (scheduler != Qnil)
+            run_via_fiber_worker(scheduler, lazy_poll_without_gvl, &poll);
+        else
+#endif
+            rb_thread_call_without_gvl(lazy_poll_without_gvl, &poll, unblock_perform,
+                                       &ctx->session);
+        return;
+    }
+
+    if (next_retry > 0) {
+        long long delay = next_retry - fast_now_ms();
+        if (delay > 0)
+            retry_delay_sleep((long)delay);
+    }
+}
+
+static int lazy_deadline_reached(lazy_execute_ctx_t *ctx) {
+    if (ctx->opts.deadline_ms <= 0 || fast_now_ms() < ctx->opts.deadline_ms)
+        return 0;
+
+    ctx->deadline_hit = 1;
+    ctx->stop = 1;
+    return 1;
+}
+
+static void lazy_progress(lazy_execute_ctx_t *ctx) {
+    if (ctx->stop || lazy_deadline_reached(ctx))
+        return;
+
+    if (lazy_activate_retries(ctx) || lazy_activate_pending(ctx)) {
+        ctx->stop = 1;
+        return;
+    }
+
+    curl_multi_perform(ctx->session.multi, &ctx->session.still_running);
+    if (lazy_process_completed(ctx)) {
+        ctx->stop = 1;
+        return;
+    }
+
+    if (ctx->occupied_count == 0)
+        return;
+
+    lazy_wait(ctx);
+    if (lazy_process_completed(ctx))
+        ctx->stop = 1;
+}
+
+static VALUE lazy_each_request(VALUE yielded, VALUE arg, int argc, const VALUE *argv,
+                               VALUE blockarg) {
+    (void)blockarg;
+    lazy_execute_ctx_t *ctx = (lazy_execute_ctx_t *)arg;
+    VALUE request = argc == 1 ? argv[0] : yielded;
+
+    while (!ctx->stop && ctx->occupied_count >= ctx->capacity)
+        lazy_progress(ctx);
+
+    if (ctx->stop || lazy_deadline_reached(ctx))
+        rb_iter_break();
+
+    if (ctx->next_index > INT_MAX)
+        rb_raise(rb_eArgError, "lazy request index exceeds supported range");
+
+    int slot = ctx->free_slots[--ctx->free_count];
+    request_ctx_init(&ctx->session.requests[slot], ctx->next_index++);
+    rb_ary_store(ctx->anchors, slot, request);
+    ctx->states[slot] = LAZY_SLOT_PENDING;
+    ctx->occupied_count++;
+    lazy_pending_push(ctx, slot);
+
+    if (lazy_activate_retries(ctx) || lazy_activate_pending(ctx)) {
+        ctx->stop = 1;
+        rb_iter_break();
+    }
+
+    curl_multi_perform(ctx->session.multi, &ctx->session.still_running);
+    if (lazy_process_completed(ctx)) {
+        ctx->stop = 1;
+        rb_iter_break();
+    }
+
+    return Qnil;
+}
+
+static void lazy_finalize_deadline(lazy_execute_ctx_t *ctx) {
+    if (ctx->cctx.stream || ctx->cctx.target > 0)
+        return;
+
+    for (int slot = 0; slot < ctx->capacity; slot++) {
+        if (ctx->states[slot] == LAZY_SLOT_FREE)
+            continue;
+
+        request_ctx_t *request = &ctx->session.requests[slot];
+        if (request->active) {
+            curl_multi_remove_handle(ctx->session.multi, request->easy);
+            request->active = 0;
+            if (ctx->session.active_count > 0)
+                ctx->session.active_count--;
+        }
+
+        VALUE response =
+            build_error_response("Total timeout exceeded", ERR_DEADLINE, request->attempts);
+        record_response(&ctx->cctx, request->index, response);
+        lazy_release_slot(ctx, slot);
+    }
+}
+
+static VALUE lazy_execute_body(VALUE arg) {
+    lazy_execute_ctx_t *ctx = (lazy_execute_ctx_t *)arg;
+
+    if (ctx->opts.total_timeout_ms > 0)
+        ctx->opts.deadline_ms = fast_now_ms() + ctx->opts.total_timeout_ms;
+
+    rb_block_call(ctx->source, rb_intern("each"), 0, NULL, lazy_each_request, (VALUE)ctx);
+
+    while (!ctx->stop && ctx->occupied_count > 0)
+        lazy_progress(ctx);
+
+    if (ctx->deadline_hit)
+        lazy_finalize_deadline(ctx);
+
+    RB_GC_GUARD(ctx->source);
+    RB_GC_GUARD(ctx->anchors);
+    return ctx->cctx.stream ? Qnil : ctx->cctx.results;
+}
+
+static VALUE cleanup_lazy_execute(VALUE arg) {
+    lazy_execute_ctx_t *ctx = (lazy_execute_ctx_t *)arg;
+
+    if (ctx->session.requests) {
+        for (int slot = 0; slot < ctx->capacity; slot++) {
+            request_ctx_t *request = &ctx->session.requests[slot];
+            if (request->easy && request->active && ctx->session.multi)
+                curl_multi_remove_handle(ctx->session.multi, request->easy);
+            request_ctx_free(request);
+        }
+        free(ctx->session.requests);
+        ctx->session.requests = NULL;
+    }
+
+    free(ctx->states);
+    ctx->states = NULL;
+    free(ctx->free_slots);
+    ctx->free_slots = NULL;
+    free(ctx->pending_slots);
+    ctx->pending_slots = NULL;
+    free(ctx->retry_at_ms);
+    ctx->retry_at_ms = NULL;
+
+    if (ctx->session.multi) {
+        curl_multi_cleanup(ctx->session.multi);
+        ctx->session.multi = NULL;
+    }
+
+    if (ctx->retry_cfg.retry_http_codes) {
+        free(ctx->retry_cfg.retry_http_codes);
+        ctx->retry_cfg.retry_http_codes = NULL;
+    }
+
+    return Qnil;
+}
+
+static VALUE internal_lazy_execute(VALUE requests, VALUE options, int target, int stream) {
+    if (!rb_respond_to(requests, rb_intern("each")))
+        rb_raise(rb_eArgError, "requests must be an Array or respond to #each");
+
+    lazy_execute_ctx_t ctx;
+    memset(&ctx, 0, sizeof(ctx));
+
+    int max_conn;
+    parse_options(options, &ctx.opts, &max_conn, &ctx.retry_cfg);
+    ctx.buffer_size = NIL_P(options) ? max_conn
+                                     : parse_int_option(options, KEY_BUFFER, "buffer", 1,
+                                                        MAX_BUFFER, max_conn, NULL);
+
+    if (stream || target > 0) {
+        if (ctx.retry_cfg.retries_explicit && ctx.retry_cfg.max_retries > 0 && stream)
+            rb_warn(
+                "FastCurl: retries are not supported in stream_execute, ignoring retries option");
+        if (ctx.retry_cfg.retries_explicit && ctx.retry_cfg.max_retries > 0 && target > 0)
+            rb_warn(
+                "FastCurl: retries are not supported in first_execute, ignoring retries option");
+        ctx.retry_cfg.max_retries = 0;
+    }
+
+    ctx.capacity = max_conn + ctx.buffer_size;
+    ctx.source = requests;
+    ctx.anchors = rb_ary_new2(ctx.capacity);
+    ctx.next_index = 0;
+
+    ctx.cctx.results = stream ? Qnil : rb_ary_new();
+    ctx.cctx.accept = target > 0 && !NIL_P(options) ? hash_aref_key(options, KEY_ACCEPT) : Qnil;
+    ctx.cctx.completed = 0;
+    ctx.cctx.target = target;
+    ctx.cctx.stream = stream;
+
+    if (!NIL_P(ctx.cctx.accept) && !rb_respond_to(ctx.cctx.accept, rb_intern("call")))
+        rb_raise(rb_eArgError, "accept must respond to #call");
+
+    multi_session_init(&ctx.session, curl_multi_init(), ctx.capacity, max_conn,
+                       ctx.opts.timeout_sec);
+    if (!ctx.session.multi)
+        rb_raise(rb_eNoMemError, "failed to initialize curl multi handle");
+    multi_session_configure(ctx.session.multi, max_conn);
+
+    ctx.session.requests = calloc((size_t)ctx.capacity, sizeof(request_ctx_t));
+    ctx.states = calloc((size_t)ctx.capacity, sizeof(int));
+    ctx.free_slots = malloc(sizeof(int) * (size_t)ctx.capacity);
+    ctx.pending_slots = malloc(sizeof(int) * (size_t)ctx.capacity);
+    ctx.retry_at_ms = calloc((size_t)ctx.capacity, sizeof(long long));
+
+    if (!ctx.session.requests || !ctx.states || !ctx.free_slots || !ctx.pending_slots ||
+        !ctx.retry_at_ms) {
+        cleanup_lazy_execute((VALUE)&ctx);
+        rb_raise(rb_eNoMemError, "failed to allocate lazy request state");
+    }
+
+    for (int slot = 0; slot < ctx.capacity; slot++)
+        ctx.free_slots[ctx.free_count++] = slot;
+
+    return rb_ensure(lazy_execute_body, (VALUE)&ctx, cleanup_lazy_execute, (VALUE)&ctx);
+}
+
 #ifdef FAST_CURL_HAVE_FIBER_SCHEDULER
 typedef struct {
     execute_args_t *ea;
@@ -1247,6 +2098,9 @@ static VALUE execute_with_fiber_scheduler(VALUE arg) {
 #endif
 
 static VALUE internal_execute(VALUE requests, VALUE options, int target, int stream) {
+    if (!RB_TYPE_P(requests, T_ARRAY))
+        return internal_lazy_execute(requests, options, target, stream);
+
     Check_Type(requests, T_ARRAY);
 
     long count_long = RARRAY_LEN(requests);
@@ -1262,10 +2116,37 @@ static VALUE internal_execute(VALUE requests, VALUE options, int target, int str
     if (target > 0 && target > count)
         target = count;
 
-    long timeout_sec;
+    request_options_t opts;
     int max_conn;
     retry_config_t retry_cfg;
-    parse_options(options, &timeout_sec, &max_conn, &retry_cfg);
+    parse_options(options, &opts, &max_conn, &retry_cfg);
+
+    if (target > 0 && !NIL_P(options)) {
+        VALUE accept = hash_aref_key(options, KEY_ACCEPT);
+        if (!NIL_P(accept) && !rb_respond_to(accept, rb_intern("call")))
+            rb_raise(rb_eArgError, "accept must respond to #call");
+    }
+
+    for (int i = 0; i < count; i++) {
+        request_ctx_t probe;
+        request_ctx_init(&probe, i);
+        if (!request_ctx_prepare_easy(&probe)) {
+            request_ctx_free(&probe);
+            continue;
+        }
+        setup_easy_handle(&probe, rb_ary_entry(requests, i), &opts);
+        int fatal = probe.setup_error_fatal;
+        const char *message = probe.setup_error;
+        char buffer[128];
+        if (fatal && message) {
+            snprintf(buffer, sizeof(buffer), "%s (request %d)", message, i);
+        }
+        request_ctx_free(&probe);
+        if (fatal) {
+            VALUE klass = NIL_P(fast_validation_error) ? rb_eArgError : fast_validation_error;
+            rb_raise(klass, "%s", buffer);
+        }
+    }
 
     if (stream || target > 0) {
         if (retry_cfg.retries_explicit && retry_cfg.max_retries > 0 && stream)
@@ -1279,7 +2160,7 @@ static VALUE internal_execute(VALUE requests, VALUE options, int target, int str
 
     multi_session_t session;
     int *invalid = NULL;
-    multi_session_init(&session, curl_multi_init(), count, max_conn, timeout_sec);
+    multi_session_init(&session, curl_multi_init(), count, max_conn, opts.timeout_sec);
 
     cleanup_ctx_t cleanup = {.session = &session, .invalid = NULL, .retry_cfg = &retry_cfg};
 
@@ -1304,12 +2185,13 @@ static VALUE internal_execute(VALUE requests, VALUE options, int target, int str
         .session = &session,
         .invalid = invalid,
         .retry_cfg = &retry_cfg,
-        .timeout_sec = timeout_sec,
+        .opts = &opts,
     };
 
 #ifdef FAST_CURL_HAVE_FIBER_SCHEDULER
     VALUE scheduler = current_fiber_scheduler();
-    if (scheduler != Qnil && !stream) {
+    VALUE accept = target > 0 && !NIL_P(options) ? hash_aref_key(options, KEY_ACCEPT) : Qnil;
+    if (scheduler != Qnil && !stream && NIL_P(accept)) {
         scheduler_execute_ctx_t scheduler_ctx = {
             .ea = &ea,
             .scheduler = scheduler,
@@ -1326,7 +2208,6 @@ static VALUE internal_execute(VALUE requests, VALUE options, int target, int str
                          (VALUE)&cleanup);
     }
 #endif
-
     return rb_ensure(internal_execute_body, (VALUE)&ea, cleanup_session, (VALUE)&cleanup);
 }
 
@@ -1366,6 +2247,7 @@ static VALUE rb_fast_curl_stream_execute(int argc, VALUE *argv, VALUE self) {
 
 void Init_fast_curl(void) {
     curl_global_init(CURL_GLOBAL_ALL);
+    fast_share_init();
 
     for (int i = 0; i < KEY_LAST; i++) {
         fast_ids[i] = rb_intern(KEY_NAMES[i]);
@@ -1373,8 +2255,18 @@ void Init_fast_curl(void) {
         rb_gc_register_address(&fast_syms[i]);
     }
 
+    for (int i = 0; i < ERR_LAST; i++) {
+        error_syms[i] = ID2SYM(rb_intern(ERROR_KIND_NAMES[i]));
+        rb_gc_register_address(&error_syms[i]);
+    }
+
     VALUE mFastCurl = rb_define_module("FastCurl");
 
+    if (rb_const_defined_at(mFastCurl, rb_intern("Headers"))) {
+        fast_cHeaders = rb_const_get_at(mFastCurl, rb_intern("Headers"));
+        rb_gc_register_address(&fast_cHeaders);
+    }
+
     rb_define_module_function(mFastCurl, "execute", rb_fast_curl_execute, -1);
     rb_define_module_function(mFastCurl, "first_execute", rb_fast_curl_first_execute, -1);
     rb_define_module_function(mFastCurl, "stream_execute", rb_fast_curl_stream_execute, -1);