sidekiq-fiber 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 36e401e9716c74f87eb0423885cb6399200c06ee4ba4d55bf915be1bc2ed887b
+  data.tar.gz: 57bdd8cae18223a7264461ff58e694821ab6c576767e24839847c8e2d4ab2e3c
+SHA512:
+  metadata.gz: ca3c3d30d72a0e682dac97f1dccf9e29b0501df8301f035c5149f6df5ec69f80059474514b03d64601ec6ee4579dc02a52d660fe7103fe22186a975476a3ab17
+  data.tar.gz: 9e2fa6927df3a6caa33f3254722b3f8fdd57020c753c92303271c916e95ca5e40c88585dcc53e55a957df7b39a7a5b392766c230fb5219420e5f43a98785cdfa

data/README.md

@@ -0,0 +1,188 @@
+# sidekiq-fiber
+
+Fiber-based concurrency for IO-bound Sidekiq jobs.
+
+If your jobs mostly wait on network calls — LLM APIs, HTTP requests, S3 — threads are the wrong tool. A thread blocks completely during IO. With 20 threads and 1500 queued jobs, you're processing 20 at a time and the rest sit idle.
+
+This gem helps you solve this by using Ruby Fibers which take up a few kb per fiber and can help process 100s of fibers per thread. 
+
+## How it works
+
+Normal Sidekiq:
+```
+Thread → fetch job → perform (blocks on IO) → fetch next
+```
+
+With sidekiq-fiber:
+```
+Thread → fetch job 1 → schedule as fiber → hits IO, suspends
+       → fetch job 2 → schedule as fiber → hits IO, suspends
+       → fetch job 3 → schedule as fiber → running
+       → job 1 resumes (IO done) → completes → fetch job 4
+```
+
+One thread. Many concurrent fibers. No blocking.
+
+## Requirements
+
+- Ruby 3.2+
+- Sidekiq 7.0+
+- Jobs must use fiber-aware IO clients (see table below)
+
+## Installation
+
+```ruby
+gem "sidekiq-fiber"
+```
+
+## Usage
+
+**1. Configure a dedicated fiber capsule**
+
+```ruby
+# config/initializers/sidekiq.rb
+require "sidekiq-fiber"
+
+Sidekiq.configure_server do |config|
+  config[:fiber_concurrency] = 50  # max concurrent fibers per thread
+
+  config.capsule("fiber") do |cap|
+    cap.concurrency = 20           # threads
+    cap.queues      = ["llm_jobs", "api_calls"]
+    cap.processor_class = Sidekiq::Fiber::Processor
+  end
+end
+```
+
+**2. Opt in per job**
+
+```ruby
+class MyLlmJob
+  include Sidekiq::Worker
+  include Sidekiq::Fiber::Worker  # opt in — you are responsible for fiber-safe IO
+
+  def perform(id)
+    # Net::HTTP is fiber-aware in Ruby 3.2+ — yields during socket wait
+    response = Net::HTTP.get(URI("https://api.openai.com/..."))
+    process(response)
+  end
+end
+```
+
+**3. Add the Web UI tab (optional)**
+
+```ruby
+# config/routes.rb
+require "sidekiq/fiber/web"
+
+Sidekiq::Web.configure do |config|
+  config.register Sidekiq::Fiber::Web,
+    name:     "sidekiq-fiber",
+    tab:      "Fibers",
+    index:    "fiber-stats",
+    root_dir: Gem.loaded_specs["sidekiq-fiber"].gem_dir
+end
+```
+
+## Fiber-safe IO
+
+You're responsible for using fiber-aware clients. Blocking IO freezes the whole thread.
+
+| Client | Fiber-aware in Ruby 3.2? |
+|---|---|
+| `Net::HTTP` | ✅ Yes — via fiber scheduler |
+| `Faraday` (net-http adapter) | ✅ Yes |
+| `HTTParty` | ✅ Yes (uses Net::HTTP) |
+| `ActiveRecord` queries | ✅ Yes — with our connection pool patch |
+| `Typhoeus` | ❌ No — uses libcurl |
+
+### ActiveRecord connection pool
+
+sidekiq-fiber patches `ActiveRecord::ConnectionPool` to use `Fiber.current` as the connection cache key instead of `Thread.current`. Each fiber gets its own connection slot.
+
+Keep this in mind when sizing your DB pool:
+
+```
+max DB connections = threads × fiber_concurrency
+```
+
+If your DB pool is 100 and you have 20 threads, set `fiber_concurrency` to 5 or lower. The Web UI will warn you when you're over this limit
+
+## Capacity planning
+
+```
+max concurrent fibers  = capsule.concurrency × fiber_concurrency
+max DB connections     = capsule.concurrency × fiber_concurrency
+peak memory (HTTP)     ≈ max concurrent fibers × ~50KB per connection
+```
+
+## Benchmark
+
+Measured on Ruby 3.2.2, MacBook Air M2.
+**Thread model:** 20 threads, one job at a time (max 20 concurrent)
+**Fiber model:** 20 threads × 50 fibers (max 1000 concurrent)
+
+### Part 1 — sleep() simulation (fixed latency)
+
+`sleep()` is fiber-scheduler aware in Ruby 3.2. In a thread it blocks completely. In a fiber it yields, so other fibers can run. Results are clean and predictable here.
+
+| Scenario | Jobs | IO wait | Threads | Fibers | Speedup |
+|---|---|---|---|---|---|
+| Light | 50 | 0.1s | 0.32s | 0.10s | **3.0x** |
+| Medium | 200 | 0.5s | 5.04s | 0.51s | **9.9x** |
+| Heavy | 500 | 1.0s | 25.10s | 1.02s | **24.7x** |
+
+### Part 2 — Real HTTP calls (variable latency)
+
+Jobs make actual `Net::HTTP` requests to a local WEBrick server that responds after a random delay. Real socket IO. `Net::HTTP` in Ruby 3.2 hooks into the fiber scheduler — the socket read suspends the fiber and resumes it when data arrives.
+
+| Scenario | Jobs | Latency range | Threads | Fibers | Speedup |
+|---|---|---|---|---|---|
+| Fast API | 50 | 0.05s–0.3s | 0.63s | 0.31s | **2.1x** |
+| Medium API | 100 | 0.5s–2.0s | 7.64s | 2.06s | **3.7x** |
+| LLM-like | 50 | 2.0s–8.0s | 16.40s | 7.84s | **2.1x** |
+| **Real burst** | **1500** | **0.5s–2.0s** | **95.46s** | **17.44s** | **5.5x** |
+
+### Inference
+
+**Speedup scales with job_count / thread_count.** The more jobs you have relative to threads, the more fibers help. The Heavy scenario hits 24.7x because 500 jobs / 20 threads = 25 serial batches — fibers collapse that to 1. (Best usecase)
+
+**The LLM-like scenario (50 jobs, 2-8s) is only 2.1x** because with 50 jobs and 1000 fiber slots, all 50 start immediately. Both approaches then wait for the slowest request (~8s). Fibers don't make requests faster — they stop threads from sitting idle during IO.
+
+**The Real burst scenario (1500 jobs, 0.5-2.0s) is the honest one** — closest to high traffic production LLM workloads. Threads: 95s. Fibers: 17s. Threads process 20 at a time across 75 serial batches. Fibers process up to 1000 across 2 batches.
+
+**Memory:** the Real burst run peaked at +52.9MB for fibers vs +3.3MB for threads. 1000 concurrent HTTP connections means 1000 open sockets with buffers and response objects in memory. Set `fiber_concurrency` based on your memory budget, not just throughput.
+
+To reproduce:
+
+```bash
+bundle exec ruby bench/throughput.rb
+```
+
+## Web UI
+
+The optional "Fibers" tab shows:
+
+- **Global health** — active fibers, semaphore utilization, DB connection warning
+- **Per-thread breakdown** — semaphore fill, throughput, blocking IO detection
+- **In-flight fibers** — long-running fiber alerts (> 30s)
+
+**Blocking IO detection:** if a thread has active fibers but zero completions for > 60 seconds, the UI flags it. This catches jobs accidentally using non-fiber-aware clients that freeze the whole thread.
+
+## Design decisions
+
+**Why a dedicated capsule, not mixed with normal jobs?**
+Fiber and non-fiber jobs on the same processor share thread-level interrupt handling and connection pool state in ways that are subtle to reason about. A dedicated capsule makes the boundary structural and hence avoid accidental issues.
+
+**Why the `async` gem for the event loop?**
+The fiber scheduler interface in Ruby 3.2 has edge cases around IO readiness, timeout handling, and signal interrupts. `async` is battle tested and I didn't want to reinvent the wheel for this.
+
+**Why patch `connection_cache_key` instead of a custom pool?**
+The patch is 3 lines and uses the pool's designed extension point. A custom pool would duplicate hundreds of lines of connection management logic and diverge from ActiveRecord's battle-tested implementation. 
+
+**Why opt-in per job instead of per queue?**
+Writing fiber-safe code requires deliberate choices about which IO clients you use. Making it explicit at the job class level enforces that — a queue declaration hides it. If you use a blocking client inside a fiber job, the whole thread stalls silently. Explicit opt-in helps the developers make accidental mistakes.
+
+## License
+
+MIT

