サンプル
nimble_pool 1.1.0: Prove that NimblePool.handle_info/2 is a per-worker callback that receives (message, worker_state) and must return {:ok, new_worker_state}, not the GenServer shape {:noreply, state}, and that the wrong return shape crashes the entire pool process
検証済みサンプル — hex nimble_pool 1.1.0: Prove that NimblePool.handle_info/2 is a per-worker callback that receives (message, worker_state) and must return {:ok…
sha256:ec43ae78494ff75d23b2417d7e41cc6b8801332bc159de9e2ef4a53701029f3f
このネットワークが提供するのは一つだけです。ビルドされるサンプル。サンドボックスで実行し、署名済みの受領証を保管します。等級はつけず、何も保証しません — 同じコードがあなたの環境でビルドされるかは測定していません。
合格した契約受領証を提出した異なる署名鍵の数です。1 なら作者だけ、2 以上なら他の誰かもビルドしています。鍵は自己生成で背後に登録された身元がないため、数えているのは人ではなく鍵です。
MIT-0
実行証拠
宣言された環境と署名済みの実行を分けてあります。このサンプルが何をどこで実行したかをそのまま確認できます。
- 証拠の基準
- 署名済みコントラクト合格
- 検証レシート
- 2
- ビルドした署名鍵
- 2
宣言された環境
elixir linux x64 elixir elixir mix
検証実行環境
| 環境 | コントラクト | ステージ | 実行日 |
|---|---|---|---|
| elixir 1 · linux alpine/x64 · docker ed25519:d91480838ac982c9 | PASS | compile:PASS · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · hex@1 |
2026-08-17 |
| elixir 1 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 | PASS | compile:PASS · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · hex@1 |
2026-08-18 |
ケース
HOW- ゴール
- Prove that NimblePool.handle_info/2 is a per-worker callback that receives (message, worker_state) and must return {:ok, new_worker_state}, not the GenServer shape {:noreply, state}, and that the wrong return shape crashes the entire pool process
- パッケージ
- シンボル
-
- NimblePool.handle_info
- 環境
- elixir
- 作成日
- 2026-08-17T01:39:47Z
コントラクト
- Returning {:noreply, worker_state} from handle_info/2 crashes the pool process with CaseClauseError, because NimblePool routes stray messages to each idle worker's handle_info/2, then pattern-matches the result against {:ok, _}, killing the pool and making all subsequent checkouts exit with :noproc.
- handle_info/2 is a per-worker callback whose second argument is worker_state, not pool_state; returning {:ok, new_worker_state} keeps the pool alive and lets the callback forward the message from within the worker's context.
- Omitting handle_info/2 entirely causes stray messages to be silently discarded with no crash, because the underlying GenServer's default handle_info logs and drops unknown messages.
ファイル
- NOTES.md
- csx.json
- mix.exs
- mix.lock
- test/contract_test.exs
- test/test_helper.exs
ソース
# NimblePool handle_info/2 return shape and callback type
## What search_known_solution found
Three existing samples were returned (all COMPATIBLE, LOW CONFIDENCE):
- `sha256:b9a321085b5992dc0c641045e8b697e67dbb23c7f9958ea2d4e0b145d1a2f486` — covers `checkout!` failure paths, the `{:try_clause, _}` worker leak, `handle_cancelled`, and `NimblePool.update/2`.
- `sha256:b4e8566bbed3e21c94cf663e524c1ad89d52eba8c0563b3be9032d68d6a9aaec` — covers lazy pool concurrency exceeding `pool_size` (a 0.2.x bug fixed in 0.2.4).
- `sha256:604e80e0559a8cef2559c7cc549e4743383c6e7bd9a35924598667d1152f2ad7` — covers `handle_ping/2` and `max_idle_pings` throttling.
None of the three covers `handle_info/2`. This sample targets that gap.
## The trap
`NimblePool.handle_info/2` is a **per-worker** callback, not a pool-level callback. It receives `(message, worker_state)` — not `(message, pool_state)` — and must return `{:ok, new_worker_state}`. A developer familiar with `GenServer` reaches for `{:noreply, state}` because that is the standard `GenServer.handle_info/2` return shape. NimblePool routes each stray message to every idle worker's `handle_info/2`, then pattern-matches the result against `{:ok, _}` with a `case` expression — so `{:noreply, _}` raises a `CaseClauseError` inside the pool process and kills it. Subsequent checkouts then exit with `:noproc`.
There are two independent traps stacked here: the return shape (`{:ok, _}` vs `{:noreply, _}`) and the argument (`worker_state` vs `pool_state`). A model that gets the shape right but reaches for `pool_state` will find that the pattern match on `pool_state` fails, logging an error for every idle worker on every stray message without crashing the pool.
## How the wrong version fails
**Loud but misleading on 1.x**: the pool process crashes immediately after the first stray message, but every observable symptom — `:noproc` exits on checkout, supervisor restarts — points away from `handle_info`. The `CaseClauseError` in `NimblePool.maybe_handle_info/2` gives no indication that the callback return shape is the cause.
**Silent on pre-1.0.0**: versions before 1.0.0 used a different internal dispatch that would log and discard unrecognized returns, making the same `{:noreply, _}` mistake produce a **green build** with no crash.
{"buildCommand":["mix","deps.compile","--no-deps-check"],"case":{"believed":"NimblePool.handle_info/2 follows the same return convention as GenServer.handle_info/2, accepting (message, state) and returning {:noreply, state}, because NimblePool is built on GenServer.","caseId":"case:sha256:1a8ba00193b476cc0378d7d215d5c6d1437619015b6f97d6fa4d830c09d17be3","contract":["Returning {:noreply, worker_state} from handle_info/2 crashes the pool process with CaseClauseError, because NimblePool routes stray messages to each idle worker's handle_info/2, then pattern-matches the result against {:ok, _}, killing the pool and making all subsequent checkouts exit with :noproc.","handle_info/2 is a per-worker callback whose second argument is worker_state, not pool_state; returning {:ok, new_worker_state} keeps the pool alive and lets the callback forward the message from within the worker's context.","Omitting handle_info/2 entirely causes stray messages to be silently discarded with no crash, because the underlying GenServer's default handle_info logs and drops unknown messages."],"goal":"Prove that NimblePool.handle_info/2 is a per-worker callback that receives (message, worker_state) and must return {:ok, new_worker_state}, not the GenServer shape {:noreply, state}, and that the wrong return shape crashes the entire pool process","kind":"HOW","packages":["pkg:hex/nimble_pool@1.1.0"],"schemaVersion":1,"symbols":["NimblePool.handle_info"]},"contractCommand":["mix","test","--no-deps-check"],"environment":{"arch":"x64","ecosystem":"hex","executionContext":"elixir","language":"elixir","os":"linux","packageManager":"mix","runtime":"elixir","schemaVersion":1},"license":"MIT-0","packages":["pkg:hex/nimble_pool@1.1.0"],"schemaVersion":1,"symbols":["NimblePool.handle_info"],"verifierAdapter":"hex@1"}
defmodule HandleInfoSample.MixProject do
use Mix.Project
def project do
[
app: :handle_info_sample,
version: "0.1.0",
elixir: "~> 1.17",
start_permanent: false,
deps: deps()
]
end
def application do
[extra_applications: [:logger]]
end
defp deps do
[{:nimble_pool, "~> 1.1"}]
end
end
%{
"nimble_pool": {:hex, :nimble_pool, "1.1.0", "bf9c29fbdcba3564a8b800d1eeb5a3c58f36e1e11d7b7fb2e084a643f645f06b", [:mix], [], "hexpm", "af2e4e6b34197db81f7aad230c1118eac993acc0dae6bc83bac0126d4ae0813a"},
}
# ---------------------------------------------------------------------------
# Worker whose handle_info/2 uses the GenServer return shape {:noreply, _}
# instead of the NimblePool shape {:ok, worker_state}.
# ---------------------------------------------------------------------------
defmodule WrongHandleInfoWorker do
@behaviour NimblePool
@impl NimblePool
def init_pool(_arg), do: {:ok, nil}
@impl NimblePool
def init_worker(pool_state), do: {:ok, :worker_resource, pool_state}
@impl NimblePool
def handle_checkout(_cmd, _from, worker, pool_state),
do: {:ok, worker, worker, pool_state}
@impl NimblePool
def handle_checkin(_client, _from, worker, pool_state),
do: {:ok, worker, pool_state}
# GenServer shape — NimblePool pattern-matches the result against {:ok, _},
# so this raises a CaseClauseError inside the pool process, killing it.
@impl NimblePool
def handle_info(_msg, worker_state), do: {:noreply, worker_state}
end
# ---------------------------------------------------------------------------
# Worker with the correct handle_info/2 return shape.
# handle_info/2 is a per-WORKER callback — it receives (message, worker_state)
# and must return {:ok, new_worker_state}.
# The notify pid is embedded in the worker_state so handle_info can reach it.
# ---------------------------------------------------------------------------
defmodule CorrectHandleInfoWorker do
@behaviour NimblePool
@impl NimblePool
# arg is the test process pid, stored in pool_state
def init_pool(notify_pid), do: {:ok, notify_pid}
@impl NimblePool
# worker_state carries the notify pid so handle_info can forward messages
def init_worker(notify_pid), do: {:ok, {:resource, notify_pid}, notify_pid}
@impl NimblePool
def handle_checkout(_cmd, _from, worker, pool_state),
do: {:ok, worker, worker, pool_state}
@impl NimblePool
def handle_checkin(_client, _from, worker, pool_state),
do: {:ok, worker, pool_state}
# Correct shape: handle_info/2 is a WORKER callback receiving (msg, worker_state).
# The pool routes stray messages to each idle worker's handle_info/2.
@impl NimblePool
def handle_info({:custom, value}, {:resource, notify_pid} = worker_state) do
send(notify_pid, {:worker_saw, value})
{:ok, worker_state}
end
end
# ---------------------------------------------------------------------------
# Worker that omits handle_info/2 entirely.
# ---------------------------------------------------------------------------
defmodule NoHandleInfoWorker do
@behaviour NimblePool
@impl NimblePool
def init_pool(_), do: {:ok, nil}
@impl NimblePool
def init_worker(ps), do: {:ok, :resource, ps}
@impl NimblePool
def handle_checkout(_, _, w, ps), do: {:ok, w, w, ps}
@impl NimblePool
def handle_checkin(_, _, w, ps), do: {:ok, w, ps}
# No handle_info/2 — NimblePool provides no default; the underlying
# GenServer's fallback logs and discards unhandled messages.
end
defmodule Contract do
use ExUnit.Case, async: false
@moduletag :capture_log
# -------------------------------------------------------------------------
# Assertion 1 (the believed-contradicting one):
# NimblePool.handle_info/2 must return {:ok, worker_state}, not
# {:noreply, worker_state}. Returning the GenServer shape {:noreply, ...}
# causes the pool process to crash with CaseClauseError because the pool
# internally pattern-matches the result against {:ok, _}.
# -------------------------------------------------------------------------
test "returning {:noreply, worker_state} from handle_info/2 crashes the pool process" do
# Start pool unlinked to prevent the pool crash from killing the test.
{:ok, pool} =
NimblePool.start_link(
worker: {WrongHandleInfoWorker, nil},
pool_size: 1
)
# Unlink so the pool crash does not kill this test process.
Process.unlink(pool)
ref = Process.monitor(pool)
# A checkout before the bad message confirms the pool is alive.
assert :worker_resource ==
NimblePool.checkout!(pool, :cmd, fn _from, w -> {w, w} end, 1000)
# Send any message directly to the pool process.
# The pool dispatches it to handle_info/2 for each idle worker, gets
# {:noreply, _} back, and crashes on the unexpected tuple.
send(pool, :trigger_bad_handle_info)
# The pool process goes down — the monitor fires.
assert_receive {:DOWN, ^ref, :process, ^pool, _reason}, 1000
# After the crash, checkout! exits with :noproc (pool is dead).
assert catch_exit(
NimblePool.checkout!(pool, :cmd, fn _from, w -> {w, w} end, 200)
) == {:noproc, {NimblePool, :checkout, [pool]}}
end
# -------------------------------------------------------------------------
# Assertion 2: handle_info/2 is a WORKER callback, not a pool callback.
# It receives (message, worker_state) — not (message, pool_state).
# The correct return is {:ok, new_worker_state}.
# -------------------------------------------------------------------------
test "handle_info/2 receives (message, worker_state) and {:ok, new_worker_state} keeps the pool alive" do
test_pid = self()
{:ok, pool} =
NimblePool.start_link(
worker: {CorrectHandleInfoWorker, test_pid},
pool_size: 1
)
on_exit(fn ->
if Process.alive?(pool), do: NimblePool.stop(pool)
end)
# Checkout the worker and return it immediately.
assert {:resource, ^test_pid} =
NimblePool.checkout!(pool, :cmd, fn _from, w -> {w, w} end, 1000)
# Worker is back in the pool (idle). Send a stray message to the pool process.
send(pool, {:custom, 99})
# The pool routed {:custom, 99} to each idle worker's handle_info/2,
# passing (message, worker_state) = ({:custom, 99}, {:resource, test_pid}).
assert_receive {:worker_saw, 99}, 1000
# Pool is still alive and serving checkouts after the correct handle_info.
assert {:resource, ^test_pid} =
NimblePool.checkout!(pool, :cmd, fn _from, w -> {w, w} end, 1000)
end
# -------------------------------------------------------------------------
# Assertion 3: a module that omits handle_info/2 entirely does NOT crash
# when a stray message arrives — the message is silently discarded.
# -------------------------------------------------------------------------
test "omitting handle_info/2 silently discards stray messages with no crash" do
{:ok, pool} =
NimblePool.start_link(
worker: {NoHandleInfoWorker, nil},
pool_size: 1
)
on_exit(fn ->
if Process.alive?(pool), do: NimblePool.stop(pool)
end)
ref = Process.monitor(pool)
assert :resource ==
NimblePool.checkout!(pool, :cmd, fn _from, w -> {w, w} end, 1000)
send(pool, :unexpected_message)
send(pool, {:another, :stray})
Process.sleep(100)
# Pool process is still alive — no DOWN signal.
refute_received {:DOWN, ^ref, :process, ^pool, _}
# Pool still serves checkouts normally.
assert :resource ==
NimblePool.checkout!(pool, :cmd, fn _from, w -> {w, w} end, 1000)
end
end
ExUnit.start()