跳转到内容

std.Io.net.HostName

标准库Zig 0.17.0官方原文
源码std/Io/net/HostName.zig

第 1 行

已通过验证的主机名。有效主机名:

  • 长度小于或等于 max_len。
  • 是有效的 UTF-8。
  • 除字母、数字、'-' 和 '.' 外,不含其他 ASCII 字符。

字段

bytes: []const u8

外部管理的内存。已检查为有效。

std.Io.net.HostName.assert

别名

第 14 行

别名目标 std.debug.assert

std.Io.net.HostName.builtin

常量

第 7 行

std.Io.net.HostName.connect

函数

第 301 行

pub fn connect( host_name: HostName, io: Io, port: u16, options: IpAddress.ConnectOptions, ) ConnectError!Stream

参数

host_name: HostName
io: Io
port: u16
options: IpAddress.ConnectOptions

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
NameServerFailure LookupError
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Timeout ConnectError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnknownHostName LookupError
WouldBlock ConnectError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.net.HostName.ConnectError

错误集合

第 299 行

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionPending ConnectError
ConnectionRefused ConnectError
ConnectionResetByPeer ConnectError
DetectingNetworkConfigurationFailed LookupError

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

HostUnreachable ConnectError
InvalidDnsAAAARecord LookupError
InvalidDnsARecord LookupError
InvalidDnsCnameRecord LookupError
NameServerFailure LookupError
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NetworkUnreachable ConnectError
NoAddressReturned LookupError
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed LookupError
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Timeout ConnectError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnknownHostName LookupError
WouldBlock ConnectError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.net.HostName.connectMany

函数

第 358 行

异步连接与主机名关联的所有 IP 地址, 并在完成后将结果加入结果队列。

error.Canceled 绝不会加入队列,但可能加入其他错误。

返回前关闭 results,即使出错也如此。

断言在此调用返回前 results 不会关闭。

pub fn connectMany( host_name: HostName, io: Io, port: u16, results: *Io.Queue(IpAddress.ConnectError!Stream), options: IpAddress.ConnectOptions, ) LookupError!void

参数

host_name: HostName
io: Io
port: u16
results: *Io.Queue(IpAddress.ConnectError!Stream)
options: IpAddress.ConnectOptions

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

DetectingNetworkConfigurationFailed

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

InvalidDnsAAAARecord
InvalidDnsARecord
InvalidDnsCnameRecord
NameServerFailure
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NoAddressReturned
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnknownHostName

std.Io.net.HostName.DnsRecord

容器

第 241 行

字段

A = 1
CNAME = 5
AAAA = 28
_

std.Io.net.HostName.DnsResponse

容器

第 248 行

字段

bytes: []const u8
bytes_index: u32
answers_remaining: u16

std.Io.net.HostName.DnsResponse.Answer

容器

第 253 行

字段

rr: DnsRecord
packet: []const u8
data_off: u32
data_len: u16

std.Io.net.HostName.DnsResponse.Error

错误集合

第 260 行

错误

InvalidDnsPacket

std.Io.net.HostName.DnsResponse.init

函数

第 262 行

pub fn init(r: []const u8) Error!DnsResponse

参数

r: []const u8

错误

InvalidDnsPacket

std.Io.net.HostName.DnsResponse.next

函数

第 279 行

pub fn next(dr: *DnsResponse) Error!?Answer

参数

错误

InvalidDnsPacket

std.Io.net.HostName.enqueueConnection

函数

第 390 行

fn enqueueConnection( address: IpAddress, io: Io, queue: *Io.Queue(IpAddress.ConnectError!Stream), options: IpAddress.ConnectOptions, ) Io.Cancelable!void

参数

错误

Canceled

调用方请求停止异步操作。

std.Io.net.HostName.eql

函数

第 149 行

域名不区分大小写(RFC 5890,第 2.3.2.4 节)。

pub fn eql(a: HostName, b: HostName) bool

参数

std.Io.net.HostName.expand

函数

第 202 行

解压 DNS 名称。

返回从 packet 的 i 位置开始消耗的字节数, 以及展开后的 HostName。

