Skip to content

Errors and FAQ

Jump to bottom
github-actions[bot] edited this page Jul 16, 2026 · 1 revision

错误码与 FAQ

先看 NT_SUCCESS(status)，再按场景分支。Release/Close 接受 nullptr，失败路径也统一释放。

常用 NTSTATUS

通用

NTSTATUS 典型含义
STATUS_SUCCESS 成功（也可用 NT_SUCCESS，勿只比 == SUCCESS）
STATUS_INVALID_PARAMETER 非法 URL、禁止头、配置越界、Paged 池类型等
STATUS_NOT_SUPPORTED scheme 不支持、手写 TE、0-RTT 未声明 replay-safe、WS 3xx/401/407、未启用能力
STATUS_INSUFFICIENT_RESOURCES 分配失败、异步队列满(256)、每主机连接配额满
STATUS_INTEGER_OVERFLOW 长度/大小计算溢出
STATUS_INVALID_DEVICE_REQUEST 非 PASSIVE_LEVEL 调用
STATUS_INVALID_DEVICE_STATE 句柄状态非法、WSK 未就绪、序列号溢出
STATUS_DEVICE_NOT_READY WSK 未初始化 / 异步运行时已停止

网络 / HTTP

NTSTATUS 典型含义
STATUS_IO_TIMEOUT 收发/握手/等待超时
STATUS_CONNECTION_DISCONNECTED 对端断开、短写、GOAWAY 非 0、RST
STATUS_BUFFER_TOO_SMALL 响应超 MaxResponseBytes、WS 消息超限、缓冲不足
STATUS_INVALID_NETWORK_RESPONSE 协议违规（状态行/头/帧/HPACK/obs-fold/解压失败等）
STATUS_RETRY 可重试（如干净 GOAWAY 未处理本流）；高层仅对安全方法自动一次
STATUS_CANCELLED 异步取消完成
STATUS_NOT_FOUND 无解析地址 / 无响应可取

TLS / 证书

NTSTATUS 典型含义
STATUS_TRUST_FAILURE 链/有效期/主机名/pin/信任锚/撤销 fail-closed
STATUS_INVALID_SIGNATURE MAC / AEAD / CBC MAC 失败
STATUS_NOT_SUPPORTED 版本/策略拒绝、弱算法、0-RTT 策略 
NTSTATUS s = wknet::http::GetEx(session, url, urlLen, nullptr, nullptr, &resp);
if (!NT_SUCCESS(s)) {
    switch (s) {
    case STATUS_IO_TIMEOUT:              /* 超时策略 */ break;
    case STATUS_TRUST_FAILURE:           /* 检查 Store/主机名/撤销 */ break;
    case STATUS_CONNECTION_DISCONNECTED: /* 重连或换节点 */ break;
    case STATUS_BUFFER_TOO_SMALL:        /* 调大 MaxResponseBytes */ break;
    case STATUS_RETRY:                   /* 安全方法可再试 */ break;
    default:                             /* 记录 0x%08X */ break;
    }
}

FAQ

Q：调用 IRQL？
A：同步 HTTP / WebSocket / TLS / 证书路径必须 PASSIVE_LEVEL。RAII 析构同样要求（内部 Release/Close）。

Q：支持服务端吗？
A：不支持。客户端 only；无入站 request parser。

Q：代理怎么配？
A：SessionConfig.Proxy 配置 Host / Port / Family / Authority / AuthHeader。HTTPS 经 CONNECT 隧道；明文 HTTP 使用 absolute-form。启用代理时不会选用 HTTP/3 Auto。

Q：HTTP/3 默认开吗？
A：默认 Http3ConnectMode::Auto。首次 HTTPS 使用 TCP；从通过校验的 Alt-Svc 学习后，后续请求可优先 H3。Disabled 关闭；Required 表示 prior-knowledge。

Q：POST 会自动重试吗？
A：不会。stale 重试仅 GET/HEAD/OPTIONS 一次。POST/PUT/PATCH/DELETE 不自动重放。

Q：重定向次数用尽？
A：默认最多 10 跳；用尽不报错，返回当前 3xx，自行处理 Location。HTTPS→HTTP 默认拒绝。

Q：证书能关吗？
A：存在 CertPolicy::NoVerify，生产严禁。库不带系统 CA，须自备信任锚。IP literal 只匹配 iPAddress SAN；域名不回退 CN。

Q：产品 API 能开 TLS 1.3 0-RTT 吗？
A：不能。EnableEarlyData / EarlyDataReplaySafe 是内部 TLS 连接选项，未映射到 TlsConfig / SendOptions。HTTP/3 应用数据 0-RTT 当前也不支持。

Q：WebSocket 命名空间？
A：wknet::websocket（Connect/SendText/Receive/Close）；Session 仍是 wknet::http::Session。wss 可走 RFC 8441 或 HTTP/1.1 Upgrade。

Q：异步路径下驱动如何卸载？
A：调用过 Async* 时，在卸载路径先 wknet::http::Destroy()，再释放 WSK 与句柄。AsyncCancel 之后仍要 AsyncWait + AsyncRelease。

Q：close-delimited 响应会进池吗？
A：不会。close-delimited 与 101 响应不回连接池。

支持范围见 能力边界。

