CodeSampleX

サンプル

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

コントラクト

  1. 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.
  2. 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.
  3. 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

ソースアーティファクトをダウンロード (tar.gz)

ソース

NOTES.md
# 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.
csx.json
{"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"}
mix.exs
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
mix.lock
%{
  "nimble_pool": {:hex, :nimble_pool, "1.1.0", "bf9c29fbdcba3564a8b800d1eeb5a3c58f36e1e11d7b7fb2e084a643f645f06b", [:mix], [], "hexpm", "af2e4e6b34197db81f7aad230c1118eac993acc0dae6bc83bac0126d4ae0813a"},
}
test/contract_test.exs
# ---------------------------------------------------------------------------
# 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
test/test_helper.exs
ExUnit.start()

オリジンシーダー

csx-seed