簡介

ylong_http 構(gòu)建了完整的 HTTP 能力，支持用戶使用 HTTP 能力完成通信場景的需求。

ylong_http 使用 Rust 編寫，為 OpenHarmony 的 Rust 能力構(gòu)筑提供支持。

ylong_http 在 OpenHarmony 中的位置

ylong_http 向 OpenHarmony 系統(tǒng)服務(wù)層中的網(wǎng)絡(luò)協(xié)議棧模塊提供 HTTP 協(xié)議支持，經(jīng)由網(wǎng)絡(luò)協(xié)議棧模塊幫助上層應(yīng)用建立 HTTP 通信能力。

以下是對于上圖關(guān)鍵字段的描述信息：

• APP：需要使用上傳下載能力的直接面向用戶的上層應(yīng)用。
• request：提供上傳下載能力的系統(tǒng)組件。
• netstack：提供網(wǎng)絡(luò)協(xié)議棧功能的系統(tǒng)組件。
• ylong_http：提供 HTTP 能力的系統(tǒng)組件。
  • ylong_http_client：ylong_http 下的模塊之一，提供 HTTP 客戶端能力。
  • ylong_http:ylong_http 下的模塊之一，提供 HTTP 的基礎(chǔ)能力。
• ylong_runtime：ylong 提供的 Rust 異步運(yùn)行時(shí)庫。
• tokio：業(yè)界常用的第三方 Rust 異步運(yùn)行時(shí)庫。
• OpenSSL：業(yè)界常用的第三方 TLS 實(shí)現(xiàn)庫。

ylong_http 的內(nèi)部架構(gòu):

ylong_http 內(nèi)部當(dāng)前分為兩個(gè)主要模塊：ylong_http_client 客戶端模塊和 ylong_http 協(xié)議組件模塊。

ylong_http_client 模塊負(fù)責(zé)提供 HTTP 客戶端功能，能夠支持用戶發(fā)送 HTTP 請求，并接收 HTTP 響應(yīng)，內(nèi)部又分為三個(gè)主要部分:

• sync_impl：同步的 HTTP 客戶端實(shí)現(xiàn)，該客戶端實(shí)現(xiàn)不依賴于任何運(yùn)行時(shí)，可以直接在線程模型上運(yùn)行，但是整體使用同步阻塞策略。
• async_impl：異步的 HTTP 客戶端實(shí)現(xiàn)，該客戶端實(shí)現(xiàn)需要使用 Rust 的異步運(yùn)行時(shí)組件。異步 HTTP 客戶端利用 Rust 的異步能力，具有優(yōu)異的性能表現(xiàn)。
• Util：同步和異步的 HTTP 客戶端部分實(shí)現(xiàn)共通，例如自動(dòng)重定向、HTTP 代理等。

sync_impl 和 async_impl 接口原型基本一致（主要是 Rust 異步語法與同步語法的差異），所以用戶可以在較小的代碼改動(dòng)量下完成同步和異步邏輯的切換。

sync_impl 和 async_impl 的整體架構(gòu)相同，分為如下模塊：

• Client：對外提供 HTTP 客戶端的基本接口，例如配置客戶端的相關(guān)選項(xiàng)，發(fā)送 HTTP 請求等。
• ConnectionPool：主要負(fù)責(zé)大量連接管理，管理所有 Dispatcher 的生命周期，包括啟動(dòng)、運(yùn)行、停止。HTTP 協(xié)議是基于連接的通信協(xié)議，涉及連接復(fù)用、連接管理等功能。
• Dispatcher：主要負(fù)責(zé)單一連接管理，管理單個(gè)連接的啟動(dòng)、運(yùn)行、停止、傳輸。每個(gè)連接都被一個(gè) Dispatcher 管轄，由 Dispatcher 決定當(dāng)前待發(fā)送的請求是不是使用它管理的連接。
• Connections：連接對象，可以是 TCP 連接、TLS 連接或者是更加泛化的連接對象，在該連接上進(jìn)行消息傳輸和接收，是 Client 和 HTTP 協(xié)議的底座。
• Connector：負(fù)責(zé)創(chuàng)建連接對象。Connector 也是一個(gè) trait，用戶可以使用它來定義創(chuàng)建連接時(shí)的行為。

Util 中包含了同步和異步的 HTTP 客戶端共通的能力，例如：

• Redirect：HTTP 自動(dòng)重定向能力。當(dāng) HTTP 響應(yīng)返回重定向相關(guān)的狀態(tài)碼時(shí)，HTTP 客戶端會(huì)進(jìn)行自動(dòng)重定向，并自動(dòng)發(fā)送新的請求到下一跳。
• Proxy：HTTP 代理能力。發(fā)送 HTTP 請求時(shí)，向代理發(fā)送而非直接發(fā)送給原始服務(wù)器，然后由代理服務(wù)器返回原始服務(wù)器的響應(yīng)。
• Pool：通用連接池實(shí)現(xiàn)，支持多個(gè)同步或異步連接的管理，便于上層同步或異步客戶端復(fù)用已有連接，減少連接重復(fù)創(chuàng)建次數(shù)，提高性能。
• OpenSSL_adapter：HTTPS 需要在 HTTP 的基礎(chǔ)上使用 TLS 能力，在 OpenHarmony 上使用的是 OpenSSL，所以需要對 OpenSSL 的接口進(jìn)行 Rust 封裝。

