Changelog

Copy Markdown View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Fixed

  • CI: the three telemetry_test.exs tests no longer flake on 2-vCPU runners. Test-only change — nothing in lib/ moved, so the published package is unaffected. Two causes, both fixed:
    • The pool-scaling tests pointed their pools at a closed port. Those tests only assert size bookkeeping, but a pool that cannot connect leaves every worker (up to 20, resized repeatedly) in a ~100ms reconnect loop, and pools from consecutive tests overlap while tearing down. The resulting background churn starved the telemetry tests' deadlines. They now run against a live TestServer listener, so workers connect once and go idle, and teardown stops the pool before the listener.
    • The telemetry deadlines were ceilings of 1–5s on events that land in single-digit milliseconds. On a shared runner an unlucky scheduling window blows them for no good reason, so they were widened; a generous ceiling costs a fast machine nothing. Worker.status/1 is a GenServer.call, and its timeout exited and failed the test outright rather than reporting "not yet" — polling now treats a timed-out call as an unknown status and retries.

[0.5.2] - 2026-08-06

Security

  • cowlib 2.18.0 → 2.19.0 fixes CVE-2026-59248 (HIGH): unbounded HPACK/QPACK prefixed-integer decoding allowed a memory-exhaustion DoS. This one is squarely in the pool's path — gRPC is HTTP/2, so gun decodes HPACK from whatever the server sends, and a malicious or compromised endpoint could exhaust client memory. Upgrading is recommended for all users.
  • cowboy 2.17.0 → 2.18.0 fixes CVE-2026-65624 (MEDIUM) (max_headers bypass via duplicate header names). Test-only: cowboy backs the h2c test server and is not a runtime dependency.
  • Still open upstream, and why it is not actionable here: cowlib carries two advisories with no fixed release — CVE-2026-43966 (MEDIUM, HTTP response splitting via non-VCHAR bytes in cow_http_struct_hd:escape_string/2) and CVE-2026-43969 (LOW, cookie request-header injection). Both are mitigated a layer up: gun ≥ 2.4.0 rejects CR/LF in header values by default (invalid_request_headers), and the lock has pinned gun 2.4.1 since 0.5.1. Note that scanners reading the GitHub advisory will flag any gun release as vulnerable to CVE-2026-43966 — that record lists gun's patched version as "2.16.0", a cowboy version number, so no gun release can satisfy it. The ERLEF CNA record (the issuing CNA) is the accurate one: "applications using gun 2.4.0 or later are protected".

Changed

  • grpc 1.0.2 → 1.0.3 (and grpc_core to match), plus ranch 2.2.0 → 2.2.1.
  • gun stays at 2.4.1, which is the latest release the pool can use: grpc 1.0.3 still requires gun ~> 2.4.0, so gun 2.5.0 is out of range on grpc 1.x. Confirmed by resolution, not by inspection — mix deps.update gun leaves 2.4.1 in place.
  • Raised the :gun requirement from ~> 2.2 to ~> 2.4 (also updated in the README install snippet). gun 2.4.0 is where invalid_request_headers landed — the validation that mitigates CVE-2026-43966, which has no cowlib-side fix — so the floor is a security boundary rather than housekeeping. Consumers on grpc 1.0 were already resolving to 2.4.x because grpc requires gun ~> 2.4.0; this makes the real floor explicit and stops a stale lock from silently sitting on 2.2.x.
  • Typespec: grpc 1.0.3 removed the @type t from GRPC.Channel, leaving the bare struct with no named type to reference. GrpcConnectionPool.Pool now publishes its own @type channel :: %GRPC.Channel{}, and Pool.get_channel/1 specs {:ok, channel()}. Runtime behaviour is unchanged; only the spec's spelling moved.
  • Dialyzer filters removed, as designed. grpc 1.0.3 fixed the finalize_connection/2 success-typing regression that 1.0.2 introduced, so both entries in .dialyzer_ignore.exs went unused and list_unused_filters: true failed the build — exactly the expiry the 0.5.1 notes described. The list is now empty and dialyzer is clean with no suppressions.

Fixed

  • Test suite no longer depends on port 50051 being closed. The two pool-scaling test files hardcoded port: 50_051 for pools whose workers are never meant to connect. On any machine where that port is blackholed rather than closed — a Docker/OrbStack forward, VPN, or packet filter that drops the SYN instead of refusing it — every connect burned the full 3s timeout instead of failing in ~0ms, and the resulting backoff churn starved the 5s deadlines in telemetry_test.exs, failing three unrelated tests. Ports now come from a new TestServer.dead_port/0, which binds port 0 and closes it so the connect is genuinely refused. Full suite: 16.5s → 2.2s, green across seeds, and 78/78 with mix test --include emulator against a live Pub/Sub emulator.

[0.5.1] - 2026-07-26

