emb 0.3.0 → 0.4.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aff64eb7fb61e9d6ce29bb76786020087ea90c317ec04344bf1cb8d3b3fd4e8
-  data.tar.gz: ccf361c3c12406e71e778976e63f580b6bd56c0d658f12a2acdef6c75d42143f
+  metadata.gz: 646506ae908e1f9db100c67c6d4e20dc6c6fc84e9d2d2a62c7954385ff632d73
+  data.tar.gz: 07e42cf06b265483d14899ad8607909ad8caa99243e28bd7fe66dfad6eef1496
 SHA512:
-  metadata.gz: 40ba7fd979d43af7ab056f4c4981245f3d19080d8f19b19026d6f3d132a947d1ae3e14c8cef326a4b65876250ddfc58cd00b5ce48f6301d65e5a21b3bffe945a
-  data.tar.gz: 583dd05fd04481dcdc7f4c3a4312c9464e1660d7e27bf16caebe543ddda8cde7ff8e4f6a156eefcd54b484cc4031551a1e89361ea437ec76082f3e0a4fb44ebe
+  metadata.gz: 0ea5a3f7613be7280da47b7e52ebcff8b7773ef33ebbdcdbaa231e28084b8e4b3b12755be415b965b82ce395ea252c1dbf7592a4981740e2ba45b67e97338d49
+  data.tar.gz: 869f1f0df61b44fc09aa6ce95b4b04bbcf0de1542f2697594160e16baf977dc6707df7a7a6da77a0e68be3d1f199c77f2cac171e0a41cabdf467c8958a352e89

data/Gemfile

@@ -4,7 +4,6 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'connection_pool'
 gem 'redis-client'
 
 gem 'rake', require: false

data/README.md

@@ -55,7 +55,7 @@ resolve in this order — the first one wins:
 ```ruby
 Emb.configure do |c|
   c.pool = 8
-  c.batch = false   # opt out of lazy batching app-wide
+  c.lazy = :multi   # defer and coalesce embed calls app-wide
 end
 
 Emb.configuration   # => the shared Emb::Configuration
@@ -67,11 +67,28 @@ Emb::Client.new(pool: 20)  # per-call still wins
 
 ### Out-of-the-box defaults
 
-The shipped defaults are benchmark-derived (see `BENCHMARK.md`): **lazy batching is on by
-default** (`batch: true` — each embed coalesces into one `EMB.MULTI`), pool `5`, pure-Ruby
-RESP driver, `protocol: 2`, `reconnect_attempts: 3`. To keep the eager behavior (immediate
-`EMB` per call), opt out globally via `Emb.configure { |c| c.batch = false }` or per client
-with `Emb.new(batch: false)`.
+The shipped defaults are benchmark-derived (see `BENCHMARK.md`) with secure-by-default
+network behavior: **eager execution by default** (`lazy: false` — every `Emb[:model][t]`
+sends one `EMB` round trip), pool `5`, pure-Ruby RESP driver, `protocol: 2`,
+`read_timeout`/`write_timeout` both **10s**, and `reconnect_attempts: 0`. Opt into
+coalescing with `lazy: :multi` or concurrent fan-out with `lazy: :batch` — globally via
+`Emb.configure { |c| c.lazy = :batch }` or per client with `Emb.new(lazy: :batch)`.
+
+**Why the timeout and reconnect defaults matter:** batched `EMB.MULTI` (up to 512 pairs)
+can take over a second of inference on a shared CPU, and redis-client's silent default is
+1.0s — a slower reply times out. The gem therefore defaults to an explicit 10s timeout
+and `reconnect_attempts: 0`: a failing batch fails closed after one attempt and raises
+`Emb::ServerError` (see [Lazy execution modes](#lazy-execution-modes)). Set
+`Emb.configure { |c| c.reconnect_attempts = 2 }` and redis-client re-sends
+**connection and protocol failures** up to that many extra times before the batch fails
+closed — each re-send re-runs server inference, so keep the budget small. Operation
+errors (unknown model, auth, bad pairs) are never retried, and neither are **read
+timeouts**: redis-client treats `ReadTimeoutError` as terminal, and re-sending a timed-out
+command could duplicate inference the server already did. `lazy: :batch` shares
+additionally retry a refused connection on the next configured instance. Raise the
+timeouts if you raise `batch_size`. `reconnect_attempts` also accepts an Array of
+per-retry delays (a redis-client passthrough); each entry grants one retry and counts
+toward `Emb::ServerError#attempts`.
 
 ### Connection pool
 