断言 buffer 的长度至少为 max_len。

pub fn expand(noalias packet: []const u8, start_i: usize, noalias dest_buffer: []u8) ExpandError!struct { usize, HostName }

参数

packet: []const u8
start_i: usize
dest_buffer: []u8

错误

InvalidDnsPacket
InvalidHostName ValidateError
NameTooLong ValidateError

std.Io.net.HostName.ExpandError

错误集合

第 194 行

错误

InvalidDnsPacket
InvalidHostName ValidateError
NameTooLong ValidateError

std.Io.net.HostName.fromUri

函数

第 35 行

返回的 HostName.bytes 可能指向 buffer 或 uri.host 内部。

pub fn fromUri(uri: std.Uri, buffer: *[HostName.max_len]u8) FromUriError!HostName

参数

uri: std.Uri
buffer: *[HostName.max_len]u8

错误

InvalidHostName ValidateError
NameTooLong ValidateError
UriMissingHost

std.Io.net.HostName.FromUriError

错误集合

第 32 行

错误

InvalidHostName ValidateError
NameTooLong ValidateError
UriMissingHost

std.Io.net.HostName.HostName

别名

第 5 行

别名目标 std.Io.net.HostName

std.Io.net.HostName.init

函数

第 127 行

pub fn init(bytes: []const u8) ValidateError!HostName

参数

bytes: []const u8

错误

InvalidHostName
NameTooLong

std.Io.net.HostName.Io

别名

第 11 行

别名目标 std.Io

std.Io.net.HostName.Ip6Address

别名

第 13 行

别名目标 std.Io.net.Ip6Address

std.Io.net.HostName.IpAddress

别名

第 12 行

别名目标 std.Io.net.IpAddress

std.Io.net.HostName.lookup

函数

第 185 行

向 resolved 加入任意数量的 LookupResult.address,及恰好一个 LookupResult.canonical_name。

如果提供的队列容量至少为 16,则保证不阻塞。

返回前关闭 resolved,即使发生错误也如此。

断言在此调用返回前,resolved 不会被关闭。

pub fn lookup( host_name: HostName, io: Io, resolved: *Io.Queue(LookupResult), options: LookupOptions, ) LookupError!void

参数

host_name: HostName
io: Io
resolved: *Io.Queue(LookupResult)
options: LookupOptions

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

DetectingNetworkConfigurationFailed

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

InvalidDnsAAAARecord
InvalidDnsARecord
InvalidDnsCnameRecord
NameServerFailure
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NoAddressReturned
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnknownHostName

std.Io.net.HostName.LookupError

错误集合

第 160 行

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

DetectingNetworkConfigurationFailed

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

InvalidDnsAAAARecord
InvalidDnsARecord
InvalidDnsCnameRecord
NameServerFailure
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NoAddressReturned
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnknownHostName

std.Io.net.HostName.LookupOptions

容器

第 153 行

字段

port: u16
canonical_name_buffer: ?*[max_len]u8 = null

null 表示任意一种。

family: ?IpAddress.Family = null

std.Io.net.HostName.LookupResult

容器

第 172 行

字段

address: IpAddress
canonical_name: HostName

std.Io.net.HostName.max_len

常量

第 29 行

存储最大长度主机名的文本表示所需的 最大字节数,其中标签以点分隔, 包括末尾的点和长度为零的根标签。

主机名的最大长度由其分组表示决定: 每个标签有一个八位组的长度前缀,根标签 长度为 0,八位组总数最多为 255。

参见 RFC 1035,第 3.1 节

std.Io.net.HostName.max_len_without_root

常量

第 30 行

std.Io.net.HostName.native_os

常量

第 8 行

std.Io.net.HostName.ResolvConf

容器

第 407 行

字段

attempts: u32
ndots: u32
timeout_seconds: u32
nameservers_buffer: [max_nameservers]IpAddress
nameservers_len: usize
search_buffer: [max_len]u8
search_len: usize

std.Io.net.HostName.ResolvConf.addNumeric

函数

第 502 行

fn addNumeric(rc: *ResolvConf, io: Io, name: []const u8, port: u16) !void

参数

