fix: extract target normalisation and fix IPv6 parsing crashes

[arctarus]

The bug

GRPC.Client.Connection contained two private functions, normalize_target_and_opts/2 and split_host_port/1, responsible for parsing and normalising the raw target string passed to GRPC.Stub.connect/2.

Both functions had untested edge cases around IPv6 addresses that caused runtime crashes in production:

1. normalize_target_and_opts/2 — CaseClauseError on IPv6 targets

The function delegated schemeless targets to a cond block that only handled two shapes: "a string with one colon" (host:port) and "a string with no colon" (unix socket). When an IPv6 address was passed — which always contains multiple colons — no branch matched and Elixir raised a CaseClauseError, crashing the Connection process before a connection was even attempted.

Affected inputs included any of:

GRPC.Stub.connect("[::1]:50051", [])       # bracketed IPv6 — crash
GRPC.Stub.connect("::1:50051", [])         # bare IPv6 with port — crash
GRPC.Stub.connect("2001:db8::1:8080", [])  # full IPv6 address — crash

2. split_host_port/1 — incorrect parsing of bracketed IPv6 without port

When a bracketed IPv6 address was provided with no port (e.g. "[::1]"), the regex for the [addr]:port pattern did not match. The fallback called strip_scheme/1, which splits on the first : character. Applied to "[::1]" this produced the host ":1]" — a silently wrong value that would cause a connection failure at the adapter level with a confusing error.

Why these bugs matter

Both failures happen before any network activity. The Connection process is a GenServer: a CaseClauseError during init/1 means the process never starts, and the supervision tree restarts it immediately with the same arguments, causing a restart loop. The bracketed-IPv6-without-port bug silently constructs a malformed host and attempts to connect to it, producing a cryptic adapter error. Neither failure points back to IPv6 as the root cause, making both hard to diagnose in production.

While most Kubernetes clusters today connect to gRPC services via DNS names rather than raw IP addresses, there are real and growing scenarios where a caller passes an IPv6 address directly to GRPC.Stub.connect/2: local development and testing ([::1]:50051 is the natural loopback on any IPv6-enabled machine), dual-stack clusters (stable since Kubernetes 1.21, increasingly enabled by cloud providers), telco and edge deployments (5G core network functions are specified over IPv6, where gRPC is a primary protocol), and bare-metal clusters going IPv6-first to avoid RFC 1918 exhaustion.

A bug that causes a silent restart loop with no actionable error message warrants a fix even if it affects a minority of users today.

The fix

Extraction to GRPC.Client.Connection.Target

The normalisation logic was extracted from Connection into a dedicated internal module, GRPC.Client.Connection.Target, with two public functions:

• normalize/2 — takes a raw target string and an optional %GRPC.Credential{}, returns {norm_target, scheme, cred}.
• split_host_port/1 — takes a normalised target string, returns {host, port}.

This separation keeps Connection focused on lifecycle concerns and makes the parsing logic independently testable.

IPv6 handling in normalize/2

The schemeless branch now explicitly handles three shapes before falling through:

1. Bracketed IPv6 with port — "[::1]:50051" matched by ~r/^\[([^\]]+)\]:(\d+)$/, yielding "ipv4:::1:50051".
2. Bracketed IPv6 without port — "[::1]" matched by a fallback ~r/\[([^\]]+)\]/ regex, stripping the brackets and returning the default port.
3. Bare IPv6 with port — "2001:db8::1:8080" handled by inspecting whether the last colon-separated segment is an integer, treating it as the port and joining the remaining segments as the address.

Bracketed IPv6 fallback in split_host_port/1

The _ -> fallback when the [addr]:port regex does not match now uses a second regex ~r/\[([^\]]+)\]/ to extract the address from the brackets, rather than calling strip_scheme/1 which blindly splits on the first :.

Interface simplification

normalize/2 previously accepted a keyword() opts list and returned the full opts back to the caller with :cred injected. The function only ever read one key from opts (opts[:cred]). The return type now reflects the module's actual concern:

# before
normalize(target, opts) :: {norm_target, norm_opts, scheme}

# after
normalize(target, cred) :: {norm_target, scheme, cred}

Connection now calls Target.normalize(target, opts[:cred]) and reassembles its own state directly, keeping opts management in Connection where it belongs.

The nimble_options dependency that was previously added to validate opts[:cred] was removed, as it is no longer needed — the type is enforced by the is_struct(cred, GRPC.Credential) guard clause.

Tests

A new test file, grpc/test/grpc/client/connection/target_test.exs, provides exhaustive coverage of Target.normalize/2 and Target.split_host_port/1, including all IPv6 input shapes, scheme inference, credential propagation, and the ArgumentError raised when a credential is passed alongside an http:// target.

The test suite was written first as failing tests to reproduce the original crashes, then made green by the implementation. The bracketed-IPv6-without-port bug in split_host_port/1 was itself discovered by the new tests during the review pass.

[sleipnir]

Hi, thanks for the PR.

Could you reduce the number of comments in the code that don't translate into some high-level explanation? I've seen many comments that are self-explanatory within the code itself, below the comment.

[sleipnir]

@arctarus We also have an error in the CI.

[arctarus]

@sleipnir feedback applied and errors fixed! Let me know if there is something else I can do.

[sleipnir]

@arctarus thank you
Great job!