@@ -79,11 +96,48 @@ with `Emb.new(batch: false)`.
 Emb.setup(url: "redis://localhost:6379", pool: 10)
 ```
 
-The default pool size is **5**. The pool is usually not the bottleneck for
-inference-bound workloads (small pools are fine); it becomes a knob only at high
-concurrency on a multi-model box — see [Performance](#performance). If a pool checkout
-would wait too long, `RedisClient`'s `connect_timeout`/`read_timeout` (above) bound the
-wait.
+The default pool size is **5**. The client keeps `pool` persistent connections per
+emb **instance** and routes commands through them **in round-robin order** —
+consecutive commands use different connections instead of reusing one hot connection.
+
+`url` also accepts an **array of instances** (interchangeable replicas serving the same
+model set); commands then round-robin across instances first, then across connections
+within the selected instance:
+
+```ruby
+Emb.setup(url: ["redis://emb-a:6379", "redis://emb-b:6379", "redis://emb-c:6379"], pool: 5)
+```
+
+Each url gets its own pool of `pool` connections, so `pool: 5` with three urls maintains
+15 connections total. If an instance refuses a connection **before a command is sent**
+(connection refused/unreachable), the command is retried on the next instance — this is
+why `reconnect_attempts` stays `0`: a retry after a *sent* command could duplicate
+inference, but a never-sent command is safe to move elsewhere.
+
+This matters when emb runs as a pool of instances behind a **connection-level load
+balancer** (AWS Service Connect, an NLB, or Envoy): the balancer assigns each
+keep-alive connection to exactly one instance for its lifetime, so relying on a
+single connection would pin all of a process's embedding traffic to one instance —
+and queue it there even while other instances sit idle. Round-robin spreading across
+`pool` connections spreads traffic across up to `pool` instances, so set `pool` to
+**at least your expected emb instance count** (e.g. `pool: 10` for 10 instances).
+
+Commands beyond the pool's parallelism do **not** time out: when `pool` commands are
+already in flight, later commands wait on the shared connections until one frees
+(there is no checkout timeout — unlike the previous pool's 5s
+`ConnectionPool::TimeoutError`). Only the wait for a free pool connection is
+unbounded — once a command runs, `RedisClient`'s `connect_timeout`,
+`read_timeout`, and `write_timeout` still apply. For inference workloads this
+lets commands ride out token-budget batching instead of erroring.
+
+Locally (a single server) only the backend selection is identical whatever the
+pool size — every command reaches the same server. The pool size still controls
+how many persistent connections the client holds and how many commands run in
+parallel. The pool is usually not the bottleneck for
+inference-bound workloads (small pools are fine); it becomes a knob at high
+concurrency on a multi-model box — see [Performance](#performance). With
+round-robin selection up to `pool` commands run in parallel; beyond that, commands
+share connections and serialize on them.
 
 ### Authentication
 
@@ -124,8 +178,8 @@ Emb.setup(
 ```
 
 See the [redis-client documentation](https://github.com/redis-rb/redis-client) for
-all available options. Only `pool` and `batch` are handled by the gem — everything
-else passes through to `RedisClient.new`.
+all available options. Only `pool`, `lazy`, and `batch_size` are handled by the
+gem — everything else passes through to `RedisClient.new`.
 
 ## Instance-based clients
 
@@ -169,6 +223,12 @@ automatically.
 
 ## Server info & config
 
+> **Per-instance data.** `Emb.server_info`, `stats`, `info`, and `config` read
+> from ONE instance, and with round-robin connection selection that instance
+> may change between calls (with `pool: 1` it never does) — each call is a
+> sample. `Emb.config[key] = value` mutates one (arbitrary) instance. Use
+> per-connection queries if you need a specific or aggregated view.
+
 The server exposes Redis-style `INFO` and `CONFIG` commands; the gem wraps them.
 
 ### `Emb.stats` — server statistics as a hash
@@ -190,15 +250,18 @@ Emb.stats
 ### `Emb.server_info` — sectioned INFO, parsed
 
 The Redis-style `INFO` reply is parsed into a nested Hash. **No arguments = all
-sections**; pass section names to filter (`:server`, `:cache`, `:keyspace`, `:stats`, `:clients`):
+sections**; pass section names to filter (`:server`, `:cache`, `:keyspace`, `:stats`, `:memory`, `:cpu`, `:clients`):
 
 ```ruby
 Emb.server_info
 # => {Server: {redis_version: "0.2.4", emb_version: "0.2.4", uptime_secs: "7", ...},
 #     Cache: {cache_hits: 0, cache_misses: 0, cache_hit_rate: "0.0%", ...},
-#     Keyspace: {db0: "model=minilm,keys=0,hits=0,misses=0,hit_rate=0.0%"}, ...}
+#     Keyspace: {db0: "model=minilm,keys=0,hits=0,misses=0,hit_rate=0.0%"},
+#     Memory: {used_memory_rss_bytes: 262438912, used_memory_heap_bytes: 154960,
+#              goroutines: 4, total_system_memory_bytes: 25769803776},
+#     CPU: {used_cpu_user_usec: 188900, used_cpu_sys_usec: 50462, gomaxprocs: 10}, ...}
 
-Emb.server_info(:server, :cache)   # only those two sections
+Emb.server_info(:memory, :cpu)   # live process resources only
 ```
 
 ### `Emb.config` — hot config read & change
@@ -273,38 +336,73 @@ client.multi do |m|
 end
 ```
 
-### Lazy batching (`Emb.batch`)
+### Lazy execution modes
+
+Embed-call behavior is governed by a single `lazy` mode — `false` (default, eager),
+`:multi` (defer and coalesce into one `EMB` for a single model / one `EMB.MULTI` for mixed scopes, serial), or `:batch` (defer and execute
+the coalesced chunk shares **concurrently**). The three are mutually exclusive.
+
+| mode | `Emb[:model][text]` | execution |
+|---|---|---|
+| `false` (default) | immediate `EMB` round trip | serial, per call |
+| `:multi` | deferred → coalesces into one `EMB` (single model) or `EMB.MULTI` (mixed) | serial, one command at a time |
+| `:batch` | deferred → coalesces into `EMB`/`EMB.MULTI` chunks | **concurrent** — chunk shares run in parallel |
 
-Instead of collecting pairs by hand, `Emb.batch` returns lazy embeddings that all
-coalesce into a single `EMB.MULTI` round trip when the first one is used. This is
-powered by the [batch-loader](https://github.com/exAspArk/batch-loader) gem.
+In `:batch` mode the shares fan out across the configured instances (one share per
+instance when the share count allows) or across the instance's pool connections when a
+single url is configured — a batch whose pieces take 60ms and 10ms completes in roughly
+the slowest share (~60ms) instead of the sum (~70ms). Deferred work is powered by the
+[batch-loader](https://github.com/exAspArk/batch-loader) gem:
 
 ```ruby
+Emb.setup(lazy: :multi)  # or :batch — Emb[:minilm] now defers
+
 users = User.all # some application objects
 
 # Create loaders first...
-l1 = Emb.batch[:minilm]["hello"]
-l2 = Emb.batch[:minilm]["world"]
-l3 = Emb.batch[:bge]["bonjour"]
+l1 = Emb[:minilm]["hello"]
+l2 = Emb[:minilm]["world"]
+l3 = Emb[:bge]["bonjour"]
 
-# ...then consume them. The first use sends ONE EMB.MULTI for all three.
+# ...then consume them. The first use sends ONE EMB (single-model scope)
+# or ONE EMB.MULTI (mixed-model scope) for all three.
 l1.sum  # => 12.345
 l2.sum  # => -0.678
 l3.sum  # => 3.141
 ```
 
-Instance clients expose the same API:
-
-```ruby
-client.batch[:minilm]["hello"].sum
-```
-
 Each lazy value materializes to the same shape as the eager API: a single text
-yields an `Array<Float>`, multiple texts yield `Array<Array<Float>>`:
+yields an `Array<Float>`, multiple texts yield `Array<Array<Float>>`. For explicit
+composition that always sends immediately regardless of mode, use `Emb.multi { }`
+(see [Multi-model queries](#multi-model-queries)).
+
+The batch executes in the current thread's scope; the Rack/ActiveJob middleware
+clears that scope after every request/job (`Emb::BatchScope`), so deferred work
+can never accumulate across requests (in eager mode there is nothing to clear).
+
+**Fail-closed batches.** If a batch command fails — a timeout, an operation error, or in
+`:batch` mode a share failure after pre-send retries are exhausted — the batch raises
+**`Emb::ServerError`** to the code that first used it, and every deferred item of that
+batch is removed from the scope — retrying (or using other items of the failed batch)
+**does not re-send the batch** and resolves to `[]` instead. The error's `cause` is the
+underlying redis error (`RedisClient::ReadTimeoutError`, `RedisClient::CommandError`, ...)
+and its message includes the model(s), text count, and attempt count. Transient failures
+(timeout, connection error, protocol error) re-send up to `reconnect_attempts` extra
+times when that option is set above 0 (default 0 = a single attempt); operation errors
+are never retried. A non-redis error raised by the batch call itself (e.g. a `TypeError`
+from bad arguments) is a local bug, not a server failure: the batch's pending items are
+still cleared, but the original error is re-raised. This
+prevents a slow server from turning one failed batch into endless duplicate work
+(retries re-running the whole batch) or growth of the pending set across retries.
+Pair-level failures the server reports as `null` (MGET semantics) are unaffected.
+
+> **Breaking change (gem ≥ next release):** a failed batch raises `Emb::ServerError`
+> instead of the raw `RedisClient::*` error. Rescue `Emb::ServerError` and read `cause`
+> for the original error. Eager `Emb.multi` and the `lazy: false` path are unchanged.
 
 ```ruby
-vec   = Emb.batch[:minilm]["hello"]   # use -> Array of Float
-vecs  = Emb.batch[:minilm]["hello", "world"]  # use -> Array of Array of Float
+vec   = Emb[:minilm]["hello"]            # use -> Array of Float
+vecs  = Emb[:minilm]["hello", "world"]  # use -> Array of Array of Float
 ```
 
 Embeddings are cached per thread, so reusing a lazy value (or creating an
@@ -318,43 +416,59 @@ Loaders only fire when a value is **used**. Create all loaders *first*, then
 consume them, so they share one round trip:
 
 ```ruby
-texts.each { |t| process(Emb.batch[:minilm][t]) }   # wrong: one MULTI per item
-loaders = texts.map { |t| Emb.batch[:minilm][t] }   # right: ONE MULTI for all
+texts.each { |t| process(Emb[:minilm][t]) }   # wrong: one EMB per item
+loaders = texts.map { |t| Emb[:minilm][t] }   # right: ONE EMB for all
 loaders.each { |l| process(l) }
 ```
 
 A loader that is created but never used **never embeds** (unless a sibling batch
 fires first) and is silently dropped when the thread's scope ends. Duration and
-scope: batching is per-thread — a multithreaded app issues one `EMB.MULTI` per
+scope: batching is per-thread — a multithreaded app issues one `EMB`/`EMB.MULTI` per
 thread per flush.
 
-### `batch` configuration option
+### `lazy` configuration option
 
-Setting `batch: true` makes the standard proxy API lazy, so existing call sites
-batch automatically without restructuring:
+Setting `lazy: :multi` or `lazy: :batch` makes the standard proxy API defer, so
+existing call sites batch automatically without restructuring:
 
 ```ruby
-Emb.setup(url: "redis://localhost:6379", batch: true)
+Emb.setup(url: "redis://localhost:6379", lazy: :multi)
 # or
-Emb.new(url: "redis://localhost:6379", batch: true)
+Emb.new(url: "redis://localhost:6379", lazy: :batch)
 ```
 
-With `batch: true`, `Emb[:minilm]["hello"]` returns a lazy embedding that sends
-`EMB.MULTI` on first use. The default is `false` — the proxy API stays eager,
-sending `EMB` immediately. `Emb.batch` works regardless of the option, and
-`Emb.multi` remains the explicit, eager, deterministic batching API.
+Under `lazy: :multi`, `Emb[:minilm]["hello"]` returns a lazy embedding that sends
+`EMB` on first use (serial chunks; `EMB.MULTI` only for mixed-model scopes). Under `lazy: :batch`, the chunk shares
+execute concurrently — with multiple `url`s they fan out across instances. The
+default is eager (`lazy: false`). `Emb.multi` remains the explicit, eager,
+deterministic composition API in every mode.
 
 ### Clearing the cache per request
 
-The per-thread batch scope holds cached embeddings for the life of the thread. In
-request-shaped processes (Rails, Rack apps, Sidekiq) mount `Emb::Middleware` to
-clear the scope at the end of each request:
+The per-thread batch scope holds cached embeddings for the life of the thread.
+In a Rails application the bundled Railtie mounts `Emb::Middleware`
+automatically, so the scope is cleared at the end of every request with no
+configuration:
 
 ```ruby
-# config/application.rb (Rails)
-config.middleware.use Emb::Middleware
+# nothing to do — Emb::Railtie inserts Emb::Middleware for you
+```
+
+Opt out if you want to manage the stack yourself:
+
+```ruby
+# config/application.rb
+config.emb.middleware = false
+```
+
+If your Gemfile loads `emb` before Rails is required (non-standard boot order), the
+guarded railtie require in `emb.rb` is skipped — add `require "emb/railtie"` in
+`config/application.rb` right after `require "rails/all"` (or in an initializer).
 
-# Any Rack app
+The middleware is also safe to mount manually in any Rack app (the Railtie
+skips insertion when it is already present):
+
+```ruby
 use Emb::Middleware
 ```
 
@@ -362,6 +476,46 @@ The scope is cleared even when the app raises, and a fresh scope starts
 automatically with the next request. Loaders created but never used within a
 request are dropped — the create-then-consume contract applies per request.
 
+### Job-scoped cache clearing
+
+The Railtie also registers `Emb::JobMiddleware` — the same per-scope clearing
+for background work — for every job framework present. Each job execution
+starts with a fresh batch scope: cached embeddings and loaders created but
+never used are dropped at the end of the job (even when it raises), so worker
+threads never leak scope state between jobs.
+
+- **ActiveJob** (SolidQueue, Sidekiq, Shoryuken, async, test adapters): an
+  `around_perform` callback on `ActiveJob::Base` registered by the Railtie.
+- **Plain Sidekiq workers** (non-ActiveJob): a server middleware added by the
+  Railtie.
+- **Plain Shoryuken workers** (non-ActiveJob): a server middleware added by the
+  Railtie.
+
+```ruby
+# opt out of all job-scope protection
+config.emb.job_middleware = false
+```
+
+In a non-Rails process, register the middleware manually:
+
+```ruby
+# sidekiq.rb / an initializer
+Sidekiq.configure_server do |config|
+  config.server_middleware { |chain| chain.add Emb::JobMiddleware }
+end
+
+# Shoryuken
+Shoryuken.configure_server do |config|
+  config.server_middleware { |chain| chain.add Emb::JobMiddleware }
+end
+```
+
+The Railtie also registers `Emb::JobMiddleware` into the `Sidekiq::Testing` middleware
+chain when `Sidekiq::Testing` is loaded *before the app finishes booting* (e.g. a dev
+`INLINE_SIDEKIQ` initializer). For RSpec test modes, `sidekiq/testing` typically loads
+after the app boots, so require it before your environment to get per-job clearing in
+fake/inline tests — e.g. `gem "sidekiq", require: ["sidekiq", "sidekiq/testing"]`.
+
 ## Performance
 
 ### Eager-burst pipelining (no new API)
@@ -372,7 +526,7 @@ batching doesn't fit), coalesce them into one packet with `RedisClient#pipelined
 ```ruby
 client = Emb.new(url: "redis://localhost:6379")
 
-a = client.pool.with do |conn|
+a = client.pools.first.with do |conn|
   conn.pipelined do |pipe|
     texts.each { |t| pipe.call("EMB", "minilm", t) }
   end
@@ -380,9 +534,22 @@ end
 # a -> Array of Float32-binary replies; unpack each with r.unpack("e*")
 ```
 
-`Client#pool` exposes the pool's `RedisClient` connections. This measurably beats
-plain per-call round trips; use it for bursts, and `Emb.batch`/`Emb.multi` when you want
-server-side coalescing into one `EMB.MULTI`.
+`Client#pools` exposes the per-instance pools' `RedisClient` connections (the
+first pool for a single-instance client). This measurably beats
+plain per-call round trips; use it for bursts, and `Emb.multi` or a deferred `lazy`
+mode when you want
+server-side coalescing into one packed inference.
+
+### Benchmark harness coverage
+
+The client benchmark harness (`gems/emb/bench/bench.rb`, `just bench-ruby`)
+reports one row per execution mechanism: `eager` (one `EMB` per call), `multi`
+(coalesced `EMB`, or `EMB.MULTI` for mixed models), `batch` (concurrent `EMB` chunk shares),
+`pipelined` (raw RESP pipelining), and `threaded` (eager across threads).
+`just bench-ruby-multi` starts two partitioned emb instances and adds the
+url-array rows `eager-2node` (round-robin distribution) and `batch-2node`
+(concurrent fan-out across instances); the two-node rows are skipped unless a
+second instance is reachable (`EMB_BENCH_PORT2`).
 
 ### RESP driver: pure-Ruby default, `hiredis` on demand
 
