跳转到内容
标准库Zig 0.17.0官方原文
源码std/http.zig

第 1 行

std.http.assert

别名

第 3 行

别名目标 std.debug.assert

std.http.BodyWriter

容器

第 743 行

请求或响应正文。

字段

http_protocol_output: *Writer

在 BodyWriter 的生存期结束前, 除通过 BodyWriter 方法外,禁止修改此对象状态。

state: State
writer: Writer

std.http.BodyWriter.chunk_header_template

常量

第 755 行

std.http.BodyWriter.chunk_len_digits

常量

第 753 行

为十六进制编码的分块长度预留的零的数量。

std.http.BodyWriter.chunkedDrain

函数

第 997 行

pub fn chunkedDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize

参数

w: *Writer
data: []const []const u8
splat: usize

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.chunkedSendFile

函数

第 961 行

pub fn chunkedSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize

参数

w: *Writer
file_reader: *File.Reader
limit: std.Io.Limit

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.http.BodyWriter.contentLengthDrain

函数

第 886 行

pub fn contentLengthDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize

参数

w: *Writer
data: []const []const u8
splat: usize

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.contentLengthSendFile

函数

第 952 行

pub fn contentLengthSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize

参数

w: *Writer
file_reader: *File.Reader
limit: std.Io.Limit

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.http.BodyWriter.elidingDrain

函数

第 903 行

pub fn elidingDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize

参数

w: *Writer
data: []const []const u8
splat: usize

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.elidingSendFile

函数

第 917 行

pub fn elidingSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize

参数

w: *Writer
file_reader: *File.Reader
limit: std.Io.Limit

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.http.BodyWriter.end

函数

第 801 行

使用 content-length 时,断言已发送数据量与 标头中的值一致,然后刷新 http_protocol_output。

使用 transfer-encoding: chunked 时,写入带有空尾部字段的 流结束消息,然后将流刷新到系统。断言所有 已开始的块都已完整结束。

遵循 isEliding 的值,按需省略标头之后的全部数据。

另请参见:

  • endUnflushed
  • endChunked
pub fn end(w: *BodyWriter) Error!void

参数

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.endChunked

函数

第 846 行

写入流结束消息和任何可选尾部字段,并刷新 底层流。

断言 BodyWriter 正在使用 transfer-encoding: chunked。

遵循 isEliding 的值,以省略标头之后的所有数据。

另见:

  • endChunkedUnflushed
  • end
pub fn endChunked(w: *BodyWriter, options: EndChunkedOptions) Error!void

参数

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.EndChunkedOptions

容器

第 832 行

字段

trailers: []const Header = &.{}

std.http.BodyWriter.endChunkedUnflushed

函数

第 863 行

写入流结束消息及可选尾部字段。

不执行刷新。

断言 BodyWriter 使用 transfer-encoding: chunked。

遵循 isEliding 的值,按需省略标头之后的全部数据。

另请参见:

  • endChunked
  • endUnflushed
  • end
pub fn endChunkedUnflushed(w: *BodyWriter, options: EndChunkedOptions) Error!void

参数

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.endUnflushed

函数

第 819 行

使用 content-length 时,断言已发送数据量与 标头中的值一致。

否则使用 transfer-encoding: chunked,写入 带有空尾部字段的流结束消息。

遵循 isEliding 的值,按需省略标头之后的全部数据。

不刷新 http_protocol_output,但会刷新 writer。

另请参见:

  • end
  • endChunked
pub fn endUnflushed(w: *BodyWriter) Error!void

参数

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.Error

别名

第 750 行

别名目标 std.Io.Writer.Error

std.http.BodyWriter.flush

函数

第 782 行

通过 BodyWriter.http_protocol_output 发送所有缓冲数据。

pub fn flush(w: *BodyWriter) Error!void

参数

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.isEliding

函数

第 777 行

pub fn isEliding(w: *const BodyWriter) bool

参数

w: *const BodyWriter

std.http.BodyWriter.max_chunk_len

常量

第 754 行

usize

std.http.BodyWriter.noneDrain

函数

第 895 行

pub fn noneDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize

参数

w: *Writer
data: []const []const u8
splat: usize

错误

WriteFailed Error

详细诊断信息见 Writer 实现。

std.http.BodyWriter.noneSendFile

函数

第 944 行

如果无法在不执行系统调用的前提下计算大小,则返回 null。

pub fn noneSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize

参数

w: *Writer
file_reader: *File.Reader
limit: std.Io.Limit

错误

EndOfStream

已到达正在读取的文件末尾。

ReadFailed

详细诊断信息位于 File.Reader 结构体上。

Unimplemented

表示调用方应自行读取文件;被调用方无法 提供更高效的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.http.BodyWriter.State

容器

第 761 行

字段

none

连接结束表示流结束。

content_length: u64

作为调试工具,每写入一个字节便递减,直到零。

chunk_len: usize

每个数据块都由头部及尾部包装。 此长度是下一个头部之前 要写入的字节数,其中为 \r\n 尾部额外计入 +2, 流起始处该值为零。

end

流已正常结束;连接可以复用。

std.http.BodyWriter.State.init_chunked

常量

第 774 行

State

std.http.BodyWriter.writeHex

函数

第 1026 行

将整数以十六进制右对齐写入 buf,假定 缓冲区已填零。

fn writeHex(buf: []u8, x: usize) void

参数

buf: []u8
x: usize

std.http.builtin

常量

第 1 行

std.http.ChunkParser

别名

第 10 行

别名目标 std.http.ChunkParser

std.http.Client

别名

第 7 行

别名目标 std.http.Client

std.http.Connection

容器

第 308 行

字段

keep_alive
close

std.http.ContentEncoding

容器

第 279 行

字段

zstd
gzip
deflate
compress
identity

std.http.ContentEncoding.fromString

函数

第 286 行

pub fn fromString(s: []const u8) ?ContentEncoding

参数

s: []const u8

std.http.ContentEncoding.minBufferCapacity

函数

第 299 行

pub fn minBufferCapacity(ce: ContentEncoding) usize

参数

std.http.Decompress

容器

第 709 行

字段

std.http.Decompress.init

函数

第 714 行

pub fn init( decompress: *Decompress, transfer_reader: *std.Io.Reader, buffer: []u8, content_encoding: ContentEncoding, ) *std.Io.Reader

参数

decompress: *Decompress
transfer_reader: *std.Io.Reader
buffer: []u8
content_encoding: ContentEncoding

std.http.File

别名

第 5 行

别名目标 std.Io.File

std.http.Header

容器

第 313 行

字段

name: []const u8
value: []const u8