Fixed

  • Docs: documented the one supervision-tree change grpc 1.0 requires — a leftover {GRPC.Client.Supervisor, []} child spec now crashes at boot, because grpc 1.0 removed that module and starts a DynamicSupervisor under the same name itself. Consumers were reading the crash as an unfixable version conflict and pinning grpc back to 0.11.x. See the install note and the Troubleshooting entry in the README, plus the 0.5.0 upgrade notes below.
  • mix docs is warning-free again: qualified GrpcConnectionPool.Config.production/1 and removed the autolink to the (deliberately) nonexistent execute/1 in the 0.4.0 entries.

Changed

  • CHANGELOG.md is now shipped in the Hex package (it was already a docs extra).
  • Dialyzer filters (.dialyzer_ignore.exs, wired up via ignore_warnings + list_unused_filters): grpc 1.0.2 extracted finalize_connection/2 out of GRPC.Client.Connection.connect/2, and analyzed alone that function's success typing rejects the still-nil virtual channel connect/2 passes it. Dialyzer concludes the call never returns, narrows GRPC.Stub.connect/2 to {:error, _}, and then flags the pool's success branch and monitor_connection/1 as dead code. Both warnings are false — the suite connects for real — so they are filtered with an explanation. A stale filter is a hard error, so the suppression expires when grpc fixes the typing.
  • Dependencies refreshed (mix deps.update --all): grpc 1.0.1 → 1.0.2 and gun 2.2.0 → 2.4.1 — grpc 1.0.1 constrained gun to ~> 2.2.0, and 1.0.2 relaxes it, so gun could finally move. Test/dev only: cowboy 2.14.2 → 2.17.0, cowlib 2.16.0 → 2.18.0, finch 0.20.0 → 0.23.0, mint 1.9.0 → 1.9.3, hpax 1.0.3 → 1.0.4, jose 1.11.10 → 1.11.12, plus erlex, earmark_parser, and makeup patches. Full suite green on Elixir 1.20 / OTP 29, including the :emulator integration tests.

[0.5.0] - 2026-06-26

Changed

  • grpc 1.0 support. Bumped grpc to ~> 1.0 (was 0.11.5). grpc 1.0 is client-only (GRPC.Server was removed) and makes :gun optional, so gun ~> 2.2 is now a direct dependency (the pool uses the default Gun adapter). :public_key and :ssl are declared in extra_applications (used by Config).
  • BREAKING (telemetry): the [:grpc_connection_pool, :channel, :gun_down] and [:grpc_connection_pool, :channel, :gun_error] events were removed. Under grpc 1.0 the Gun adapter owns the socket in its own process, so those gun messages never reach the pool. A single adapter-agnostic [:grpc_connection_pool, :channel, :connection_down] event (metadata pool_name, reason) is emitted instead. :disconnected and :reconnect_scheduled are unchanged. Consumers handling :gun_down/:gun_error should switch to :connection_down (or :disconnected).
  • Disconnect detection reworked. grpc 1.0's Gun adapter keeps the live connection inside its own ConnectionProcess, which lingers as a zombie after a drop, so the old gun_down/gun_error message handlers were dead code. The worker now monitors the inner gun process and pairs it with adapter_opts: [retry: 0] so gun fails fast on a drop and the pool's own Backoff governs reconnection. This also restores fast-fail connects (a dead endpoint now errors in ~0ms instead of stalling ~5s per attempt).