rc: *ResolvConf
io: Io
name: []const u8
port: u16

std.Io.net.HostName.ResolvConf.Directive

容器

第 454 行

字段

options
nameserver
domain
search

std.Io.net.HostName.ResolvConf.init

函数

第 421 行

若某行超过 512 字节,则返回 error.StreamTooLong。

pub fn init(io: Io) !ResolvConf

参数

io: Io

std.Io.net.HostName.ResolvConf.max_nameservers

常量

第 418 行

根据 resolv.conf(5), 此文件最多包含 3 个名称服务器。

std.Io.net.HostName.ResolvConf.nameservers

函数

第 509 行

pub fn nameservers(rc: *const ResolvConf) []const IpAddress

参数

rc: *const ResolvConf

std.Io.net.HostName.ResolvConf.Option

容器

第 455 行

字段

ndots
attempts
timeout

std.Io.net.HostName.ResolvConf.parse

函数

第 457 行

pub fn parse(rc: *ResolvConf, io: Io, reader: *Io.Reader) !void

参数

rc: *ResolvConf
io: Io
reader: *Io.Reader

std.Io.net.HostName.sameParentDomain

函数

第 132 行

pub fn sameParentDomain(parent_host: HostName, child_host: HostName) bool

参数

parent_host: HostName
child_host: HostName

用法示例

test sameParentDomain {
    try std.testing.expect(!sameParentDomain(try .init("foo.com"), try .init("bar.com")));
    try std.testing.expect(sameParentDomain(try .init("foo.com"), try .init("foo.com")));
    try std.testing.expect(sameParentDomain(try .init("foo.com"), try .init("bar.foo.com")));
    try std.testing.expect(!sameParentDomain(try .init("bar.foo.com"), try .init("foo.com")));
}

std.Io.net.HostName.std

别名

第 10 行

别名目标 std

std.Io.net.HostName.Stream

别名

第 15 行

别名目标 std.Io.net.Stream

std.Io.net.HostName.validate

函数

第 50 行

根据 RFC 1123 验证主机名

pub fn validate(bytes: []const u8) ValidateError!void

参数

bytes: []const u8

错误

InvalidHostName
NameTooLong

用法示例

test validate {
    // 有效主机名
    try validate("example");
    try validate("example.com");
    try validate("www.example.com");
    try validate("sub.domain.example.com");
    try validate("example.com.");
    try validate("host-name.example.com.");
    try validate("123.example.com.");
    try validate("a-b.com");
    try validate("a.b.c.d.e.f.g");
    try validate("127.0.0.1"); // 也是有效主机名

    const many_a: [63]u8 = @splat('a');
    try validate(&many_a ++ ".com"); // 标签恰好包含 63 个字符(有效)

    const many_a_dot_buf: [126][2]u8 = @splat(.{ 'a', '.' });
    const many_a_dot: []const u8 = @ptrCast(&many_a_dot_buf);
    try validate(many_a_dot ++ "a"); // 总长度 253(不含尾随点号)
    try validate(many_a_dot ++ "a."); // 总长度为 254(包含末尾的点)

    // 无效的主机名
    try std.testing.expectError(error.InvalidHostName, validate(""));
    try std.testing.expectError(error.InvalidHostName, validate(".example.com"));
    try std.testing.expectError(error.InvalidHostName, validate("example.com.."));
    try std.testing.expectError(error.InvalidHostName, validate("host..domain"));
    try std.testing.expectError(error.InvalidHostName, validate("-hostname"));
    try std.testing.expectError(error.InvalidHostName, validate("hostname-"));
    try std.testing.expectError(error.InvalidHostName, validate("hostname-.com"));
    try std.testing.expectError(error.InvalidHostName, validate("a.-.b"));
    try std.testing.expectError(error.InvalidHostName, validate("host_name.com"));
    try std.testing.expectError(error.InvalidHostName, validate("."));
    try std.testing.expectError(error.InvalidHostName, validate(".."));
    try std.testing.expectError(error.InvalidHostName, validate(&many_a ++ "a.com")); // 标签长度为 64(过长)
    try std.testing.expectError(error.NameTooLong, validate(many_a_dot ++ "ab")); // 总长度为 254(不含末尾的点)
    try std.testing.expectError(error.NameTooLong, validate(many_a_dot ++ "ab.")); // 总长度 255(含末尾点号)
}

