Capability Matrix

能力边界

本文说明 wknet 当前支持什么、默认开启什么、以及哪些行为会被拒绝。章节按状态分组，便于对照集成需求。

1. 已实现 — 当前可用；除非另有说明，按默认配置即可使用
2. 默认关闭 — 已实现，但需显式开启
3. 策略拒绝 — 出于协议或安全策略会拒绝的请求/响应
4. 当前不支持 — 现阶段未提供

定位：HTTP/HTTPS/WebSocket/SSE 客户端。传输主路径为 WSK，密码学主路径为 CNG/BCrypt；不使用 WinHTTP、WinINet 或 SChannel。信任锚、CA 包、pin 与撤销证据由调用方提供。同步路径要求 PASSIVE_LEVEL。

---

1. 已实现

HTTP/1.1（RFC 9110/9112）

• 请求体：Content-Length、库生成 chunked、流式 BodyCreateStream / RequestSetBodySource；用户手设 Transfer-Encoding/TE 会被拒绝。
• 请求 trailer：仅 chunked 路径；禁止字段与 CRLF 注入拒绝。
• 响应：状态行仅 HTTP/1.0/1.1；头行/头段/头数有界；拒绝 obs-fold；多 Content-Length 或 TE+CL 冲突 → STATUS_INVALID_NETWORK_RESPONSE。
• Body 框定：CL / chunked / close-delimited；无 body：1xx、204、205、304、HEAD。
• 206 / Content-Range 只读解析；Range 与条件请求 helper；可选 RFC 9111 内存 cache 参与验证与 partial 合并。
• Content-Encoding：gzip/deflate/br/compress/zstd/dcz/aes128gcm/exi/pack200-gzip/identity（最多 2 级，反序解码；膨胀比有界）。
• 中间 1xx（除 101）吞掉重解析；自动 redirect；keep-alive 池复用。
• 代理：HTTPS CONNECT；明文 HTTP absolute-form；Proxy-Authorization 仅来自显式配置。

HTTP/2（RFC 9113 + HPACK）

• 前导 + SETTINGS；客户端 ENABLE_PUSH=0；CONTINUATION 洪泛防护；流控与伪头校验。
• 连接池 stream 租约：同源 H2 多请求；DATA 按流控与 MAX_FRAME_SIZE 切分；请求 trailer 以 final HEADERS 发送。
• 模式：TLS ALPN h2；h2c prior knowledge / Upgrade 为 opt-in（见下节）。
• RFC 8441 extended CONNECT：对端 SETTINGS_ENABLE_CONNECT_PROTOCOL=1 时可供 WebSocket。
• GOAWAY/REFUSED_STREAM → 可 STATUS_RETRY；高层仅安全方法重试一次。

HTTP/3 + QUIC v1 + QPACK

• WSK Datagram + 内核 CNG 主路径；QUIC v1 包/帧、TLS 1.3 over QUIC、ACK/loss/PTO、流控、CID、关闭状态机。
• HTTP/3：控制/QPACK 关键单向流、SETTINGS、HEADERS/DATA、1xx、trailer、GOAWAY/取消；server push 会被拒绝。
• 默认 Http3ConnectMode::Auto：首次 HTTPS 使用 TCP；只有通过证书与 TLS 策略校验的响应中的精确 h3 Alt-Svc 会被缓存。DNS/UDP 可指向 alternative，SNI、证书校验与 :authority 仍绑定原 origin。
• 以下情况不使用 HTTP/3：CertPolicy::NoVerify、HTTP 代理、明文 HTTP、h2c、WebSocket、非 HTTP ALPN、带 Http2Priority 的请求。
• 回落 TCP 仅在请求尚未发送，或满足一次安全重放规则时允许。

WebSocket（RFC 6455）

• ws/wss；Accept 常量时间比对；子协议；调用方 opening headers（拒绝库受控头）。
• wss 默认可 offer h2,http/1.1 → RFC 8441 或回落 HTTP/1.1 Upgrade；ws:// 不隐式 h2c。
• 分片发送/可选分片接收；自动 Pong；UTF-8/长度/控制帧上限；主动/被动 close。
• 握手 3xx/401/407 不自动跟随 → STATUS_NOT_SUPPORTED。