data/lib/sidekiq/fiber/connection_pool_patch.rb

@@ -0,0 +1,27 @@
+module Sidekiq
+  module Fiber
+    # Patches ActiveRecord's connection pool to use Fiber.current as the
+    # cache key instead of Thread.current.
+    #
+    # Without this patch, all fibers on the same thread share one connection
+    # slot — causing either connection sharing (data corruption) or unbounded
+    # connection checkout (one per fiber).
+    #
+    # With this patch, each fiber gets its own connection slot. The developer
+    # must still bound fiber concurrency via fiber_concurrency config to avoid
+    # exhausting the database connection limit.
+    #
+    # Only applied when ActiveRecord is present.
+    module ConnectionPoolPatch
+      def connection_cache_key(_thread)
+        ::Fiber.current
+      end
+    end
+  end
+end
+
+if defined?(ActiveRecord::ConnectionAdapters::ConnectionPool)
+  ActiveRecord::ConnectionAdapters::ConnectionPool.prepend(
+    Sidekiq::Fiber::ConnectionPoolPatch
+  )
+end

data/lib/sidekiq/fiber/manager_patch.rb

@@ -0,0 +1,46 @@
+require "sidekiq/manager"
+require "sidekiq/capsule"
+
+module Sidekiq
+  module Fiber
+    # Extends Sidekiq::Capsule with a per-capsule processor_class attribute.
+    # We can't use capsule[:processor_class] because capsule delegates [] to
+    # the global config — setting it would affect all capsules.
+    module CapsulePatch
+      def processor_class=(klass)
+        @processor_class = klass
+      end
+
+      def processor_class
+        @processor_class
+      end
+    end
+
+    # Patches Sidekiq::Manager to respect the per-capsule processor_class.
+    module ManagerPatch
+      def initialize(capsule)
+        super
+        klass = capsule.respond_to?(:processor_class) && capsule.processor_class
+        @processor_class = klass || Sidekiq::Processor
+        @workers.clear
+        @count.times do
+          @workers << @processor_class.new(@config, &method(:processor_result))
+        end
+      end
+
+      def processor_result(processor, reason = nil)
+        @plock.synchronize do
+          @workers.delete(processor)
+          unless @done
+            p = @processor_class.new(@config, &method(:processor_result))
+            @workers << p
+            p.start
+          end
+        end
+      end
+    end
+  end
+end
+
+Sidekiq::Capsule.prepend(Sidekiq::Fiber::CapsulePatch)
+Sidekiq::Manager.prepend(Sidekiq::Fiber::ManagerPatch)