std.Io.net.HostName.ValidateError

错误集合

第 44 行

错误

InvalidHostName
NameTooLong
源码

std/Io/net/HostName.zig

//! 已通过验证的主机名。有效主机名:
//! * 长度小于或等于 `max_len`。
//! * 是有效的 UTF-8。
//! * 除字母、数字、'-' 和 '.' 外,不含其他 ASCII 字符。
const HostName = @This();

const builtin = @import("builtin");
const native_os = builtin.os.tag;

const std = @import("../../std.zig");
const Io = std.Io;
const IpAddress = Io.net.IpAddress;
const Ip6Address = Io.net.Ip6Address;
const assert = std.debug.assert;
const Stream = Io.net.Stream;

/// 外部管理的内存。已检查为有效。
bytes: []const u8,

/// 存储最大长度主机名的文本表示所需的
/// 最大字节数,其中标签以点分隔,
/// 包括末尾的点和长度为零的根标签。
///
/// 主机名的最大长度由其分组表示决定:
/// 每个标签有一个八位组的长度前缀,根标签
/// 长度为 0,八位组总数最多为 255。
///
/// 参见 [RFC 1035,第 3.1 节](https://datatracker.ietf.org/doc/html/rfc1035#section-3.1)
pub const max_len = 254;
const max_len_without_root = max_len - 1;

pub const FromUriError = error{UriMissingHost} || ValidateError;

/// 返回的 `HostName.bytes` 可能指向 `buffer` 或 `uri.host` 内部。
pub fn fromUri(uri: std.Uri, buffer: *[HostName.max_len]u8) FromUriError!HostName {
    const component = uri.host orelse return error.UriMissingHost;
    const bytes = component.toRaw(buffer) catch |err| switch (err) {
        error.NoSpaceLeft => return error.NameTooLong,
    };
    try validate(bytes);
    return .{ .bytes = bytes };
}

pub const ValidateError = error{
    NameTooLong,
    InvalidHostName,
};

/// 根据 [RFC 1123](https://www.rfc-editor.org/rfc/rfc1123) 验证主机名
pub fn validate(bytes: []const u8) ValidateError!void {
    if (bytes.len == 0) return error.InvalidHostName;

    // 忽略末尾的点(FQDN)。
    const end = if (bytes[bytes.len - 1] == '.') bytes.len - 1 else bytes.len;

    // 可接受的主机名最大长度,包括各标签及点号。
    if (end > max_len_without_root) return error.NameTooLong;

    // 主机名按点分隔为“标签”,其规则为:
    //
    // - 以字母或数字开头
    // - 可包含字母、数字或连字符
    // - 必须以字母或数字结尾
    // - 最少 1 个字符,最多 63 个字符
    var label_len: usize = 0;
    for (bytes[0..end], 0..) |c, i| {
        switch (c) {
            '.' => {
                if (label_len == 0 or label_len > 63) return error.InvalidHostName;
                if (!std.ascii.isAlphanumeric(bytes[i - 1])) return error.InvalidHostName;
                label_len = 0;
            },
            '-' => {
                if (label_len == 0) return error.InvalidHostName;
                label_len += 1;
            },
            else => {
                if (!std.ascii.isAlphanumeric(c)) return error.InvalidHostName;
                label_len += 1;
            },
        }
    }

    // 验证最后一个标签
    if (label_len == 0 or label_len > 63) return error.InvalidHostName;
    if (!std.ascii.isAlphanumeric(bytes[end - 1])) return error.InvalidHostName;
}