std.http.HeaderIterator

别名

第 11 行

别名目标 std.http.HeaderIterator

std.http.HeadParser

别名

第 9 行

别名目标 std.http.HeadParser

std.http.Method

容器

第 25 行

字段

GET
HEAD
POST
PUT
DELETE
CONNECT
OPTIONS
TRACE
PATCH
QUERY

std.http.Method.cacheable

函数

第 87 行

可缓存的响应可存储起来,以便之后取用, 从而省去向服务器发起新请求。

https://developer.mozilla.org/en-US/docs/Glossary/cacheable

https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.3

pub fn cacheable(m: Method) bool

参数

m: Method

std.http.Method.idempotent

函数

第 74 行

若相同请求执行一次或连续执行多次,效果相同,且服务器最终保持相同状态,则该 HTTP 方法是幂等的。

https://developer.mozilla.org/en-US/docs/Glossary/Idempotent

https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2

pub fn idempotent(m: Method) bool

参数

m: Method

std.http.Method.requestHasBody

函数

第 39 行

若此方法的请求允许包含消息体,返回 true。 服务器的实际行为可能不同,仍应检查。

pub fn requestHasBody(m: Method) bool

参数

m: Method

std.http.Method.responseHasBody

函数

第 48 行

若此方法的响应允许包含消息体,返回 true。 客户端的实际行为可能不同,仍应检查。

pub fn responseHasBody(m: Method) bool

参数

m: Method

std.http.Method.safe

函数

第 60 行

pub fn safe(m: Method) bool

参数

m: Method

std.http.Reader

容器

第 318 行

字段

in: *std.Io.Reader
interface: std.Io.Reader

这是可能由 bodyReader 使用的预分配内存。 该函数可能返回指向此字段的指针,也可能返回其他 *std.Io.Reader。建议不要直接访问此字段。

state: State

跟踪流是否已准备好接受新请求,使无效 API 用法触发断言失败,而非违反 HTTP 协议。

trailers: []const u8 = &.{}

HTTP 尾部字段字节,位于 transfer-encoding: chunked 消息的末尾。仅在调用某个 “end”函数后可用,指向 in 的缓冲区内的数据, 因此下一次调用 receiveHead 或以其他方式从 in 读取时会失效。

body_err: ?BodyError = null
max_head_len: usize

std.http.Reader.BodyError

错误集合

第 365 行

错误

HttpChunkInvalid
HttpChunkTruncated
HttpHeadersOversize

std.http.Reader.bodyReader

函数

第 426 行

若已协商压缩消息体,则返回压缩后的字节。

断言仅调用一次,且位于 receiveHead 之后。

另见:

  • interfaceDecompressing
pub fn bodyReader( reader: *Reader, transfer_buffer: []u8, transfer_encoding: TransferEncoding, content_length: ?u64, ) *std.Io.Reader

参数

reader: *Reader
transfer_buffer: []u8
transfer_encoding: TransferEncoding
content_length: ?u64

std.http.Reader.bodyReaderDecompressing

函数

第 474 行

如果已协商使用压缩消息体,则返回解压后的字节。

断言仅调用一次,且在 receiveHead 之后调用。

另请参见:

  • interface
pub fn bodyReaderDecompressing( reader: *Reader, transfer_buffer: []u8, transfer_encoding: TransferEncoding, content_length: ?u64, content_encoding: ContentEncoding, decompress: *Decompress, decompress_buffer: []u8, ) *std.Io.Reader

参数

reader: *Reader
transfer_buffer: []u8
transfer_encoding: TransferEncoding
content_length: ?u64
content_encoding: ContentEncoding
decompress: *Decompress
decompress_buffer: []u8

std.http.Reader.chunkedDiscard

函数

第 610 行

fn chunkedDiscard(io_r: *std.Io.Reader, limit: std.Io.Limit) std.Io.Reader.Error!usize

参数

io_r: *std.Io.Reader
limit: std.Io.Limit

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.http.Reader.chunkedDiscardEndless

函数

第 630 行

fn chunkedDiscardEndless( reader: *Reader, limit: std.Io.Limit, chunk_len_ptr: *RemainingChunkLen, ) (BodyError || std.Io.Reader.Error)!usize

参数

reader: *Reader
limit: std.Io.Limit
chunk_len_ptr: *RemainingChunkLen

std.http.Reader.chunkedReadEndless

函数

第 561 行

fn chunkedReadEndless( reader: *Reader, w: *Writer, limit: std.Io.Limit, chunk_len_ptr: *RemainingChunkLen, ) (BodyError || std.Io.Reader.StreamError)!usize

参数

reader: *Reader
w: *Writer
limit: std.Io.Limit
chunk_len_ptr: *RemainingChunkLen

std.http.Reader.chunkedStream

函数

第 541 行

fn chunkedStream(io_r: *std.Io.Reader, w: *Writer, limit: std.Io.Limit) std.Io.Reader.StreamError!usize

参数

io_r: *std.Io.Reader
w: *Writer
limit: std.Io.Limit

错误

EndOfStream

Reader 指示流结束。此错误不会从 Writer 产生。

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Reader.contentLengthDiscard

函数

第 527 行

fn contentLengthDiscard(io_r: *std.Io.Reader, limit: std.Io.Limit) std.Io.Reader.Error!usize

参数

io_r: *std.Io.Reader
limit: std.Io.Limit

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.http.Reader.contentLengthStream

函数

第 509 行

fn contentLengthStream( io_r: *std.Io.Reader, w: *Writer, limit: std.Io.Limit, ) std.Io.Reader.StreamError!usize

参数

io_r: *std.Io.Reader
w: *Writer
limit: std.Io.Limit

错误

EndOfStream

Reader 指示流结束。此错误不会从 Writer 产生。

ReadFailed

详细诊断参见 Reader 的实现。

WriteFailed

详细诊断信息见 Writer 实现。

std.http.Reader.HeadError

错误集合

第 371 行

错误

HttpConnectionClosing

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

HttpHeadersOversize

HTTP 头部字节数过多。

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

HttpRequestTruncated

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

ReadFailed

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

std.http.Reader.parseTrailers

函数

第 680 行

当流中接下来的字节为尾部字段,或用于表示分块消息体结束的 "\r\n" 时, 调用此函数。

fn parseTrailers(reader: *Reader, amt_read: usize) (BodyError || std.Io.Reader.Error)!usize

参数

reader: *Reader
amt_read: usize

std.http.Reader.receiveHead

函数

第 391 行

将整个头部缓存在 in 中。

后续任何消费输入流的操作都会使结果内存失效。

pub fn receiveHead(reader: *Reader) HeadError![]const u8