data/lib/sidekiq/fiber/processor.rb

@@ -0,0 +1,155 @@
+require "async"
+require "sidekiq/processor"
+require_relative "stats"
+
+module Sidekiq
+  module Fiber
+    # A Sidekiq::Processor replacement that runs fiber-aware jobs as fibers
+    # inside a per-thread Async event loop.
+    #
+    # One event loop runs per thread. Each fiber job is scheduled as a child
+    # task inside that loop. The thread fetches jobs continuously, scheduling
+    # each as a fiber without waiting for previous fibers to finish.
+    #
+    # A semaphore bounds concurrent fibers per thread. This directly controls
+    # how many DB connections this processor can consume:
+    #   max_connections = threads * fiber_concurrency
+    #
+    # On normal shutdown (@done = true), the fetch loop exits but the event
+    # loop waits for all in-flight fibers to complete before returning.
+    #
+    # On hard shutdown (Sidekiq::Shutdown raised), in-flight fibers that have
+    # not completed are requeued — identical to Sidekiq's default behaviour.
+    class Processor < Sidekiq::Processor
+      def initialize(capsule, &block)
+        super
+        @fiber_concurrency  = capsule.config[:fiber_concurrency] || 100
+        @active_fibers      = 0
+        @active_fibers_lock = Mutex.new
+        stats_pool = capsule.config.new_redis_pool(@fiber_concurrency, "sidekiq-fiber-stats")
+        @stats = Stats.new(stats_pool)
+      end
+
+      private
+
+      # Replaces the default run loop with a fixed pool of fiber workers.
+      #
+      # We spawn exactly fiber_concurrency persistent fibers. Each fiber owns
+      # its own fetch-process loop: it fetches one job, processes it, then
+      # fetches the next. This means jobs stay in Redis until there is actual
+      # capacity — we never drain the queue into memory ahead of processing.
+      #
+      # The previous design (single fetch loop + semaphore) fetched unboundedly
+      # fast, pulling all queued jobs into pending async tasks before any fiber
+      # started working. With 5000 jobs enqueued that meant 5000 tasks created
+      # instantly, all invisible to the Sidekiq UI.
+      def run
+        Thread.current[:sidekiq_capsule] = @capsule
+
+        thread_id = Thread.current.object_id.to_s
+
+        @stats.register_thread(thread_id: thread_id, fiber_concurrency: @fiber_concurrency)
+
+        Async do |task|
+          workers = @fiber_concurrency.times.map do
+            task.async do
+              until @done
+                uow = fetch
+                unless uow
+                  task.yield  # nothing in queue — yield so other fibers can run
+                  next
+                end
+
+                klass_name = begin
+                  Sidekiq.load_json(uow.job)["class"]
+                rescue
+                  nil
+                end
+
+                is_fiber_job = klass_name &&
+                  Object.const_get(klass_name).include?(Sidekiq::Fiber::Worker)
+
+                if is_fiber_job
+                  active = @active_fibers_lock.synchronize { @active_fibers += 1 }
+                  @stats.update_thread_stats(
+                    thread_id:          thread_id,
+                    semaphore_size:     @fiber_concurrency,
+                    semaphore_acquired: active
+                  )
+                  process_in_fiber(uow, thread_id: thread_id)
+                  active = @active_fibers_lock.synchronize { @active_fibers -= 1 }
+                  @stats.update_thread_stats(
+                    thread_id:          thread_id,
+                    semaphore_size:     @fiber_concurrency,
+                    semaphore_acquired: active
+                  )
+                else
+                  process(uow)
+                end
+              end
+            end
+          end
+
+          workers.each(&:wait)
+        end
+
+        @stats.deregister_thread(thread_id: thread_id)
+        @callback.call(self)
+      rescue Sidekiq::Shutdown
+        @stats.deregister_thread(thread_id: Thread.current.object_id.to_s)
+        @callback.call(self)
+      rescue Exception => ex
+        @stats.deregister_thread(thread_id: Thread.current.object_id.to_s)
+        @callback.call(self, ex)
+      end
+
+      # Runs a single job unit of work inside the current fiber.
+      # Mirrors Sidekiq::Processor#process but with per-fiber ack tracking
+      # so that hard shutdown can requeue incomplete jobs correctly.
+      def process_in_fiber(uow, thread_id:)
+        jobstr   = uow.job
+        queue    = uow.queue_name
+        job_hash = nil
+
+        begin
+          job_hash = Sidekiq.load_json(jobstr)
+        rescue => ex
+          handle_exception(ex, { context: "Invalid JSON for job", jobstr: jobstr })
+          return uow.acknowledge
+        end
+
+        jid       = job_hash["jid"]
+        job_class = job_hash["class"]
+        ack       = false
+
+        @stats.fiber_started(jid: jid, job_class: job_class, thread_id: thread_id)
+
+        begin
+          dispatch(job_hash, queue, jobstr) do |instance|
+            @capsule.config.server_middleware.invoke(instance, job_hash, queue) do
+              execute_job(instance, job_hash["args"])
+            end
+          end
+          ack = true
+        rescue Sidekiq::Shutdown
+          # Fiber was stopped before job completed. Do not acknowledge.
+          # Job will be requeued by the capsule fetcher on shutdown.
+        rescue Sidekiq::JobRetry::Skip => s
+          ack = true
+          raise s
+        rescue Sidekiq::JobRetry::Handled => h
+          ack = true
+          e = h.cause || h
+          handle_exception(e, { context: "Job raised exception", job: job_hash })
+          raise e
+        rescue Exception => ex
+          handle_exception(ex, { context: "Internal exception!", job: job_hash, jobstr: jobstr })
+          raise ex
+        ensure
+          @stats.fiber_completed(jid: jid, thread_id: thread_id)
+          uow.acknowledge if ack
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/fiber/stats.rb