test validate {
    // 有效主机名
    try validate("example");
    try validate("example.com");
    try validate("www.example.com");
    try validate("sub.domain.example.com");
    try validate("example.com.");
    try validate("host-name.example.com.");
    try validate("123.example.com.");
    try validate("a-b.com");
    try validate("a.b.c.d.e.f.g");
    try validate("127.0.0.1"); // 也是有效主机名

    const many_a: [63]u8 = @splat('a');
    try validate(&many_a ++ ".com"); // 标签恰好包含 63 个字符(有效)

    const many_a_dot_buf: [126][2]u8 = @splat(.{ 'a', '.' });
    const many_a_dot: []const u8 = @ptrCast(&many_a_dot_buf);
    try validate(many_a_dot ++ "a"); // 总长度 253(不含尾随点号)
    try validate(many_a_dot ++ "a."); // 总长度为 254(包含末尾的点)

    // 无效的主机名
    try std.testing.expectError(error.InvalidHostName, validate(""));
    try std.testing.expectError(error.InvalidHostName, validate(".example.com"));
    try std.testing.expectError(error.InvalidHostName, validate("example.com.."));
    try std.testing.expectError(error.InvalidHostName, validate("host..domain"));
    try std.testing.expectError(error.InvalidHostName, validate("-hostname"));
    try std.testing.expectError(error.InvalidHostName, validate("hostname-"));
    try std.testing.expectError(error.InvalidHostName, validate("hostname-.com"));
    try std.testing.expectError(error.InvalidHostName, validate("a.-.b"));
    try std.testing.expectError(error.InvalidHostName, validate("host_name.com"));
    try std.testing.expectError(error.InvalidHostName, validate("."));
    try std.testing.expectError(error.InvalidHostName, validate(".."));
    try std.testing.expectError(error.InvalidHostName, validate(&many_a ++ "a.com")); // 标签长度为 64(过长)
    try std.testing.expectError(error.NameTooLong, validate(many_a_dot ++ "ab")); // 总长度为 254(不含末尾的点)
    try std.testing.expectError(error.NameTooLong, validate(many_a_dot ++ "ab.")); // 总长度 255(含末尾点号)
}

pub fn init(bytes: []const u8) ValidateError!HostName {
    try validate(bytes);
    return .{ .bytes = bytes };
}

pub fn sameParentDomain(parent_host: HostName, child_host: HostName) bool {
    const parent_bytes = parent_host.bytes;
    const child_bytes = child_host.bytes;
    if (!std.ascii.endsWithIgnoreCase(child_bytes, parent_bytes)) return false;
    if (child_bytes.len == parent_bytes.len) return true;
    if (parent_bytes.len > child_bytes.len) return false;
    return child_bytes[child_bytes.len - parent_bytes.len - 1] == '.';
}

test sameParentDomain {
    try std.testing.expect(!sameParentDomain(try .init("foo.com"), try .init("bar.com")));
    try std.testing.expect(sameParentDomain(try .init("foo.com"), try .init("foo.com")));
    try std.testing.expect(sameParentDomain(try .init("foo.com"), try .init("bar.foo.com")));
    try std.testing.expect(!sameParentDomain(try .init("bar.foo.com"), try .init("foo.com")));
}

/// 域名不区分大小写(RFC 5890,第 2.3.2.4 节)。
pub fn eql(a: HostName, b: HostName) bool {
    return std.ascii.eqlIgnoreCase(a.bytes, b.bytes);
}

pub const LookupOptions = struct {
    port: u16,
    /// `null` 表示任意一种。
    canonical_name_buffer: ?*[max_len]u8 = null,
    family: ?IpAddress.Family = null,
};

pub const LookupError = error{
    UnknownHostName,
    ResolvConfParseFailed,
    InvalidDnsARecord,
    InvalidDnsAAAARecord,
    InvalidDnsCnameRecord,
    NameServerFailure,
    NoAddressReturned,
    /// 无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。
    DetectingNetworkConfigurationFailed,
} || IpAddress.BindError || Io.Cancelable;

pub const LookupResult = union(enum) {
    address: IpAddress,
    canonical_name: HostName,
};

/// 向 `resolved` 加入任意数量的 `LookupResult.address`,及恰好一个
/// `LookupResult.canonical_name`。
///
/// 如果提供的队列容量至少为 16,则保证不阻塞。
///
/// 返回前关闭 `resolved`,即使发生错误也如此。
///
/// 断言在此调用返回前,`resolved` 不会被关闭。
pub fn lookup(
    host_name: HostName,
    io: Io,
    resolved: *Io.Queue(LookupResult),
    options: LookupOptions,
) LookupError!void {
    return io.vtable.netLookup(io.userdata, host_name, resolved, options);
}

