ylong_http

简介

ylong_http 为 OpenHarmony 系统服务层提供 HTTP 协议组件和客户端网络能力。源码树包含两个 Rust crate：

ylong_http：HTTP 协议数据结构和编解码组件，包括请求/响应类型、头字段、 HTTP/1.1、HTTP/2 HPACK、HTTP/3 QPACK 和 body 实现。
ylong_http_client：同步与异步 HTTP 客户端、连接池、DNS、OpenSSL FFI TLS、代理、重定向、上传下载辅助能力和示例。

HTTPS 代理能力

ylong_http_client 异步客户端支持通过 HTTPS 代理访问 HTTP 和 HTTPS 目标站点。 HTTPS 代理路径会先与代理服务器建立 TLS；HTTPS 目标站点再通过 CONNECT 隧道建立第二层 TLS。代理 TLS 配置和目标站点 TLS 配置相互独立。

文档与验证入口：

技术方案：docs/preliminary_solution.md
可运行验证：docs/runnable_demo.md
知识产权与第三方依赖说明：docs/ip_and_dependencies.md
用户指南：docs/user_guide.md

注册第三方代理协议

外部 Rust crate 可以实现公开的 ProxyProtocol trait，并把配置好的实例注册到某一个异步 ClientBuilder。这是编译、链接到应用中的 Rust 扩展点：使用方只依赖公开接口，无需修改 ylong_http_client；它不是运行时共享库加载器、稳定插件 ABI 或全局注册表。

核心库校验 custom 路由，解析并连接代理，执行连接超时控制，并继续负责 HTTP 分派、连接池，以及 HTTPS origin 的 TLS 与 ALPN。
插件接收已经连接到代理的 stream，按协议完成代理侧认证、可选的代理侧 TLS 和隧道握手。

快速验证

在仓库根目录运行独立的可观测代理插件 demo：

cargo run --quiet --manifest-path examples/proxy_plugin_demo/Cargo.toml

成功运行的最后一行是：

DEMO PASS: registered proxy protocols are independently selectable and reusable

独立 demo crate 及其公开 API 引用说明实现过程不需要改动核心库源码；运行时事件与计数则表明 blue、green 两个实例能够独立选路，且连续两个 blue 请求复用了连接池中的同一条 tunnel。参见可观测证明图。

custom protocol 支持异步 HTTP/1.1 和 HTTP/2 路径，不支持同步客户端或 HTTP/3 custom transport。公开 API 以及完整的注册、配置、错误、信任和性能规则以用户指南为准。

继续阅读：职责边界架构图、 custom HTTPS 时序图和 demo 证据指南。

架构

OpenHarmony 中的位置

ylong_http 向 OpenHarmony 系统服务层中的 netstack 提供 HTTP 协议支持。上层系统服务和应用通过网络协议栈能力完成上传、下载和 HTTP 通信。

structure

客户端架构

异步 HTTPS 代理路径分为四个边界：

API 和配置：ClientBuilder、Proxy、Proxies、TlsConfig 和代理专属 TLS 配置。
客户端运行时：Client::request、ConnectionPool、dispatcher 复用、DNS、TCP 建连和超时元数据。
代理模块：async_impl::proxy::{route,http,https,tls,tunnel} 负责代理路由、HTTP 目标转发、 HTTPS 目标隧道、proxy TLS 和 CONNECT 响应解析。
网络对端：HTTPS 代理和目标站点。代理凭据只作用于代理；origin TLS 和 proxy TLS 使用独立信任配置。

技术细节图：

请求时序：figures/https_proxy_request_sequence.svg
TLS 边界：figures/https_proxy_tls_boundaries.svg
底层 I/O 栈：figures/https_proxy_io_stack.svg
注册协议架构：figures/proxy_plugin_architecture.svg
注册协议 custom HTTPS 时序：figures/proxy_plugin_sequence.svg

核心模块

ylong_http_client 围绕运行时专属客户端入口和共享工具模块组织：

async_impl：异步客户端入口、请求/响应封装、连接池、连接器、DNS、HTTP/1.1 和 HTTP/2 连接驱动、QUIC 预留结构、上传下载 operator 和 ssl_stream。
async_impl::proxy：HTTPS 代理路由和传输模块。route.rs 选择直连、HTTP proxy 或 HTTPS proxy；http.rs 处理 HTTP 目标经过代理；https.rs 处理直连 TLS、HTTP CONNECT 和 HTTPS proxy CONNECT；tls.rs 封装异步 OpenSSL 握手；tunnel.rs 构造 CONNECT 请求并解析 CONNECT 响应；plugin.rs 定义链接式 custom protocol 边界和每客户端注册表。
sync_impl：同步 HTTP 客户端路径。HTTPS 代理能力限定在异步客户端路径，也不支持注册 custom protocol。
util：共享的重定向、代理配置、连接池辅助、dispatcher、拦截器、进度/限速、HTTP/2 和 HTTP/3 工具、OpenSSL FFI 适配层。