参数

reader: *Reader

错误

HttpConnectionClosing

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

HttpHeadersOversize

HTTP 头部字节数过多。

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

HttpRequestTruncated

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

ReadFailed

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

std.http.Reader.RemainingChunkLen

容器

第 337 行

字段

head = 0
n = 1
rn = 2
_

std.http.Reader.RemainingChunkLen.init

函数

第 343 行

pub fn init(integer: u64) RemainingChunkLen

参数

integer: u64

std.http.Reader.RemainingChunkLen.int

函数

第 347 行

pub fn int(rcl: RemainingChunkLen) u64

参数

std.http.Reader.State

容器

第 352 行

字段

ready

该流可供首次使用或再次使用。

received_head
body_none

流将持续到连接关闭。

body_remaining_content_length: u64
body_remaining_chunk_len: RemainingChunkLen
closing

流本可以接受另一个 HTTP 请求,但客户端和服务器未协商持久连接。

std.http.Server

别名

第 8 行

别名目标 std.http.Server

std.http.Status

容器

第 96 行

字段

@"continue" = 100
switching_protocols = 101
processing = 102
early_hints = 103
ok = 200
created = 201
accepted = 202
non_authoritative_info = 203
no_content = 204
reset_content = 205
partial_content = 206
multi_status = 207
already_reported = 208
im_used = 226
multiple_choice = 300
moved_permanently = 301
found = 302
see_other = 303
not_modified = 304
use_proxy = 305
temporary_redirect = 307
permanent_redirect = 308
bad_request = 400
unauthorized = 401
payment_required = 402
forbidden = 403
not_found = 404
method_not_allowed = 405
not_acceptable = 406
proxy_auth_required = 407
request_timeout = 408
conflict = 409
gone = 410
length_required = 411
precondition_failed = 412
payload_too_large = 413
uri_too_long = 414
unsupported_media_type = 415
range_not_satisfiable = 416
expectation_failed = 417
teapot = 418
misdirected_request = 421
unprocessable_entity = 422
locked = 423
failed_dependency = 424
too_early = 425
upgrade_required = 426
precondition_required = 428
too_many_requests = 429
request_header_fields_too_large = 431
unavailable_for_legal_reasons = 451
internal_server_error = 500
not_implemented = 501
bad_gateway = 502
service_unavailable = 503
gateway_timeout = 504
http_version_not_supported = 505
variant_also_negotiates = 506
insufficient_storage = 507
loop_detected = 508
not_extended = 510
network_authentication_required = 511
_

std.http.Status.class

函数

第 252 行

pub fn class(self: Status) Class

参数

self: Status

std.http.Status.Class

容器

第 244 行

字段

informational
success
redirect
client_error
server_error

std.http.Status.phrase

函数

第 166 行

pub fn phrase(self: Status) ?[]const u8

参数

self: Status

std.http.std

别名

第 2 行

别名目标 std

std.http.TransferEncoding

容器

第 274 行

此处有意省略压缩,因为它由 ContentEncoding 处理。

字段

chunked
none

std.http.Version

容器

第 13 行

字段

@"HTTP/1.0"
@"HTTP/1.1"

std.http.Writer

别名

第 4 行

别名目标 std.Io.Writer

源码

std/http.zig

const builtin = @import("builtin");
const std = @import("std.zig");
const assert = std.debug.assert;
const Writer = std.Io.Writer;
const File = std.Io.File;

pub const Client = @import("http/Client.zig");
pub const Server = @import("http/Server.zig");
pub const HeadParser = @import("http/HeadParser.zig");
pub const ChunkParser = @import("http/ChunkParser.zig");
pub const HeaderIterator = @import("http/HeaderIterator.zig");

pub const Version = enum {
    @"HTTP/1.0",
    @"HTTP/1.1",
};

/// https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
///
/// https://datatracker.ietf.org/doc/html/rfc7231#section-4 初始定义
///
/// https://datatracker.ietf.org/doc/html/rfc5789#section-2 PATCH
///
/// https://datatracker.ietf.org/doc/html/rfc10008#name-query-method QUERY
pub const Method = enum {
    GET,
    HEAD,
    POST,
    PUT,
    DELETE,
    CONNECT,
    OPTIONS,
    TRACE,
    PATCH,
    QUERY,

    /// 若此方法的请求允许包含消息体,返回 true。
    /// 服务器的实际行为可能不同,仍应检查。
    pub fn requestHasBody(m: Method) bool {
        return switch (m) {
            .POST, .PUT, .PATCH, .QUERY => true,
            .GET, .HEAD, .DELETE, .CONNECT, .OPTIONS, .TRACE => false,
        };
    }

    /// 若此方法的响应允许包含消息体,返回 true。
    /// 客户端的实际行为可能不同,仍应检查。
    pub fn responseHasBody(m: Method) bool {
        return switch (m) {
            .GET, .POST, .PUT, .DELETE, .CONNECT, .OPTIONS, .PATCH, .QUERY => true,
            .HEAD, .TRACE => false,
        };
    }

    /// 若 HTTP 方法不会改变服务器状态,则该方法是安全的。
    ///
    /// https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP
    ///
    /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.1
    pub fn safe(m: Method) bool {
        return switch (m) {
            .GET, .HEAD, .OPTIONS, .TRACE, .QUERY => true,
            .POST, .PUT, .DELETE, .CONNECT, .PATCH => false,
        };
    }

    /// 若相同请求执行一次或连续执行多次,效果相同,且服务器最终保持相同状态,则该 HTTP 方法是幂等的。
    ///
    /// https://developer.mozilla.org/en-US/docs/Glossary/Idempotent
    ///
    /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2
    ///
    ///
    pub fn idempotent(m: Method) bool {
        return switch (m) {
            .GET, .HEAD, .PUT, .DELETE, .OPTIONS, .TRACE, .QUERY => true,
            .CONNECT, .POST, .PATCH => false,
        };
    }

    /// 可缓存的响应可存储起来,以便之后取用,
    /// 从而省去向服务器发起新请求。
    ///
    /// https://developer.mozilla.org/en-US/docs/Glossary/cacheable
    ///
    /// https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.3
    pub fn cacheable(m: Method) bool {
        return switch (m) {
            .GET, .HEAD, .QUERY => true,
            .POST, .PUT, .DELETE, .CONNECT, .OPTIONS, .TRACE, .PATCH => false,
        };
    }
};