@@ -0,0 +1,136 @@
+module Sidekiq
+  module Fiber
+    # Writes fiber execution stats to Redis.
+    # Called from the processor at key lifecycle points:
+    #   - fiber starts      → record in-flight fiber
+    #   - fiber completes   → remove in-flight, increment completed counter
+    #   - semaphore changes → update utilization
+    #
+    # All keys are namespaced under "sidekiq-fiber:" and expire automatically
+    # so stale data doesn't accumulate after a worker restarts.
+    class Stats
+      NAMESPACE      = "sidekiq-fiber"
+      FIBER_TTL      = 600  # 10 minutes — long-running fiber alert threshold
+      THREAD_TTL     = 120  # 2 minutes — thread stats expire if worker dies
+      GLOBAL_TTL     = 120
+
+      def initialize(redis_pool)
+        @redis = redis_pool
+      end
+
+      # Called when a fiber starts executing a job.
+      def fiber_started(jid:, job_class:, thread_id:)
+        safe_redis do |conn|
+          key = fiber_key(jid)
+          conn.hset(key,
+            "job_class",  job_class,
+            "thread_id",  thread_id,
+            "started_at", Time.now.to_f
+          )
+          conn.expire(key, FIBER_TTL)
+        end
+      end
+
+      def fiber_completed(jid:, thread_id:)
+        safe_redis do |conn|
+          conn.del(fiber_key(jid))
+          conn.hincrby(thread_key(thread_id), "completed_total", 1)
+          conn.hset(thread_key(thread_id), "last_completed_at", Time.now.to_f)
+          conn.expire(thread_key(thread_id), THREAD_TTL)
+        end
+      end
+
+      def update_thread_stats(thread_id:, semaphore_size:, semaphore_acquired:)
+        safe_redis do |conn|
+          conn.hset(thread_key(thread_id),
+            "semaphore_size",     semaphore_size,
+            "semaphore_acquired", semaphore_acquired
+          )
+          conn.expire(thread_key(thread_id), THREAD_TTL)
+        end
+      end
+
+      def register_thread(thread_id:, fiber_concurrency:)
+        safe_redis do |conn|
+          conn.sadd(threads_index_key, thread_id)
+          conn.expire(threads_index_key, GLOBAL_TTL)
+          conn.hset(thread_key(thread_id),
+            "semaphore_size",     fiber_concurrency,
+            "semaphore_acquired", 0,
+            "completed_total",    0,
+            "last_completed_at",  ""
+          )
+          conn.expire(thread_key(thread_id), THREAD_TTL)
+        end
+      end
+
+      def deregister_thread(thread_id:)
+        safe_redis do |conn|
+          conn.srem(threads_index_key, thread_id)
+          conn.del(thread_key(thread_id))
+        end
+      end
+
+      # ── Readers (used by Web UI) ─────────────────────────────────────────────
+
+      def all_thread_stats
+        @redis.with do |conn|
+          thread_ids = conn.smembers(threads_index_key)
+          thread_ids.filter_map do |tid|
+            stats = conn.hgetall(thread_key(tid))
+            next if stats.empty?
+            stats.merge("thread_id" => tid)
+          end
+        end
+      end
+
+      def all_in_flight_fibers
+        @redis.with do |conn|
+          keys = conn.keys("#{NAMESPACE}:fiber:*")
+          keys.filter_map do |key|
+            data = conn.hgetall(key)
+            next if data.empty?
+            jid = key.split(":").last
+            data.merge(
+              "jid"        => jid,
+              "running_for" => (Time.now.to_f - data["started_at"].to_f).round(1)
+            )
+          end
+        end
+      end
+
+      def global_summary
+        @redis.with do |conn|
+          thread_ids   = conn.smembers(threads_index_key)
+          total_active = 0
+          total_max    = 0
+
+          thread_ids.each do |tid|
+            stats        = conn.hgetall(thread_key(tid))
+            total_active += stats["semaphore_acquired"].to_i
+            total_max    += stats["semaphore_size"].to_i
+          end
+
+          {
+            thread_count:  thread_ids.size,
+            total_active:  total_active,
+            total_max:     total_max
+          }
+        end
+      end
+
+      private
+
+      def safe_redis(&block)
+        @redis.with(&block)
+      rescue ConnectionPool::TimeoutError, StandardError
+        # Stats writes are best-effort. A timeout or Redis blip should never
+        # propagate into the fiber and fail the job.
+      end
+
+      def fiber_key(jid)        = "#{NAMESPACE}:fiber:#{jid}"
+      def thread_key(thread_id) = "#{NAMESPACE}:thread:#{thread_id}"
+      def threads_index_key     = "#{NAMESPACE}:threads"
+    end
+  end
+end