ylong_http 提供客户端使用的协议层：

request、response、headers、version 和 URI 解析。
body 中的 empty、text、chunked 和 MIME body。
h1、h2、h3 和 huffman 协议组件。

构建与验证

环境准备

构建需要 Rust 和 Cargo。启用 TLS 时还需要 OpenSSL 开发文件，以及对应的库和头文件路径：

export OPENSSL_LIB_DIR=$(pkg-config --variable=libdir openssl)
export OPENSSL_INCLUDE_DIR=$(pkg-config --variable=includedir openssl)

Cargo 构建检查

Tokio 运行时路径：

cargo check -p ylong_http_client \
  --features "async,http1_1,tokio_base,c_openssl_3_0"

OpenHarmony ylong 运行时路径：

cargo check -p ylong_http_client \
  --features "async,http1_1,http2,ylong_base,c_openssl_3_0"

HTTPS 代理正式示例：

cargo check -p ylong_http_client \
  --features "async,http1_1,tokio_base,c_openssl_3_0" \
  --example async_https_proxy

无 TLS 路由和错误检查：

cargo test -p ylong_http_client --lib ut_proxy_route \
  --features "async http1_1 tokio_base" --release

OpenHarmony GN 目标

ylong_http/BUILD.gn 定义协议 crate 目标：

:ylong_http
feature：http1_1、http2、huffman、ylong_base

ylong_http_client/BUILD.gn 定义客户端 shared library 和单元测试目标：

:ylong_http_client_inner
:rust_ylong_http_client_test_ut
:unittest
feature：async、http1_1、http2、ylong_base、c_openssl_3_0、 __tls、__c_openssl
外部依赖：OpenSSL、rust_libc、ylong_runtime

下游 GN 目标应按 OpenHarmony 源码布局依赖 ylong_http_client_inner 目标。

正确性测试

cargo test -p ylong_http_client --test sdv_async_https_proxy \
  --features "async http1_1 ylong_base c_openssl_3_0" --release

cargo test -p ylong_http_client --test sdv_async_http_proxy \
  --features "async http1_1 ylong_base" --release

cargo test -p ylong_http_client --lib ut_proxy_route \
  --features "async http1_1 tokio_base c_openssl_3_0" --release

可运行验证

可运行验证指南提供从仓库根目录执行的命令，用于编译正式 async_https_proxy 示例、运行 HTTPS 代理和注册第三方代理协议 SDV，以及执行可观测代理插件 demo。这些检查保留了双层 TLS 路径、安全失败边界、公开扩展边界和 tunnel 复用证明。

历史性能复现资产保存在 archive/https-proxy-benchmark-repro 分支。

ylong_http
├── docs                         # 用户指南、技术方案、运行验证、依赖说明
├── examples
│   └── proxy_plugin_demo        # 可观测注册协议 demo
├── figures                      # 架构图和协议图
├── ylong_http
│   ├── BUILD.gn
│   ├── Cargo.toml
│   └── src
│       ├── body                 # body 实现
│       ├── h1                   # HTTP/1.1 编解码组件
│       ├── h2                   # HTTP/2 frame、HPACK、encoder/decoder
│       ├── h3                   # HTTP/3 frame、QPACK、stream 辅助
│       ├── huffman              # HPACK/QPACK Huffman 支持
│       ├── request              # request 和 URI 类型
│       └── response             # response 和 status 类型
└── ylong_http_client
    ├── BUILD.gn
    ├── Cargo.toml
    ├── examples
    │   └── async_https_proxy.rs
    ├── src
    │   ├── async_impl
    │   │   ├── conn             # 异步 HTTP 连接驱动
    │   │   ├── connector        # DNS/TCP/TLS 建连
    │   │   ├── dns              # 默认 DNS、DoH、Happy Eyeballs
    │   │   ├── proxy            # HTTP/HTTPS 代理路由、TLS、CONNECT
    │   │   ├── ssl_stream       # 异步 OpenSSL stream 集成
    │   │   ├── client.rs
    │   │   ├── pool.rs
    │   │   ├── request.rs
    │   │   └── response.rs
    │   ├── sync_impl            # 同步客户端路径
    │   └── util
    │       ├── c_openssl        # OpenSSL FFI 适配层
    │       ├── config           # client、connector、TLS、HTTP 配置
    │       ├── h2               # HTTP/2 客户端工具
    │       ├── h3               # HTTP/3 客户端工具
    │       ├── interceptor      # 拦截器扩展点
    │       ├── monitor          # 计时和监控辅助
    │       ├── progress         # 进度和限速辅助
    │       ├── proxy.rs
    │       └── redirect.rs
    └── tests                    # SDV 与集成测试

用户指南

详细内容见 docs/user_guide.md。