pub const ExpandError = error{InvalidDnsPacket} || ValidateError;

/// 解压 DNS 名称。
///
/// 返回从 `packet` 的 `i` 位置开始消耗的字节数,
/// 以及展开后的 `HostName`。
///
/// 断言 `buffer` 的长度至少为 `max_len`。
pub fn expand(noalias packet: []const u8, start_i: usize, noalias dest_buffer: []u8) ExpandError!struct { usize, HostName } {
    const dest = dest_buffer[0..max_len];

    var i = start_i;
    var dest_i: usize = 0;
    var len: ?usize = null;

    // 使用迭代计数器检测引用循环。
    for (0..packet.len / 2) |_| {
        if (i >= packet.len) return error.InvalidDnsPacket;

        const c = packet[i];
        if ((c & 0xc0) != 0) {
            if (i + 1 >= packet.len) return error.InvalidDnsPacket;
            const j: usize = (@as(usize, c & 0x3F) << 8) | packet[i + 1];
            if (j >= packet.len) return error.InvalidDnsPacket;
            if (len == null) len = (i + 2) - start_i;
            i = j;
        } else if (c != 0) {
            if (dest_i != 0) {
                dest[dest_i] = '.';
                dest_i += 1;
            }
            const label_len: usize = c;
            if (i + 1 + label_len > packet.len) return error.InvalidDnsPacket;
            if (dest_i + label_len + 1 > dest.len) return error.InvalidDnsPacket;
            @memcpy(dest[dest_i..][0..label_len], packet[i + 1 ..][0..label_len]);
            dest_i += label_len;
            i += 1 + label_len;
        } else {
            return .{
                len orelse i - start_i + 1,
                try .init(dest[0..dest_i]),
            };
        }
    }
    return error.InvalidDnsPacket;
}

pub const DnsRecord = enum(u8) {
    A = 1,
    CNAME = 5,
    AAAA = 28,
    _,
};

pub const DnsResponse = struct {
    bytes: []const u8,
    bytes_index: u32,
    answers_remaining: u16,

    pub const Answer = struct {
        rr: DnsRecord,
        packet: []const u8,
        data_off: u32,
        data_len: u16,
    };

    pub const Error = error{InvalidDnsPacket};

    pub fn init(r: []const u8) Error!DnsResponse {
        if (r.len < 12) return error.InvalidDnsPacket;
        if ((r[3] & 15) != 0) return .{ .bytes = r, .bytes_index = 3, .answers_remaining = 0 };
        var i: u32 = 12;
        var query_count = std.mem.readInt(u16, r[4..6], .big);
        while (query_count != 0) : (query_count -= 1) {
            while (i < r.len and r[i] -% 1 < 127) i += 1;
            if (r.len - i < 6) return error.InvalidDnsPacket;
            i = i + 5 + @intFromBool(r[i] != 0);
        }
        return .{
            .bytes = r,
            .bytes_index = i,
            .answers_remaining = std.mem.readInt(u16, r[6..8], .big),
        };
    }

    pub fn next(dr: *DnsResponse) Error!?Answer {
        if (dr.answers_remaining == 0) return null;
        dr.answers_remaining -= 1;
        const r = dr.bytes;
        var i = dr.bytes_index;
        while (i < r.len and r[i] -% 1 < 127) i += 1;
        if (r.len - i < 12) return error.InvalidDnsPacket;
        i = i + 1 + @intFromBool(r[i] != 0);
        const len = std.mem.readInt(u16, r[i + 8 ..][0..2], .big);
        if (i + 10 + len > r.len) return error.InvalidDnsPacket;
        defer dr.bytes_index = i + 10 + len;
        return .{
            .rr = @fromBackingInt(@intCast(r[i + 1])),
            .packet = r,
            .data_off = i + 10,
            .data_len = len,
        };
    }
};

pub const ConnectError = LookupError || IpAddress.ConnectError;