/// https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
pub const Status = enum(u10) {
    @"continue" = 100, // RFC7231 第 6.2.1 节
    switching_protocols = 101, // RFC7231,第 6.2.2 节
    processing = 102, // RFC2518
    early_hints = 103, // RFC8297

    ok = 200, // RFC7231,第 6.3.1 节
    created = 201, // RFC7231 第 6.3.2 节
    accepted = 202, // RFC7231,第 6.3.3 节
    non_authoritative_info = 203, // RFC7231,第 6.3.4 节
    no_content = 204, // RFC7231 第 6.3.5 节
    reset_content = 205, // RFC7231,第 6.3.6 节
    partial_content = 206, // RFC7233 第 4.1 节
    multi_status = 207, // RFC4918
    already_reported = 208, // RFC5842
    im_used = 226, // RFC3229

    multiple_choice = 300, // RFC7231,第 6.4.1 节
    moved_permanently = 301, // RFC7231 第 6.4.2 节
    found = 302, // RFC7231,第 6.4.3 节
    see_other = 303, // RFC7231,第 6.4.4 节
    not_modified = 304, // RFC7232,第 4.1 节
    use_proxy = 305, // RFC7231 第 6.4.5 节
    temporary_redirect = 307, // RFC7231,第 6.4.7 节
    permanent_redirect = 308, // RFC7538

    bad_request = 400, // RFC7231,第 6.5.1 节
    unauthorized = 401, // RFC7235,第 3.1 节
    payment_required = 402, // RFC7231 第 6.5.2 节
    forbidden = 403, // RFC7231,第 6.5.3 节
    not_found = 404, // RFC7231,第 6.5.4 节
    method_not_allowed = 405, // RFC7231 第 6.5.5 节
    not_acceptable = 406, // RFC7231,第 6.5.6 节
    proxy_auth_required = 407, // RFC7235 第 3.2 节
    request_timeout = 408, // RFC7231,第 6.5.7 节
    conflict = 409, // RFC7231 第 6.5.8 节
    gone = 410, // RFC7231,第 6.5.9 节
    length_required = 411, // RFC7231 第 6.5.10 节
    precondition_failed = 412, // RFC7232,第 4.2 节][RFC8144,第 3.2 节
    payload_too_large = 413, // RFC7231,第 6.5.11 节
    uri_too_long = 414, // RFC7231,第 6.5.12 节
    unsupported_media_type = 415, // RFC7231,第 6.5.13 节][RFC7694,第 3 节
    range_not_satisfiable = 416, // RFC7233,第 4.4 节
    expectation_failed = 417, // RFC7231 第 6.5.14 节
    teapot = 418, // RFC 7168,第 2.3.3 节
    misdirected_request = 421, // RFC7540,第 9.1.2 节
    unprocessable_entity = 422, // RFC4918
    locked = 423, // RFC4918
    failed_dependency = 424, // RFC4918
    too_early = 425, // RFC8470
    upgrade_required = 426, // RFC7231,第 6.5.15 节
    precondition_required = 428, // RFC6585
    too_many_requests = 429, // RFC6585
    request_header_fields_too_large = 431, // RFC6585
    unavailable_for_legal_reasons = 451, // RFC7725

    internal_server_error = 500, // RFC7231 第 6.6.1 节
    not_implemented = 501, // RFC7231,第 6.6.2 节
    bad_gateway = 502, // RFC7231,第 6.6.3 节
    service_unavailable = 503, // RFC7231 第 6.6.4 节
    gateway_timeout = 504, // RFC7231,第 6.6.5 节
    http_version_not_supported = 505, // RFC7231,第 6.6.6 节
    variant_also_negotiates = 506, // RFC2295
    insufficient_storage = 507, // RFC4918
    loop_detected = 508, // RFC5842
    not_extended = 510, // RFC2774
    network_authentication_required = 511, // RFC6585

    _,

    pub fn phrase(self: Status) ?[]const u8 {
        return switch (self) {
            // 1xx 状态码
            .@"continue" => "Continue",
            .switching_protocols => "Switching Protocols",
            .processing => "Processing",
            .early_hints => "Early Hints",

            // 2xx 状态码
            .ok => "OK",
            .created => "Created",
            .accepted => "Accepted",
            .non_authoritative_info => "Non-Authoritative Information",
            .no_content => "No Content",
            .reset_content => "Reset Content",
            .partial_content => "Partial Content",
            .multi_status => "Multi-Status",
            .already_reported => "Already Reported",
            .im_used => "IM Used",

            // 3xx 状态码
            .multiple_choice => "Multiple Choice",
            .moved_permanently => "Moved Permanently",
            .found => "Found",
            .see_other => "See Other",
            .not_modified => "Not Modified",
            .use_proxy => "Use Proxy",
            .temporary_redirect => "Temporary Redirect",
            .permanent_redirect => "Permanent Redirect",

            // 4xx 状态码
            .bad_request => "Bad Request",
            .unauthorized => "Unauthorized",
            .payment_required => "Payment Required",
            .forbidden => "Forbidden",
            .not_found => "Not Found",
            .method_not_allowed => "Method Not Allowed",
            .not_acceptable => "Not Acceptable",
            .proxy_auth_required => "Proxy Authentication Required",
            .request_timeout => "Request Timeout",
            .conflict => "Conflict",
            .gone => "Gone",
            .length_required => "Length Required",
            .precondition_failed => "Precondition Failed",
            .payload_too_large => "Payload Too Large",
            .uri_too_long => "URI Too Long",
            .unsupported_media_type => "Unsupported Media Type",
            .range_not_satisfiable => "Range Not Satisfiable",
            .expectation_failed => "Expectation Failed",
            .teapot => "I'm a teapot",
            .misdirected_request => "Misdirected Request",
            .unprocessable_entity => "Unprocessable Entity",
            .locked => "Locked",
            .failed_dependency => "Failed Dependency",
            .too_early => "Too Early",
            .upgrade_required => "Upgrade Required",
            .precondition_required => "Precondition Required",
            .too_many_requests => "Too Many Requests",
            .request_header_fields_too_large => "Request Header Fields Too Large",
            .unavailable_for_legal_reasons => "Unavailable For Legal Reasons",

            // 5xx 状态码
            .internal_server_error => "Internal Server Error",
            .not_implemented => "Not Implemented",
            .bad_gateway => "Bad Gateway",
            .service_unavailable => "Service Unavailable",
            .gateway_timeout => "Gateway Timeout",
            .http_version_not_supported => "HTTP Version Not Supported",
            .variant_also_negotiates => "Variant Also Negotiates",
            .insufficient_storage => "Insufficient Storage",
            .loop_detected => "Loop Detected",
            .not_extended => "Not Extended",
            .network_authentication_required => "Network Authentication Required",

            else => return null,
        };
    }

    pub const Class = enum {
        informational,
        success,
        redirect,
        client_error,
        server_error,
    };

    pub fn class(self: Status) Class {
        return switch (@backingInt(self)) {
            100...199 => .informational,
            200...299 => .success,
            300...399 => .redirect,
            400...499 => .client_error,
            else => .server_error,
        };
    }

    test {
        try std.testing.expectEqualStrings("OK", Status.ok.phrase().?);
        try std.testing.expectEqualStrings("Not Found", Status.not_found.phrase().?);
    }

    test {
        try std.testing.expectEqual(Status.Class.success, Status.ok.class());
        try std.testing.expectEqual(Status.Class.client_error, Status.not_found.class());
    }
};

