@spec collect_answers(:gen_udp.socket(), non_neg_integer()) :: [Hue.Bridge.Info.t()]

Reads mDNS answers from an already-open UDP socket until timeout milliseconds have passed, and returns what they name.

timeout is a budget for the whole collection, not for each receive. The deadline is absolute for that reason: a responder answers across several packets, and restarting the clock on each one turns a 5s budget into 5s per packet, with no bound on the total.

Separate from the socket that sends the query so that the collection loop can be driven over an ordinary unicast socket, which is the only way to test it without standing up a multicast responder.

@spec discover(keyword()) :: {:ok, [Hue.Bridge.Info.t()]} | {:error, Hue.Error.t()}

Finds every reachable bridge, confirms each one, and pins its certificate.

Runs the enabled methods concurrently, merges what they found, and confirms each candidate with identify/2. Only confirmed bridges come back, so every Hue.Bridge.Info in the list carries a bridge id and — unless the request was stubbed — a fingerprint.

Options

• :cloud — set false to skip the cloud endpoint. Defaults to true.
• :mdns — set false to skip multicast. Defaults to true.
• :timeout — the budget in milliseconds for one phase of one thing. Defaults to 5000. It bounds mDNS collection as a whole — answers are collected until an absolute deadline rather than restarting the clock per packet — and it bounds each of identify/2's 3 phases. It is not a wall-clock ceiling on discover/1: finding runs concurrently with a budget of its own, and confirmation follows it, so a run against candidates that all stall takes roughly 4 times the budget. Candidates are confirmed concurrently, so their number does not extend it.

Every other option is forwarded to identify/2, and from there to Hue.new/2 and Req.new/1.

Candidates that could not be confirmed

A candidate that answers neither the certificate capture nor /api/config is not returned — the list would otherwise contain entries with no bridge id and no pin, and Hue.from_bridge/2 would happily build unverified clients from them. It is not discarded silently either: each one is logged at :warning with its address and the reason, because "found it, could not reach it" and "found nothing" call for completely different fixes and a caller who cannot tell them apart is stuck.

@spec identify(
  String.t(),
  keyword()
) :: {:ok, Hue.Bridge.Info.t()} | {:error, Hue.Error.t()}

Confirms a candidate address is a CLIP v2 bridge, pins its certificate, and captures its identity.

GET /api/config needs no application key, which is what makes trust bootstrappable: it yields the bridge id needed to make sense of the certificate's common name.

Options

• :port — defaults to 443.
• :timeout — milliseconds allowed per phase, of which there are 3: capturing the certificate, connecting and handshaking for the request, and waiting for the response. Defaults to 5000, so the worst case is that many times the budget. It sets :receive_timeout and connect_options[:timeout] unless the caller set them, because between them those are what bound the request — :receive_timeout alone leaves connecting and the handshake on Finch's five-second default, which ignores the budget entirely.
• :discovered_by — recorded on the result. Defaults to :manual.
• :fingerprint — an already-trusted pin. Given one, no certificate is captured and no trust decision is made: the request is pinned to it and fails if the bridge presents anything else. This is how to re-check a bridge you already know without re-deciding whether to trust it.

Every other option is forwarded to Hue.new/2 and from there to Req.new/1.

Errors

• :unsupported_bridge — a BSB001, the v1 bridge.
• :bridge_identity_mismatch — the certificate's common name is not the bridge id the bridge reported.
• :unexpected_response — a 200 that is not a bridge configuration.
• anything Hue.Error.from_response/4 or Hue.Error.transport/2 produces.

@spec identity_agrees?(String.t() | nil, String.t() | nil) :: boolean()

Whether a certificate's common name corroborates the bridge id the bridge reported. Pure.

On real hardware the common name is the bridge id, so these are two independent statements of the same fact and they should agree. Compared case-insensitively: /api/config reports the id in upper case, the cloud endpoint in lower case, and a certificate in whichever its issuer chose.

A nil on either side is not a disagreement. Absent corroboration and contradicted corroboration are different situations, and only the second one is evidence of anything.

@spec merge([Hue.Bridge.Info.t()]) :: [Hue.Bridge.Info.t()]

Deduplicates candidates, preferring the locally-discovered record.

A bridge found by both methods is one bridge. mDNS wins because it proves link-local reachability, which the cloud endpoint does not — it reports an address that the client may have no route to at all. Fields the winner is missing are filled from the records it displaced, so preferring mDNS never costs the bridge id only the cloud endpoint knows.

Candidates that carry no bridge id — everything mDNS produces, which yields addresses and nothing else — are deduplicated by host instead, and dropped when a record that does carry an id already names that host.

@spec parse_cloud_response(list()) :: [Hue.Bridge.Info.t()]

Parses the cloud endpoint's response body. Pure.

The live shape, captured 2026-08-06:

[{"id":"001788fffeae1b58","internalipaddress":"192.168.178.146","port":443}]

Note id, lower case, where /api/config reports bridgeid upper case. Upcased here so the two agree.

@spec parse_mdns_packet(binary()) :: [String.t()]

Parses an mDNS response packet into addresses. Pure.

Reads the answer, authority, and additional sections. A responder answers _hue._tcp.local with a PTR to the service instance and puts the SRV and A records in the additional section, so a parser that reads only anlist finds the instance name and no address at all.

Only A records are extracted: the CLIP v2 API is IPv4-only in practice, and the SRV port is always 443, which is Hue.Bridge.Info's default.

Decoding is :inet_dns, which is undocumented kernel internals. Verified against OTP 28: decode/1 defaults to mDNS mode, returns {:ok, dns_rec} or {:error, :formerr}, and rr/2 reads :type and :data off a dns_rr. A packet it cannot decode yields [] — a malformed multicast packet from something else on the LAN is not this library's problem to report.

@spec query_packet() :: binary()

The mDNS query this library multicasts: one PTR question for _hue._tcp.local. Pure.

Built with :inet_dns's make_* constructors rather than as positional tuples. The record shapes are undocumented and they move: on OTP 28 dns_header carries nine fields and dns_query four, so the tuples this was first written with raise FunctionClauseError. The constructors are the only form that does not have to be re-verified against every release.