From e2d2e52a5ed9b6a1b989cbf905578ec60f485669 Mon Sep 17 00:00:00 2001 From: hu-kai45 Date: Wed, 5 Jul 2023 16:04:40 +0800 Subject: [PATCH] =?UTF-8?q?README=20=E6=95=B4=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: hu-kai45 --- README.md | 93 ++++++++++++++++++++-------------------------------- README_zh.md | 92 ++++++++++++++++++++------------------------------- 2 files changed, 71 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 0336ebb..124d3ce 100644 --- a/README.md +++ b/README.md @@ -32,64 +32,41 @@ The following is the description information for the key fields in the figure ab ![inner_structure](./figures/inner_structure.png) -The following is the description information for the key fields in the figure above: - -- `ylong_http_client`: One of the modules under `ylong_http` provides HTTP client capabilities. - - `sync_impl`: Synchronize HTTP client implementation without relying on any runtime. - - `Client`: Synchronize HTTP clients to send HTTP requests. - - `ConnectionPool`: Manage all `Dispatchers`. - - `Dispatcher`: Manage the usage rights of `Connections`. - - `Connector`: Used to create a synchronous connection. - - `Connections`: Synchronous TCP or TLS connections, etc. - - `async_impl`: Asynchronous HTTP client implementation. - - `Client`: Asynchronous HTTP client used to send HTTP requests. - - `ConnectionPool`: Manage all `Dispatchers`. - - `Dispatcher`: Manage the usage rights of `Connections`. - - `Connector`: Used to create an asynchronous connection. - - `Connections`: Asynchronous TCP or TLS connections, etc. - - `Util`: Contains common components for both synchronous and asynchronous HTTP client implementations. - - `Redirect`: HTTP automatic redirection policy. - - `Proxy`: HTTP proxy policy. - - `Pool`: Universal Connection pool implementation. - - `OpenSSL_adapter`: OpenSSL Rust adaptation layer. -- `ylong_http`: One of the modules under `ylong_http` provides the basic components of HTTP. - - `Request`: HTTP Request implementation. - - `Response`: HTTP Response implementation. - - `Body`: HTTP message body implementation. - - `TextBody`: HTTP message body in plain text. - - `EmptyBody`: Empty message body implementation. - - `Mime`: Multipart message body implementation. - - `ylong_http`: ChunkBody message body implementation. - - `H1`: HTTP1 related component implementation. - - `H2`: HTTP2 related component implementation. - - `H3`: HTTP3 related component implementation. - -### ylong_http_client crate - -`ylong_http_client` crate supports HTTP client functionality and allows users -to create HTTP clients to send HTTP requests to specified servers. - -Abilities supported by the current `ylong_http_client` crate: - -- Synchronous and asynchronous HTTP clients. -- HTTP/1.1 and HTTP/2 protocol versions. -- Proxy. -- Redirect. -- Automatic retry. -- Progress callback. -- Connection management and reuse. - -### ylong_http crate - -`ylong_http` crate provides various basic components of the HTTP protocol, such -as serialization components, compression components, etc. - -Abilities supported by the current `ylong_http` crate: - -- Serializer and deserializer of `HTTP/1.1` and `HTTP/2`. -- HPACK implementation. -- Basic types of HTTP Request and HTTP Response. -- Body trait and implementations of bodies. +`ylong_http` is currently divided into two main modules internally: `ylong_http_client` client module and `ylong_http` protocol component module. + +The `ylong_http_client` module is responsible for providing HTTP client functions, which can support users to send HTTP requests and return HTTP responses. + +`ylong_http_client` is divided into three main parts: +- `sync_impl`: A synchronous HTTP client implementation that does not depend on any runtime and can run directly on the thread model, but uses a synchronous blocking strategy as a whole. +- `async_impl`: an asynchronous HTTP client implementation that requires the use of Rust's asynchronous runtime components. Asynchronous HTTP clients take advantage of Rust's asynchronous capabilities to provide excellent performance. +- `Util`: some implementations of synchronous and asynchronous HTTP clients are common, so this part of common implementation is placed in this part, such as automatic redirection implementation, HTTP proxy implementation, etc. + +Although the overall implementation of `sync_impl` and `async_impl` are in two forms, the prototypes of the interfaces are basically the same (mainly the difference between Rust asynchronous syntax and synchronous syntax). Since the interface is basically the same, users can switch between synchronous and asynchronous logic with a small amount of code changes. + +The overall structure of `sync_impl` and `async_impl` is the same, divided into the following modules: +- `Client`: Provide the basic interface of the HTTP client externally, such as configuring related options of the client, sending HTTP requests, etc. +- `ConnectionPool`: Mainly responsible for a large number of connection management, managing the life cycle of all `Dispatcher`, including start, run, stop. The HTTP protocol is a communication protocol based on various IO connections, so it may involve functions such as connection multiplexing and connection management. +- `Dispatcher`: Mainly responsible for single connection management, managing the start, operation, stop, and transmission of a single connection. Each connection is governed by a `Dispatcher`, and it is up to `Dispatcher` to decide whether the current request to be sent is through the connection it manages. +- `Connections`: The real connection object, which can be a TCP connection, a TLS connection or a more generalized connection object. Messages are transmitted and received on this connection, and it is the base of `Client` and the HTTP protocol. +- `Connector`: Responsible for creating connection objects. This part provides traits so that the behavior when creating a connection can be defined by the user. + +`Util` contains the common capabilities of synchronous and asynchronous HTTP clients, such as: +- `Redirect`: HTTP automatic redirection capability, when the HTTP response returns a status code related to redirection, the HTTP client will perform automatic redirection and automatically send a new request to the next hop. +- `Proxy`: HTTP proxy capability, when sending an HTTP request, send it to the proxy instead of directly to the original server, and then the proxy server returns a response. +- `Pool`: A general-purpose connection pool implementation that supports the management of multiple synchronous or asynchronous connections, which facilitates the reuse of existing connections by upper-layer synchronous or asynchronous clients to reduce the number of repeated connection creations and improve performance. +- `OpenSSL_adapter`: HTTPS needs to use TLS capability on the basis of HTTP, and OpenSSL’s TLS capability is used on OpenHarmony, so the OpenSSL interface needs to be encapsulated in Rust before it can be used by Rust. + +The `ylong_http` module is responsible for providing the basic capabilities of HTTP, such as HTTP2's HPACK, HTTP3's QPACK, etc. + +`ylong_http` mainly includes the following key modules: +- `Request`: The basic capability of HTTP requests, which implements all the content and behaviors of HTTP requests according to `RFC9110`. HTTP requests are mainly used to send requests to specified servers to obtain server resources. +- `Response`: The basic capability of HTTP response, which implements all the content and behavior of HTTP response according to `RFC9110`. The HTTP response is mainly the server's response to the request sent by the client to return the results generated by the server. +- `Body`: + HTTP message body capability, according to `RFC9110` regulations to achieve all the content and behavior of the HTTP message body. The main data content is stored in the HTTP message body, so that the client and server can communicate. + The HTTP message body has various forms in the protocol, and it is also implemented in the `ylong_http` library. For example, `EmptyBody` corresponds to an empty message body, `TextBody` corresponds to a plaintext message body, `ChunkBody` corresponds to a chunked message body,` Mime` corresponds to the Multipart message body. +- `H1`: All basic capabilities of HTTP1, such as serializers and deserializers for requests and responses in HTTP1 format. +- `H2`: All basic capabilities of HTTP2, such as serializers and deserializers for requests and responses in HTTP2 format, HTTP2 frame serializers, HPACK, etc. +- `H3`: All basic capabilities of HTTP3, such as serializers and deserializers for requests and responses in HTTP3 format, QPACK, etc. ## Build diff --git a/README_zh.md b/README_zh.md index fcac8e2..5c55cb0 100644 --- a/README_zh.md +++ b/README_zh.md @@ -25,64 +25,44 @@ ylong_http 向 OpenHarmony 系统服务层中的网络协议栈模块提供 HTTP - `OpenSSL`：业界常用的第三方 TLS 实现库, C 语言实现。 ### ylong_http 的内部架构: -![inner_structure](./figures/inner_structure.png) -以下是对于上图关键字段的描述信息： +![inner_structure](./figures/inner_structure.png) -- `ylong_http_client` 库：`ylong_http` 下的模块之一，提供 HTTP 客户端能力。 - - `sync_impl`：同步 HTTP 客户端实现，不依赖于任何运行时。 - - `Client`：同步 HTTP 客户端，用于发送 HTTP 请求。 - - `ConnectionPool`：管理所有的 `Dispatcher`。 - - `Dispatcher`：管理 `Connections` 的使用权。 - - `Connector`：用于创建同步连接。 - - `Connections`：同步的 TCP 或 TLS 连接等。 - - `async_impl`：异步 HTTP 客户端实现，不依赖于任何运行时。 - - `Client`：异步 HTTP 客户端，用于发送 HTTP 请求。 - - `ConnectionPool`：管理所有的 `Dispatcher`。 - - `Dispatcher`：管理 `Connections` 的使用权。 - - `Connector`：用于创建异步连接。 - - `Connections`：异步的 TCP 或 TLS 连接等。 - - `Util`：包含同步和异步 HTTP 客户端实现的共同组件。 - - `Redirect`：HTTP 自动重定向策略。 - - `Proxy`：HTTP 代理策略。 - - `Pool`：通用的连接池实现。 - - `OpenSSL_adapter`：OpenSSL Rust 适配层。 -- `ylong_http`：提供 HTTP 基础组件的模块。 - - `Request`：HTTP 请求实现 - - `Response`：HTTP 响应实现 - - `Body`：HTTP 消息体实现，提供基础的 trait。 - - `TextBody`：纯文本的消息体实现。 - - `EmptyBody`：空的消息体实现。 - - `Mime`：Multipart 消息体实现。 - - `ylong_http`：ChunkBody 消息体实现。 - - `H1`：HTTP1 相关组件实现。 - - `H2`：HTTP2 相关组件实现。 - - `H3`：HTTP3 相关组件实现。 - -### ylong_http_client 库 - -ylong_http_client 库支持 HTTP 客户端功能，支持用户创建 HTTP 客户端向指定 Server 发送 HTTP 请求。 - -当前 ylong_http_client 库支持的功能： - -- 同步、异步客户端 -- HTTP/1.1、HTTP/2 协议版本 -- 代理 -- 自动重定向 -- 自动重试 -- 进度回调显示 -- 连接管理和复用 - -### ylong_http 库 - -ylong_http 库提供了 HTTP 协议的各种基础组件，例如序列化组件、压缩组件等。 - -当前 ylong_http 库支持的功能： - -- HTTP/1 序列化组件、HTTP/2 序列化组件 -- HPACK 头部压缩实现 -- Request、Response 以及相关基础类型 -- Body trait 以及 Body 的各种实现 +`ylong_http` 当前内部整体分为两个主要模块：`ylong_http_client` 客户端模块和 `ylong_http` 协议组件模块。 + +`ylong_http_client` 模块负责提供 HTTP 客户端功能，能够支撑用户发送 HTTP 请求，并返回 HTTP 响应。 + +`ylong_http_client` 内部又分为三个主要部分: + - `sync_impl`：同步的 HTTP 客户端实现，该客户端实现不依赖于任何运行时，可以直接在线程模型上运行，但是整体使用同步阻塞策略。 + - `async_impl`：异步的 HTTP 客户端实现，该客户端实现需要使用 Rust 的异步运行时组件。异步 HTTP 客户端利用 Rust 的异步能力能够提供优异的性能表现。 + - `Util`：同步和异步的 HTTP 客户端有一部分实现是共通的，所以这部分通用实现放在该部分中，例如自动重定向实现、HTTP 代理实现等。 + +`sync_impl` 和 `async_impl` 虽然整体实现是两个形式，但是接口的原型基本一致（主要是 Rust 异步语法与同步语法的差异）。由于接口基本一致所以用户可以在较小的代码改动量之下完成同步和异步逻辑的切换。 + +`sync_impl` 和 `async_impl` 的整体架构相同，分为如下模块： + - `Client`：对外提供 HTTP 客户端的基本接口，例如配置客户端的相关选项，发送 HTTP 请求等。 + - `ConnectionPool`：主要负责大量连接管理，管理所有 `Dispatcher` 的生命周期，包括启动、运行、停止。HTTP 协议是基于各种 IO 连接的通信协议，所以可能涉及连接复用、连接管理等功能。 + - `Dispatcher`：主要负责单一连接管理，管理单个连接的启动、运行、停止、传输。每个连接都被一个 `Dispatcher` 管辖，由 `Dispatcher` 决定当前待发送的请求是不是走它管理的连接。 + - `Connections`：真正的连接对象，可以是 TCP 连接、TLS 连接或者是更加泛化的连接对象，在该连接上进行消息传输和接收，是 `Client` 和 HTTP 协议的底座。 + - `Connector`：负责创建连接对象。这一部分提供了 trait，因此可以由用户定义创建连接时的行为。 + +`Util` 中包含了同步和异步的 HTTP 客户端共通的能力，例如： +- `Redirect`：HTTP 自动重定向能力，当 HTTP 响应返回重定向相关的状态码时，HTTP 客户端会进行自动重定向，自动发送新的请求到下一跳。 +- `Proxy`：HTTP 代理能力，发送 HTTP 请求时，向代理发送而非直接发送给原始服务器，然后由代理服务器返回响应。 +- `Pool`：通用的连接池实现，支持多个同步或异步连接的管理，便于上层同步或异步客户端复用已有连接，以减少连接重复创建次数以提高性能。 +- `OpenSSL_adapter`：HTTPS 需要在 HTTP 的基础上使用 TLS 能力，在 OpenHarmony 上使用 OpenSSL 的 TLS 能力，所以需要对 OpenSSL 的接口进行 Rust 封装才可以被 Rust 使用。 + +`ylong_http` 模块负责提供 HTTP 的基础能力，例如 HTTP2 的 HPACK、HTTP3 的 QPACK 等。 + +`ylong_http` 主要包含以下关键模块： +- `Request`：HTTP 请求基础能力，根据 `RFC9110` 规定实现了 HTTP 请求的所有内容和行为。HTTP 请求主要用于向指定服务器发送请求，以获取服务器资源。 +- `Response`：HTTP 响应基础能力，根据 `RFC9110` 规定实现了 HTTP 响应的所有内容和行为。HTTP 响应主要是服务器针对客户端发送请求的回应，以返回服务器产生的结果。 +- `Body`： + HTTP 消息体能力，根据 `RFC9110` 规定实现了 HTTP 消息体的所有内容和行为。HTTP 消息体内保存了主要的数据内容，以便客户端和服务器通信。 + HTTP 消息体在协议中有多种形式，在 `ylong_http` 库中也有实现，例如 `EmptyBody` 对应于空消息体，`TextBody` 对应于明文消息体，`ChunkBody` 对应于分块消息体，`Mime` 对应于 Multipart 消息体。 +- `H1`：HTTP1 的所有基础能力，例如 HTTP1 格式的请求和响应的序列化器和反序列化器等。 +- `H2`：HTTP2 的所有基础能力，例如 HTTP2 格式的请求和响应的序列化器和反序列化器、HTTP2 帧序列化器、HPACK等。 +- `H3`：HTTP3 的所有基础能力，例如 HTTP3 格式的请求和响应的序列化器和反序列化器、QPACK 等。 ## 编译构建 -- Gitee