std.http | Zero

状态

当前可运行：

API	返回值	说明
`std.http.parseMethod(text)`	`HttpMethod`	解析小型 HTTP 方法令牌。
`std.http.client(net)`	`HttpClient`	从网络能力创建托管客户端元数据。
`std.http.server(net, address)`	`HttpServer`	从网络能力和地址创建托管服务器元数据。
`std.http.fetch(client, request, response, timeout)`	`HttpResult`	执行托管 HTTP(S) 请求，使用 `Duration` 超时，并将响应元数据、头部和正文写入调用者拥有的存储。
`std.http.resultOk(result)`	`Bool`	当传输成功且状态码为 2xx 时为真。
`std.http.resultStatus(result)`	`u16`	读取 HTTP 状态码，无可用状态时返回 `0`。
`std.http.resultBodyLen(result)`	`usize`	读取写入响应缓冲区的响应正文字节数。
`std.http.resultError(result)`	`HttpError`	读取传输/提供者错误。
`std.http.errorNone()`	`HttpError`	传输成功。
`std.http.errorInvalidUrl()`	`HttpError`	请求 URL 无效。
`std.http.errorUnsupportedProtocol()`	`HttpError`	不支持该 URL 协议。
`std.http.errorDns()`	`HttpError`	DNS 查找失败。
`std.http.errorConnect()`	`HttpError`	连接远程主机失败。
`std.http.errorTls()`	`HttpError`	TLS 验证或连接建立失败。
`std.http.errorTimeout()`	`HttpError`	请求超时。
`std.http.errorTooLarge()`	`HttpError`	响应超出调用者拥有的缓冲区大小。
`std.http.errorProviderUnavailable()`	`HttpError`	托管 HTTP 提供者不可用。
`std.http.errorIo()`	`HttpError`	提供者报告了 I/O 故障。
`std.http.errorInvalidRequest()`	`HttpError`	请求信封无效。
`std.http.responseLen(response)`	`usize`	读取内部元数据前缀之后写入的响应字节数。
`std.http.responseHeadersLen(response)`	`usize`	读取原始响应头字节数。
`std.http.responseBodyOffset(response)`	`usize`	读取响应缓冲区中正文起始偏移量。
`std.http.headerValue(response, name)`	`HttpHeaderValue`	通过不区分大小写的头部名称定位响应头值。
`std.http.headerFound(value)`	`Bool`	当 `headerValue` 找到匹配的头部时为真。
`std.http.headerOffset(value)`	`usize`	读取响应缓冲区中头部值的字节偏移量。
`std.http.headerLen(value)`	`usize`	读取头部值的字节长度。
`std.http.tlsBoundary()`	`String`	命名平台或 C 库 TLS 边界。

元数据标签：

副作用：net、memory、parse，或命名错误常量对应 none
分配行为：元数据辅助函数不分配；fetch 写入调用者拥有的响应缓冲区，内部使用提供者运行时
目标支持：解析辅助函数与目标无关；client/server 需要具备网络能力的目标；fetch 在受支持的 Darwin arm64 和 Linux x64 宿主可执行目标上运行
错误行为：元数据辅助函数不会失败；fetch 返回状态码、正文长度和错误元数据，因此非 2xx 响应可与传输故障区分
所有权说明：HTTP 辅助函数借用网络能力元数据，仅写入调用者拥有的缓冲区
示例：conformance/native/pass/std-http-metadata-neutral.0、 conformance/native/pass/std-http-fetch.0、 conformance/native/pass/std-http-errors.0、 conformance/native/pass/std-http-response-helpers.0、 examples/std-http-json.0、 examples/std-http-request.0、 examples/std-http-headers.0

示例

元数据辅助函数：

pub fn main Void world World !  let net std.net.host()  let addr std.net.address "localhost" 8080_u16  let _client std.http.client net  let _server std.http.server net addr  let method std.http.parseMethod "GET"  if && (== method (std.http.parseMethod "GET")) (== (std.mem.len (std.mem.span "body")) 4)    check world.out.write "http ok\n"

GET 请求：

pub fn main Void world World !  let net std.net.host()  let client std.http.client net  mut response [512]u8 [0_u8;512]  let request std.mem.span "GET https://example.com\n\n"  let result std.http.fetch client request response (std.time.ms 1000)  if std.http.resultOk result    check world.out.write "http get ok\n"    ret  check world.err.write "http get failed\n"

带头部和正文的请求：

pub fn main Void world World !  let net std.net.host()  let client std.http.client net  let request std.mem.span "POST https://example.com/api\ncontent-type: application/json\n\n{\"ping\":1}"  mut response [512]u8 [0_u8;512]  let result std.http.fetch client request response (std.time.ms 1000)  if std.http.resultOk result    check world.out.write "http post ok\n"    ret  check world.err.write "http post failed\n"

响应字节：

pub fn main Void world World !  let maybe_request std.args.get 1  if == maybe_request.has false    check world.err.write "usage: pass HTTP request envelope\n"    ret  let net std.net.host()  let client std.http.client net  mut response [512]u8 [0_u8;512]  let result std.http.fetch client (std.mem.span maybe_request.value) response (std.time.ms 5000)  let body_len std.http.resultBodyLen result  let body_offset std.http.responseBodyOffset response  let bytes response[body_offset..+ body_offset body_len]  mut arena_buf [16]u8 [0_u8;16]  mut arena std.mem.fixedBufAlloc arena_buf  let parsed std.json.parseBytes arena bytes  if && (std.http.resultOk result) parsed.has    check world.out.write "http response json ok\n"    ret  check world.err.write "http response json failed\n"

设计说明

std.http.fetch 是出站 HTTP 客户端原语。请求参数是一个字节信封：METHOD URL，后跟零行或多行 Header-Name: value，一个空行，以及可选的请求正文字节。超时为 Duration 类型，通常通过 std.time.ms(...) 构建。

fetch 在受支持的宿主可执行目标上支持 http:// 和 https:// URL，使用 C 库 curl 提供者，不跟随重定向，并通过提供者验证 TLS。TLS 验证始终启用。ZERO_HTTP_TEST_CA_BUNDLE 可将提供者指向显式 CA 捆绑包，同时保持证书验证开启。

响应缓冲区以内部元数据开头，随后是原始响应头，然后是响应正文。使用 responseHeadersLen 和 responseBodyOffset 而非硬编码偏移量。headerValue 扫描响应缓冲区并返回匹配值的打包偏移/长度元数据；headerFound、headerOffset 和 headerLen 检查该元数据而不进行分配。

将 resultError 与命名的 HttpError 辅助函数比较，而非原始数字。errorNone 表示传输成功；HTTP 非 2xx 状态码仍然携带 errorNone，可通过 resultStatus 检查。

该模块不暴露原始套接字读写 API、结构化头部集合、流式正文、重定向或堆分配的响应对象。