Server-Sent Events（WHATWG event-stream）

• wknet::sse::SseClient：Connect / Receive / Close；仅 GET；默认要求 Content-Type: text/event-stream。
• 解析：半包、comment、id/event/data/retry、多行 data；Last-Event-ID 跟踪与重连注入。
• 自动重连默认开；指数退避 + 尊重 retry:；HTTP 4xx open 失败不重连；Close 中止 delay。
• 超时：ConnectTimeoutMs / Body 空闲 IdleTimeoutMs / 单次 ReceiveTimeoutMs 分字段（不再把整条长流绑在 30s 总 deadline）。
• 底层响应体为真增量：SendOptions.OnBody 在启用时按到达顺序多次回调，finalChunk 仅在结束时为 true。
• 首版：identity Content-Encoding；无 SSE 服务端；无 POST body 型 SSE。

TLS / 证书 / 密码学

• TLS 1.2/1.3 单版本路径；无握手内自动降级；EMS + 安全重协商指示；CBC 须 EtM。
• 证书：有界链、主机名（IP→iPAddress SAN only；域名不回退 CN）、离线撤销证据、SPKI pin、mTLS 回调签名（私钥不入库）。
• 密码学：CNG 优先；ChaCha20-Poly1305、X25519 等内核软件补齐；最小 RSA 2048。

会话行为（关键默认）

行为	默认
MaxRedirects	10；用尽返回当前 3xx，不报错
HTTPS→HTTP redirect	拒绝
Stale retry	仅 GET/HEAD/OPTIONS，恰好一次
close-delimited / 101	不回池
TRACE	关（SendFlagAllowTrace）
同步 IRQL	PASSIVE_LEVEL

---

2. 默认关闭

默认关闭的能力，以及对应配置字段。头文件：Types.h、Cache.h、websocket/WebSocket.h。

能力	配置对象	字段 / 用法
Expect: 100-continue	SendOptions	Flags |= SendFlagExpectContinue；可选 ExpectContinueTimeoutMs（默认 1000）
TRACE	SendOptions	Flags |= SendFlagAllowTrace（仍拒绝 body / trailer / 敏感头）
HTTP/1.1 pipeline	SessionConfig	EnableHttp11Pipeline = true；Http11PipelineMaxDepth（默认 4，上限 64）；Http11PipelineMethodMask（默认 GET|HEAD|OPTIONS）
h2c	SendOptions	Http2CleartextMode = PriorKnowledge 或 Upgrade
HTTP/2 PING 保活	SessionConfig	Http2KeepAlive.Enabled = true；IdleMs / IntervalMs / AckTimeoutMs（默认各 30000 / 30000 / 5000）
HTTP/2 priority	SendOptions	Http2Priority 指向 Http2Priority{ StreamDependency, Weight(1..256), Exclusive }
permessage-deflate	ConnectConfig	PerMessageDeflate.Enable = true；可选 Client/ServerNoContextTakeover、Client/ServerMaxWindowBits（8..15）
TLS 1.2 兼容套件 / 重协商	TlsConfig.Policy	Profile = CompatibilityExplicit，再开 EnableTls12RsaKeyExchange / EnableTls12Cbc / EnableTls12Sha1Signatures / EnableTls12Renegotiation；TlsConfig.MaxTls12Renegotiations（默认 1，上限 4）
post-handshake client auth	TlsConfig.Policy	EnablePostHandshakeClientAuth = true，并设置 TlsConfig.ClientCredential
强撤销	TlsConfig.Policy	RequireRevocationCheck = true；调用方提供可验证 OCSP/CRL 证据
内存 cache	SessionConfig / SendOptions	CacheCreate 后赋给 SessionConfig.Cache；单次可用 SendFlagBypassCache / NoCacheStore / OnlyIfCached 或 SendOptions.Cache

示例：

// 单次发送
wknet::http::SendOptions* options = nullptr;
wknet::http::SendOptionsCreate(&options);
options->Flags |= wknet::http::SendFlagExpectContinue;
options->ExpectContinueTimeoutMs = 1000;
options->Flags |= wknet::http::SendFlagAllowTrace;
options->Http2CleartextMode = wknet::http::Http2CleartextMode::PriorKnowledge;