data/lib/sidekiq/fiber/version.rb

@@ -0,0 +1,5 @@
+module Sidekiq
+  module Fiber
+    VERSION = "0.1.0"
+  end
+end

data/lib/sidekiq/fiber/web.rb

@@ -0,0 +1,59 @@
+require "sidekiq/web"
+require_relative "stats"
+
+module Sidekiq
+  module Fiber
+    # Sidekiq Web UI extension for fiber stats.
+    #
+    # Registers a "Fibers" tab that shows:
+    #   - Global summary (active fibers, semaphore utilization, DB connection warning)
+    #   - Per-thread breakdown (semaphore fill, throughput, blocking IO detection)
+    #   - In-flight fibers (long-running fiber alert)
+    #
+    # Usage in config/routes.rb or rack config:
+    #
+    #   require "sidekiq/fiber/web"
+    #   Sidekiq::Web.configure do |config|
+    #     config.register Sidekiq::Fiber::Web,
+    #       name:     "sidekiq-fiber",
+    #       tab:      "Fibers",
+    #       index:    "fiber-stats",
+    #       root_dir: File.expand_path("../../../..", __FILE__)
+    #   end
+    module Web
+      VIEWS = File.expand_path("../../../web/views", __dir__)
+      ROOT  = File.expand_path("../../../", __dir__)
+
+      def self.registered(app)
+        app.get "/fiber-stats" do
+          pool  = Sidekiq.default_configuration.redis_pool
+          stats = Sidekiq::Fiber::Stats.new(pool)
+
+          @global         = stats.global_summary
+          @thread_stats   = stats.all_thread_stats.sort_by { |t| t["thread_id"] }
+          @in_flight      = stats.all_in_flight_fibers.sort_by { |f| -f["running_for"].to_f }
+
+          # DB connection warning threshold
+          @db_pool_size = begin
+            ActiveRecord::Base.connection_pool.size
+          rescue
+            nil
+          end
+
+          render(:erb, File.read(File.join(VIEWS, "fiber_stats.html.erb")))
+        end
+
+        app.get "/fiber-stats/thread/:thread_id" do
+          pool  = Sidekiq.default_configuration.redis_pool
+          stats = Sidekiq::Fiber::Stats.new(pool)
+
+          thread_id     = route_params(:thread_id)
+          @thread_stats = stats.all_thread_stats.find { |t| t["thread_id"] == thread_id }
+          @in_flight    = stats.all_in_flight_fibers.select { |f| f["thread_id"] == thread_id }
+
+          render(:erb, File.read(File.join(VIEWS, "fiber_thread.html.erb")))
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/fiber/worker.rb