pub fn connect(
    host_name: HostName,
    io: Io,
    port: u16,
    options: IpAddress.ConnectOptions,
) ConnectError!Stream {
    var connect_many_buffer: [32]IpAddress.ConnectError!Stream = undefined;
    var connect_many_queue: Io.Queue(IpAddress.ConnectError!Stream) = .init(&connect_many_buffer);

    var connect_many = io.async(connectMany, .{ host_name, io, port, &connect_many_queue, options });
    defer {
        connect_many.cancel(io) catch {};
        while (connect_many_queue.getOneUncancelable(io)) |loser| {
            if (loser) |s| s.close(io) else |_| {}
        } else |err| switch (err) {
            error.Closed => {},
        }
    }

    var ip_connect_error: ?IpAddress.ConnectError = null;

    while (connect_many_queue.getOne(io)) |result| {
        if (result) |stream| {
            return stream;
        } else |err| switch (err) {
            error.Canceled => unreachable,

            error.SystemResources,
            error.OptionUnsupported,
            error.ProcessFdQuotaExceeded,
            error.SystemFdQuotaExceeded,
            => |e| return e,

            error.WouldBlock => return error.Unexpected,

            else => |e| ip_connect_error = e,
        }
    } else |err| switch (err) {
        error.Canceled => |e| return e,
        error.Closed => {
            // 没有连接尝试成功。如果存在查找错误,则返回该错误。
            try connect_many.await(io);
            // 否则,返回 IP 连接尝试失败时的错误。
            return ip_connect_error orelse
                return error.UnknownHostName;
        },
    }
}

/// 异步连接与主机名关联的所有 IP 地址,
/// 并在完成后将结果加入结果队列。
///
/// `error.Canceled` 绝不会加入队列,但可能加入其他错误。
///
/// 返回前关闭 `results`,即使出错也如此。
///
/// 断言在此调用返回前 `results` 不会关闭。
pub fn connectMany(
    host_name: HostName,
    io: Io,
    port: u16,
    results: *Io.Queue(IpAddress.ConnectError!Stream),
    options: IpAddress.ConnectOptions,
) LookupError!void {
    defer results.close(io);

    var canonical_name_buffer: [max_len]u8 = undefined;
    var lookup_buffer: [32]HostName.LookupResult = undefined;
    var lookup_queue: Io.Queue(LookupResult) = .init(&lookup_buffer);
    var lookup_future = io.async(lookup, .{ host_name, io, &lookup_queue, .{
        .port = port,
        .canonical_name_buffer = &canonical_name_buffer,
    } });
    defer lookup_future.cancel(io) catch {};

    var group: Io.Group = .init;
    defer group.cancel(io);

    while (lookup_queue.getOne(io)) |dns_result| switch (dns_result) {
        .address => |address| group.async(io, enqueueConnection, .{ address, io, results, options }),
        .canonical_name => continue,
    } else |err| switch (err) {
        error.Canceled => |e| return e,
        error.Closed => {
            try group.await(io);
            return lookup_future.await(io);
        },
    }
}
fn enqueueConnection(
    address: IpAddress,
    io: Io,
    queue: *Io.Queue(IpAddress.ConnectError!Stream),
    options: IpAddress.ConnectOptions,
) Io.Cancelable!void {
    const result = address.connect(io, options) catch |err| switch (err) {
        error.Canceled => |e| return e,
        else => |e| e, // 其他错误进入结果队列
    };
    errdefer if (result) |s| s.close(io) else |_| {};
    queue.putOne(io, result) catch |err| switch (err) {
        error.Canceled => |e| return e,
        error.Closed => unreachable, // `queue` 不得关闭
    };
}

