跳转到内容

std.http.Server

标准库Zig 0.17.0官方原文
源码std/http/Server.zig

第 1 行

处理单个连接的生命周期。

字段

out: *Writer

从 HTTP 服务器发送到 HTTP 客户端的数据。

reader: http.Reader

std.http.Server.assert

别名

第 7 行

别名目标 std.debug.assert

std.http.Server.http

别名

第 4 行

别名目标 std.http

std.http.Server.init

函数

第 25 行

初始化 HTTP 服务器,能够在同一 连接上响应多个请求。

in 的缓冲区必须足够大,能存储客户端完整的 HTTP 标头,否则 receiveHead 返回 error.HttpHeadersOversize。

返回的 Server 已可调用 receiveHead。

pub fn init(in: *Reader, out: *Writer) Server

参数

in: *Reader
out: *Writer

std.http.Server.mem

别名

第 5 行

别名目标 std.mem

std.http.Server.Reader

别名

第 10 行

别名目标 std.Io.Reader

std.http.Server.receiveHead

函数

第 46 行

pub fn receiveHead(s: *Server) ReceiveHeadError!Request

参数

s: *Server

错误

HttpConnectionClosing HeadError

客户端在关闭流之前未发送任何头部字节。 这发生在保活连接最终关闭时。

HttpHeadersInvalid

客户端发送的标头不符合 HTTP 协议。

若需更详细的诊断,可将 Request.head_buffer 直接传入 Request.Head.parse。

HttpHeadersOversize HeadError

HTTP 头部字节数过多。

HTTP 规范建议在关闭连接前 响应状态码 431。

HttpRequestTruncated HeadError

收到部分 HTTP 请求,但在完整接收头部之前 连接已关闭。

ReadFailed HeadError

读取 in 时出现传递性错误。

std.http.Server.ReceiveHeadError

错误集合

第 38 行

错误

HttpConnectionClosing HeadError

客户端在关闭流之前未发送任何头部字节。 这发生在保活连接最终关闭时。

HttpHeadersInvalid

客户端发送的标头不符合 HTTP 协议。

若需更详细的诊断,可将 Request.head_buffer 直接传入 Request.Head.parse。

HttpHeadersOversize HeadError

HTTP 头部字节数过多。

HTTP 规范建议在关闭连接前 响应状态码 431。

HttpRequestTruncated HeadError

收到部分 HTTP 请求,但在完整接收头部之前 连接已关闭。

ReadFailed HeadError

读取 in 时出现传递性错误。

std.http.Server.Request

容器

第 57 行

字段

server: *Server
head: Head

请求消息体流初始化后,此结构体中的指针将失效。

head_buffer: []const u8
respond_err: ?RespondError = null

std.http.Server.Request.discardBody

函数

第 618 行

返回连接是否应保持持久连接。

如果操作将失败,则改为将 Server 状态设置为接收消息体, 并返回 false。

fn discardBody(request: *Request, keep_alive: bool) bool

参数

request: *Request
keep_alive: bool

std.http.Server.Request.ExpectContinueError

错误集合

第 599 行

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Request.Head

容器

第 70 行

字段

method: http.Method
target: []const u8
version: http.Version
expect: ?[]const u8
content_type: ?[]const u8
content_length: ?u64
transfer_encoding: http.TransferEncoding
transfer_compression: http.ContentEncoding
keep_alive: bool

std.http.Server.Request.Head.int64

函数

第 224 行

inline fn int64(array: *const [8]u8) u64

参数

array: *const [8]u8

std.http.Server.Request.Head.invalidateStrings

函数

第 230 行

当 Head 的字符串内存失效时调用此函数, 帮助程序员避免缺陷。

fn invalidateStrings(h: *Head) void

参数

h: *Head

std.http.Server.Request.Head.parse

函数

第 92 行

pub fn parse(bytes: []const u8) ParseError!Head

参数

bytes: []const u8

错误

CompressionUnsupported
HttpConnectionHeaderUnsupported
HttpHeaderContinuationsUnsupported
HttpHeadersInvalid
HttpTransferEncodingUnsupported
InvalidContentLength
MissingFinalNewline
UnknownHttpMethod

用法示例

test parse {
    const request_bytes = "GET /hi HTTP/1.0\r\n" ++
        "content-tYpe: text/plain\r\n" ++
        "content-Length:10\r\n" ++
        "expeCt:   100-continue \r\n" ++
        "TRansfer-encoding:\tdeflate, chunked \r\n" ++
        "connectioN:\t keep-alive \r\n\r\n";

    const req = try parse(request_bytes);

    try testing.expectEqual(.GET, req.method);
    try testing.expectEqual(.@"HTTP/1.0", req.version);
    try testing.expectEqualStrings("/hi", req.target);

    try testing.expectEqualStrings("text/plain", req.content_type.?);
    try testing.expectEqualStrings("100-continue", req.expect.?);

    try testing.expectEqual(true, req.keep_alive);
    try testing.expectEqual(10, req.content_length.?);
    try testing.expectEqual(.chunked, req.transfer_encoding);
    try testing.expectEqual(.deflate, req.transfer_compression);
}

std.http.Server.Request.Head.ParseError

错误集合

第 81 行

错误

CompressionUnsupported
HttpConnectionHeaderUnsupported
HttpHeaderContinuationsUnsupported
HttpHeadersInvalid
HttpTransferEncodingUnsupported
InvalidContentLength
MissingFinalNewline
UnknownHttpMethod