wknet::http::Http2Priority priority = {};
priority.Weight = 16;
options->Http2Priority = &priority;

wknet::http::SendEx(session, wknet::http::Method::Get,
    url, urlLen, nullptr, nullptr, options, &response);
wknet::http::SendOptionsRelease(options);

// 会话
wknet::http::SessionConfig config = wknet::http::DefaultSessionConfig();
config.EnableHttp11Pipeline = true;
config.Http11PipelineMaxDepth = 4;
config.Http11PipelineMethodMask =
    wknet::http::Http11PipelineMethodGet |
    wknet::http::Http11PipelineMethodHead |
    wknet::http::Http11PipelineMethodOptions;
config.Http2KeepAlive.Enabled = true;
config.Tls.Policy.Profile = wknet::http::TlsSecurityProfile::CompatibilityExplicit;
config.Tls.Policy.EnableTls12Cbc = true;
config.Tls.Policy.RequireRevocationCheck = true;

wknet::http::Cache* cache = nullptr;
wknet::http::CacheOptions cacheOptions = {};
cacheOptions.MaxBytes = 16 * 1024 * 1024;
cacheOptions.MaxEntries = 256;
cacheOptions.Mode = wknet::http::CacheMode::Private;
wknet::http::CacheCreate(&cacheOptions, &cache);
config.Cache = cache;

wknet::http::Session* session = nullptr;
wknet::http::SessionCreate(&config, &session);

// WebSocket
wknet::websocket::ConnectConfig cfg = wknet::websocket::DefaultConnectConfig();
cfg.Url = "wss://example.com/ws";
cfg.UrlLength = 18;
cfg.PerMessageDeflate.Enable = true;
wknet::websocket::WebSocket* ws = nullptr;
wknet::websocket::ConnectEx(session, &cfg, &ws);

TLS 1.3 0-RTT（EnableEarlyData / EarlyDataReplaySafe）仅存在于内部 TLS 连接选项，未映射到 TlsConfig / SendOptions，产品 HTTP API 不能开启。HTTP/3 应用数据 0-RTT 见「当前不支持」。

---

3. 策略拒绝

下列行为会被拒绝；这是既定策略，不表示实现缺失。

行为	处理
用户手写请求 Transfer-Encoding / TE	拒绝；framing 由库生成
HTTP br 作 Transfer-Encoding	拒绝；br 仅 Content-Encoding
HTTP/2 PUSH_PROMISE	协议错误
未请求/非法 WebSocket 扩展	拒绝
WS 握手 redirect / 401 / 407 自动跟随	STATUS_NOT_SUPPORTED
TLS 握手内 1.3→1.2 自动降级	不做；仅可验证证据后上层显式重连
证书：IP 用 dNSName/CN；域名回退 CN	不做
HTTPS→HTTP 自动 redirect	默认拒绝
在线 OCSP/CRL 抓取	库从不发起

---

4. 当前不支持

能力	说明
HTTP server / 入站 request parser	客户端库，不提供服务端
SSE 服务端 / POST body 型 SSE	仅客户端 GET event-stream
磁盘持久化 HTTP cache	仅有内存 NonPaged cache 对象
HTTP/2 本地 priority 树带宽调度	不实现
除 permessage-deflate 外的 WS 扩展	不协商其它扩展
在线撤销抓取	库不发起 OCSP/CRL 网络请求
流式 Content-Encoding（SSE/OnBody 路径 gzip/br 等）	首版要求 identity；架构可扩展
QUIC v2、H3 0-RTT 应用数据、主动迁移、多路径、ECN、DPLPMTUD、WebTransport、QUIC Datagram、WebSocket over H3	当前不支持
WinHTTP / WinINet / SChannel 内核主路径	不使用
独立 client 层 / 第二套连接生命周期	不提供

---

实现策略与信任模型

• 传输：WSK。TLS/HTTP/证书：内核路径自实现。
• 密码学：CNG/BCrypt 优先，缺口由内核软件实现补齐。
• 信任：调用方显式提供锚、CA 包、撤销证据与 pin；库不硬编码系统 CA。