Upgrade notes

  • Remove {GRPC.Client.Supervisor, []} from your supervision tree. grpc 1.0 deleted that module; the name is now just the registered name of a DynamicSupervisor that grpc starts itself (in GRPC.Client.Application). Keeping the old child spec (which pre-1.0 grpc's README recommended) crashes at boot with "The module GRPC.Client.Supervisor was given as a child to a supervisor but it does not exist". Nothing replaces it — no manual start is needed in applications or in test_helper.exs. This is the only supervision-tree change required to move a grpc_connection_pool consumer from grpc 0.11.x to 1.0.

Fixed

  • License declaration now correctly reports Apache-2.0 (matching the committed LICENSE file) instead of MIT in mix.exs and README — resolves the Hex.pm mismatch (#6).

[0.4.0] - 2026-06-01

Changed

  • Security: production configs now default to verifying TLS. GrpcConnectionPool.Config.production/1 sets verify: :verify_peer, and a :production endpoint built without ssl/credentials no longer silently downgrades to plaintext h2c — it raises a clear configuration error.
  • Narrowed several broad rescue/catch clauses (Pool.scale_up/scale_down, Worker.send_ping, TelemetryReporter) so unexpected errors surface instead of being swallowed; demoted expected reconnect/retry logs to :debug.

Fixed

  • Documentation: replaced README examples referencing a non-existent GrpcConnectionPool.execute/1 with the real get_channel/1 + stub-call pattern; corrected the stale install snippet and the :get_channel telemetry/strategy docs.

[0.3.5] - 2026-06-01

Fixed

  • Slot-claim race in the hot path — slot claim/release are now serialized through PoolState (register_channel/3, unregister_channel/2). Concurrent worker connects/disconnects could previously collide on a slot, leaving :channel_count higher than the populated channels so get_channel/1 returned :not_connected on a healthy pool.
  • get_channel/1 now returns {:error, :not_connected} (instead of raising) when the pool is not started or PoolState is restarting.

Changed

  • Hot-path performance: collapsed the per-call ETS table-name rebuild + two persistent_term lookups into one combined term; RoundRobin uses unsigned atomics (no abs/1); PowerOfTwo now tracks load in lock-free :atomics counters (least-frequently-used) instead of writing a timestamp to ETS on every selection.
  • Per-call :get_channel telemetry is configurable via telemetry_sample_rate (default 1 = emit every call; 0 disables; N samples ~1-in-N).
  • The pid => slot map moved from ETS into PoolState state (slot claim is now O(1)).

[0.3.0] - 2026-03-24

Added

  • Zero GenServer.call hot path — channels stored directly in ETS for O(1) indexed access, eliminating the GenServer.call bottleneck on every get_channel request
  • Pluggable connection strategies via GrpcConnectionPool.Strategy behaviour:
    • :round_robin (default) — lock-free atomics-based round-robin
    • :random — random selection, good for avoiding hot-spotting
    • :power_of_two — power-of-two-choices with least-recently-used tiebreak
    • Custom strategies supported via behaviour implementation
  • :persistent_term for pool config — zero-copy reads for configuration data
  • ETS with read/write concurrency — optimized concurrent access flags
  • PoolState GenServer — dedicated ETS table owner for crash resilience
  • TelemetryReporter GenServer — replaced recursive :timer.sleep telemetry loop with a proper GenServer using Process.send_after
  • await_ready/2 — blocks until at least one channel is connected or timeout, useful for application startup
  • Stale scaling lock detection — scaling locks older than 30 seconds are automatically released
  • max_reconnect_attempts config — workers crash after N consecutive connection failures instead of the fragile crash_after_reconnect_attempt timer
  • Benchee benchmarks — bench/get_channel_bench.exs for measuring hot path performance
  • Strategy tests — comprehensive tests for all three built-in strategies
  • CI/CD pipeline — GitHub Actions with compile, format, credo, test, dialyzer, and auto-publish to Hex on tag push

Changed

  • 4.3x–5.8x faster get_channel — single-process throughput improved from ~470K ips to ~2M ips
  • O(n) scaling eliminated — pool_size=25 was 38% slower than pool_size=5, now only 2% slower
  • 44–58% lower latency under concurrency — 100 concurrent callers: median 553μs → 312μs, p99 1035μs → 439μs
  • 28–56% less memory per call — memory now constant regardless of pool size (was O(n))
  • Pool.status 2.5x faster — reads from ETS channel_count instead of Registry.lookup
  • Pool supervision tree restructured: PoolState starts first, then Registry, DynamicSupervisor, workers, and TelemetryReporter

Removed

  • crash_after_reconnect_attempt message — replaced by max_reconnect_attempts config with clean {:stop, reason, state} on exhaustion

[0.2.3] - 2026-01-29

Added

  • Enhanced telemetry events for better observability:
    • [:grpc_connection_pool, :pool, :init] - Pool initialization with size and endpoint
    • [:grpc_connection_pool, :channel, :ping] - Ping health check with duration and result
    • [:grpc_connection_pool, :channel, :gun_down] - Gun connection down events with reason and protocol
    • [:grpc_connection_pool, :channel, :gun_error] - Gun error events with reason
    • [:grpc_connection_pool, :channel, :reconnect_scheduled] - Reconnection scheduling with delay and attempt count
  • Reconnect attempt tracking in worker state
  • Comprehensive telemetry documentation in README
  • Telemetry test suite

[0.2.2] - 2026-01-29

Added

  • Support for gRPC client interceptors in endpoint configuration (thanks @arctarus)
  • Comprehensive tests for interceptors feature
  • CHANGELOG.md file

[0.2.1] - 2025-11-22

Fixed

  • Handle GRPC v0.11.5 FunctionClauseError during disconnect

[0.2.0] - 2025-11-22

Added

  • Dynamic pool scaling feature

[0.1.6] - 2025-11-22

Fixed

  • Handle GenServer exit gracefully in connection cleanup

[0.1.5] - 2025-11-21

Changed

  • Refactored to replace Poolex with DynamicSupervisor
  • Added conn_grpc features
  • Fixed documentation LICENSE reference warnings

[0.1.4] - 2025-11-19

Changed

  • Updated dependencies: poolex to 1.4.2, grpc to 0.11.5
  • Changed gRPC connection logs from info to debug level

Added

  • suppress_connection_errors config option for GCP endpoints

[0.1.3] - 2025-11-18

Added

  • License file

[0.1.2] - 2025-11-18

Added

  • Comprehensive README with complete configuration examples and architecture details

[0.1.0] - 2025-11-18

Added

  • Initial release: Complete GrpcConnectionPool library
  • Configuration module with support for production, local, and custom environments
  • Connection pooling with DynamicSupervisor
  • Automatic connection warming and health monitoring
  • Retry logic with exponential backoff and jitter
  • Telemetry integration for metrics