@@ -409,7 +576,7 @@ instance. Scale out without a cluster client:
   (optionally seed with `-cache` and a warmup pass).
 
 Lazy batching stays per server (a thread's loaders target one client), so batching and
-horizontal scale compose: each instance receives one `EMB.MULTI` per request.
+horizontal scale compose: each instance receives one `EMB` (single model) or `EMB.MULTI` (mixed) share per request.
 
 ### Commands
 

data/lib/emb/batch.rb

@@ -1,69 +1,116 @@
 # frozen_string_literal: true
 
 require 'batch_loader'
+require 'redis_client'
+require_relative 'batch_dispatch'
 
 module Emb
+  extend BatchDispatch
+
   BATCH_KEY = :emb
 
+  # Raised by resolve_slice when the server reply carries fewer entries than
+  # the slice's texts. Subclasses RedisClient::ProtocolError so the existing
+  # fail-closed rescue/wrap paths treat it as a client error, but stays
+  # distinct so transient_error? does not count it as a transport retry: the
+  # reply shape was wrong on the single send — nothing was re-sent.
+  ShortReplyError = Class.new(RedisClient::ProtocolError)
+
   BATCH_BLOCK = lambda do |items, loader, _args|
     items.group_by(&:first).each do |client, client_items|
       chunk = client.respond_to?(:batch_size) && client.batch_size ? client.batch_size : Emb.configuration.batch_size
 
-      # Chunk at batch_size pairs per EMB.MULTI so a single command stays well
-      # under the server's max_pairs cap and within client read timeouts.
-      client_items.each_slice(chunk) do |slice|
-        pairs = slice.flat_map { |_, model, text| Array(text).flat_map { |t| [model.to_s, t] } }
-        results = Array(client.send_command('EMB.MULTI', *pairs))
-
-        offset = 0
-        slice.each do |item|
-          _, _, text = item
-          texts = Array(text)
-          values = results[offset, texts.size].map { |entry| entry&.unpack('e*') }
-          offset += texts.size
-
-          # eager Proxy#[] shape: vector for a single text, vectors for many
-          loader.call(item, values.size == 1 ? values.first : values)
+      slices = pack_slices(client_items, chunk)
+      if client.respond_to?(:parallel_batch?) && client.parallel_batch? && slices.size > 1
+        dispatch_parallel(client, slices, loader)
+      else
+        # Serial dispatch: one share in flight at a time. Redis errors fail
+        # closed with context; anything else is a local bug and is re-raised
+        # unchanged after the pending set is dropped.
+        slices.each do |slice|
+          resolve_slice(loader, slice, dispatch_slice(client, slice))
+        rescue RedisClient::Error => e
+          fail_batch!(e, slice: slice, budget: retry_budget(client))
+        rescue StandardError
+          clear_batch_pending!
+          raise
         end
       end
     end
   end
 
   class << self
-    def build_batch_loader(client, model, text)
-      BatchLoader.for([client, model, text]).batch(key: BATCH_KEY, &BATCH_BLOCK)
-    end
-  end
+    # BatchDispatch mechanics (pack_slices, dispatch_parallel, resolve_slice,
+    # ...) are internal to BATCH_BLOCK; nothing outside Emb calls them with an
+    # explicit receiver.
+    private(*BatchDispatch.instance_methods(false))
 
-  class BatchProxy
-    def initialize(client)
-      @client = client
-      @models = {}
+    def build_batch_loader(client, model, text)
+      # default_value []: an item whose batch failed (fail-closed) resolves to
+      # an empty vector collection instead of nil, so resolver methods like
+      # `loader.sum` do not blow up with NoMethodError-on-nil.
+      BatchLoader.for([client, model, text]).batch(default_value: [], key: BATCH_KEY, &BATCH_BLOCK)
     end
 
-    def [](name)
-      @models[name.to_sym] ||= BatchModelProxy.new(@client, name.to_sym)
+    # Removes every pending item of the batch scope. batch-loader prunes
+    # pending items only after a successful batch block, so failed batches
+    # would otherwise stay queued: retries would re-run the whole batch and
+    # stale items would be re-sent by later batches in the same scope. Guarded
+    # for a nil executor (no batch scope).
+    def clear_batch_pending!
+      key = [BATCH_BLOCK.source_location, BATCH_KEY]
+      BatchLoader::Executor.current&.items_by_block&.delete(key)
     end
 
-    def inspect
-      "#<Emb::BatchProxy client=#{@client.inspect}>"
+    # Fail-closed tail for a failed batch: clear the pending set, then raise
+    # Emb::ServerError carrying the cause and the models/texts/attempts
+    # context. The raise happens inside a rescue of the original error so Ruby
+    # attaches it as `cause` regardless of whether this runs while a rescue is
+    # active (serial path) or from the forcing thread after parallel workers
+    # captured the error (parallel path). `attempts` counts the error's retry
+    # class: connection/protocol errors (the ones redis-client actually
+    # re-sends) report `budget + 1`; operation errors and read timeouts (never
+    # re-sent — a timeout may already have executed server work) report 1. A
+    # pre-send connection refusal is retried across instances by the
+    # connection router before it can reach here as a terminal error.
+    def fail_batch!(error, slice:, budget:)
+      clear_batch_pending!
+      attempts = transient_error?(error) ? budget + 1 : 1
+      models = slice.map { |_, model, _| model }.uniq.join(', ')
+      texts = slice.sum { |_, _, text| Array(text).size }
+      message = "batch failed after #{attempts} attempt(s) " \
+                "(models: #{models}, #{texts} text(s)) #{error.class}: #{error.message}"
+      begin
+        raise error
+      rescue StandardError
+        raise ServerError.new(message, attempts: attempts)
+      end
     end
-  end
 
-  class BatchModelProxy
-    attr_reader :name
+    # How many additional re-sends redis-client performs for transient
+    # failures: the per-client option when set, else the global default.
+    # Normalized to an Integer (redis-client also accepts a delay Array, whose
+    # truthy slots each grant one retry).
+    def retry_budget(client)
+      value = client.reconnect_attempts if client.respond_to?(:reconnect_attempts)
+      value = Emb.configuration.reconnect_attempts if value.nil?
+      return value if value.is_a?(Integer)
 
-    def initialize(client, name)
-      @client = client
-      @name = name
+      value.is_a?(Array) ? value.count(&:itself) : 0
     end
 
-    def [](text, *texts)
-      Emb.build_batch_loader(@client, @name, texts.empty? ? text : [text, *texts])
+    # The error classes redis-client actually re-dispatches under
+    # reconnect_attempts: ConnectionError (connect/transport breaks) and
+    # ProtocolError. ReadTimeoutError is intercepted before the retry loop
+    # (a timed-out command may already have executed server work), so it is
+    # terminal and counts a single attempt. Emb::ShortReplyError is raised
+    # locally by resolve_slice (reply shape wrong on the single send), so it
+    # is likewise terminal and counts one attempt.
+    def transient_error?(error)
+      (error.is_a?(RedisClient::ConnectionError) && !error.is_a?(RedisClient::ReadTimeoutError)) ||
+        (error.is_a?(RedisClient::ProtocolError) && !error.is_a?(ShortReplyError))
     end
 
-    def inspect
-      "#<Emb::BatchModelProxy #{@name}>"
-    end
+    private :clear_batch_pending!, :fail_batch!, :retry_budget, :transient_error?
   end
 end

data/lib/emb/batch_dispatch.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Emb
+  # Share-dispatch mechanics for the deferred batch path: EMB/MULTI wire
+  # shaping, per-slice result mapping, and the bounded concurrent fan-out used
+  # by `lazy: :batch`. Extended into Emb by batch.rb.
+  module BatchDispatch
+    # Sends one chunk share and returns the raw reply entries. Single-model
+    # shares use plain `EMB <model> <text>...` (one inference, model once);
+    # mixed-model shares keep EMB.MULTI per-pair nil semantics. Errors after
+    # the command may have been sent are terminal and propagate so the forcing
+    # thread can fail closed.
+    def dispatch_slice(client, slice)
+      models = slice.map { |_, model, _| model }.uniq
+      args = models.size == 1 ? same_model_args(slice, models.first) : mixed_model_args(slice)
+      Array(client.send_command(*args))
+    end
+
+    def same_model_args(slice, model)
+      ['EMB', model.to_s, *slice.flat_map { |_, _, text| Array(text) }]
+    end
+
+    def mixed_model_args(slice)
+      ['EMB.MULTI', *slice.flat_map { |_, model, text| Array(text).flat_map { |t| [model.to_s, t] } }]
+    end
+
+    # Maps a slice's reply entries onto its items in deferral order. Runs on
+    # the forcing thread (batch-loader's executor is per-thread), so workers
+    # never resolve loaders. A reply shorter than the slice's texts is a
+    # protocol violation: fail the batch via Emb::ShortReplyError (distinct
+    # from a client-raised ProtocolError so it is not counted as a transport
+    # retry).
+    def resolve_slice(loader, slice, results)
+      expected = slice.sum { |_, _, text| Array(text).size }
+      unless results.size >= expected
+        raise ShortReplyError, "expected #{expected} reply entries, got #{results.size}"
+      end
+
+      offset = 0
+      slice.each do |item|
+        _, _, text = item
+        texts = Array(text)
+        values = entry_values(results, offset, texts)
+        offset += texts.size
+
+        # eager Proxy#[] shape: vector for a single text, vectors for many
+        loader.call(item, values)
+      end
+    end
+
+    def entry_values(results, offset, texts)
+      values = results[offset, texts.size].map { |entry| entry&.unpack('e*') }
+      values.size == 1 ? values.first : values
+    end
+
+    # The worker captures failures as outcomes; only the forcing thread
+    # resolves loaders (see resolve_slice).
+    def dispatch_share(client, slice)
+      [:ok, slice, dispatch_slice(client, slice)]
+    rescue StandardError => e
+      [:error, slice, e]
+    end
+
+    # Dispatches all shares concurrently over at most the client's connection
+    # capacity workers, then fails closed on the first terminal error.
+    def dispatch_parallel(client, slices, loader)
+      workers = slices.size.clamp(1, worker_capacity(client))
+      queue = share_queue(slices, workers)
+      outcomes = Array.new(slices.size)
+      run_worker_threads(client, queue, outcomes, workers)
+      resolve_outcomes(client, outcomes, loader)
+    end
+
+    def share_queue(slices, workers)
+      queue = Queue.new
+      slices.each_with_index { |slice, index| queue << [index, slice] }
+      workers.times { queue << nil }
+      queue
+    end
+
+    def worker_capacity(client)
+      return Float::INFINITY unless client.respond_to?(:pools)
+
+      client.pools.sum { |pool| pool.respond_to?(:size) ? pool.size : 1 }
+    end
+
+    def run_worker_threads(client, queue, outcomes, workers)
+      workers.times.map do
+        Thread.new do
+          while (job = queue.pop)
+            index, slice = job
+            outcomes[index] = dispatch_share(client, slice)
+          end
+        end
+      end.each(&:join)
+    end
+
+    # Redis errors fail closed with context (Emb::ServerError, matching the
+    # serial path); non-redis errors are local bugs and re-raise unchanged.
+    def resolve_outcomes(client, outcomes, loader)
+      first_error, failed_slice = collect_outcomes(outcomes, loader)
+      return unless first_error
+
+      raise first_error unless first_error.is_a?(RedisClient::Error)
+
+      fail_batch!(first_error, slice: failed_slice, budget: retry_budget(client))
+    rescue StandardError
+      clear_batch_pending!
+      raise
+    end
+
+    def collect_outcomes(outcomes, loader)
+      first_error = nil
+      failed_slice = nil
+      outcomes.each do |status, slice, result|
+        if status == :ok
+          resolve_slice(loader, slice, result)
+        else
+          first_error ||= result
+          failed_slice ||= slice
+        end
+      end
+      [first_error, failed_slice]
+    end
+
+    # Packs items into shares by accumulated text count so one command stays
+    # within `chunk` texts. An item larger than the chunk goes alone; the
+    # server truncates it with null reply slots, as in the eager path. `used`
+    # carries the running text count of the current slice instead of
+    # re-summing it for every item (O(n) per item would be O(n²)).
+    def pack_slices(items, chunk)
+      slices = []
+      used = 0
+      items.each do |item|
+        size = Array(item[2]).size
+        if slices.empty? || used + size > chunk
+          slices << [item]
+          used = size
+        else
+          slices.last << item
+          used += size
+        end
+      end
+      slices
+    end
+  end
+end

data/lib/emb/batch_scope.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'batch_loader'
+
+module Emb
+  # Runs a block of work and clears the per-thread batch scope afterwards,
+  # even when the block raises. Clearing is unconditional: batch-loader scopes
+  # are thread-global and shared by every client, so a deferred-mode client
+  # (global `lazy` config or a per-call override) inside the block would
+  # otherwise leak cached values and pending loaders into the next request/job.
+  # Under the eager default (`lazy: false`) embed calls never create a scope,
+  # so the clear is a no-op — the middleware is observably inert there.
+  module BatchScope
+    def self.wrap
+      yield
+    ensure
+      BatchLoader::Executor.clear_current
+    end
+  end
+end

data/lib/emb/client.rb

@@ -1,52 +1,41 @@
 # frozen_string_literal: true
 
-require 'connection_pool'
+require_relative 'connection_router'
 require 'redis_client'
 
 module Emb
   class Client
     include Commands
 
-    attr_reader :pool, :batch_size
-
-    def initialize(pool: nil, batch: nil, **redis_options)
+    # Accepts a single redis URL (String) or several (Array of Strings) naming
+    # interchangeable emb instances serving the same model set; each url gets
+    # its own pool of `pool` connections (see ConnectionRouter).
+    def initialize(pool: nil, lazy: nil, **redis_options)
       cfg = Emb.configuration
-      @batch_enabled = batch.nil? ? cfg.batch : batch
+      @lazy_mode = lazy.nil? ? cfg.lazy : validate_lazy!(lazy)
       @batch_size = redis_options.delete(:batch_size) || cfg.batch_size
-      size = pool.nil? ? cfg.pool : pool
       url = extract_url!(redis_options, cfg)
+      # Captured before ConnectionRouter consumes the merged options, so
+      # fail-closed batches can report the retry budget (Emb::ServerError).
       redis_options = merged_redis_options(redis_options, cfg, url)
-
-      @pool = ConnectionPool.new(size: size) do
-        RedisClient.new(url: url, **redis_options)
-      end
-
+      @reconnect_attempts = redis_options.fetch(:reconnect_attempts, cfg.reconnect_attempts)
+      @router = ConnectionRouter.new(pool || cfg.pool, instance_urls(url), redis_options)
       @registry = {}
     end
 
-    def send_command(*args)
-      return @pool.with { |r| r.call(*args) } unless Emb.debug?
+    def send_command(...) = @router.call(...)
 
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      result = @pool.with { |r| r.call(*args) }
-      elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000
+    def pools = @router.pools
 
-      $stdout.puts "[EMB] #{args.map(&:inspect).join(' ')} (#{format('%.2f', elapsed)}ms)"
-
-      result
-    end
+    attr_reader :batch_size, :lazy_mode, :reconnect_attempts
 
     def [](name)
       @registry[name] ||= Proxy.new(self, name.to_sym)
     end
 
-    def batch
-      @batch ||= BatchProxy.new(self)
-    end
+    def lazy? = @lazy_mode != false
 
-    def batch?
-      @batch_enabled
-    end
+    def parallel_batch? = @lazy_mode == :batch
 
     # Live view of the server's runtime configuration (CONFIG GET/SET).
     def config
@@ -103,9 +92,23 @@ module Emb
 
     private
 
+    def validate_lazy!(value)
+      unless Configuration::LAZY_MODES.include?(value)
+        raise ArgumentError, "lazy must be false, :multi, or :batch (got #{value.inspect})"
+      end
+
+      value
+    end
+
+    def instance_urls(url)
+      raise ArgumentError, 'url array must not be empty' if url.is_a?(Array) && url.empty?
+
+      url.nil? ? [nil] : Array(url)
+    end
+
     def merged_redis_options(opts, cfg, url)
       defaults = cfg.to_h
-      keys = defaults.keys - %i[url pool batch batch_size]
+      keys = defaults.keys - %i[url pool lazy batch_size]
       keys -= %i[host port] if url
 
       keys.each do |key|

data/lib/emb/configuration.rb

@@ -3,25 +3,51 @@
 module Emb
   class Configuration
     OPTIONS = %i[
-      host port url pool batch batch_size driver protocol
+      host port url pool lazy batch_size driver protocol
       connect_timeout read_timeout write_timeout reconnect_attempts
     ].freeze
 
+    # Execution modes for embed calls. false = eager (default, one EMB round
+    # trip per call); :multi = defer and coalesce into EMB.MULTI, serial;
+    # :batch = defer and execute chunk shares concurrently. Mutually exclusive
+    # by construction.
+    LAZY_MODES = [false, :multi, :batch].freeze
+
     attr_accessor(*OPTIONS)
 
+    def lazy=(value)
+      unless LAZY_MODES.include?(value)
+        raise ArgumentError, "lazy must be false, :multi, or :batch (got #{value.inspect})"
+      end
+
+      @lazy = value
+    end
+
     def initialize
       self.host = 'localhost'
       self.port = 6379
       self.url = nil
       self.pool = 5
-      self.batch = true
+      self.lazy = false
       self.batch_size = 512
       self.driver = nil
       self.protocol = 2
       self.connect_timeout = nil
-      self.read_timeout = nil
-      self.write_timeout = nil
-      self.reconnect_attempts = 3
+      # Read/write timeouts are explicit, NOT nil: nil forwards nothing and
+      # redis-client silently applies its 1.0s default, which makes 512-pair
+      # EMB.MULTI batches fail under load. 10s covers worst-case inference on
+      # shared CPUs; scale up if you raise batch_size.
+      self.read_timeout = 10
+      self.write_timeout = 10
+      # 0 = default: a failing batch fails closed after one attempt and raises
+      # Emb::ServerError. Set > 0 to opt into bounded re-sends: redis-client
+      # retries connection/protocol failures (never read timeouts) up to that
+      # many extra times — EMB.MULTI is not idempotent, so each re-send
+      # duplicates inference — and the batch still terminates in
+      # Emb::ServerError. An Array of per-retry delays is also accepted (one
+      # retry per entry). Operation errors (server error replies) are never
+      # retried.
+      self.reconnect_attempts = 0
     end
 
     def to_h

data/lib/emb/connection_router.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'round_robin_pool'
+require 'redis_client'
+
+module Emb
+  # Owns a client's instance fan-out: one RoundRobinPool per configured url,
+  # instance-level round-robin on top of each pool's connection rotation, and
+  # the pre-send retry across instances.
+  #
+  # Retry is deliberately limited to PRESEND_CONNECTION_ERROR: a connection
+  # that was never established means the command was not written, so moving it
+  # to another instance is safe. Errors after a command may have been sent
+  # (timeouts, mid-flight connection loss) are never re-dispatched — retrying
+  # them would duplicate inference on the server.
+  class ConnectionRouter
+    # Captured at load so `rescue` keeps working when tests or apps replace the
+    # RedisClient constant (stub_const) — a runtime constant lookup in the
+    # rescue clause would otherwise resolve against the replacement.
+    PRESEND_CONNECTION_ERROR = RedisClient::CannotConnectError
+
+    attr_reader :pools
+
+    def initialize(size, urls, redis_options)
+      @pools = urls.map do |url|
+        RoundRobinPool.new(size) do
+          RedisClient.new(url: url, **redis_options)
+        end
+      end
+      @next_instance = 0
+      @instance_mutex = Mutex.new
+    end
+
+    def call(*args)
+      attempts = @pools.size
+      idx = pick_instance
+      last_error = nil
+      attempts.times do
+        return perform_command(@pools[idx], args)
+      rescue PRESEND_CONNECTION_ERROR => e
+        last_error = e
+        idx = (idx + 1) % @pools.size if @pools.size > 1
+      end
+      raise last_error
+    end
+
+    private
+
+    def pick_instance
+      return 0 if @pools.size == 1
+
+      @instance_mutex.synchronize do
+        idx = @next_instance % @pools.size
+        @next_instance += 1
+        idx
+      end
+    end
+
+    def perform_command(pool, args)
+      debug = Emb.debug?
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC) if debug
+      result = pool.with { |r| r.call(*args) }
+      log_command(args, started) if debug
+      result
+    end
+
+    def log_command(args, started)
+      elapsed = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+      $stdout.puts "[EMB] #{args.map(&:inspect).join(' ')} (#{format('%.2f', elapsed)}ms)"
+    end
+  end
+end