pub const ResolvConf = struct {
    attempts: u32,
    ndots: u32,
    timeout_seconds: u32,
    nameservers_buffer: [max_nameservers]IpAddress,
    nameservers_len: usize,
    search_buffer: [max_len]u8,
    search_len: usize,

    /// 根据 resolv.conf(5),
    /// 此文件最多包含 3 个名称服务器。
    pub const max_nameservers = 3;

    /// 若某行超过 512 字节,则返回 `error.StreamTooLong`。
    pub fn init(io: Io) !ResolvConf {
        var rc: ResolvConf = .{
            .nameservers_buffer = undefined,
            .nameservers_len = 0,
            .search_buffer = undefined,
            .search_len = 0,
            .ndots = 1,
            .timeout_seconds = 5,
            .attempts = 2,
        };

        const file = Io.Dir.openFileAbsolute(io, "/etc/resolv.conf", .{}) catch |err| switch (err) {
            error.FileNotFound,
            error.NotDir,
            error.AccessDenied,
            => {
                try addNumeric(&rc, io, "127.0.0.1", 53);
                return rc;
            },

            else => |e| return e,
        };
        defer file.close(io);

        var line_buf: [512]u8 = undefined;
        var file_reader = file.reader(io, &line_buf);
        parse(&rc, io, &file_reader.interface) catch |err| switch (err) {
            error.ReadFailed => return file_reader.err.?,
            else => |e| return e,
        };
        return rc;
    }

    const Directive = enum { options, nameserver, domain, search };
    const Option = enum { ndots, attempts, timeout };

    pub fn parse(rc: *ResolvConf, io: Io, reader: *Io.Reader) !void {
        while (reader.takeSentinel('\n')) |line_with_comment| {
            const line = line: {
                var split = std.mem.splitScalar(u8, line_with_comment, '#');
                break :line split.first();
            };
            var line_it = std.mem.tokenizeAny(u8, line, " \t");

            const token = line_it.next() orelse continue;
            switch (std.meta.stringToEnum(Directive, token) orelse continue) {
                .options => while (line_it.next()) |sub_tok| {
                    var colon_it = std.mem.splitScalar(u8, sub_tok, ':');
                    const name = colon_it.first();
                    const value_txt = colon_it.next() orelse continue;
                    const value = std.fmt.parseInt(u8, value_txt, 10) catch |err| switch (err) {
                        error.Overflow => 255,
                        error.InvalidCharacter => continue,
                    };
                    switch (std.meta.stringToEnum(Option, name) orelse continue) {
                        .ndots => rc.ndots = @min(value, 15),
                        .attempts => rc.attempts = @min(value, 10),
                        .timeout => rc.timeout_seconds = @min(value, 60),
                    }
                },
                .nameserver => {
                    const ip_txt = line_it.next() orelse continue;
                    try addNumeric(rc, io, ip_txt, 53);
                },
                .domain, .search => {
                    const rest = line_it.rest();
                    if (rest.len > rc.search_buffer.len) continue;
                    @memcpy(rc.search_buffer[0..rest.len], rest);
                    rc.search_len = rest.len;
                },
            }
        } else |err| switch (err) {
            error.EndOfStream => if (reader.bufferedLen() != 0) return error.EndOfStream,
            else => |e| return e,
        }

        if (rc.nameservers_len == 0) {
            try addNumeric(rc, io, "127.0.0.1", 53);
        }
    }

    fn addNumeric(rc: *ResolvConf, io: Io, name: []const u8, port: u16) !void {
        if (rc.nameservers_len < rc.nameservers_buffer.len) {
            rc.nameservers_buffer[rc.nameservers_len] = try .resolve(io, name, port);
            rc.nameservers_len += 1;
        }
    }

    pub fn nameservers(rc: *const ResolvConf) []const IpAddress {
        return rc.nameservers_buffer[0..rc.nameservers_len];
    }
};

test ResolvConf {
    const input =
        \\# Generated by resolvconf
        \\nameserver 1.0.0.1
        \\nameserver 1.1.1.1
        \\nameserver fe80::e0e:76ff:fed4:cf22
        \\options edns0
        \\
    ;
    var reader: Io.Reader = .fixed(input);

    var rc: ResolvConf = .{
        .nameservers_buffer = undefined,
        .nameservers_len = 0,
        .search_buffer = undefined,
        .search_len = 0,
        .ndots = 1,
        .timeout_seconds = 5,
        .attempts = 2,
    };

    try rc.parse(std.testing.io, &reader);
    try std.testing.expectEqual(3, rc.nameservers().len);
}