处理单个连接的生命周期。
字段
std.http.Server.assert
别名
别名目标 std.debug.assert
std.http.Server.http
别名
别名目标 std.http
std.http.Server.init
函数
初始化 HTTP 服务器,能够在同一 连接上响应多个请求。
in 的缓冲区必须足够大,能存储客户端完整的 HTTP
标头,否则 receiveHead 返回 error.HttpHeadersOversize。
返回的 Server 已可调用 receiveHead。
pub fn init(in: *Reader, out: *Writer) Server
参数
std.http.Server.mem
别名
别名目标 std.mem
std.http.Server.Reader
别名
别名目标 std.Io.Reader
std.http.Server.receiveHead
函数
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
错误集合
错误
- 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
容器
字段
server: *Server
head: Head请求消息体流初始化后,此结构体中的指针将失效。
head_buffer: []const u8
respond_err: ?RespondError = null
std.http.Server.Request.discardBody
函数
返回连接是否应保持持久连接。
如果操作将失败,则改为将 Server 状态设置为接收消息体, 并返回 false。
fn discardBody(request: *Request, keep_alive: bool) bool
参数
request: *Request
keep_alive: bool
std.http.Server.Request.ExpectContinueError
错误集合
错误
- HttpExpectationFailed
客户端发送的 expect HTTP 头字段值 不是 "100-continue"。
- WriteFailed
无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。
std.http.Server.Request.Head
容器
字段
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
函数
inline fn int64(array: *const [8]u8) u64
参数
array: *const [8]u8
std.http.Server.Request.Head.invalidateStrings
函数
当 Head 的字符串内存失效时调用此函数,
帮助程序员避免缺陷。
fn invalidateStrings(h: *Head) void
参数
h: *Head
std.http.Server.Request.Head.parse
函数
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
错误集合
错误
- CompressionUnsupported
- HttpConnectionHeaderUnsupported
- HttpHeaderContinuationsUnsupported
- HttpHeadersInvalid
- HttpTransferEncodingUnsupported
- InvalidContentLength
- MissingFinalNewline
- UnknownHttpMethod
std.http.Server.Request.iterateHeaders
函数
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,
.side = .request,
},
.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
函数
若请求包含 "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
函数
断言 expect 标头为 null。调用方必须手动处理
预期内容,并在调用此函数之前将其设为 null。
断言此函数仅调用一次。
使 Head 内部的字符串内存失效。
pub fn readerExpectNone(request: *Request, buffer: []u8) *Reader
参数
request: *Request
buffer: []u8
std.http.Server.Request.respond
函数
向客户端发送完整 HTTP 响应,包括标头和正文。
自动处理 HEAD 请求,省略正文。
除非指定 transfer_encoding,否则使用 "content-length"
标头。
如果请求包含正文且连接将被复用,
则丢弃请求正文,使 Server 处于 ready 状态。
如果丢弃失败,则将连接标记为不再复用,
且不向上报告错误。
断言状态不是 continue。
断言任何标头名称或值中都不存在 "\r\n"。
pub fn respond( request: *Request, content: []const u8, options: RespondOptions, ) ExpectContinueError!void
参数
错误
- HttpExpectationFailed
客户端发送的 expect HTTP 头字段值 不是 "100-continue"。
- WriteFailed
无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。
std.http.Server.Request.RespondError
错误集合
错误
- HttpExpectationFailed
请求包含值无法识别的
expect头字段。
std.http.Server.Request.RespondOptions
容器
字段
std.http.Server.Request.respondStreaming
函数
在调用 BodyWriter.flush 或
BodyWriter.end 之前,不保证头部已发送。
若请求包含正文且连接计划复用,
则丢弃请求正文,使 Server 保持 ready 状态。
若丢弃失败,连接会标记为不可复用,
但不会对外报告错误。
HEAD 请求通过设置
BodyWriter.elide 标志透明处理;该标志位于返回的 BodyWriter 上,
使响应流省略正文。不过,调用方也值得检查
该标志,跳过原本为满足请求而需要执行的
高开销操作。
断言状态不是 continue。
pub fn respondStreaming( request: *Request, buffer: []u8, options: RespondStreamingOptions, ) ExpectContinueError!http.BodyWriter
参数
错误
- HttpExpectationFailed
客户端发送的 expect HTTP 头字段值 不是 "100-continue"。
- WriteFailed
无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。
std.http.Server.Request.RespondStreamingOptions
容器
字段
content_length: ?u64 = null若提供,则响应使用 content-length 头; 否则使用 transfer-encoding: chunked。
respond_options: RespondOptions = .{}与 respond 方法共用的选项。
std.http.Server.Request.respondUnflushed
函数
pub fn respondUnflushed( request: *Request, content: []const u8, options: RespondOptions, ) ExpectContinueError!void
参数
错误
- HttpExpectationFailed
客户端发送的 expect HTTP 头字段值 不是 "100-continue"。
- WriteFailed
无法向流写入 "HTTP/1.1 100 Continue\r\n\r\n"。
std.http.Server.Request.respondWebSocket
函数
只有对返回的结构体调用 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
容器
字段
websocket: ?[]const u8
other: []const u8
none
std.http.Server.Request.upgradeRequested
函数
不会使 request.head 失效。
pub fn upgradeRequested(request: *const Request) UpgradeRequest
参数
request: *const Request
std.http.Server.Request.WebSocketOptions
容器
字段
std.http.Server.Request.writeExpectContinue
函数
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
别名
别名目标 std.http.Server
std.http.Server.std
别名
别名目标 std
std.http.Server.testing
别名
别名目标 std.testing
std.http.Server.Uri
别名
别名目标 std.Uri
std.http.Server.WebSocket
容器
字段
std.http.Server.WebSocket.flush
函数
pub fn flush(ws: *WebSocket) Writer.Error!void
参数
ws: *WebSocket
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.http.Server.WebSocket.Header0
容器
字段
std.http.Server.WebSocket.Header1
容器
字段
payload_len: enum(u7) {
len16 = 126,
len64 = 127,
_,
}
mask: bool
std.http.Server.WebSocket.Opcode
容器
字段
continuation = 0
text = 1
binary = 2
connection_close = 8
ping = 9
pong = 10"可以主动发送 Pong 帧,用作单向 心跳。接收方无需响应主动发送的 Pong 帧。"
_
std.http.Server.WebSocket.readSmallMessage
函数
读取 WebSocket 流中的下一条消息;如果 输入缓冲区无法容纳消息,则失败。返回内存指向 输入缓冲区,并在下次读取时失效。
pub fn readSmallMessage(ws: *WebSocket) ReadSmallTextMessageError!SmallMessage
参数
ws: *WebSocket
错误
- ConnectionClose
- EndOfStream
- MessageOversize
- MissingMaskBit
- ReadFailed
- UnexpectedOpCode
std.http.Server.WebSocket.ReadSmallTextMessageError
错误集合
错误
- ConnectionClose
- EndOfStream
- MessageOversize
- MissingMaskBit
- ReadFailed
- UnexpectedOpCode
std.http.Server.WebSocket.SmallMessage
容器
字段
std.http.Server.WebSocket.writeMessage
函数
pub fn writeMessage(ws: *WebSocket, data: []const u8, op: Opcode) Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.http.Server.WebSocket.writeMessageUnflushed
函数
pub fn writeMessageUnflushed(ws: *WebSocket, data: []const u8, op: Opcode) Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.http.Server.WebSocket.writeMessageVec
函数
pub fn writeMessageVec(ws: *WebSocket, data: [][]const u8, op: Opcode) Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.http.Server.WebSocket.writeMessageVecUnflushed
函数
pub fn writeMessageVecUnflushed(ws: *WebSocket, data: [][]const u8, op: Opcode) Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.http.Server.Writer
别名
别名目标 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,
.side = .request,
},
.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,
.side = .request,
},
.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 == .HEAD) 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.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();
}
};