data/lib/emb/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Emb
+  # Raised when an EMB.MULTI batch fails — after redis-client exhausted its
+  # configured re-sends (`reconnect_attempts`) on a transient error, or on the
+  # first attempt for an operation error (server error reply) or the default
+  # `reconnect_attempts: 0` configuration. The underlying redis error is
+  # preserved as `cause`; `attempts` counts the wire sends that were made.
+  class ServerError < StandardError
+    attr_reader :attempts
+
+    def initialize(message, attempts: 1)
+      super(message)
+      @attempts = attempts
+    end
+  end
+end

data/lib/emb/job_middleware.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'batch_loader'
+require_relative 'batch_scope'
+
+module Emb
+  # Job middleware: clears the per-thread batch scope after each job execution,
+  # even when the job raises. Registered as a Sidekiq/Shoryuken server
+  # middleware (positional args differ per framework and are unused) and used by
+  # the ActiveJob perform callback.
+  class JobMiddleware
+    def call(*_args, &)
+      BatchScope.wrap(&)
+    end
+  end
+end

data/lib/emb/middleware.rb

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
 require 'batch_loader'
+require_relative 'batch_scope'
 
 module Emb
-  # Rack middleware that clears the per-thread batch scope at the end of each
-  # request, bounding cache growth in long-lived request threads. The scope is
-  # cleared even when the app raises; a fresh scope starts with the next request.
+  # Rack middleware: clears the per-thread batch scope after each request,
+  # even when the app raises.
   class Middleware
     def initialize(app)
       @app = app
     end
 
     def call(env)