方向摘要见 路线图。能力现状以本页账本为准。

---

English

Capability matrix

This page describes what wknet supports today, what is enabled by default, and which behaviors are rejected. Sections are grouped by status for integration review.

1. Implemented — available now; usable under default configuration unless noted
2. Default-off — implemented, but must be enabled explicitly
3. Policy rejection — requests or responses rejected by protocol or security policy
4. Not supported — not provided in the current release

Scope: HTTP/HTTPS/WebSocket/SSE client. Transport main path is WSK; cryptography main path is CNG/BCrypt. WinHTTP, WinINet, and SChannel are not used. Trust anchors, CA bundles, pins, and revocation evidence are caller-supplied. Synchronous paths require PASSIVE_LEVEL.

---

1. Implemented

HTTP/1.1 (RFC 9110/9112)

• Request bodies: Content-Length, library-generated chunked, streaming BodyCreateStream / RequestSetBodySource; caller-supplied Transfer-Encoding/TE is rejected.
• Request trailers: chunked path only; forbidden fields and CRLF injection rejected.
• Responses: status line HTTP/1.0/1.1 only; bounded header line/block/count; obs-fold rejected; multiple Content-Length or TE+CL conflict → STATUS_INVALID_NETWORK_RESPONSE.
• Body framing: CL / chunked / close-delimited; no body for 1xx, 204, 205, 304, HEAD.
• Read-only 206 / Content-Range; Range and conditional helpers; optional RFC 9111 in-memory cache participates in validation and partial combining.
• Content-Encoding: gzip/deflate/br/compress/zstd/dcz/aes128gcm/exi/pack200-gzip/identity (max two layers, reverse decode; bounded expansion).
• Interim 1xx (except 101) swallowed and reparsed; automatic redirects; keep-alive pool reuse.
• Proxy: HTTPS CONNECT; cleartext HTTP absolute-form; Proxy-Authorization only from explicit config.

HTTP/2 (RFC 9113 + HPACK)

• Preface + SETTINGS; client ENABLE_PUSH=0; CONTINUATION flood guards; flow control and pseudo-header checks.
• Pooled stream leases: multiple same-origin H2 requests; DATA sliced by flow control and MAX_FRAME_SIZE; request trailers as final HEADERS.
• Modes: TLS ALPN h2; h2c prior knowledge / Upgrade are opt-in (next section).
• RFC 8441 extended CONNECT when peer advertises SETTINGS_ENABLE_CONNECT_PROTOCOL=1 (WebSocket).
• GOAWAY/REFUSED_STREAM may yield STATUS_RETRY; high level fresh-retries safe methods once only.

HTTP/3 + QUIC v1 + QPACK

• WSK Datagram + kernel CNG main path; QUIC v1 packets/frames, TLS 1.3 over QUIC, ACK/loss/PTO, flow control, CIDs, close state machine.
• HTTP/3: critical control/QPACK unidirectional streams, SETTINGS, HEADERS/DATA, 1xx, trailers, GOAWAY/cancel; server push is rejected.
• Default Http3ConnectMode::Auto: first HTTPS uses TCP; only an exact h3 Alt-Svc from a response that already passed certificate and TLS-policy checks is cached. DNS/UDP may target the alternative; SNI, certificate checks, and :authority remain bound to the origin.
• HTTP/3 is not used for CertPolicy::NoVerify, HTTP proxies, cleartext HTTP, h2c, WebSocket, non-HTTP ALPN, or requests with Http2Priority.
• TCP fallback is allowed only while the request is still unsent, or when the one-replay safety rules apply.

WebSocket (RFC 6455)

• ws/wss; constant-time Accept compare; subprotocols; caller opening headers (library-controlled headers rejected).
• wss may offer h2,http/1.1 → RFC 8441 or fall back to HTTP/1.1 Upgrade; ws:// never implicitly uses h2c.
• Fragmented send / optional fragment receive; auto-Pong; UTF-8/length/control-frame limits; active/passive close.
• Handshake 3xx/401/407 are not auto-followed → STATUS_NOT_SUPPORTED.