ylong_http 模塊負(fù)責(zé)提供 HTTP 的基礎(chǔ)能力，例如 HTTP2 的 HPACK、HTTP3 的 QPACK 等，主要包含以下關(guān)鍵模塊：

• Request：HTTP 請求基礎(chǔ)能力，根據(jù) RFC9110 規(guī)定實(shí)現(xiàn)了 HTTP 請求的所有內(nèi)容和行為。HTTP 請求主要用于向指定服務(wù)器發(fā)送請求。
• Response：HTTP 響應(yīng)基礎(chǔ)能力，根據(jù) RFC9110 規(guī)定實(shí)現(xiàn)了 HTTP 響應(yīng)的所有內(nèi)容和行為。HTTP 響應(yīng)主要是服務(wù)器針對客戶端請求的回應(yīng)。
• Body： HTTP 消息體能力，根據(jù) RFC9110 規(guī)定實(shí)現(xiàn)了 HTTP 消息體的所有內(nèi)容和行為。HTTP 消息體保存主要數(shù)據(jù)內(nèi)容，以便客戶端和服務(wù)器通信。 HTTP 消息體在協(xié)議中有多種形式，在 ylong_http 庫中有對應(yīng)實(shí)現(xiàn)，例如 EmptyBody 對應(yīng)于空消息體，TextBody 對應(yīng)于明文消息體，ChunkBody 對應(yīng)于分塊消息體，Mime 對應(yīng)于 Multipart 消息體。
• H1：HTTP1 的所有基礎(chǔ)能力，例如 HTTP1 格式的請求和響應(yīng)的編碼器和解碼器等。
• H2：HTTP2 的所有基礎(chǔ)能力，例如 HTTP2 格式的請求和響應(yīng)的編碼器和解碼器、HTTP2 幀編碼器和解碼器、HPACK等。
• H3：HTTP3 的所有基礎(chǔ)能力，例如 HTTP3 格式的請求和響應(yīng)的編碼器和解碼器、QPACK 等。

編譯構(gòu)建

若使用 GN 編譯工具鏈, 在 BUILD.gn 的 deps 段下添加依賴。添加后使用 GN 進(jìn)行編譯和構(gòu)建：

deps += ["http://example_path/ylong_http_client:ylong_http_client"]

若使用 Cargo 編譯工具鏈, 在 Cargo.toml 下添加依賴。添加后使用 cargo 進(jìn)行編譯和構(gòu)建：

[dependencies]
ylong_http_client = { path = "/example_path/ylong_http_client" } # 請使用路徑依賴

目錄

ylong_http
├── docs                        # ylong_http 用戶指南
├── figures                     # ylong_http 圖片資源
├── patches                     # ylong_http 門禁使用的補(bǔ)丁資源
├── ylong_http
│   ├── examples                # ylong_http 基礎(chǔ)組件庫代碼示例
│   ├── src                     # ylong_http 基礎(chǔ)組件庫源碼
│   │   ├── body                # Body trait 定義和擴(kuò)展 Body 類型
│   │   ├── h1                  # HTTP/1.1 相關(guān)組件實(shí)現(xiàn)
│   │   ├── h2                  # HTTP/2 相關(guān)組件實(shí)現(xiàn)
│   │   ├── h3                  # HTTP/3 相關(guān)組件實(shí)現(xiàn)
│   │   ├── huffman             # Huffman 編解碼實(shí)現(xiàn)
│   │   ├── request             # Request 定義和實(shí)現(xiàn)
│   │   └── response            # Response 定義和實(shí)現(xiàn)
│   └── tests                   # ylong_http 基礎(chǔ)組件庫測試目錄
│
└── ylong_http_client
    ├── examples                # ylong_http_client 庫代碼示例
    ├── src                     # ylong_http_client 庫源碼
    │   ├── async_impl          # ylong_http_client 異步客戶端實(shí)現(xiàn)
    │   │   ├── conn            # 異步連接層
    │   │   ├── downloader      # 異步下載器實(shí)現(xiàn)
    │   │   ├── ssl_stream      # 異步 tls 適配層
    │   │   └── uploader        # 異步上傳器實(shí)現(xiàn)   
    │   ├── sync_impl           # ylong_http_client 同步客戶端實(shí)現(xiàn)
    │   │   └── conn            # 同步連接層
    │   └── util                # ylong_http_client 組件實(shí)現(xiàn)
    │       ├── c_openssl       # OpenSSL 封裝層
    │       │   ├── ffi         # ffi 封裝層
    │       │   └── ssl         # ssl 適配層
    │       └── config          # 配置選項(xiàng)實(shí)現(xiàn)
    │           └── tls         # TLS 選項(xiàng)實(shí)現(xiàn)
    │               └── alpn    # ALPN 實(shí)現(xiàn)
    └── tests                   # ylong_http_client 庫測試目錄

審核編輯：劉清