fast_curl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d01979b9bff516a526b66220807d7d325846eb507815dcfe46810daa14f5f782
+  data.tar.gz: d9ff4cb707451f4d3516426e84f22798d89ff8b7fdc549addb4e68fc22e55f3b
+SHA512:
+  metadata.gz: 354b9d90daaa884f6bc31819a7377a10946874d945add791c61e5801c4c65fe618bb364ea0cc25e8bc155afddf07c9cb7dc0593accff7be33559a7c71b23cf1d
+  data.tar.gz: a6a87dae54ce7c8fb52aa5f7f5780df2943767b46a9c87f582fa20bb76475736eac3f4feb360b5cacf5edaad11e6eee2c81ecc7632248ef80b8154a6e6b88c27

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haydarov Roman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,141 @@
+# fast_curl
+
+Ultra-fast parallel HTTP client for Ruby. C extension built on libcurl `curl_multi` API.
+
+## Features
+
+- **Parallel requests** via `curl_multi` — no threads, no fibers needed
+- **GVL release** — `rb_thread_call_without_gvl` during I/O, other Ruby threads keep running
+- **Fiber scheduler compatible** — works inside `Async do ... end` without blocking other fibers
+- **Three modes**: execute (all), first_execute (first N), stream_execute (yield as ready)
+- **Zero dependencies** — only libcurl (available everywhere)
+
+## Installation
+
+**Requirements**: Ruby >= 3.0 (for Fiber scheduler support)
+
+```ruby
+gem 'fast_curl'
+```
+
+Requires libcurl development headers:
+
+```bash
+# macOS
+brew install curl
+
+# Ubuntu/Debian
+apt-get install libcurl4-openssl-dev
+
+# Alpine
+apk add curl-dev
+```
+
+## Usage
+
+### Basic GET
+
+```ruby
+results = FastCurl.get([
+  { url: "https://api.example.com/users" },
+  { url: "https://api.example.com/posts" }
+], connections: 20, timeout: 30)
+
+results.each do |index, response|
+  puts "#{index}: #{response[:status]} — #{response[:body]}"
+end
+```
+
+### POST with body and headers
+
+```ruby
+FastCurl.post([
+  {
+    url: "https://api.example.com/users",
+    headers: { "Authorization" => "Bearer token" },
+    body: { name: "John" }
+  }
+])
+```
+
+### First N responses (cancel the rest)
+
+```ruby
+result = FastCurl.first_get([
+  { url: "https://mirror1.example.com/file" },
+  { url: "https://mirror2.example.com/file" },
+  { url: "https://mirror3.example.com/file" }
+], count: 1)
+```
+
+### Stream responses as they arrive
+
+```ruby
+FastCurl.stream_get(urls, connections: 50) do |index, response|
+  puts "Got response #{index}: #{response[:status]}"
+end
+```
+
+### Inside Async
+
+```ruby
+require "async"
+
+Async do
+  # fast_curl detects the fiber scheduler and yields
+  # to other fibers during I/O instead of blocking
+  results = FastCurl.get(urls, connections: 20)
+end
+```
+
+## Response format
+
+```ruby
+[index, {
+  status: 200,             # HTTP status code (0 on error)
+  headers: { "Key" => "Value" },
+  body: "response body"
+}]
+```
+
+## Available methods
+
+| Method | Description |
+|---|---|
+| `FastCurl.get(requests, **opts)` | GET all, wait for all |
+| `FastCurl.post(requests, **opts)` | POST all, wait for all |
+| `FastCurl.put(requests, **opts)` | PUT all, wait for all |
+| `FastCurl.delete(requests, **opts)` | DELETE all, wait for all |
+| `FastCurl.patch(requests, **opts)` | PATCH all, wait for all |
+| `FastCurl.first_get(requests, count: 1, **opts)` | GET, return first N |
+| `FastCurl.stream_get(requests, **opts) { \|i, r\| }` | GET, yield each |
+| `FastCurl.execute(requests, **opts)` | Raw execute |
+| `FastCurl.first_execute(requests, count: 1, **opts)` | Raw first N |
+| `FastCurl.stream_execute(requests, **opts) { \|pair\| }` | Raw stream |
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `connections` | 20 | Max parallel connections |
+| `timeout` | 30 | Per-request timeout in seconds |
+
+## Performance
+
+Benchmark results (`bundle exec ruby benchmark/local_bench.rb`):
+
+| Method | 4 parallel | 10 parallel | 20 parallel | 200 parallel |
+|--------|------------|-------------|--------------|---------------|
+| Net::HTTP sequential | 7.93s (+2.1 MB) | 24.20s (+0.3 MB) | 48.58s (+1.2 MB) | - |
+| fast_curl (thread) | 2.09s (+0.7 MB) | 3.73s (+0.9 MB) | 3.76s (+0.0 MB) | 5.88s (+2.3 MB) |
+| fast_curl (fiber) | 1.96s (+0.4 MB) | 4.86s (+0.0 MB) | 3.71s (+0.2 MB) | 9.60s (+1.6 MB) |
+| Async::HTTP | 2.54s (+0.3 MB) | 4.27s (+0.4 MB) | 9.16s (+0.5 MB) | 22.44s (+10.7 MB) |
+
+Additional scenarios:
+- Stream execute (5 requests): 5.99s (+0.0 MB)
+- First execute (first 1 of 5): 2.40s (+0.0 MB)
+- Error handling (timeout=2s): 2.01s (+0.0 MB)
+
+## License
+
+MIT