English

Errors & FAQ

Check NT_SUCCESS(status) first, then branch by scenario. Release/Close accept nullptr — free on failure paths too.

Common NTSTATUS values

General

NTSTATUS Typical meaning
STATUS_SUCCESS Success (prefer NT_SUCCESS; do not only compare == SUCCESS)
STATUS_INVALID_PARAMETER Bad URL, forbidden header, out-of-range config, Paged pool type, etc.
STATUS_NOT_SUPPORTED Unsupported scheme, caller TE, 0-RTT without replay-safe, WS 3xx/401/407, disabled capability
STATUS_INSUFFICIENT_RESOURCES Allocation failure, async queue full (256), per-host connection quota
STATUS_INTEGER_OVERFLOW Length/size arithmetic overflow
STATUS_INVALID_DEVICE_REQUEST Call not at PASSIVE_LEVEL
STATUS_INVALID_DEVICE_STATE Bad handle state, WSK not ready, sequence overflow
STATUS_DEVICE_NOT_READY WSK not initialized / async runtime stopped

Network / HTTP

NTSTATUS Typical meaning
STATUS_IO_TIMEOUT Send/receive/handshake/wait timeout
STATUS_CONNECTION_DISCONNECTED Peer close, short write, non-zero GOAWAY, RST
STATUS_BUFFER_TOO_SMALL Response over MaxResponseBytes, WS message over limit, buffer too small
STATUS_INVALID_NETWORK_RESPONSE Protocol violation (status/headers/frames/HPACK/obs-fold/decode failure)
STATUS_RETRY Retryable (e.g. clean GOAWAY for unprocessed stream); high level auto-retries safe methods once
STATUS_CANCELLED Async cancel completed
STATUS_NOT_FOUND No resolved address / no response to take

TLS / certificates

NTSTATUS Typical meaning
STATUS_TRUST_FAILURE Chain/validity/hostname/pin/anchor/revocation fail-closed
STATUS_INVALID_SIGNATURE MAC / AEAD / CBC MAC failure
STATUS_NOT_SUPPORTED Version/policy refusal, weak algorithms, 0-RTT policy 
NTSTATUS s = wknet::http::GetEx(session, url, urlLen, nullptr, nullptr, &resp);
if (!NT_SUCCESS(s)) {
    switch (s) {
    case STATUS_IO_TIMEOUT:              /* timeout policy */ break;
    case STATUS_TRUST_FAILURE:           /* check Store/hostname/revocation */ break;
    case STATUS_CONNECTION_DISCONNECTED: /* reconnect or switch peer */ break;
    case STATUS_BUFFER_TOO_SMALL:        /* raise MaxResponseBytes */ break;
    case STATUS_RETRY:                   /* safe methods may retry */ break;
    default:                             /* log 0x%08X */ break;
    }
}

FAQ

Q: Required IRQL?
A: Synchronous HTTP / WebSocket / TLS / certificate paths must run at PASSIVE_LEVEL. RAII destructors require the same (they call Release/Close).

Q: Server role?
A: No. Client only; no inbound request parser.

Q: How is proxy configured?
A: Configure SessionConfig.Proxy with Host / Port / Family / Authority / AuthHeader. HTTPS uses a CONNECT tunnel; cleartext HTTP uses absolute-form. HTTP/3 Auto is not selected when a proxy is enabled.

Q: Is HTTP/3 on by default?
A: Default is Http3ConnectMode::Auto. The first HTTPS request uses TCP; after validated Alt-Svc is learned, later requests may prefer H3. Disabled turns it off; Required is prior-knowledge.

Q: Are POSTs auto-retried?
A: No. Stale retry is GET/HEAD/OPTIONS only, once. POST/PUT/PATCH/DELETE are never auto-replayed.

Q: Redirect hop budget exhausted?
A: Default 10 hops; exhaustion is not an error — the current 3xx is returned for you to handle Location. HTTPS→HTTP is rejected by default.

Q: Can certificate checks be disabled?
A: CertPolicy::NoVerify exists but is forbidden in production. No system CAs are bundled; supply trust anchors. IP literals match iPAddress SAN only; DNS names never fall back to CN.

Q: Can the product API enable TLS 1.3 0-RTT?
A: No. EnableEarlyData / EarlyDataReplaySafe are internal TLS connection options and are not mapped onto TlsConfig / SendOptions. HTTP/3 application-data 0-RTT is also unsupported.

Q: WebSocket namespace?
A: wknet::websocket (Connect/SendText/Receive/Close); sessions remain wknet::http::Session. wss may use RFC 8441 or HTTP/1.1 Upgrade.

Q: How do I unload a driver that used async APIs?
A: On the unload path call wknet::http::Destroy(), then release WSK and handles. After AsyncCancel, still call AsyncWait + AsyncRelease.

Q: Are close-delimited responses pooled?
A: No. close-delimited bodies and 101 never return to the pool.

Full capability classes: Capability Matrix.

wknet · 纯内核态 HTTP/HTTPS 客户端库 · Pure kernel-mode HTTP/HTTPS client · MIT License · 仓库 / Repo · Issues

This Wiki is generated from docsite; edit repository docs and let the docs workflow sync it.

wknet Wiki

Clone this wiki locally