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.

[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