/// 此处有意省略压缩,因为它由 `ContentEncoding` 处理。
pub const TransferEncoding = enum {
    chunked,
    none,
};

pub const ContentEncoding = enum {
    zstd,
    gzip,
    deflate,
    compress,
    identity,

    pub fn fromString(s: []const u8) ?ContentEncoding {
        const map = std.StaticStringMap(ContentEncoding).initComptime(.{
            .{ "zstd", .zstd },
            .{ "gzip", .gzip },
            .{ "x-gzip", .gzip },
            .{ "deflate", .deflate },
            .{ "compress", .compress },
            .{ "x-compress", .compress },
            .{ "identity", .identity },
        });
        return map.get(s);
    }

    pub fn minBufferCapacity(ce: ContentEncoding) usize {
        return switch (ce) {
            .zstd => std.compress.zstd.default_window_len,
            .gzip, .deflate => std.compress.flate.max_window_len,
            .compress, .identity => 0,
        };
    }
};

pub const Connection = enum {
    keep_alive,
    close,
};

pub const Header = struct {
    name: []const u8,
    value: []const u8,
};

pub const Reader = struct {
    in: *std.Io.Reader,
    /// 这是可能由 `bodyReader` 使用的预分配内存。
    /// 该函数可能返回指向此字段的指针,也可能返回其他
    /// `*std.Io.Reader`。建议不要直接访问此字段。
    interface: std.Io.Reader,
    /// 跟踪流是否已准备好接受新请求,使无效 API 用法触发断言失败,而非违反 HTTP 协议。
    ///
    ///
    state: State,
    /// HTTP 尾部字段字节,位于 transfer-encoding:
    /// chunked 消息的末尾。仅在调用某个
    /// “end”函数后可用,指向 `in` 的缓冲区内的数据,
    /// 因此下一次调用 `receiveHead` 或以其他方式从
    /// `in` 读取时会失效。
    trailers: []const u8 = &.{},
    body_err: ?BodyError = null,
    max_head_len: usize,

    pub const RemainingChunkLen = enum(u64) {
        head = 0,
        n = 1,
        rn = 2,
        _,

        pub fn init(integer: u64) RemainingChunkLen {
            return @fromBackingInt(@intCast(integer));
        }

        pub fn int(rcl: RemainingChunkLen) u64 {
            return @backingInt(rcl);
        }
    };

    pub const State = union(enum) {
        /// 该流可供首次使用或再次使用。
        ready,
        received_head,
        /// 流将持续到连接关闭。
        body_none,
        body_remaining_content_length: u64,
        body_remaining_chunk_len: RemainingChunkLen,
        /// 流本可以接受另一个 HTTP 请求,但客户端和服务器未协商持久连接。
        ///
        closing,
    };

    pub const BodyError = error{
        HttpChunkInvalid,
        HttpChunkTruncated,
        HttpHeadersOversize,
    };

    pub const HeadError = error{
        /// HTTP 头部字节数过多。
        ///
        /// HTTP 规范建议在关闭连接前
        /// 响应状态码 431。
        HttpHeadersOversize,
        /// 收到部分 HTTP 请求,但在完整接收头部之前
        /// 连接已关闭。
        HttpRequestTruncated,
        /// 客户端在关闭流之前未发送任何头部字节。
        /// 这发生在保活连接最终关闭时。
        HttpConnectionClosing,
        /// 读取 `in` 时出现传递性错误。
        ReadFailed,
    };

    /// 将整个头部缓存在 `in` 中。
    ///
    /// 后续任何消费输入流的操作都会使结果内存失效。
    ///
    pub fn receiveHead(reader: *Reader) HeadError![]const u8 {
        reader.trailers = &.{};
        const in = reader.in;
        const max_head_len = reader.max_head_len;
        var hp: HeadParser = .{};
        var head_len: usize = 0;
        while (true) {
            if (head_len >= max_head_len) return error.HttpHeadersOversize;
            const remaining = in.buffered()[head_len..];
            if (remaining.len == 0) {
                in.fillMore() catch |err| switch (err) {
                    error.EndOfStream => switch (head_len) {
                        0 => return error.HttpConnectionClosing,
                        else => return error.HttpRequestTruncated,
                    },
                    error.ReadFailed => |e| return e,
                };
                continue;
            }
            head_len += hp.feed(remaining);
            if (hp.state == .finished) {
                reader.state = .received_head;
                const head_buffer = in.buffered()[0..head_len];
                in.toss(head_len);
                return head_buffer;
            }
        }
    }

    /// 若已协商压缩消息体,则返回压缩后的字节。
    ///
    /// 断言仅调用一次,且位于 `receiveHead` 之后。
    ///
    /// 另见:
    /// * `interfaceDecompressing`
    pub fn bodyReader(
        reader: *Reader,
        transfer_buffer: []u8,
        transfer_encoding: TransferEncoding,
        content_length: ?u64,
    ) *std.Io.Reader {
        assert(reader.state == .received_head);
        switch (transfer_encoding) {
            .chunked => {
                reader.state = .{ .body_remaining_chunk_len = .head };
                reader.interface = .{
                    .buffer = transfer_buffer,
                    .seek = 0,
                    .end = 0,
                    .vtable = &.{
                        .stream = chunkedStream,
                        .discard = chunkedDiscard,
                    },
                };
                return &reader.interface;
            },
            .none => {
                if (content_length) |len| {
                    reader.state = if (len == 0) .ready else .{ .body_remaining_content_length = len };
                    reader.interface = .{
                        .buffer = transfer_buffer,
                        .seek = 0,
                        .end = 0,
                        .vtable = &.{
                            .stream = contentLengthStream,
                            .discard = contentLengthDiscard,
                        },
                    };
                    return &reader.interface;
                } else {
                    reader.state = .body_none;
                    return reader.in;
                }
            },
        }
    }

    /// 如果已协商使用压缩消息体,则返回解压后的字节。
    ///
    /// 断言仅调用一次,且在 `receiveHead` 之后调用。
    ///
    /// 另请参见:
    /// * `interface`
    pub fn bodyReaderDecompressing(
        reader: *Reader,
        transfer_buffer: []u8,
        transfer_encoding: TransferEncoding,
        content_length: ?u64,
        content_encoding: ContentEncoding,
        decompress: *Decompress,
        decompress_buffer: []u8,
    ) *std.Io.Reader {
        if (transfer_encoding == .none and content_length == null) {
            assert(reader.state == .received_head);
            reader.state = .body_none;
            switch (content_encoding) {
                .identity => {
                    return reader.in;
                },
                .deflate => {
                    decompress.* = .{ .flate = .init(reader.in, .zlib, decompress_buffer) };
                    return &decompress.flate.reader;
                },
                .gzip => {
                    decompress.* = .{ .flate = .init(reader.in, .gzip, decompress_buffer) };
                    return &decompress.flate.reader;
                },
                .zstd => {
                    decompress.* = .{ .zstd = .init(reader.in, decompress_buffer, .{ .verify_checksum = false }) };
                    return &decompress.zstd.reader;
                },
                .compress => unreachable,
            }
        }
        const transfer_reader = bodyReader(reader, transfer_buffer, transfer_encoding, content_length);
        return decompress.init(transfer_reader, decompress_buffer, content_encoding);
    }

    fn contentLengthStream(
        io_r: *std.Io.Reader,
        w: *Writer,
        limit: std.Io.Limit,
    ) std.Io.Reader.StreamError!usize {
        const reader: *Reader = @alignCast(@fieldParentPtr("interface", io_r));
        if (reader.state == .ready) return error.EndOfStream;
        const remaining_content_length = &reader.state.body_remaining_content_length;
        const remaining = remaining_content_length.*;
        const n = try reader.in.stream(w, limit.min(.limited64(remaining)));
        if (n == remaining) {
            reader.state = .ready;
        } else {
            remaining_content_length.* = remaining - n;
        }
        return n;
    }

    fn contentLengthDiscard(io_r: *std.Io.Reader, limit: std.Io.Limit) std.Io.Reader.Error!usize {
        const reader: *Reader = @alignCast(@fieldParentPtr("interface", io_r));
        if (reader.state == .ready) return error.EndOfStream;
        const remaining_content_length = &reader.state.body_remaining_content_length;
        const remaining = remaining_content_length.*;
        const n = try reader.in.discard(limit.min(.limited64(remaining)));
        if (n == remaining) {
            reader.state = .ready;
        } else {
            remaining_content_length.* = remaining - n;
        }
        return n;
    }

    fn chunkedStream(io_r: *std.Io.Reader, w: *Writer, limit: std.Io.Limit) std.Io.Reader.StreamError!usize {
        const reader: *Reader = @alignCast(@fieldParentPtr("interface", io_r));
        const chunk_len_ptr = switch (reader.state) {
            .ready => return error.EndOfStream,
            .body_remaining_chunk_len => |*x| x,
            else => unreachable,
        };
        return chunkedReadEndless(reader, w, limit, chunk_len_ptr) catch |err| switch (err) {
            error.ReadFailed, error.WriteFailed => |e| return e,
            error.EndOfStream => {
                reader.body_err = error.HttpChunkTruncated;
                return error.ReadFailed;
            },
            else => |e| {
                reader.body_err = e;
                return error.ReadFailed;
            },
        };
    }

    fn chunkedReadEndless(
        reader: *Reader,
        w: *Writer,
        limit: std.Io.Limit,
        chunk_len_ptr: *RemainingChunkLen,
    ) (BodyError || std.Io.Reader.StreamError)!usize {
        const in = reader.in;
        len: switch (chunk_len_ptr.*) {
            .head => {
                var cp: ChunkParser = .init;
                while (true) {
                    const i = cp.feed(in.buffered());
                    switch (cp.state) {
                        .invalid => return error.HttpChunkInvalid,
                        .data => {
                            in.toss(i);
                            break;
                        },
                        else => {
                            in.toss(i);
                            try in.fillMore();
                            continue;
                        },
                    }
                }
                if (cp.chunk_len == 0) return parseTrailers(reader, 0);
                const n = try in.stream(w, limit.min(.limited64(cp.chunk_len)));
                chunk_len_ptr.* = .init(cp.chunk_len + 2 - n);
                return n;
            },
            .n => {
                if ((try in.peekByte()) != '\n') return error.HttpChunkInvalid;
                in.toss(1);
                continue :len .head;
            },
            .rn => {
                const rn = try in.peekArray(2);
                if (rn[0] != '\r' or rn[1] != '\n') return error.HttpChunkInvalid;
                in.toss(2);
                continue :len .head;
            },
            else => |remaining_chunk_len| {
                const n = try in.stream(w, limit.min(.limited64(@backingInt(remaining_chunk_len) - 2)));
                chunk_len_ptr.* = .init(@backingInt(remaining_chunk_len) - n);
                return n;
            },
        }
    }

    fn chunkedDiscard(io_r: *std.Io.Reader, limit: std.Io.Limit) std.Io.Reader.Error!usize {
        const reader: *Reader = @alignCast(@fieldParentPtr("interface", io_r));
        const chunk_len_ptr = switch (reader.state) {
            .ready => return error.EndOfStream,
            .body_remaining_chunk_len => |*x| x,
            else => unreachable,
        };
        return chunkedDiscardEndless(reader, limit, chunk_len_ptr) catch |err| switch (err) {
            error.ReadFailed => |e| return e,
            error.EndOfStream => {
                reader.body_err = error.HttpChunkTruncated;
                return error.ReadFailed;
            },
            else => |e| {
                reader.body_err = e;
                return error.ReadFailed;
            },
        };
    }

    fn chunkedDiscardEndless(
        reader: *Reader,
        limit: std.Io.Limit,
        chunk_len_ptr: *RemainingChunkLen,
    ) (BodyError || std.Io.Reader.Error)!usize {
        const in = reader.in;
        len: switch (chunk_len_ptr.*) {
            .head => {
                var cp: ChunkParser = .init;
                while (true) {
                    const i = cp.feed(in.buffered());
                    switch (cp.state) {
                        .invalid => return error.HttpChunkInvalid,
                        .data => {
                            in.toss(i);
                            break;
                        },
                        else => {
                            in.toss(i);
                            try in.fillMore();
                            continue;
                        },
                    }
                }
                if (cp.chunk_len == 0) return parseTrailers(reader, 0);
                const n = try in.discard(limit.min(.limited64(cp.chunk_len)));
                chunk_len_ptr.* = .init(cp.chunk_len + 2 - n);
                return n;
            },
            .n => {
                if ((try in.peekByte()) != '\n') return error.HttpChunkInvalid;
                in.toss(1);
                continue :len .head;
            },
            .rn => {
                const rn = try in.peekArray(2);
                if (rn[0] != '\r' or rn[1] != '\n') return error.HttpChunkInvalid;
                in.toss(2);
                continue :len .head;
            },
            else => |remaining_chunk_len| {
                const n = try in.discard(limit.min(.limited64(remaining_chunk_len.int() - 2)));
                chunk_len_ptr.* = .init(remaining_chunk_len.int() - n);
                return n;
            },
        }
    }

    /// 当流中接下来的字节为尾部字段,或用于表示分块消息体结束的 "\r\n" 时,
    /// 调用此函数。
    fn parseTrailers(reader: *Reader, amt_read: usize) (BodyError || std.Io.Reader.Error)!usize {
        const in = reader.in;
        const rn = try in.peekArray(2);
        if (rn[0] == '\r' and rn[1] == '\n') {
            in.toss(2);
            reader.state = .ready;
            assert(reader.trailers.len == 0);
            return amt_read;
        }
        var hp: HeadParser = .{ .state = .seen_rn };
        var trailers_len: usize = 2;
        while (true) {
            if (in.buffer.len - trailers_len == 0) return error.HttpHeadersOversize;
            const remaining = in.buffered()[trailers_len..];
            if (remaining.len == 0) {
                try in.fillMore();
                continue;
            }
            trailers_len += hp.feed(remaining);
            if (hp.state == .finished) {
                reader.state = .ready;
                reader.trailers = in.buffered()[0..trailers_len];
                in.toss(trailers_len);
                return amt_read;
            }
        }
    }
};

