DNS (Effect's Dns): the Dns service, its records and errors.
Dns looks up hosts, queries records by class and reverse-resolves
addresses::
dns = yield from Dns()
mail = yield from dns.resolve("example.com", Mx) # tuple[Mx, ...]make builds the service from a lookup (and optionally a resolver and
reverse lookup); layer_static answers from a fixed zone, for tests;
layer_system asks the operating system. Records are
validated frozen dataclasses; make_record builds one as a Result.
Values#
| Attribute | Type | Description |
|---|---|---|
record_classes | tuple[type[DnsRecord], ...] | |
record_types | tuple[RecordType, ...] |
Types#
| Type | Definition | Description |
|---|---|---|
DnsErrorReason | type DnsErrorReason = Literal['NotFound', 'Timeout', 'Temporary', 'Refused', 'ServerFailure', 'BadName', 'InvalidResponse', 'Unsupported', 'Unknown'] | |
DnsMethod | type DnsMethod = Literal['lookup', 'resolve', 'reverse'] | |
DnsRecord | type DnsRecord = A | Aaaa | Caa | Cname | Mx | Naptr | Ns | Ptr | Soa | Srv | Tlsa | Txt | |
RecordType | type RecordType = Literal['A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NAPTR', 'NS', 'PTR', 'SOA', 'SRV', 'TLSA', 'TXT'] | |
Lookup | type Lookup = Callable[[DomainName, IpFamily | None], Effect[Sequence[IpAddress], DnsError]] | |
Resolve | type Resolve = Callable[[DomainName, RecordType], Effect[Sequence[DnsRecord], DnsError]] | |
Reverse | type Reverse = Callable[[IpAddress], Effect[Sequence[str], DnsError]] |
Classes#
Functions#
format_record#
format_record(record) -> strThe record in DNS presentation format (MX 10 mail.example.com).
| Parameter | Type | Description |
|---|---|---|
record | DnsRecord |
Returns str
def format_record(record: DnsRecord) -> str: # noqa: PLR0911
"""The record in DNS presentation format (``MX 10 mail.example.com``)."""
match record:
case A() | Aaaa():
return f"{record.tag} {format_ip(record.address)}"
case Caa():
return f"CAA {128 if record.critical else 0} {record.tag_name} {_quote(record.value)}"
case Cname():
return f"CNAME {record.target}"
case Mx():
return f"MX {record.priority} {record.exchange}"
case Naptr():
return (
f"NAPTR {record.order} {record.preference} {_quote(record.flags)} "
f"{_quote(record.service)} {_quote(record.regexp)} {record.replacement}"
)
case Ns():
return f"NS {record.host}"
case Ptr():
return f"PTR {_format_name(record.host)}"
case Soa():
timers = " ".join(
_seconds(t) for t in (record.refresh, record.retry, record.expire, record.minimum)
)
return f"SOA {record.primary} {_format_name(record.admin)} {record.serial} {timers}"
case Srv():
return f"SRV {record.priority} {record.weight} {record.port} {record.target}"
case Tlsa():
return (
f"TLSA {record.cert_usage} {record.selector} {record.matching_type} "
f"{record.data.hex().upper()}"
)
case Txt():
return "TXT " + " ".join(_quote(chunk) for chunk in record.chunks)is_record_type#
is_record_type(value) -> bool| Parameter | Type | Description |
|---|---|---|
value | object |
Returns bool
def is_record_type(value: object) -> bool:
return value in record_typesmake_record#
make_record[R: DnsRecord](record_type, **fields) -> Result[R, NetAddressError]Build a record, as its constructor does, giving the rejection as an
Err instead of raising it.
| Parameter | Type | Description |
|---|---|---|
record_type | type[R] | |
fields | Any = {} |
Returns Result[R, NetAddressError]
def make_record[R: DnsRecord](record_type: type[R], /, **fields: Any) -> Result[R, NetAddressError]:
"""Build a record, as its constructor does, giving the rejection as an
``Err`` instead of raising it."""
try:
return Ok(record_type(**fields))
except NetAddressError as error:
return Err(error)
except TypeError as cause:
return Err(NetAddressError(f"invalid {record_type.tag} record", fields, cause))reverse_name#
reverse_name(address) -> DomainNameThe in-addr.arpa / ip6.arpa name a PTR lookup queries.
| Parameter | Type | Description |
|---|---|---|
address | IpAddress |
Returns DomainName
def reverse_name(address: IpAddress) -> DomainName:
"""The ``in-addr.arpa`` / ``ip6.arpa`` name a PTR lookup queries."""
if isinstance(address, IPv4Address):
return DomainName(
".".join(str(o) for o in reversed(ipv4_to_octets(address))) + ".in-addr.arpa"
)
nibbles = [f"{n:x}" for octet in ipv6_to_octets(address) for n in (octet >> 4, octet & 0xF)]
return DomainName(".".join(reversed(nibbles)) + ".ip6.arpa")layer_static#
layer_static(hosts=None, records=None) -> Layer[Dns, NetAddressError]A Dns layer answering from a fixed zone.
| Parameter | Type | Description |
|---|---|---|
hosts | Mapping[str, Sequence[IpAddressInput]] | None = None | |
records | Mapping[str, Sequence[DnsRecord]] | None = None |
Returns Layer[Dns, NetAddressError]
def layer_static(
hosts: Mapping[str, Sequence[IpAddressInput]] | None = None,
records: Mapping[str, Sequence[DnsRecord]] | None = None,
) -> Layer[Dns, NetAddressError]:
"""A ``Dns`` layer answering from a fixed zone."""
return layer_effect(Dns, from_result(make_static(hosts, records)))make#
make(lookup, resolve=None, reverse=None) -> DnsServiceA DNS service from its primitives. Without resolve, record
queries fail with Unsupported; without reverse, reverse lookups
query PTR records.
| Parameter | Type | Description |
|---|---|---|
lookup | Lookup | |
resolve | Resolve | None = None | |
reverse | Reverse | None = None |
Returns DnsService
def make(
lookup: Lookup, resolve: Resolve | None = None, reverse: Reverse | None = None
) -> DnsService:
"""A DNS service from its primitives. Without ``resolve``, record
queries fail with ``Unsupported``; without ``reverse``, reverse lookups
query PTR records."""
def unsupported(
name: DomainName, record_type: RecordType
) -> Effect[Sequence[DnsRecord], DnsError]:
return fail(DnsError("Unsupported", "resolve", name, record_type))
resolve_records = resolve or unsupported
def reverse_by_ptr(address: IpAddress) -> Effect[Sequence[str], DnsError]:
def rename(error: DnsError) -> DnsError:
return DnsError(error.reason, "reverse", format_ip(address), cause=error.cause)
return (
resolve_records(reverse_name(address), "PTR")
.map(lambda records: [r.host for r in records if isinstance(r, Ptr)])
.map_error(rename)
)
return DnsService(lookup, resolve_records, reverse or reverse_by_ptr)make_static#
make_static(hosts=None, records=None) -> Result[DnsService, NetAddressError]A DNS service answering from a fixed zone: addresses by host name, records by name.
| Parameter | Type | Description |
|---|---|---|
hosts | Mapping[str, Sequence[IpAddressInput]] | None = None | |
records | Mapping[str, Sequence[DnsRecord]] | None = None |
Returns Result[DnsService, NetAddressError]
def make_static(
hosts: Mapping[str, Sequence[IpAddressInput]] | None = None,
records: Mapping[str, Sequence[DnsRecord]] | None = None,
) -> Result[DnsService, NetAddressError]:
"""A DNS service answering from a fixed zone: addresses by host name,
records by name."""
entries: dict[str, _Entry] = {}
def entry(name: str) -> Result[_Entry, NetAddressError]:
return domain_name_from_input(name).map(
lambda domain: entries.setdefault(_zone_key(domain), _Entry([], []))
)
for name, inputs in (hosts or {}).items():
match entry(name):
case Err() as error:
return error
case Ok(current):
for value in inputs:
match ip_from_input(value):
case Err() as error:
return error
case Ok(address):
current.addresses.append(address)
for name, values in (records or {}).items():
match entry(name):
case Err() as error:
return error
case Ok(current):
for record in values:
if not isinstance(record, record_classes):
return Err(NetAddressError("expected a DNS record", record))
current.records.append(record)
def records_at(name: str) -> list[DnsRecord]:
found = entries.get(_zone_key(name))
return [] if found is None else found.records
def lookup(host: DomainName, _family: IpFamily | None) -> Effect[Sequence[IpAddress], DnsError]:
def answer() -> Sequence[IpAddress]:
found = entries.get(_zone_key(host))
direct = [] if found is None else found.addresses
return [*direct, *(r.address for r in records_at(host) if isinstance(r, (A, Aaaa)))]
return sync(answer)
def resolve(name: DomainName, _type: RecordType) -> Effect[Sequence[DnsRecord], DnsError]:
return sync(lambda: records_at(name))
def reverse(address: IpAddress) -> Effect[Sequence[str], DnsError]:
def answer() -> Sequence[str]:
named = [name for name, current in entries.items() if address in current.addresses]
pointed = [r.host for r in records_at(reverse_name(address)) if isinstance(r, Ptr)]
return [*named, *pointed]
return sync(answer)
return Ok(make(lookup, resolve, reverse))name_server_from_input#
name_server_from_input(value) -> Result[InetAddress, NetAddressError]A name server address from text, parts with a port, or an IP address (port 53).
| Parameter | Type | Description |
|---|---|---|
value | IpAddressInput | InetAddressInput |
Returns Result[InetAddress, NetAddressError]
def name_server_from_input(
value: IpAddressInput | InetAddressInput,
) -> Result[InetAddress, NetAddressError]:
"""A name server address from text, parts with a port, or an IP address
(port 53)."""
if isinstance(value, str):
return name_server_from_string(value)
if isinstance(value, (Mapping, InetAddressV4, InetAddressV6)):
return inet_address_from_input(value)
return ip_from_input(value).map(lambda address: inet_address_unsafe(address, 53))name_server_from_string#
name_server_from_string(text) -> Result[InetAddress, NetAddressError]A name server address; port 53 unless given.
| Parameter | Type | Description |
|---|---|---|
text | str |
Returns Result[InetAddress, NetAddressError]
def name_server_from_string(text: str) -> Result[InetAddress, NetAddressError]:
"""A name server address; port 53 unless given."""
if text.startswith("[") or _HOST_PORT.fullmatch(text):
return parse_inet(text)
return parse_inet(f"[{text}]:53" if ":" in text else f"{text}:53")dns_error_from_cause#
dns_error_from_cause(cause, method, hostname) -> DnsErrorThe DnsError of a resolver failure, by its error code.
| Parameter | Type | Description |
|---|---|---|
cause | OSError | |
method | DnsMethod | |
hostname | str |
Returns DnsError
def dns_error_from_cause(cause: OSError, method: DnsMethod, hostname: str) -> DnsError:
"""The ``DnsError`` of a resolver failure, by its error code."""
if isinstance(cause, socket.herror):
return DnsError("NotFound", method, hostname, cause=cause)
reason = _REASONS.get(cause.errno, "Unknown") if cause.errno is not None else "Unknown"
return DnsError(reason, method, hostname, cause=cause)layer_system#
layer_system(name_servers=()) -> Layer[Dns]Dns answered by the operating system's resolver.
| Parameter | Type | Description |
|---|---|---|
name_servers | Sequence[InetAddress] = () |
Returns Layer[Dns]
def layer_system(name_servers: Sequence[InetAddress] = ()) -> Layer[Dns]:
"""``Dns`` answered by the operating system's resolver."""
return layer_succeed(Dns, make_system(name_servers))make_system#
make_system(name_servers=()) -> DnsServiceThe system resolver as a DnsService; PTR queries and reverse
lookups ask name_servers (from dns.name_server_from_input) instead
of the system's name servers when given.
| Parameter | Type | Description |
|---|---|---|
name_servers | Sequence[InetAddress] = () |
Returns DnsService
def make_system(name_servers: Sequence[InetAddress] = ()) -> DnsService:
"""The system resolver as a ``DnsService``; PTR queries and reverse
lookups ask ``name_servers`` (from ``dns.name_server_from_input``) instead
of the system's name servers when given."""
return make(_lookup, _resolver(name_servers))