data/ext/fast_curl/extconf.rb

@@ -0,0 +1,14 @@
+require "mkmf"
+
+abort "libcurl is required" unless have_library("curl", "curl_multi_init")
+abort "curl/curl.h is required" unless have_header("curl/curl.h")
+
+have_header("ruby/thread.h")
+have_header("ruby/fiber/scheduler.h")
+
+have_func("rb_fiber_scheduler_current", "ruby.h")
+have_func("rb_io_wait", "ruby.h")
+
+$CFLAGS << " -std=c99 -O2 -Wall -Wextra -Wno-unused-parameter"
+
+create_makefile("fast_curl/fast_curl")

data/ext/fast_curl/fast_curl.c

@@ -0,0 +1,653 @@
+#include <ruby.h>
+#include <ruby/io.h>
+#include <ruby/thread.h>
+#ifdef HAVE_RUBY_FIBER_SCHEDULER_H
+#include <ruby/fiber/scheduler.h>
+#endif
+#include <curl/curl.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define MAX_RESPONSE_SIZE (100 * 1024 * 1024)
+#define MAX_REDIRECTS 5
+#define MAX_TIMEOUT 300
+
+typedef struct {
+  char *data;
+  size_t len;
+  size_t cap;
+  size_t max_size;
+} buffer_t;
+
+static void buffer_init(buffer_t *buf) {
+  buf->data = NULL;
+  buf->len = 0;
+  buf->cap = 0;
+  buf->max_size = MAX_RESPONSE_SIZE;
+}
+
+static void buffer_free(buffer_t *buf) {
+  if (buf->data) {
+    free(buf->data);
+    buf->data = NULL;
+  }
+  buf->len = 0;
+  buf->cap = 0;
+}
+
+static size_t write_callback(char *ptr, size_t size, size_t nmemb,
+                             void *userdata) {
+  buffer_t *buf = (buffer_t *)userdata;
+  size_t total = size * nmemb;
+
+  if (buf->len + total > buf->max_size) {
+    return 0;
+  }
+
+  if (buf->len + total >= buf->cap) {
+    size_t new_cap = (buf->cap == 0) ? 4096 : buf->cap;
+    while (new_cap <= buf->len + total)
+      new_cap *= 2;
+
+    if (new_cap > buf->max_size) {
+      new_cap = buf->max_size;
+    }
+
+    char *new_data = realloc(buf->data, new_cap);
+    if (!new_data)
+      return 0;
+    buf->data = new_data;
+    buf->cap = new_cap;
+  }
+
+  memcpy(buf->data + buf->len, ptr, total);
+  buf->len += total;
+  return total;
+}
+
+typedef struct {
+  char **entries;
+  int count;
+  int cap;
+} header_list_t;
+
+static void header_list_init(header_list_t *h) {
+  h->entries = NULL;
+  h->count = 0;
+  h->cap = 0;
+}
+
+static void header_list_free(header_list_t *h) {
+  for (int i = 0; i < h->count; i++)
+    free(h->entries[i]);
+  free(h->entries);
+  h->entries = NULL;
+  h->count = 0;
+  h->cap = 0;
+}
+
+static size_t header_callback(char *ptr, size_t size, size_t nmemb,
+                              void *userdata) {
+  header_list_t *h = (header_list_t *)userdata;
+  size_t total = size * nmemb;
+
+  if (total <= 2)
+    return total;
+
+  if (h->count >= h->cap) {
+    int new_cap = (h->cap == 0) ? 16 : h->cap * 2;
+    char **new_entries = realloc(h->entries, sizeof(char *) * new_cap);
+    if (!new_entries)
+      return 0;
+    h->entries = new_entries;
+    h->cap = new_cap;
+  }
+
+  char *entry = malloc(total + 1);
+  if (!entry)
+    return 0;
+  memcpy(entry, ptr, total);
+
+  while (total > 0 && (entry[total - 1] == '\r' || entry[total - 1] == '\n'))
+    total--;
+  entry[total] = '\0';
+  h->entries[h->count++] = entry;
+  return size * nmemb;
+}
+
+typedef struct {
+  CURL *easy;
+  int index;
+  buffer_t body;
+  header_list_t headers;
+  struct curl_slist *req_headers;
+  int done;
+} request_ctx_t;
+
+static void request_ctx_init(request_ctx_t *ctx, int index) {
+  ctx->easy = curl_easy_init();
+  ctx->index = index;
+  buffer_init(&ctx->body);
+  header_list_init(&ctx->headers);
+  ctx->req_headers = NULL;
+  ctx->done = 0;
+}
+
+static void request_ctx_free(request_ctx_t *ctx) {
+  if (ctx->easy) {
+    curl_easy_cleanup(ctx->easy);
+    ctx->easy = NULL;
+  }
+  buffer_free(&ctx->body);
+  header_list_free(&ctx->headers);
+  if (ctx->req_headers) {
+    curl_slist_free_all(ctx->req_headers);
+    ctx->req_headers = NULL;
+  }
+}
+
+typedef struct {
+  CURLM *multi;
+  request_ctx_t *requests;
+  int count;
+  int still_running;
+  long timeout_ms;
+  int max_connections;
+} multi_session_t;
+
+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();
+  for (int i = 0; i < ctx->headers.count; i++) {
+    char *colon = strchr(ctx->headers.entries[i], ':');
+    if (colon) {
+      VALUE key =
+          rb_str_new(ctx->headers.entries[i], colon - ctx->headers.entries[i]);
+      char *val_start = colon + 1;
+      while (*val_start == ' ' || *val_start == '\t')
+        val_start++;
+
+      char *val_end = ctx->headers.entries[i] + strlen(ctx->headers.entries[i]);
+      while (val_end > val_start &&
+             (*(val_end - 1) == ' ' || *(val_end - 1) == '\t' ||
+              *(val_end - 1) == '\r' || *(val_end - 1) == '\n')) {
+        val_end--;
+      }
+
+      size_t val_len = val_end - val_start;
+      VALUE val = rb_str_new(val_start, val_len);
+      rb_hash_aset(headers_hash, key, val);
+    }
+  }
+
+  VALUE body_str = ctx->body.data ? rb_str_new(ctx->body.data, ctx->body.len)
+                                  : rb_str_new_cstr("");
+
+  VALUE result = rb_hash_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("status")), LONG2NUM(status));
+  rb_hash_aset(result, ID2SYM(rb_intern("headers")), headers_hash);
+  rb_hash_aset(result, ID2SYM(rb_intern("body")), body_str);
+
+  return result;
+}
+
+static VALUE build_error_response(const char *message) {
+  VALUE result = rb_hash_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("status")), INT2NUM(0));
+  rb_hash_aset(result, ID2SYM(rb_intern("headers")), Qnil);
+  rb_hash_aset(result, ID2SYM(rb_intern("body")), rb_str_new_cstr(message));
+  return result;
+}
+
+static int is_valid_url(const char *url);
+static VALUE build_error_response_with_code(const char *message,
+                                            int error_code);
+
+#define CURL_SETOPT_CHECK(handle, option, value)                               \
+  do {                                                                         \
+    CURLcode res = curl_easy_setopt(handle, option, value);                    \
+    if (res != CURLE_OK) {                                                     \
+      return res;                                                              \
+    }                                                                          \
+  } while (0)
+
+static CURLcode setup_basic_options(CURL *easy, const char *url_str,
+                                    long timeout_sec, request_ctx_t *ctx) {
+
+  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_NOSIGNAL, 1L);
+  CURL_SETOPT_CHECK(easy, CURLOPT_FOLLOWLOCATION, 1L);
+  CURL_SETOPT_CHECK(easy, CURLOPT_MAXREDIRS, MAX_REDIRECTS);
+  CURL_SETOPT_CHECK(easy, CURLOPT_ACCEPT_ENCODING, "");
+  CURL_SETOPT_CHECK(easy, CURLOPT_PRIVATE, (char *)ctx);
+
+  return CURLE_OK;
+}
+
+static CURLcode setup_security_options(CURL *easy) {
+
+  CURL_SETOPT_CHECK(easy, CURLOPT_SSL_VERIFYPEER, 1L);
+  CURL_SETOPT_CHECK(easy, CURLOPT_SSL_VERIFYHOST, 2L);
+
+#ifdef CURLOPT_PROTOCOLS_STR
+  CURL_SETOPT_CHECK(easy, CURLOPT_PROTOCOLS_STR, "http,https");
+  CURL_SETOPT_CHECK(easy, CURLOPT_REDIR_PROTOCOLS_STR, "http,https");
+#else
+
+  CURL_SETOPT_CHECK(easy, CURLOPT_PROTOCOLS, CURLPROTO_HTTP | CURLPROTO_HTTPS);
+  CURL_SETOPT_CHECK(easy, CURLOPT_REDIR_PROTOCOLS,
+                    CURLPROTO_HTTP | CURLPROTO_HTTPS);
+#endif
+
+  return CURLE_OK;
+}
+
+static CURLcode setup_method_and_body(CURL *easy, VALUE method, VALUE body) {
+  if (!NIL_P(method)) {
+    const char *m = StringValueCStr(method);
+    if (strcmp(m, "POST") == 0) {
+      CURL_SETOPT_CHECK(easy, CURLOPT_POST, 1L);
+    } else if (strcmp(m, "PUT") == 0) {
+      CURL_SETOPT_CHECK(easy, CURLOPT_CUSTOMREQUEST, "PUT");
+    } else if (strcmp(m, "DELETE") == 0) {
+      CURL_SETOPT_CHECK(easy, CURLOPT_CUSTOMREQUEST, "DELETE");
+    } else if (strcmp(m, "PATCH") == 0) {
+      CURL_SETOPT_CHECK(easy, CURLOPT_CUSTOMREQUEST, "PATCH");
+    } else if (strcmp(m, "GET") != 0) {
+
+      CURL_SETOPT_CHECK(easy, CURLOPT_CUSTOMREQUEST, m);
+    }
+  }
+
+  if (!NIL_P(body)) {
+    CURL_SETOPT_CHECK(easy, CURLOPT_POSTFIELDS, StringValuePtr(body));
+    CURL_SETOPT_CHECK(easy, CURLOPT_POSTFIELDSIZE, RSTRING_LEN(body));
+  }
+
+  return CURLE_OK;
+}
+
+static int setup_easy_handle(request_ctx_t *ctx, VALUE request,
+                             long timeout_sec) {
+  VALUE url = rb_hash_aref(request, ID2SYM(rb_intern("url")));
+  VALUE method = rb_hash_aref(request, ID2SYM(rb_intern("method")));
+  VALUE headers = rb_hash_aref(request, ID2SYM(rb_intern("headers")));
+  VALUE body = rb_hash_aref(request, ID2SYM(rb_intern("body")));
+
+  if (NIL_P(url)) {
+    return 0;
+  }
+
+  const char *url_str = StringValueCStr(url);
+
+  if (!is_valid_url(url_str)) {
+    rb_raise(rb_eArgError, "Invalid URL: %s", url_str);
+  }
+
+  CURLcode res;
+
+  res = setup_basic_options(ctx->easy, url_str, timeout_sec, ctx);
+  if (res != CURLE_OK)
+    return 0;
+
+  res = setup_security_options(ctx->easy);
+  if (res != CURLE_OK)
+    return 0;
+
+  res = setup_method_and_body(ctx->easy, method, body);
+  if (res != CURLE_OK)
+    return 0;
+
+  if (!NIL_P(headers) && rb_obj_is_kind_of(headers, rb_cHash)) {
+    VALUE keys = rb_funcall(headers, rb_intern("keys"), 0);
+    long hlen = RARRAY_LEN(keys);
+    for (long i = 0; i < hlen; i++) {
+      VALUE key = rb_ary_entry(keys, i);
+      VALUE val = rb_hash_aref(headers, key);
+      VALUE header_line;
+
+      if (NIL_P(val) || RSTRING_LEN(rb_String(val)) == 0) {
+        header_line = rb_sprintf("%" PRIsVALUE ";", key);
+      } else {
+        header_line = rb_sprintf("%" PRIsVALUE ": %" PRIsVALUE, key, val);
+      }
+
+      ctx->req_headers =
+          curl_slist_append(ctx->req_headers, StringValueCStr(header_line));
+      if (!ctx->req_headers) {
+        return 0;
+      }
+    }
+
+    res = curl_easy_setopt(ctx->easy, CURLOPT_HTTPHEADER, ctx->req_headers);
+    if (res != CURLE_OK)
+      return 0;
+  }
+
+  return 1;
+}
+
+static void *perform_without_gvl(void *arg) {
+  multi_session_t *session = (multi_session_t *)arg;
+
+  while (session->still_running > 0) {
+    CURLMcode mc = curl_multi_perform(session->multi, &session->still_running);
+    if (mc != CURLM_OK)
+      break;
+
+    if (session->still_running > 0) {
+      int numfds = 0;
+      mc = curl_multi_poll(session->multi, NULL, 0, 100, &numfds);
+      if (mc != CURLM_OK)
+        break;
+    }
+  }
+
+  return NULL;
+}
+
+static void *poll_without_gvl(void *arg) {
+  multi_session_t *session = (multi_session_t *)arg;
+  int numfds = 0;
+  curl_multi_poll(session->multi, NULL, 0, 100, &numfds);
+  curl_multi_perform(session->multi, &session->still_running);
+  return NULL;
+}
+
+static void unblock_perform(void *arg) {
+  multi_session_t *session = (multi_session_t *)arg;
+  (void)session;
+}
+
+static int has_fiber_scheduler(void) {
+#ifdef HAVE_RB_FIBER_SCHEDULER_CURRENT
+  VALUE scheduler = rb_fiber_scheduler_current();
+  return scheduler != Qnil && scheduler != Qfalse;
+#else
+  return 0;
+#endif
+}
+
+typedef struct {
+  VALUE results;
+  int completed;
+  int target;
+  int stream;
+} completion_ctx_t;
+
+static int process_completed(multi_session_t *session, completion_ctx_t *cctx) {
+  CURLMsg *msg;
+  int msgs_left;
+
+  while ((msg = curl_multi_info_read(session->multi, &msgs_left))) {
+    if (msg->msg != CURLMSG_DONE)
+      continue;
+
+    request_ctx_t *ctx = NULL;
+    curl_easy_getinfo(msg->easy_handle, CURLINFO_PRIVATE, (char **)&ctx);
+    if (!ctx || ctx->done)
+      continue;
+    ctx->done = 1;
+
+    VALUE response;
+    if (msg->data.result == CURLE_OK) {
+      response = build_response(ctx);
+    } else {
+
+      response = build_error_response_with_code(
+          curl_easy_strerror(msg->data.result), (int)msg->data.result);
+    }
+
+    VALUE pair = rb_ary_new_from_args(2, INT2NUM(ctx->index), response);
+
+    if (cctx->stream) {
+      rb_yield(pair);
+    } else if (!NIL_P(cctx->results)) {
+      rb_ary_store(cctx->results, ctx->index, pair);
+    }
+
+    cctx->completed++;
+
+    if (cctx->target > 0 && cctx->completed >= cctx->target) {
+      return 1;
+    }
+  }
+
+  return 0;
+}
+
+static VALUE build_error_response_with_code(const char *message,
+                                            int error_code) {
+  VALUE result = rb_hash_new();
+  rb_hash_aset(result, ID2SYM(rb_intern("status")), INT2NUM(0));
+  rb_hash_aset(result, ID2SYM(rb_intern("headers")), Qnil);
+  rb_hash_aset(result, ID2SYM(rb_intern("body")), rb_str_new_cstr(message));
+  rb_hash_aset(result, ID2SYM(rb_intern("error_code")), INT2NUM(error_code));
+  return result;
+}
+
+static int is_valid_url(const char *url) {
+  if (!url || strlen(url) == 0)
+    return 0;
+
+  size_t url_len = strlen(url);
+
+  if (url_len > 2048) {
+    return 0;
+  }
+
+  if (strncmp(url, "http://", 7) != 0 && strncmp(url, "https://", 8) != 0) {
+    return 0;
+  }
+
+  if (strncmp(url, "file://", 7) == 0 || strncmp(url, "ftp://", 6) == 0 ||
+      strncmp(url, "gopher://", 9) == 0 || strncmp(url, "ldap://", 7) == 0 ||
+      strncmp(url, "dict://", 7) == 0 || strncmp(url, "tftp://", 7) == 0) {
+    return 0;
+  }
+
+  return 1;
+}
+
+static VALUE parse_options(VALUE options, long *timeout, int *max_conn) {
+  *timeout = 30;
+  *max_conn = 20;
+
+  if (!NIL_P(options) && rb_obj_is_kind_of(options, rb_cHash)) {
+    VALUE t = rb_hash_aref(options, ID2SYM(rb_intern("timeout")));
+    VALUE c = rb_hash_aref(options, ID2SYM(rb_intern("connections")));
+
+    if (!NIL_P(t)) {
+      long timeout_val = NUM2LONG(t);
+
+      if (timeout_val > MAX_TIMEOUT) {
+        timeout_val = MAX_TIMEOUT;
+      } else if (timeout_val <= 0) {
+        timeout_val = 30;
+      }
+      *timeout = timeout_val;
+    }
+
+    if (!NIL_P(c)) {
+      int conn_val = NUM2INT(c);
+
+      if (conn_val > 100) {
+        conn_val = 100;
+      } else if (conn_val <= 0) {
+        conn_val = 20;
+      }
+      *max_conn = conn_val;
+    }
+  }
+
+  return Qnil;
+}
+
+static VALUE internal_execute(VALUE requests, VALUE options, int target,
+                              int stream) {
+  Check_Type(requests, T_ARRAY);
+  int count = (int)RARRAY_LEN(requests);
+  if (count == 0)
+    return rb_ary_new();
+
+  long timeout_sec;
+  int max_conn;
+  parse_options(options, &timeout_sec, &max_conn);
+
+  multi_session_t session;
+  session.multi = curl_multi_init();
+  session.count = count;
+  session.timeout_ms = timeout_sec * 1000;
+  session.max_connections = max_conn;
+
+  curl_multi_setopt(session.multi, CURLMOPT_MAXCONNECTS, (long)max_conn);
+  curl_multi_setopt(session.multi, CURLMOPT_MAX_TOTAL_CONNECTIONS,
+                    (long)max_conn);
+
+  session.requests = calloc(count, sizeof(request_ctx_t));
+  if (!session.requests) {
+    curl_multi_cleanup(session.multi);
+    rb_raise(rb_eNoMemError, "failed to allocate request contexts");
+  }
+
+  int valid_requests = 0;
+  for (int i = 0; i < count; i++) {
+    VALUE req = rb_ary_entry(requests, i);
+    request_ctx_init(&session.requests[i], i);
+
+    if (!setup_easy_handle(&session.requests[i], req, timeout_sec)) {
+
+      session.requests[i].done = 1;
+      continue;
+    }
+
+    CURLMcode mc =
+        curl_multi_add_handle(session.multi, session.requests[i].easy);
+    if (mc != CURLM_OK) {
+      session.requests[i].done = 1;
+      continue;
+    }
+
+    valid_requests++;
+  }
+
+  if (valid_requests == 0) {
+    session.still_running = 0;
+  }
+
+  completion_ctx_t cctx;
+  cctx.results = stream ? Qnil : rb_ary_new2(count);
+  cctx.completed = 0;
+  cctx.target = target;
+  cctx.stream = stream;
+
+  if (!stream) {
+    for (int i = 0; i < count; i++)
+      rb_ary_store(cctx.results, i, Qnil);
+  }
+
+  if (has_fiber_scheduler()) {
+    while (session.still_running > 0 || 1) {
+      CURLMcode mc = curl_multi_perform(session.multi, &session.still_running);
+      if (mc != CURLM_OK)
+        break;
+      if (process_completed(&session, &cctx))
+        break;
+      if (session.still_running == 0)
+        break;
+
+      int numfds = 0;
+      curl_multi_poll(session.multi, NULL, 0, 1, &numfds);
+      rb_thread_schedule();
+    }
+
+    process_completed(&session, &cctx);
+  } else {
+    if (stream || target > 0) {
+      curl_multi_perform(session.multi, &session.still_running);
+      while (session.still_running > 0) {
+        rb_thread_call_without_gvl(poll_without_gvl, &session, unblock_perform,
+                                   &session);
+        if (process_completed(&session, &cctx))
+          break;
+      }
+      process_completed(&session, &cctx);
+    } else {
+      session.still_running = 1;
+      curl_multi_perform(session.multi, &session.still_running);
+      rb_thread_call_without_gvl(perform_without_gvl, &session, unblock_perform,
+                                 &session);
+      process_completed(&session, &cctx);
+    }
+  }
+
+  if (!stream) {
+    for (int i = 0; i < count; i++) {
+      if (session.requests[i].done && rb_ary_entry(cctx.results, i) == Qnil) {
+
+        VALUE error_response =
+            build_error_response("Invalid request configuration");
+        VALUE pair = rb_ary_new_from_args(2, INT2NUM(i), error_response);
+        rb_ary_store(cctx.results, i, pair);
+      }
+    }
+  }
+
+  for (int i = 0; i < count; i++) {
+    curl_multi_remove_handle(session.multi, session.requests[i].easy);
+    request_ctx_free(&session.requests[i]);
+  }
+  free(session.requests);
+  curl_multi_cleanup(session.multi);
+
+  return stream ? Qnil : cctx.results;
+}
+
+static VALUE rb_fast_curl_execute(int argc, VALUE *argv, VALUE self) {
+  VALUE requests, options;
+  rb_scan_args(argc, argv, "1:", &requests, &options);
+  return internal_execute(requests, options, -1, 0);
+}
+
+static VALUE rb_fast_curl_first_execute(int argc, VALUE *argv, VALUE self) {
+  VALUE requests, options;
+  rb_scan_args(argc, argv, "1:", &requests, &options);
+
+  int count = 1;
+  if (!NIL_P(options)) {
+    VALUE c = rb_hash_aref(options, ID2SYM(rb_intern("count")));
+    if (!NIL_P(c))
+      count = NUM2INT(c);
+  }
+
+  return internal_execute(requests, options, count, 0);
+}
+
+static VALUE rb_fast_curl_stream_execute(int argc, VALUE *argv, VALUE self) {
+  VALUE requests, options;
+  rb_scan_args(argc, argv, "1:", &requests, &options);
+
+  if (!rb_block_given_p())
+    rb_raise(rb_eArgError, "stream_execute requires a block");
+
+  return internal_execute(requests, options, -1, 1);
+}
+
+void Init_fast_curl(void) {
+  curl_global_init(CURL_GLOBAL_ALL);
+
+  VALUE mFastCurl = rb_define_module("FastCurl");
+
+  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);
+}