Server-Sent Events (WHATWG event-stream)

• wknet::sse::SseClient: Connect / Receive / Close; GET only; default requires Content-Type: text/event-stream.
• Parser: partial chunks, comments, id/event/data/retry, multi-line data; Last-Event-ID tracking and reconnect injection.
• Auto-reconnect on by default; exponential backoff + retry:; no reconnect on HTTP 4xx open; Close aborts delay.
• Timeouts: separate ConnectTimeoutMs / body idle IdleTimeoutMs / per-ReceiveTimeoutMs (long streams are not bound to a single 30s whole-response deadline).
• Response bodies are truly incremental: when set, SendOptions.OnBody is invoked multiple times in arrival order; finalChunk is true only at the real end.
• First release: identity Content-Encoding; no SSE server; no POST-body SSE.

TLS / certificates / crypto

• TLS 1.2/1.3 single-version path; no in-handshake automatic downgrade; EMS + secure renegotiation indication; CBC requires EtM.
• Certificates: bounded chains, hostnames (IP → iPAddress SAN only; DNS names do not fall back to CN), offline revocation evidence, SPKI pins, mTLS callback signatures (private keys remain with the caller).
• Crypto: CNG first; ChaCha20-Poly1305, X25519, and similar filled by in-kernel software; minimum RSA 2048.

Session behavior (key defaults)

Behavior	Default
MaxRedirects	10; exhausted hops return the current 3xx without error
HTTPS→HTTP redirect	Rejected
Stale retry	GET/HEAD/OPTIONS only, exactly once
close-delimited / 101	Not returned to the pool
TRACE	Off (SendFlagAllowTrace)
Sync IRQL	PASSIVE_LEVEL

---

2. Default-off

Features that are implemented but disabled by default, with the fields that enable them. Headers: Types.h, Cache.h, websocket/WebSocket.h.

Capability	Object	Fields / usage
Expect: 100-continue	SendOptions	Flags |= SendFlagExpectContinue; optional ExpectContinueTimeoutMs (default 1000)
TRACE	SendOptions	Flags |= SendFlagAllowTrace (body / trailers / sensitive headers still rejected)
HTTP/1.1 pipeline	SessionConfig	EnableHttp11Pipeline = true; Http11PipelineMaxDepth (default 4, cap 64); Http11PipelineMethodMask (default GET|HEAD|OPTIONS)
h2c	SendOptions	Http2CleartextMode = PriorKnowledge or Upgrade
HTTP/2 PING keepalive	SessionConfig	Http2KeepAlive.Enabled = true; IdleMs / IntervalMs / AckTimeoutMs (defaults 30000 / 30000 / 5000)
HTTP/2 priority	SendOptions	Http2Priority → Http2Priority{ StreamDependency, Weight(1..256), Exclusive }
permessage-deflate	ConnectConfig	PerMessageDeflate.Enable = true; optional Client/ServerNoContextTakeover, Client/ServerMaxWindowBits (8..15)
TLS 1.2 compatibility / renegotiation	TlsConfig.Policy	Profile = CompatibilityExplicit, then EnableTls12RsaKeyExchange / EnableTls12Cbc / EnableTls12Sha1Signatures / EnableTls12Renegotiation; TlsConfig.MaxTls12Renegotiations (default 1, cap 4)
post-handshake client auth	TlsConfig.Policy	EnablePostHandshakeClientAuth = true, plus TlsConfig.ClientCredential
Hard revocation	TlsConfig.Policy	RequireRevocationCheck = true; caller supplies verifiable OCSP/CRL evidence
In-memory cache	SessionConfig / SendOptions	CacheCreate → SessionConfig.Cache; per-send SendFlagBypassCache / NoCacheStore / OnlyIfCached or SendOptions.Cache

Examples:

// Per send
wknet::http::SendOptions* options = nullptr;
wknet::http::SendOptionsCreate(&options);
options->Flags |= wknet::http::SendFlagExpectContinue;
options->ExpectContinueTimeoutMs = 1000;
options->Flags |= wknet::http::SendFlagAllowTrace;
options->Http2CleartextMode = wknet::http::Http2CleartextMode::PriorKnowledge;