-      @app.call(env)
-    ensure
-      BatchLoader::Executor.clear_current
+      BatchScope.wrap { @app.call(env) }
     end
   end
 end

data/lib/emb/proxy.rb

@@ -10,7 +10,7 @@ module Emb
     end
 
     def [](text, *texts)
-      return Emb.build_batch_loader(@client, @name, texts.empty? ? text : [text, *texts]) if @client.batch?
+      return Emb.build_batch_loader(@client, @name, texts.empty? ? text : [text, *texts]) if @client.lazy?
 
       set = Array(@client.send_command('EMB', @name.to_s, text, *texts))
       result = set.map { |entry| entry.unpack('e*') }

data/lib/emb/railtie.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+if defined?(Rails::Railtie)
+  require_relative '../emb'
+
+  module Emb
+    # Rails integration, loaded by emb.rb when Rails is present.
+    #
+    #   config.emb.middleware = false      # skip Emb::Middleware in the stack
+    #   config.emb.job_middleware = false  # skip job-scope protection
+    class Railtie < Rails::Railtie
+      config.emb = ActiveSupport::OrderedOptions.new
+      config.emb.middleware = true
+      config.emb.job_middleware = true
+
+      initializer 'emb.middleware' do |app|
+        next if config.emb.middleware == false
+        next if app.middleware.include?(Emb::Middleware)
+
+        app.middleware.use Emb::Middleware
+      end
+
+      config.after_initialize do
+        next if config.emb.job_middleware == false
+
+        ActiveSupport.on_load(:active_job) do |base|
+          base.around_perform { |_job, block| Emb::BatchScope.wrap { block.call } }
+        end
+
+        if defined?(Sidekiq)
+          Sidekiq.configure_server do |sidekiq_config|
+            sidekiq_config.server_middleware { |chain| chain.add Emb::JobMiddleware }
+          end
+        end
+
+        if defined?(Sidekiq::Testing)
+          # Testing modes use their own middleware chain.
+          Sidekiq::Testing.server_middleware { |chain| chain.add Emb::JobMiddleware }
+        end
+
+        if defined?(Shoryuken)
+          Shoryuken.configure_server do |shoryuken_config|
+            shoryuken_config.server_middleware { |chain| chain.add Emb::JobMiddleware }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/emb/round_robin_pool.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Emb
+  # A thread-safe pool of N RedisClient connections with round-robin selection.
+  # Behind connection-level load balancers (AWS Service Connect, an NLB, or an
+  # Envoy TCP proxy) each keep-alive connection is pinned to one upstream
+  # instance, so rotating commands across the pool spreads traffic across every
+  # instance — even single-threaded at zero concurrency. Connections are created
+  # up front but connect lazily on first use.
+  #
+  # Two behaviors deliberately match the connection_pool gem it replaces: a
+  # nested `with` from the same thread re-enters the held connection, and after
+  # `fork` (Puma preload_app, unicorn, resque) the pool closes inherited sockets
+  # and rebuilds its mutexes in the child so parent and child never share a
+  # connection.
+  class RoundRobinPool
+    # Pools are tracked only to reset them in forked children. WeakMap so a
+    # pool is reclaimed together with its client.
+    INSTANCES = Process.respond_to?(:fork) ? ObjectSpace::WeakMap.new : nil
+    private_constant :INSTANCES
+
+    THREAD_KEY = :emb_round_robin_pool_held
+    private_constant :THREAD_KEY
+
+    attr_reader :size, :connections
+
+    def self.after_fork
+      INSTANCES&.each_value(&:reload_after_fork!)
+    end
+
+    def initialize(size, &)
+      raise ArgumentError, "pool size must be >= 1 (got #{size})" if size < 1
+
+      @size = size
+      @connections = Array.new(size, &)
+      @locks = Array.new(size) { Mutex.new }
+      @next = 0
+      @index_mutex = Mutex.new
+      INSTANCES&.[]=(self, self)
+    end
+
+    # Yields the next connection in rotation order. Safe from multiple threads:
+    # up to `size` commands run in parallel, each on its own connection. A
+    # nested `with` from the same thread re-enters the connection this pool
+    # already holds without re-locking; other pools are unaffected.
+    def with(&)
+      held = Thread.current[THREAD_KEY]
+      if held&.key?(self)
+        yield @connections[held[self]]
+      else
+        take(held, &)
+      end
+    end
+
+    # Child side of after_fork(): drop inherited sockets and sync state.
+    def reload_after_fork!
+      @connections.each { |conn| conn.close if conn.respond_to?(:close) }
+      @locks = Array.new(@size) { Mutex.new }
+      @next = 0
+      @index_mutex = Mutex.new
+    end
+
+    if Process.respond_to?(:fork)
+      # Hooks Process._fork (MRI 3.1+) so registered pools reset in the child.
+      module ForkTracker
+        def _fork
+          pid = super
+          RoundRobinPool.after_fork if pid.zero?
+          pid
+        end
+      end
+      Process.singleton_class.prepend(ForkTracker)
+    end
+
+    private
+
+    # Acquires the next connection, records it as held by this thread/pool, and
+    # releases both on exit — even when the block raises.
+    def take(held)
+      idx, connection = pick
+      held ||= {}
+      Thread.current[THREAD_KEY] = held
+      held[self] = idx
+      begin
+        @locks[idx].synchronize { yield connection }
+      ensure
+        held.delete(self)
+        Thread.current[THREAD_KEY] = nil if held.empty?
+      end
+    end
+
+    def pick
+      @index_mutex.synchronize do
+        idx = @next % @size
+        @next += 1
+        [idx, @connections[idx]]
+      end
+    end
+  end
+end