pub const Decompress = union(enum) {
    flate: std.compress.flate.Decompress,
    zstd: std.compress.zstd.Decompress,
    none: *std.Io.Reader,

    pub fn init(
        decompress: *Decompress,
        transfer_reader: *std.Io.Reader,
        buffer: []u8,
        content_encoding: ContentEncoding,
    ) *std.Io.Reader {
        switch (content_encoding) {
            .identity => {
                decompress.* = .{ .none = transfer_reader };
                return transfer_reader;
            },
            .deflate => {
                decompress.* = .{ .flate = .init(transfer_reader, .zlib, buffer) };
                return &decompress.flate.reader;
            },
            .gzip => {
                decompress.* = .{ .flate = .init(transfer_reader, .gzip, buffer) };
                return &decompress.flate.reader;
            },
            .zstd => {
                decompress.* = .{ .zstd = .init(transfer_reader, buffer, .{ .verify_checksum = false }) };
                return &decompress.zstd.reader;
            },
            .compress => unreachable,
        }
    }
};

/// 请求或响应正文。
pub const BodyWriter = struct {
    /// 在 `BodyWriter` 的生存期结束前,
    /// 除通过 `BodyWriter` 方法外,禁止修改此对象状态。
    http_protocol_output: *Writer,
    state: State,
    writer: Writer,

    pub const Error = Writer.Error;

    /// 为十六进制编码的分块长度预留的零的数量。
    const chunk_len_digits = 8;
    const max_chunk_len: usize = std.math.pow(u64, 16, chunk_len_digits) - 1;
    const chunk_header_template = @as([chunk_len_digits]u8, @splat('0')) ++ "\r\n";

    comptime {
        assert(max_chunk_len == std.math.maxInt(u32));
    }

    pub const State = union(enum) {
        /// 连接结束表示流结束。
        none,
        /// 作为调试工具,每写入一个字节便递减,直到零。
        content_length: u64,
        /// 每个数据块都由头部及尾部包装。
        /// 此长度是下一个头部之前
        /// 要写入的字节数,其中为 `\r\n` 尾部额外计入 +2,
        /// 流起始处该值为零。
        chunk_len: usize,
        /// 流已正常结束;连接可以复用。
        end,

        pub const init_chunked: State = .{ .chunk_len = 0 };
    };

    pub fn isEliding(w: *const BodyWriter) bool {
        return w.writer.vtable.drain == elidingDrain;
    }

    /// 通过 `BodyWriter.http_protocol_output` 发送所有缓冲数据。
    pub fn flush(w: *BodyWriter) Error!void {
        const out = w.http_protocol_output;
        switch (w.state) {
            .end, .none, .content_length, .chunk_len => return out.flush(),
        }
    }

    /// 使用 content-length 时,断言已发送数据量与
    /// 标头中的值一致,然后刷新 `http_protocol_output`。
    ///
    /// 使用 transfer-encoding: chunked 时,写入带有空尾部字段的
    /// 流结束消息,然后将流刷新到系统。断言所有
    /// 已开始的块都已完整结束。
    ///
    /// 遵循 `isEliding` 的值,按需省略标头之后的全部数据。
    ///
    /// 另请参见:
    /// * `endUnflushed`
    /// * `endChunked`
    pub fn end(w: *BodyWriter) Error!void {
        try endUnflushed(w);
        try w.http_protocol_output.flush();
    }

    /// 使用 content-length 时,断言已发送数据量与
    /// 标头中的值一致。
    ///
    /// 否则使用 transfer-encoding: chunked,写入
    /// 带有空尾部字段的流结束消息。
    ///
    /// 遵循 `isEliding` 的值,按需省略标头之后的全部数据。
    ///
    /// 不刷新 `http_protocol_output`,但会刷新 `writer`。
    ///
    /// 另请参见:
    /// * `end`
    /// * `endChunked`
    pub fn endUnflushed(w: *BodyWriter) Error!void {
        try w.writer.flush();
        switch (w.state) {
            .end => unreachable,
            .content_length => |len| {
                assert(len == 0); // 所有字节写完前调用 end() 时触发。
                w.state = .end;
            },
            .none => {},
            .chunk_len => return endChunkedUnflushed(w, .{}),
        }
    }

    pub const EndChunkedOptions = struct {
        trailers: []const Header = &.{},
    };

    /// 写入流结束消息和任何可选尾部字段,并刷新
    /// 底层流。
    ///
    /// 断言 BodyWriter 正在使用 transfer-encoding: chunked。
    ///
    /// 遵循 `isEliding` 的值,以省略标头之后的所有数据。
    ///
    /// 另见:
    /// * `endChunkedUnflushed`
    /// * `end`
    pub fn endChunked(w: *BodyWriter, options: EndChunkedOptions) Error!void {
        try endChunkedUnflushed(w, options);
        try w.http_protocol_output.flush();
    }

    /// 写入流结束消息及可选尾部字段。
    ///
    /// 不执行刷新。
    ///
    /// 断言 BodyWriter 使用 transfer-encoding: chunked。
    ///
    /// 遵循 `isEliding` 的值,按需省略标头之后的全部数据。
    ///
    /// 另请参见:
    /// * `endChunked`
    /// * `endUnflushed`
    /// * `end`
    pub fn endChunkedUnflushed(w: *BodyWriter, options: EndChunkedOptions) Error!void {
        if (w.isEliding()) {
            w.state = .end;
            return;
        }
        const bw = w.http_protocol_output;
        switch (w.state.chunk_len) {
            0 => {},
            1 => unreachable, // 写入的数据超过分块头中指定的大小。
            2 => try bw.writeAll("\r\n"),
            else => unreachable, // 先前的写入调用表示后续还有更多数据。
        }
        try bw.writeAll("0\r\n");
        for (options.trailers) |trailer| {
            try bw.writeAll(trailer.name);
            try bw.writeAll(": ");
            try bw.writeAll(trailer.value);
            try bw.writeAll("\r\n");
        }
        try bw.writeAll("\r\n");
        w.state = .end;
    }

    pub fn contentLengthDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        assert(!bw.isEliding());
        const out = bw.http_protocol_output;
        const n = try out.writeSplatHeader(w.buffered(), data, splat);
        bw.state.content_length -= n;
        return w.consume(n);
    }

    pub fn noneDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        assert(!bw.isEliding());
        const out = bw.http_protocol_output;
        const n = try out.writeSplatHeader(w.buffered(), data, splat);
        return w.consume(n);
    }

    pub fn elidingDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        const slice = data[0 .. data.len - 1];
        const pattern = data[slice.len];
        var written: usize = pattern.len * splat;
        for (slice) |bytes| written += bytes.len;
        switch (bw.state) {
            .content_length => |*len| len.* -= written + w.end,
            else => {},
        }
        w.end = 0;
        return written;
    }

    pub fn elidingSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        if (File.Handle == void) return error.Unimplemented;
        if (builtin.zig_backend == .stage2_aarch64) return error.Unimplemented;
        switch (bw.state) {
            .content_length => |*len| len.* -= w.end,
            else => {},
        }
        w.end = 0;
        if (limit == .nothing) return 0;
        if (file_reader.getSize()) |size| {
            const n = limit.minInt64(size - file_reader.pos);
            if (n == 0) return error.EndOfStream;
            file_reader.seekBy(@intCast(n)) catch return error.Unimplemented;
            switch (bw.state) {
                .content_length => |*len| len.* -= n,
                else => {},
            }
            return n;
        } else |_| {
            // 可以在 `file_reader` 实例上观察到该错误,
            // 此时更适合将文件视为管道。
            return error.Unimplemented;
        }
    }

    /// 如果无法在不执行系统调用的前提下计算大小,则返回 `null`。
    pub fn noneSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        assert(!bw.isEliding());
        const out = bw.http_protocol_output;
        const n = try out.sendFileHeader(w.buffered(), file_reader, limit);
        return w.consume(n);
    }

    pub fn contentLengthSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        assert(!bw.isEliding());
        const out = bw.http_protocol_output;
        const n = try out.sendFileHeader(w.buffered(), file_reader, limit);
        bw.state.content_length -= n;
        return w.consume(n);
    }

    pub fn chunkedSendFile(w: *Writer, file_reader: *File.Reader, limit: std.Io.Limit) Writer.FileError!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        assert(!bw.isEliding());
        const data_len = Writer.countSendFileLowerBound(w.end, file_reader, limit) orelse {
            // 文件大小未知时,无法降低为 `sendFile`,因为必须在
            // 获知分块长度前刷新分块头。
            return error.Unimplemented;
        };
        if (data_len == 0) return error.EndOfStream;
        const out = bw.http_protocol_output;
        l: switch (bw.state.chunk_len) {
            0 => {
                const header_buf = try out.writableArray(chunk_header_template.len);
                @memcpy(header_buf, chunk_header_template);
                writeHex(header_buf[0..chunk_len_digits], data_len);
                bw.state.chunk_len = data_len + 2;
                continue :l bw.state.chunk_len;
            },
            1 => unreachable, // 写入的数据超过分块头中指定的大小。
            2 => {
                try out.writeAll("\r\n");
                bw.state.chunk_len = 0;
                continue :l 0;
            },
            else => {
                const chunk_limit: std.Io.Limit = .limited(bw.state.chunk_len - 2);
                const n = if (chunk_limit.subtract(w.buffered().len)) |sendfile_limit|
                    try out.sendFileHeader(w.buffered(), file_reader, sendfile_limit.min(limit))
                else
                    try out.write(chunk_limit.slice(w.buffered()));
                bw.state.chunk_len -= n;
                return w.consume(n);
            },
        }
    }

    pub fn chunkedDrain(w: *Writer, data: []const []const u8, splat: usize) Error!usize {
        const bw: *BodyWriter = @alignCast(@fieldParentPtr("writer", w));
        assert(!bw.isEliding());
        const out = bw.http_protocol_output;
        const data_len = w.end + Writer.countSplat(data, splat);
        l: switch (bw.state.chunk_len) {
            0 => {
                const header_buf = try out.writableArray(chunk_header_template.len);
                @memcpy(header_buf, chunk_header_template);
                writeHex(header_buf[0..chunk_len_digits], data_len);
                bw.state.chunk_len = data_len + 2;
                continue :l bw.state.chunk_len;
            },
            1 => unreachable, // 写入的数据超过分块头中指定的大小。
            2 => {
                try out.writeAll("\r\n");
                bw.state.chunk_len = 0;
                continue :l 0;
            },
            else => {
                const n = try out.writeSplatHeaderLimit(w.buffered(), data, splat, .limited(bw.state.chunk_len - 2));
                bw.state.chunk_len -= n;
                return w.consume(n);
            },
        }
    }

    /// 将整数以十六进制右对齐写入 `buf`,假定
    /// 缓冲区已填零。
    fn writeHex(buf: []u8, x: usize) void {
        assert(std.mem.allEqual(u8, buf, '0'));
        const base = 16;
        var index: usize = buf.len;
        var a = x;
        while (a > 0) {
            const digit = a % base;
            index -= 1;
            buf[index] = std.fmt.digitToChar(@intCast(digit), .lower);
            a /= base;
        }
    }
};

test {
    _ = Server;
    _ = Status;
    _ = Method;
    _ = ChunkParser;
    _ = HeadParser;

    if (builtin.os.tag != .wasi) {
        _ = Client;
        _ = @import("http/test.zig");
    }
}