data/lib/fast_curl/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FastCurl
+  VERSION = "0.1.0"
+end

data/lib/fast_curl.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative "fast_curl/version"
+require_relative "fast_curl/fast_curl"
+
+module FastCurl
+  class Error < StandardError; end
+  class TimeoutError < Error; end
+
+  DEFAULT_OPTIONS = {
+    connections: 20,
+    timeout: 30
+  }.freeze
+
+  METHODS = %i[get post put delete patch].freeze
+  BODY_METHODS = %i[post put patch].freeze
+
+  class << self
+    METHODS.each do |method|
+      define_method(method) do |requests, **options|
+        execute(build_requests(requests, method), **DEFAULT_OPTIONS.merge(options))
+      end
+
+      define_method(:"first_#{method}") do |requests, count: 1, **options|
+        first_execute(build_requests(requests, method), count: count, **DEFAULT_OPTIONS.merge(options))
+      end
+
+      define_method(:"stream_#{method}") do |requests, **options, &block|
+        stream_execute(build_requests(requests, method), **DEFAULT_OPTIONS.merge(options), &block)
+      end
+    end
+
+    private
+
+    def build_requests(requests, method)
+      requests.map do |req|
+        r = { url: req[:url], method: method.to_s.upcase }
+        r[:headers] = req[:headers] if req[:headers]
+        if req[:body] && BODY_METHODS.include?(method)
+          r[:body] = req[:body].is_a?(Hash) ? req[:body].to_json : req[:body].to_s
+          r[:headers] = (r[:headers] || {}).merge("Content-Type" => "application/json") if req[:body].is_a?(Hash)
+        end
+        r
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: fast_curl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- roman-haidarov
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: Parallel HTTP requests via libcurl curl_multi API. Releases GVL during
+  I/O, compatible with Async gem and Fiber scheduler. Supports execute (all), first_execute
+  (first N), stream_execute (yield as ready).
+email:
+- roman.haidarov@gmail.com
+executables: []
+extensions:
+- ext/fast_curl/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- ext/fast_curl/extconf.rb
+- ext/fast_curl/fast_curl.c
+- lib/fast_curl.rb
+- lib/fast_curl/version.rb
+homepage: https://github.com/roman-haidarov/fast_curl
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Ultra-fast parallel HTTP client as Ruby C extension on libcurl multi
+test_files: []