@@ -0,0 +1,24 @@
+module Sidekiq
+  module Fiber
+    # Marker module. Including this in a Sidekiq job class signals to
+    # SidekiqFiber::Processor that this job should run as a fiber.
+    #
+    # The developer is responsible for ensuring all IO inside the job
+    # uses fiber-aware clients. Blocking IO (e.g. a non-patched HTTP
+    # client) will block the entire thread, defeating the purpose.
+    #
+    # Example:
+    #
+    #   class MyJob
+    #     include Sidekiq::Worker
+    #     include Sidekiq::Fiber::Worker
+    #
+    #     def perform(id)
+    #       # only fiber-aware IO here
+    #       Net::HTTP.get(URI("https://api.example.com/#{id}"))
+    #     end
+    #   end
+    module Worker
+    end
+  end
+end

data/lib/sidekiq-fiber.rb

@@ -0,0 +1,8 @@
+require "sidekiq"
+require "async"
+
+require_relative "sidekiq/fiber/version"
+require_relative "sidekiq/fiber/worker"
+require_relative "sidekiq/fiber/processor"
+require_relative "sidekiq/fiber/connection_pool_patch"
+require_relative "sidekiq/fiber/manager_patch"

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: sidekiq-fiber
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yash Dave
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: async
+  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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  sidekiq-fiber lets you run IO-bound Sidekiq jobs as fibers instead of threads.
+  A single thread can process thousands of concurrent jobs that spend most of
+  their time waiting on external IO (HTTP, LLM APIs, S3) — without the memory
+  and OS overhead of one thread per job.
+email:
+- yash@skima.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sidekiq-fiber.rb
+- lib/sidekiq/fiber/connection_pool_patch.rb
+- lib/sidekiq/fiber/manager_patch.rb
+- lib/sidekiq/fiber/processor.rb
+- lib/sidekiq/fiber/stats.rb
+- lib/sidekiq/fiber/version.rb
+- lib/sidekiq/fiber/web.rb
+- lib/sidekiq/fiber/worker.rb
+homepage: https://github.com/yashdave00/sidekiq-fiber
+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.4.10
+signing_key:
+specification_version: 4
+summary: Fiber-based concurrency for Sidekiq IO-bound jobs
+test_files: []