GitHub

Name Resolution

TCP.connect("host:port"), TCP.listen("host:port"), and TLS.connect("host:port") all flow through a resolver layer that turns host/port strings into concrete TCP.SocketEndpoint values. Most users can ignore that layer and stay on the TCP or TLS entrypoints directly. The types documented here are advanced controls for custom resolution, caching, and explicit address-family policy.

When This Layer Matters

Most users can call Reseau.TCP.connect or Reseau.TLS.connect directly and never touch these types. Reach for this layer when you need any of the following:

  • explicit IPv4/IPv6 preference or filtering
  • a custom resolver backend
  • cached or deduplicated hostname lookups
  • pre-resolved address lists before dialing
  • deadline and fallback-race control packaged into one reusable dial policy

Resolver Policy

ResolverPolicy controls how mixed-family results are filtered and ordered:

Reseau.HostResolvers.ResolverPolicy — Type
ResolverPolicy

Host-resolution filtering and preference policy.

Fields:

  • prefer_ipv6: sort mixed-family results so IPv6 candidates come first for the generic tcp network
  • allow_ipv4: keep IPv4 candidates in the result set
  • allow_ipv6: keep IPv6 candidates in the result set

At least one family must remain enabled.

source

This is the right tool when you want a "tcp" dial to prefer IPv6 first, disable one family entirely, or otherwise steer the order of candidate endpoints before connect attempts begin.

Resolver Implementations

Reseau ships a small stack of resolver building blocks for advanced dialing control:

Reseau.HostResolvers.SingleflightResolver — Type
SingleflightResolver(parent)

Resolver wrapper that coalesces concurrent duplicate hostname lookups for the same (network, host) pair while preserving caller-local timeout and connect behavior outside the raw lookup step.

source
Reseau.HostResolvers.CachingResolver — Type
CachingResolver(; parent=SystemResolver(), ttl_ns, stale_ttl_ns, negative_ttl_ns, max_hosts)
CachingResolver(parent; ttl_ns, stale_ttl_ns, negative_ttl_ns, max_hosts)

Explicit opt-in hostname cache with policy TTLs.

This caches positive host-IP lookups for ttl_ns, may serve stale positives for up to stale_ttl_ns while refreshing in the background, and may cache LookupError failures for negative_ttl_ns. max_hosts bounds the number of cached host keys and evicts the least-recently-used entry when full.

source
Reseau.HostResolvers.StaticResolver — Type
StaticResolver

Resolver with fixed host/service mappings and optional fallback resolver.

This is useful in tests and controlled environments where you want deterministic name/service lookup without consulting the operating system.

source
Reseau.HostResolvers.HostResolver — Type
HostResolver

Connect configuration for timeout/deadline handling, optional local bind selection, and resolver/policy injection.

Fields:

  • timeout_ns: relative timeout budget for the whole resolve+connect operation
  • deadline_ns: absolute monotonic deadline for the whole operation
  • local_addr: optional local bind address for outbound connects
  • fallback_delay_ns: delay before starting the secondary address-family racer; negative disables the parallel race
  • resolver: resolver implementation for host/service lookup
  • policy: address ordering/filtering policy

The effective deadline is the earlier non-zero value of now + timeout_ns and deadline_ns.

source

The usual default path is:

  1. SystemResolver performs platform DNS and service lookups.
  2. SingleflightResolver coalesces concurrent duplicate lookups.
  3. HostResolver packages timeout, deadline, local bind, fallback delay, and policy for a whole resolve+connect operation.

Add CachingResolver or StaticResolver when you want explicit control over lookup reuse or deterministic test-time address mapping.

Error Types

String-address dialing and listening surface a small set of resolver-layer errors:

OpError is the high-level wrapper for connect/listen failures. Its inner err preserves the more specific cause such as malformed input, lookup failure, unsupported network, or a dial timeout.

Resolving Explicitly

If you want the concrete address list before dialing, use the explicit helper functions:

Reseau.HostResolvers.resolve_tcp_addrs — Function
resolve_tcp_addrs(resolver, network, address; op=:connect, policy=ResolverPolicy())

Resolve a TCP host:port string into concrete socket addresses.

Arguments:

  • resolver: resolver implementation used for host and service lookup
  • network: one of "tcp", "tcp4", or "tcp6"
  • address: host/port string

Keyword arguments:

  • op: context for wildcard handling, typically :connect, :listen, or :resolve
  • policy: address-family filtering and ordering policy

Returns a ResolvedConnectAddrs container in the order that subsequent connection logic should attempt.

Custom resolver methods extending resolve_tcp_addrs(::AbstractResolver, ...) should return ResolvedConnectAddrs directly.

Throws AddressError, LookupError, or UnknownNetworkError when parsing or resolution fails.

source
resolve_tcp_addrs(network, address) -> ResolvedConnectAddrs

Resolve concrete TCP endpoints using DEFAULT_RESOLVER.

source
Reseau.HostResolvers.resolve_tcp_addr — Function
resolve_tcp_addr(resolver, network, address; policy=ResolverPolicy())

Resolve and return the first preferred TCP endpoint.

This is a convenience wrapper over resolve_tcp_addrs that returns only the first candidate after policy ordering is applied.

source
resolve_tcp_addr(network, address) -> TCP.SocketEndpoint

Resolve the first preferred endpoint using DEFAULT_RESOLVER.

source

These helpers are useful when:

  • you want to inspect or log the resolved candidate set
  • you want to dial multiple endpoints yourself
  • you are building higher-level connection policy on top of Reseau

Relationship To TCP And TLS

Read TCP and TLS for the transport and handshake layers that sit on top of these resolved endpoints.