data/lib/emb.rb

@@ -2,13 +2,17 @@
 
 require_relative 'emb/version'
 require_relative 'emb/configuration'
+require_relative 'emb/errors'
 require_relative 'emb/commands'
 require_relative 'emb/runtime_config'
 require_relative 'emb/client'
 require_relative 'emb/proxy'
+require_relative 'emb/batch_scope'
+require_relative 'emb/middleware'
+require_relative 'emb/job_middleware'
 require_relative 'emb/multi'
 require_relative 'emb/batch'
-require_relative 'emb/middleware'
+require_relative 'emb/railtie' if defined?(Rails::Railtie)
 
 module Emb
   class << self
@@ -28,7 +32,6 @@ module Emb
     end
 
     def [](name)    = default_client[name]
-    def batch       = default_client.batch
     def models      = default_client.models
     def info(name)  = default_client.info(name)
     def stats       = default_client.stats

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: emb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0.pre1
 platform: ruby
 authors:
 - elcuervo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 2026-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: batch-loader
@@ -24,20 +24,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: connection_pool
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: redis-client
   requirement: !ruby/object:Gem::Requirement
@@ -63,12 +49,19 @@ files:
 - README.md
 - lib/emb.rb
 - lib/emb/batch.rb
+- lib/emb/batch_dispatch.rb
+- lib/emb/batch_scope.rb
 - lib/emb/client.rb
 - lib/emb/commands.rb
 - lib/emb/configuration.rb
+- lib/emb/connection_router.rb
+- lib/emb/errors.rb
+- lib/emb/job_middleware.rb
 - lib/emb/middleware.rb
 - lib/emb/multi.rb
 - lib/emb/proxy.rb
+- lib/emb/railtie.rb
+- lib/emb/round_robin_pool.rb
 - lib/emb/runtime_config.rb
 - lib/emb/version.rb
 homepage: https://github.com/elcuervo/emb