std.http.Server.Request.iterateHeaders

函数

第 237 行

pub fn iterateHeaders(r: *const Request) http.HeaderIterator

参数

r: *const Request

用法示例

test iterateHeaders {
    const request_bytes = "GET /hi HTTP/1.0\r\n" ++
        "content-tYpe: text/plain\r\n" ++
        "content-Length:10\r\n" ++
        "expeCt:   100-continue \r\n" ++
        "TRansfer-encoding:\tdeflate, chunked \r\n" ++
        "connectioN:\t keep-alive \r\n\r\n";

    var server: Server = .{
        .reader = .{
            .in = undefined,
            .state = .received_head,
            .interface = undefined,
            .max_head_len = 4096,
        },
        .out = undefined,
    };

    var request: Request = .{
        .server = &server,
        .head = undefined,
        .head_buffer = @constCast(request_bytes),
    };

    var it = request.iterateHeaders();
    {
        const header = it.next().?;
        try testing.expectEqualStrings("content-tYpe", header.name);
        try testing.expectEqualStrings("text/plain", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("content-Length", header.name);
        try testing.expectEqualStrings("10", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("expeCt", header.name);
        try testing.expectEqualStrings("100-continue", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("TRansfer-encoding", header.name);
        try testing.expectEqualStrings("deflate, chunked", header.value);
        try testing.expect(!it.is_trailer);
    }
    {
        const header = it.next().?;
        try testing.expectEqualStrings("connectioN", header.name);
        try testing.expectEqualStrings("keep-alive", header.value);
        try testing.expect(!it.is_trailer);
    }
    try testing.expectEqual(null, it.next());
}

std.http.Server.Request.readerExpectContinue

函数

第 577 行

若请求包含 "expect: 100-continue",此 函数会写入继续传输头部,因此可能发生 写错误。发送该头部后,将 请求的 expect 字段设为 null。

断言此函数只调用一次。

不会向服务器输出流写入、不会失败的替代函数 参见 readerExpectNone。

pub fn readerExpectContinue(request: *Request, buffer: []u8) ExpectContinueError!*Reader

参数

request: *Request
buffer: []u8

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Request.readerExpectNone

函数

第 591 行

断言 expect 标头为 null。调用方必须手动处理 预期内容,并在调用此函数之前将其设为 null。

断言此函数仅调用一次。

使 Head 内部的字符串内存失效。

pub fn readerExpectNone(request: *Request, buffer: []u8) *Reader

参数

request: *Request
buffer: []u8

std.http.Server.Request.respond

函数

第 323 行

向客户端发送完整 HTTP 响应,包括标头和正文。

自动处理 HEAD 请求,省略正文。

除非指定 transfer_encoding,否则使用 "content-length" 标头。

如果请求包含正文且连接将被复用, 则丢弃请求正文,使 Server 处于 ready 状态。 如果丢弃失败,则将连接标记为不再复用, 且不向上报告错误。

断言状态不是 continue。 断言任何标头名称或值中都不存在 "\r\n"。

pub fn respond( request: *Request, content: []const u8, options: RespondOptions, ) ExpectContinueError!void

参数

request: *Request
content: []const u8
options: RespondOptions

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Request.RespondError

错误集合

第 65 行

错误

HttpExpectationFailed

请求包含值无法识别的 expect 头字段。

std.http.Server.Request.RespondOptions

容器

第 300 行

字段

version: http.Version = .@"HTTP/1.1"
status: http.Status = .ok
reason: ?[]const u8 = null
keep_alive: bool = true
extra_headers: []const http.Header = &.{}
transfer_encoding: ?http.TransferEncoding = null

std.http.Server.Request.respondStreaming

函数

第 412 行

在调用 BodyWriter.flush 或 BodyWriter.end 之前,不保证头部已发送。

若请求包含正文且连接计划复用, 则丢弃请求正文,使 Server 保持 ready 状态。 若丢弃失败,连接会标记为不可复用, 但不会对外报告错误。

HEAD 请求通过设置 BodyWriter.elide 标志透明处理;该标志位于返回的 BodyWriter 上, 使响应流省略正文。不过,调用方也值得检查 该标志,跳过原本为满足请求而需要执行的 高开销操作。

断言状态不是 continue。

pub fn respondStreaming( request: *Request, buffer: []u8, options: RespondStreamingOptions, ) ExpectContinueError!http.BodyWriter

参数

request: *Request
buffer: []u8
options: RespondStreamingOptions

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Request.RespondStreamingOptions

容器

第 389 行

字段

content_length: ?u64 = null

若提供,则响应使用 content-length 头; 否则使用 transfer-encoding: chunked。

respond_options: RespondOptions = .{}

与 respond 方法共用的选项。

std.http.Server.Request.respondUnflushed

函数

第 332 行

pub fn respondUnflushed( request: *Request, content: []const u8, options: RespondOptions, ) ExpectContinueError!void

参数

request: *Request
content: []const u8
options: RespondOptions

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Request.respondWebSocket

函数

第 531 行

只有对返回的结构体调用 WebSocket.flush 后, 才能保证标头已发送。

pub fn respondWebSocket(request: *Request, options: WebSocketOptions) ExpectContinueError!WebSocket

参数

request: *Request
options: WebSocketOptions

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Request.UpgradeRequest

容器

第 493 行

字段

websocket: ?[]const u8
other: []const u8
none

std.http.Server.Request.upgradeRequested

函数

第 500 行

不会使 request.head 失效。

pub fn upgradeRequested(request: *const Request) UpgradeRequest

参数

request: *const Request

std.http.Server.Request.WebSocketOptions

容器

第 522 行

字段

key: []const u8

来自 UpgradeRequest.websocket 的值(sec-websocket-key 头字段值)。

reason: ?[]const u8 = null
extra_headers: []const http.Header = &.{}

std.http.Server.Request.writeExpectContinue

函数

第 607 行

pub fn writeExpectContinue(request: *Request) ExpectContinueError!void

参数

request: *Request

错误

HttpExpectationFailed

客户端发送的 expect HTTP 头字段值 不是 "100-continue"。

WriteFailed

无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。

std.http.Server.Server

别名

第 12 行

别名目标 std.http.Server

std.http.Server.std

别名

第 3 行

别名目标 std

std.http.Server.testing

别名

第 8 行

别名目标 std.testing

std.http.Server.Uri

别名

第 6 行

别名目标 std.Uri

std.http.Server.WebSocket

容器

第 654 行

字段

key: []const u8
input: *Reader
output: *Writer

std.http.Server.WebSocket.flush

函数

第 805 行

pub fn flush(ws: *WebSocket) Writer.Error!void

参数

ws: *WebSocket

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Server.WebSocket.Header0

容器

第 659 行

字段

opcode: Opcode
rsv3: u1 = 0
rsv2: u1 = 0
rsv1: u1 = 0
fin: bool

std.http.Server.WebSocket.Header1

容器

第 667 行

字段

payload_len: enum(u7) {
    len16 = 126,
    len64 = 127,
    _,
}
mask: bool

std.http.Server.WebSocket.Opcode

容器

第 676 行

字段

continuation = 0
text = 1
binary = 2
connection_close = 8
ping = 9
pong = 10

"可以主动发送 Pong 帧,用作单向 心跳。接收方无需响应主动发送的 Pong 帧。"

_

std.http.Server.WebSocket.readSmallMessage

函数

第 706 行

读取 WebSocket 流中的下一条消息;如果 输入缓冲区无法容纳消息,则失败。返回内存指向 输入缓冲区,并在下次读取时失效。

pub fn readSmallMessage(ws: *WebSocket) ReadSmallTextMessageError!SmallMessage

参数

ws: *WebSocket

错误

ConnectionClose
EndOfStream
MessageOversize
MissingMaskBit
ReadFailed
UnexpectedOpCode

std.http.Server.WebSocket.ReadSmallTextMessageError

错误集合

第 688 行

错误

ConnectionClose
EndOfStream
MessageOversize
MissingMaskBit
ReadFailed
UnexpectedOpCode

std.http.Server.WebSocket.SmallMessage

容器

第 697 行

字段

opcode: Opcode

可以是文本、二进制或 ping。

data: []u8

std.http.Server.WebSocket.writeMessage

函数

第 755 行

pub fn writeMessage(ws: *WebSocket, data: []const u8, op: Opcode) Writer.Error!void

参数

ws: *WebSocket
data: []const u8
op: Opcode

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Server.WebSocket.writeMessageUnflushed

函数

第 761 行

pub fn writeMessageUnflushed(ws: *WebSocket, data: []const u8, op: Opcode) Writer.Error!void

参数

ws: *WebSocket
data: []const u8
op: Opcode

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Server.WebSocket.writeMessageVec

函数

第 766 行

pub fn writeMessageVec(ws: *WebSocket, data: [][]const u8, op: Opcode) Writer.Error!void

参数

ws: *WebSocket
data: [][]const u8
op: Opcode

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Server.WebSocket.writeMessageVecUnflushed

函数

第 771 行

pub fn writeMessageVecUnflushed(ws: *WebSocket, data: [][]const u8, op: Opcode) Writer.Error!void

参数

ws: *WebSocket
data: [][]const u8
op: Opcode

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Server.Writer

别名

第 9 行

别名目标 std.Io.Writer

源码

std/http/Server.zig

//! 处理单个连接的生命周期。

const std = @import("../std.zig");
const http = std.http;
const mem = std.mem;
const Uri = std.Uri;
const assert = std.debug.assert;
const testing = std.testing;
const Writer = std.Io.Writer;
const Reader = std.Io.Reader;

const Server = @This();

/// 从 HTTP 服务器发送到 HTTP 客户端的数据。
out: *Writer,
reader: http.Reader,

/// 初始化 HTTP 服务器,能够在同一
/// 连接上响应多个请求。
///
/// `in` 的缓冲区必须足够大,能存储客户端完整的 HTTP
/// 标头,否则 `receiveHead` 返回 `error.HttpHeadersOversize`。
///
/// 返回的 `Server` 已可调用 `receiveHead`。
pub fn init(in: *Reader, out: *Writer) Server {
    return .{
        .reader = .{
            .in = in,
            .state = .ready,
            // 调用 `http.Reader.bodyReader` 时填充。
            .interface = undefined,
            .max_head_len = in.buffer.len,
        },
        .out = out,
    };
}

pub const ReceiveHeadError = http.Reader.HeadError || error{
    /// 客户端发送的标头不符合 HTTP 协议。
    ///
    /// 若需更详细的诊断,可将 `Request.head_buffer`
    /// 直接传入 `Request.Head.parse`。
    HttpHeadersInvalid,
};

pub fn receiveHead(s: *Server) ReceiveHeadError!Request {
    const head_buffer = try s.reader.receiveHead();
    return .{
        .server = s,
        .head_buffer = head_buffer,
        // 无需在此记录返回错误,因为用户可以使用头部缓冲区重复解析以获取详细诊断。
        //
        .head = Request.Head.parse(head_buffer) catch return error.HttpHeadersInvalid,
    };
}

pub const Request = struct {
    server: *Server,
    /// 请求消息体流初始化后,此结构体中的指针将失效。
    ///
    head: Head,
    head_buffer: []const u8,
    respond_err: ?RespondError = null,

    pub const RespondError = error{
        /// 请求包含值无法识别的 `expect` 头字段。
        HttpExpectationFailed,
    };

    pub const Head = struct {
        method: http.Method,
        target: []const u8,
        version: http.Version,
        expect: ?[]const u8,
        content_type: ?[]const u8,
        content_length: ?u64,
        transfer_encoding: http.TransferEncoding,
        transfer_compression: http.ContentEncoding,
        keep_alive: bool,

        pub const ParseError = error{
            UnknownHttpMethod,
            HttpHeadersInvalid,
            HttpHeaderContinuationsUnsupported,
            HttpTransferEncodingUnsupported,
            HttpConnectionHeaderUnsupported,
            InvalidContentLength,
            CompressionUnsupported,
            MissingFinalNewline,
        };

        pub fn parse(bytes: []const u8) ParseError!Head {
            var it = mem.splitSequence(u8, bytes, "\r\n");

            const first_line = it.next().?;
            if (first_line.len < 10)
                return error.HttpHeadersInvalid;

            const method_end = mem.findScalar(u8, first_line, ' ') orelse
                return error.HttpHeadersInvalid;

            const method = std.meta.stringToEnum(http.Method, first_line[0..method_end]) orelse
                return error.UnknownHttpMethod;

            const version_start = mem.findScalarLast(u8, first_line, ' ') orelse
                return error.HttpHeadersInvalid;
            if (version_start == method_end) return error.HttpHeadersInvalid;

            const version_str = first_line[version_start + 1 ..];
            if (version_str.len != 8) return error.HttpHeadersInvalid;
            const version: http.Version = switch (int64(version_str[0..8])) {
                int64("HTTP/1.0") => .@"HTTP/1.0",
                int64("HTTP/1.1") => .@"HTTP/1.1",
                else => return error.HttpHeadersInvalid,
            };

            const target = first_line[method_end + 1 .. version_start];

            var head: Head = .{
                .method = method,
                .target = target,
                .version = version,
                .expect = null,
                .content_type = null,
                .content_length = null,
                .transfer_encoding = .none,
                .transfer_compression = .identity,
                .keep_alive = switch (version) {
                    .@"HTTP/1.0" => false,
                    .@"HTTP/1.1" => true,
                },
            };

            while (it.next()) |line| {
                if (line.len == 0) return head;
                switch (line[0]) {
                    ' ', '\t' => return error.HttpHeaderContinuationsUnsupported,
                    else => {},
                }

                var line_it = mem.splitScalar(u8, line, ':');
                const header_name = line_it.next().?;
                const header_value = mem.trim(u8, line_it.rest(), " \t");
                if (header_name.len == 0) return error.HttpHeadersInvalid;

                if (std.ascii.eqlIgnoreCase(header_name, "connection")) {
                    head.keep_alive = !std.ascii.eqlIgnoreCase(header_value, "close");
                } else if (std.ascii.eqlIgnoreCase(header_name, "expect")) {
                    head.expect = header_value;
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-type")) {
                    head.content_type = header_value;
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-length")) {
                    if (head.content_length != null) return error.HttpHeadersInvalid;
                    head.content_length = std.fmt.parseInt(u64, header_value, 10) catch
                        return error.InvalidContentLength;
                } else if (std.ascii.eqlIgnoreCase(header_name, "content-encoding")) {
                    if (head.transfer_compression != .identity) return error.HttpHeadersInvalid;

                    const trimmed = mem.trim(u8, header_value, " ");

                    if (http.ContentEncoding.fromString(trimmed)) |ce| {
                        head.transfer_compression = ce;
                    } else {
                        return error.HttpTransferEncodingUnsupported;
                    }
                } else if (std.ascii.eqlIgnoreCase(header_name, "transfer-encoding")) {
                    // Transfer-Encoding: second, first
                    // Transfer-Encoding: deflate, chunked
                    var iter = mem.splitBackwardsScalar(u8, header_value, ',');

                    const first = iter.first();
                    const trimmed_first = mem.trim(u8, first, " ");

                    var next: ?[]const u8 = first;
                    if (std.meta.stringToEnum(http.TransferEncoding, trimmed_first)) |transfer| {
                        if (head.transfer_encoding != .none)
                            return error.HttpHeadersInvalid; // 我们已有传输编码
                        head.transfer_encoding = transfer;

                        next = iter.next();
                    }

                    if (next) |second| {
                        const trimmed_second = mem.trim(u8, second, " ");

                        if (http.ContentEncoding.fromString(trimmed_second)) |transfer| {
                            if (head.transfer_compression != .identity)
                                return error.HttpHeadersInvalid; // 不支持双重压缩
                            head.transfer_compression = transfer;
                        } else {
                            return error.HttpTransferEncodingUnsupported;
                        }
                    }

                    if (iter.next()) |_| return error.HttpTransferEncodingUnsupported;
                }
            }
            return error.MissingFinalNewline;
        }

        test parse {
            const request_bytes = "GET /hi HTTP/1.0\r\n" ++
                "content-tYpe: text/plain\r\n" ++
                "content-Length:10\r\n" ++
                "expeCt:   100-continue \r\n" ++
                "TRansfer-encoding:\tdeflate, chunked \r\n" ++
                "connectioN:\t keep-alive \r\n\r\n";

            const req = try parse(request_bytes);

            try testing.expectEqual(.GET, req.method);
            try testing.expectEqual(.@"HTTP/1.0", req.version);
            try testing.expectEqualStrings("/hi", req.target);

            try testing.expectEqualStrings("text/plain", req.content_type.?);
            try testing.expectEqualStrings("100-continue", req.expect.?);

            try testing.expectEqual(true, req.keep_alive);
            try testing.expectEqual(10, req.content_length.?);
            try testing.expectEqual(.chunked, req.transfer_encoding);
            try testing.expectEqual(.deflate, req.transfer_compression);
        }

        inline fn int64(array: *const [8]u8) u64 {
            return @bitCast(array.*);
        }

        /// 当 `Head` 的字符串内存失效时调用此函数,
        /// 帮助程序员避免缺陷。
        fn invalidateStrings(h: *Head) void {
            h.target = undefined;
            if (h.expect) |*s| s.* = undefined;
            if (h.content_type) |*s| s.* = undefined;
        }
    };

    pub fn iterateHeaders(r: *const Request) http.HeaderIterator {
        assert(r.server.reader.state == .received_head);
        return http.HeaderIterator.init(r.head_buffer);
    }

    test iterateHeaders {
        const request_bytes = "GET /hi HTTP/1.0\r\n" ++
            "content-tYpe: text/plain\r\n" ++
            "content-Length:10\r\n" ++
            "expeCt:   100-continue \r\n" ++
            "TRansfer-encoding:\tdeflate, chunked \r\n" ++
            "connectioN:\t keep-alive \r\n\r\n";

        var server: Server = .{
            .reader = .{
                .in = undefined,
                .state = .received_head,
                .interface = undefined,
                .max_head_len = 4096,
            },
            .out = undefined,
        };

        var request: Request = .{
            .server = &server,
            .head = undefined,
            .head_buffer = @constCast(request_bytes),
        };

        var it = request.iterateHeaders();
        {
            const header = it.next().?;
            try testing.expectEqualStrings("content-tYpe", header.name);
            try testing.expectEqualStrings("text/plain", header.value);
            try testing.expect(!it.is_trailer);
        }
        {
            const header = it.next().?;
            try testing.expectEqualStrings("content-Length", header.name);
            try testing.expectEqualStrings("10", header.value);
            try testing.expect(!it.is_trailer);
        }
        {
            const header = it.next().?;
            try testing.expectEqualStrings("expeCt", header.name);
            try testing.expectEqualStrings("100-continue", header.value);
            try testing.expect(!it.is_trailer);
        }
        {
            const header = it.next().?;
            try testing.expectEqualStrings("TRansfer-encoding", header.name);
            try testing.expectEqualStrings("deflate, chunked", header.value);
            try testing.expect(!it.is_trailer);
        }
        {
            const header = it.next().?;
            try testing.expectEqualStrings("connectioN", header.name);
            try testing.expectEqualStrings("keep-alive", header.value);
            try testing.expect(!it.is_trailer);
        }
        try testing.expectEqual(null, it.next());
    }

    pub const RespondOptions = struct {
        version: http.Version = .@"HTTP/1.1",
        status: http.Status = .ok,
        reason: ?[]const u8 = null,
        keep_alive: bool = true,
        extra_headers: []const http.Header = &.{},
        transfer_encoding: ?http.TransferEncoding = null,
    };

    /// 向客户端发送完整 HTTP 响应,包括标头和正文。
    ///
    /// 自动处理 HEAD 请求,省略正文。
    ///
    /// 除非指定 `transfer_encoding`,否则使用 "content-length"
    /// 标头。
    ///
    /// 如果请求包含正文且连接将被复用,
    /// 则丢弃请求正文,使 Server 处于 `ready` 状态。
    /// 如果丢弃失败,则将连接标记为不再复用,
    /// 且不向上报告错误。
    ///
    /// 断言状态不是 `continue`。
    /// 断言任何标头名称或值中都不存在 "\r\n"。
    pub fn respond(
        request: *Request,
        content: []const u8,
        options: RespondOptions,
    ) ExpectContinueError!void {
        try respondUnflushed(request, content, options);
        try request.server.out.flush();
    }

    pub fn respondUnflushed(
        request: *Request,
        content: []const u8,
        options: RespondOptions,
    ) ExpectContinueError!void {
        assert(options.status != .@"continue");
        if (std.debug.runtime_safety) {
            for (options.extra_headers) |header| {
                assert(header.name.len != 0);
                assert(std.mem.findScalar(u8, header.name, ':') == null);
                assert(std.mem.findPosLinear(u8, header.name, 0, "\r\n") == null);
                assert(std.mem.findPosLinear(u8, header.value, 0, "\r\n") == null);
            }
        }
        try writeExpectContinue(request);

        const transfer_encoding_none = (options.transfer_encoding orelse .chunked) == .none;
        const server_keep_alive = !transfer_encoding_none and options.keep_alive;
        const keep_alive = request.discardBody(server_keep_alive);

        const phrase = options.reason orelse options.status.phrase() orelse "";

        const out = request.server.out;
        try out.print("{s} {d} {s}\r\n", .{
            @tagName(options.version), @backingInt(options.status), phrase,
        });

        switch (options.version) {
            .@"HTTP/1.0" => if (keep_alive) try out.writeAll("connection: keep-alive\r\n"),
            .@"HTTP/1.1" => if (!keep_alive) try out.writeAll("connection: close\r\n"),
        }

        if (options.transfer_encoding) |transfer_encoding| switch (transfer_encoding) {
            .none => {},
            .chunked => try out.writeAll("transfer-encoding: chunked\r\n"),
        } else {
            try out.print("content-length: {d}\r\n", .{content.len});
        }

        for (options.extra_headers) |header| {
            var vecs: [4][]const u8 = .{ header.name, ": ", header.value, "\r\n" };
            try out.writeVecAll(&vecs);
        }

        try out.writeAll("\r\n");

        if (request.head.method != .HEAD) {
            const is_chunked = (options.transfer_encoding orelse .none) == .chunked;
            if (is_chunked) {
                if (content.len > 0) try out.print("{x}\r\n{s}\r\n", .{ content.len, content });
                try out.writeAll("0\r\n\r\n");
            } else if (content.len > 0) {
                try out.writeAll(content);
            }
        }
    }

    pub const RespondStreamingOptions = struct {
        /// 若提供,则响应使用 content-length 头;
        /// 否则使用 transfer-encoding: chunked。
        content_length: ?u64 = null,
        /// 与 `respond` 方法共用的选项。
        respond_options: RespondOptions = .{},
    };

    /// 在调用 `BodyWriter.flush` 或
    /// `BodyWriter.end` 之前,不保证头部已发送。
    ///
    /// 若请求包含正文且连接计划复用,
    /// 则丢弃请求正文,使 Server 保持 `ready` 状态。
    /// 若丢弃失败,连接会标记为不可复用,
    /// 但不会对外报告错误。
    ///
    /// HEAD 请求通过设置
    /// `BodyWriter.elide` 标志透明处理;该标志位于返回的 `BodyWriter` 上,
    /// 使响应流省略正文。不过,调用方也值得检查
    /// 该标志,跳过原本为满足请求而需要执行的
    /// 高开销操作。
    ///
    /// 断言状态不是 `continue`。
    pub fn respondStreaming(
        request: *Request,
        buffer: []u8,
        options: RespondStreamingOptions,
    ) ExpectContinueError!http.BodyWriter {
        try writeExpectContinue(request);
        const o = options.respond_options;
        assert(o.status != .@"continue");
        const transfer_encoding_none = (o.transfer_encoding orelse .chunked) == .none;
        const server_keep_alive = !transfer_encoding_none and o.keep_alive;
        const keep_alive = request.discardBody(server_keep_alive);
        const phrase = o.reason orelse o.status.phrase() orelse "";
        const out = request.server.out;

        try out.print("{s} {d} {s}\r\n", .{
            @tagName(o.version), @backingInt(o.status), phrase,
        });

        switch (o.version) {
            .@"HTTP/1.0" => if (keep_alive) try out.writeAll("connection: keep-alive\r\n"),
            .@"HTTP/1.1" => if (!keep_alive) try out.writeAll("connection: close\r\n"),
        }

        if (o.transfer_encoding) |transfer_encoding| switch (transfer_encoding) {
            .chunked => try out.writeAll("transfer-encoding: chunked\r\n"),
            .none => {},
        } else if (options.content_length) |len| {
            try out.print("content-length: {d}\r\n", .{len});
        } else {
            try out.writeAll("transfer-encoding: chunked\r\n");
        }

        for (o.extra_headers) |header| {
            assert(header.name.len != 0);
            var bufs: [4][]const u8 = .{ header.name, ": ", header.value, "\r\n" };
            try out.writeVecAll(&bufs);
        }

        try out.writeAll("\r\n");
        const elide_body = request.head.method == .HEAD;
        const state: http.BodyWriter.State = if (o.transfer_encoding) |te| switch (te) {
            .chunked => .init_chunked,
            .none => .none,
        } else if (options.content_length) |len| .{
            .content_length = len,
        } else .init_chunked;

        return if (elide_body) .{
            .http_protocol_output = request.server.out,
            .state = state,
            .writer = .{
                .buffer = buffer,
                .vtable = &.{
                    .drain = http.BodyWriter.elidingDrain,
                    .sendFile = http.BodyWriter.elidingSendFile,
                },
            },
        } else .{
            .http_protocol_output = request.server.out,
            .state = state,
            .writer = .{
                .buffer = buffer,
                .vtable = switch (state) {
                    .none => &.{
                        .drain = http.BodyWriter.noneDrain,
                        .sendFile = http.BodyWriter.noneSendFile,
                    },
                    .content_length => &.{
                        .drain = http.BodyWriter.contentLengthDrain,
                        .sendFile = http.BodyWriter.contentLengthSendFile,
                    },
                    .chunk_len => &.{
                        .drain = http.BodyWriter.chunkedDrain,
                        .sendFile = http.BodyWriter.chunkedSendFile,
                    },
                    .end => unreachable,
                },
            },
        };
    }

    pub const UpgradeRequest = union(enum) {
        websocket: ?[]const u8,
        other: []const u8,
        none,
    };

    /// 不会使 `request.head` 失效。
    pub fn upgradeRequested(request: *const Request) UpgradeRequest {
        switch (request.head.version) {
            .@"HTTP/1.0" => return .none,
            .@"HTTP/1.1" => if (request.head.method != .GET) return .none,
        }

        var sec_websocket_key: ?[]const u8 = null;
        var upgrade_name: ?[]const u8 = null;
        var it = request.iterateHeaders();
        while (it.next()) |header| {
            if (std.ascii.eqlIgnoreCase(header.name, "sec-websocket-key")) {
                sec_websocket_key = header.value;
            } else if (std.ascii.eqlIgnoreCase(header.name, "upgrade")) {
                upgrade_name = header.value;
            }
        }

        const name = upgrade_name orelse return .none;
        if (std.ascii.eqlIgnoreCase(name, "websocket")) return .{ .websocket = sec_websocket_key };
        return .{ .other = name };
    }

    pub const WebSocketOptions = struct {
        /// 来自 `UpgradeRequest.websocket` 的值(sec-websocket-key 头字段值)。
        key: []const u8,
        reason: ?[]const u8 = null,
        extra_headers: []const http.Header = &.{},
    };

    /// 只有对返回的结构体调用 `WebSocket.flush` 后,
    /// 才能保证标头已发送。
    pub fn respondWebSocket(request: *Request, options: WebSocketOptions) ExpectContinueError!WebSocket {
        if (request.head.expect != null) return error.HttpExpectationFailed;

        const out = request.server.out;
        const version: http.Version = .@"HTTP/1.1";
        const status: http.Status = .switching_protocols;
        const phrase = options.reason orelse status.phrase() orelse "";

        assert(request.head.version == version);
        assert(request.head.method == .GET);

        var sha1 = std.crypto.hash.Sha1.init(.{});
        sha1.update(options.key);
        sha1.update("258EAFA5-E914-47DA-95CA-C5AB0DC85B11");
        var digest: [std.crypto.hash.Sha1.digest_length]u8 = undefined;
        sha1.final(&digest);
        try out.print("{s} {d} {s}\r\n", .{ @tagName(version), @backingInt(status), phrase });
        try out.writeAll("connection: upgrade\r\nupgrade: websocket\r\nsec-websocket-accept: ");
        const base64_digest = try out.writableArray(28);
        assert(std.base64.standard.Encoder.encode(base64_digest, &digest).len == base64_digest.len);
        try out.writeAll("\r\n");

        for (options.extra_headers) |header| {
            assert(header.name.len != 0);
            var bufs: [4][]const u8 = .{ header.name, ": ", header.value, "\r\n" };
            try out.writeVecAll(&bufs);
        }

        try out.writeAll("\r\n");

        return .{
            .input = request.server.reader.in,
            .output = request.server.out,
            .key = options.key,
        };
    }

    /// 若请求包含 "expect: 100-continue",此
    /// 函数会写入继续传输头部,因此可能发生
    /// 写错误。发送该头部后,将
    /// 请求的 expect 字段设为 `null`。
    ///
    /// 断言此函数只调用一次。
    ///
    /// 不会向服务器输出流写入、不会失败的替代函数
    /// 参见 `readerExpectNone`。
    pub fn readerExpectContinue(request: *Request, buffer: []u8) ExpectContinueError!*Reader {
        const flush = request.head.expect != null;
        try writeExpectContinue(request);
        if (flush) try request.server.out.flush();
        return readerExpectNone(request, buffer);
    }

    /// 断言 expect 标头为 `null`。调用方必须手动处理
    /// 预期内容,并在调用此函数之前将其设为 `null`。
    ///
    /// 断言此函数仅调用一次。
    ///
    /// 使 `Head` 内部的字符串内存失效。
    ///
    pub fn readerExpectNone(request: *Request, buffer: []u8) *Reader {
        assert(request.server.reader.state == .received_head);
        assert(request.head.expect == null);
        request.head.invalidateStrings();
        if (!request.head.method.requestHasBody()) return .ending;
        return request.server.reader.bodyReader(buffer, request.head.transfer_encoding, request.head.content_length);
    }

    pub const ExpectContinueError = error{
        /// 无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。
        WriteFailed,
        /// 客户端发送的 expect HTTP 头字段值
        /// 不是 "100-continue"。
        HttpExpectationFailed,
    };

    pub fn writeExpectContinue(request: *Request) ExpectContinueError!void {
        const expect = request.head.expect orelse return;
        if (!mem.eql(u8, expect, "100-continue")) return error.HttpExpectationFailed;
        try request.server.out.writeAll("HTTP/1.1 100 Continue\r\n\r\n");
        request.head.expect = null;
    }

    /// 返回连接是否应保持持久连接。
    ///
    /// 如果操作将失败,则改为将 Server 状态设置为接收消息体,
    /// 并返回 false。
    fn discardBody(request: *Request, keep_alive: bool) bool {
        // 准备在同一连接上接收下一个请求。
        // 需要考虑两个因素:
        // * 必须丢弃客户端发送的任何正文。
        // * Server 的 read_buffer 中可能已有头部之后
        //   的字节,可能是下一个 HTTP 请求,
        //   也可能是当前请求正文。
        // 若连接不保持存活,这些均无关紧要,
        // 因为发送响应后连接就会断开。
        const r = &request.server.reader;
        if (keep_alive and request.head.keep_alive) switch (r.state) {
            .received_head => {
                if (request.head.method.requestHasBody()) {
                    assert(request.head.transfer_encoding != .none or request.head.content_length != null);
                    const reader_interface = request.readerExpectContinue(&.{}) catch return false;
                    _ = reader_interface.discardRemaining() catch return false;
                    assert(r.state == .ready);
                } else {
                    r.state = .ready;
                }
                return true;
            },
            .body_remaining_content_length, .body_remaining_chunk_len, .body_none, .ready => return true,
            else => unreachable,
        };

        // 若读取流已存在,避免破坏其状态。
        switch (r.state) {
            .received_head => r.state = .closing,
            else => {},
        }
        return false;
    }
};

/// 参见 https://tools.ietf.org/html/rfc6455
pub const WebSocket = struct {
    key: []const u8,
    input: *Reader,
    output: *Writer,

    pub const Header0 = packed struct(u8) {
        opcode: Opcode,
        rsv3: u1 = 0,
        rsv2: u1 = 0,
        rsv1: u1 = 0,
        fin: bool,
    };

    pub const Header1 = packed struct(u8) {
        payload_len: enum(u7) {
            len16 = 126,
            len64 = 127,
            _,
        },
        mask: bool,
    };

    pub const Opcode = enum(u4) {
        continuation = 0,
        text = 1,
        binary = 2,
        connection_close = 8,
        ping = 9,
        /// "可以主动发送 Pong 帧,用作单向
        /// 心跳。接收方无需响应主动发送的 Pong 帧。"
        pong = 10,
        _,
    };

    pub const ReadSmallTextMessageError = error{
        ConnectionClose,
        UnexpectedOpCode,
        MessageOversize,
        MissingMaskBit,
        ReadFailed,
        EndOfStream,
    };

    pub const SmallMessage = struct {
        /// 可以是文本、二进制或 ping。
        opcode: Opcode,
        data: []u8,
    };

    /// 读取 WebSocket 流中的下一条消息;如果
    /// 输入缓冲区无法容纳消息,则失败。返回内存指向
    /// 输入缓冲区,并在下次读取时失效。
    pub fn readSmallMessage(ws: *WebSocket) ReadSmallTextMessageError!SmallMessage {
        const in = ws.input;
        while (true) {
            const header = try in.takeArray(2);
            const h0: Header0 = @bitCast(header[0]);
            const h1: Header1 = @bitCast(header[1]);

            switch (h0.opcode) {
                .text, .binary, .pong, .ping => {},
                .connection_close => return error.ConnectionClose,
                .continuation => return error.UnexpectedOpCode,
                _ => return error.UnexpectedOpCode,
            }

            if (!h0.fin) return error.MessageOversize;
            if (!h1.mask) return error.MissingMaskBit;

            const len: usize = switch (h1.payload_len) {
                .len16 => try in.takeInt(u16, .big),
                .len64 => std.math.cast(usize, try in.takeInt(u64, .big)) orelse return error.MessageOversize,
                else => @backingInt(h1.payload_len),
            };
            if (len > in.buffer.len) return error.MessageOversize;
            const mask: [4]u8 = (try in.takeArray(4)).*;
            const payload = try in.take(len);

            // 跳过 pong。
            if (h0.opcode == .pong) continue;

            // 最后一项可能包含不足一个字的未使用数据。
            const floored_len = (payload.len / 4) * 4;

            const payload_chunks: [][4]u8 = @ptrCast(payload[0..floored_len]);
            for (payload_chunks) |*chunk| {
                const mask_i: u32 = @bitCast(mask);
                const chunk_i: u32 = @bitCast(chunk.*);
                chunk.* = @bitCast(chunk_i ^ mask_i);
            }
            for (payload[floored_len..], mask[0 .. payload.len - floored_len]) |*leftover, m| {
                leftover.* ^= m;
            }

            return .{
                .opcode = h0.opcode,
                .data = payload,
            };
        }
    }

    pub fn writeMessage(ws: *WebSocket, data: []const u8, op: Opcode) Writer.Error!void {
        var bufs: [1][]const u8 = .{data};
        try writeMessageVecUnflushed(ws, &bufs, op);
        try ws.output.flush();
    }

    pub fn writeMessageUnflushed(ws: *WebSocket, data: []const u8, op: Opcode) Writer.Error!void {
        var bufs: [1][]const u8 = .{data};
        try writeMessageVecUnflushed(ws, &bufs, op);
    }

    pub fn writeMessageVec(ws: *WebSocket, data: [][]const u8, op: Opcode) Writer.Error!void {
        try writeMessageVecUnflushed(ws, data, op);
        try ws.output.flush();
    }

    pub fn writeMessageVecUnflushed(ws: *WebSocket, data: [][]const u8, op: Opcode) Writer.Error!void {
        const total_len = l: {
            var total_len: u64 = 0;
            for (data) |iovec| total_len += iovec.len;
            break :l total_len;
        };
        const out = ws.output;
        try out.writeByte(@bitCast(@as(Header0, .{
            .opcode = op,
            .fin = true,
        })));
        switch (total_len) {
            0...125 => try out.writeByte(@bitCast(@as(Header1, .{
                .payload_len = @fromBackingInt(@intCast(total_len)),
                .mask = false,
            }))),
            126...0xffff => {
                try out.writeByte(@bitCast(@as(Header1, .{
                    .payload_len = .len16,
                    .mask = false,
                })));
                try out.writeInt(u16, @intCast(total_len), .big);
            },
            else => {
                try out.writeByte(@bitCast(@as(Header1, .{
                    .payload_len = .len64,
                    .mask = false,
                })));
                try out.writeInt(u64, total_len, .big);
            },
        }
        try out.writeVecAll(data);
    }

    pub fn flush(ws: *WebSocket) Writer.Error!void {
        try ws.output.flush();
    }
};