wknet::http::Http2Priority priority = {};
priority.Weight = 16;
options->Http2Priority = &priority;

wknet::http::SendEx(session, wknet::http::Method::Get,
    url, urlLen, nullptr, nullptr, options, &response);
wknet::http::SendOptionsRelease(options);

// Session
wknet::http::SessionConfig config = wknet::http::DefaultSessionConfig();
config.EnableHttp11Pipeline = true;
config.Http11PipelineMaxDepth = 4;
config.Http11PipelineMethodMask =
    wknet::http::Http11PipelineMethodGet |
    wknet::http::Http11PipelineMethodHead |
    wknet::http::Http11PipelineMethodOptions;
config.Http2KeepAlive.Enabled = true;
config.Tls.Policy.Profile = wknet::http::TlsSecurityProfile::CompatibilityExplicit;
config.Tls.Policy.EnableTls12Cbc = true;
config.Tls.Policy.RequireRevocationCheck = true;

wknet::http::Cache* cache = nullptr;
wknet::http::CacheOptions cacheOptions = {};
cacheOptions.MaxBytes = 16 * 1024 * 1024;
cacheOptions.MaxEntries = 256;
cacheOptions.Mode = wknet::http::CacheMode::Private;
wknet::http::CacheCreate(&cacheOptions, &cache);
config.Cache = cache;

wknet::http::Session* session = nullptr;
wknet::http::SessionCreate(&config, &session);

// WebSocket
wknet::websocket::ConnectConfig cfg = wknet::websocket::DefaultConnectConfig();
cfg.Url = "wss://example.com/ws";
cfg.UrlLength = 18;
cfg.PerMessageDeflate.Enable = true;
wknet::websocket::WebSocket* ws = nullptr;
wknet::websocket::ConnectEx(session, &cfg, &ws);

TLS 1.3 0-RTT (EnableEarlyData / EarlyDataReplaySafe) exists only on internal TLS connection options and is not mapped to TlsConfig / SendOptions, so the product HTTP API cannot enable it. HTTP/3 application-data 0-RTT is listed under “Not supported”.

---

3. Policy rejection

The following behaviors are rejected by design. Rejection here is policy, not a missing implementation.

Behavior	Handling
Caller-written request Transfer-Encoding / TE	Rejected; the library owns framing
HTTP br as Transfer-Encoding	Rejected; br is Content-Encoding only
HTTP/2 PUSH_PROMISE	Protocol error
Unrequested/invalid WebSocket extensions	Rejected
Auto-follow WS handshake redirect / 401 / 407	STATUS_NOT_SUPPORTED
In-handshake TLS 1.3→1.2 automatic downgrade	Not done; only verified evidence allows explicit upper-layer reconnect
Cert matching: IP via dNSName/CN; DNS via CN fallback	Not done
Automatic HTTPS→HTTP redirect	Rejected by default
Online OCSP/CRL fetch	Library never initiates

---

4. Not supported

Capability	Notes
HTTP server / inbound request parser	Client library; no server role
SSE server / POST-body SSE	Client GET event-stream only
On-disk persistent HTTP cache	In-memory NonPaged cache objects only
Local HTTP/2 priority-tree bandwidth scheduling	Not implemented
WebSocket extensions other than permessage-deflate	Not negotiated
Online revocation fetching	Library does not initiate OCSP/CRL network fetch
Streaming Content-Encoding on SSE/OnBody paths (gzip/br, …)	First release requires identity; architecture can grow
QUIC v2, H3 0-RTT application data, active migration, multipath, ECN, DPLPMTUD, WebTransport, QUIC Datagram, WebSocket over H3	Not supported
WinHTTP / WinINet / SChannel as kernel main path	Not used
Separate client layer / second connection lifecycle	Not provided

---

Implementation strategy and trust model

• Transport: WSK. TLS/HTTP/certificates: kernel-path implementations.
• Cryptography: CNG/BCrypt first; gaps filled by in-kernel software.
• Trust: callers explicitly supply anchors, CA bundles, revocation evidence, and pins; the library never hard-codes system CAs.

Direction summary: roadmap. For capability status, use this matrix.