README.md
1# ylong_http
2
3## Introduction
4
5`ylong_http` has built a complete HTTP capability, supporting users to use HTTP
6capability to meet the needs of communication scenarios.
7
8`ylong_http` is written in the Rust language to support OpenHarmony's Rust
9capability.
10
11### The position of ylong_http in OpenHarmony
12
13`ylong_http` provides HTTP protocol support to the `netstack` module in the
14`OpenHarmony` system service layer, and through the `netstack` module, helps
15upper layer applications build HTTP communication capabilities.
16
17
18
19The following is the description information for the key fields in the figure above:
20
21- `APP`: A direct user facing upper level application that requires the ability to upload and download.
22- `request`: The component in the OpenHarmony system service layer that provides upload and download capabilities.
23- `netstack`: The system component in the OpenHarmony system service layer that provides network protocol stack functionality.
24- `ylong_http`: The system component in the OpenHarmony system service layer that provides HTTP protocol stack functionality.
25 - `ylong_http_client`: One of the modules under `ylong_http` provides HTTP client capabilities.
26 - `ylong_http`: One of the modules under `ylong_http` provides the basic components of HTTP.
27- `ylong_runtime`: Rust asynchronous runtime library provided by `ylong` in the system service layer.
28- `tokio`: The third-party rust asynchronous runtime library commonly used in the industry.
29- `OpenSSL`: A commonly used third-party TLS implementation library in the industry.
30
31### The internal structure of ylong_http
32
33
34
35`ylong_http` is currently divided into two main modules: `ylong_http_client` client module and `ylong_http` protocol component module.
36
37The `ylong_http_client` module is responsible for providing HTTP client functions, which can support users to send HTTP requests and receive HTTP responses. It is divided into three main parts:
38- `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.
39- `async_impl`: an asynchronous HTTP client implementation that requires the use of Rust's asynchronous runtime components. The asynchronous HTTP client takes advantage of Rust's asynchronous capabilities and has excellent performance.
40- `Util`: The synchronous and asynchronous HTTP client parts are common, such as automatic redirection, HTTP proxy, etc.
41
42The interface prototypes of `sync_impl` and `async_impl` are basically the same (mainly the difference between Rust asynchronous syntax and synchronous syntax), so users can switch between synchronous and asynchronous logic with a small amount of code changes.
43
44The overall structure of `sync_impl` and `async_impl` is the same, divided into the following modules:
45- `Client`: Provide the basic interface of the HTTP client externally, such as configuring related options of the client, sending HTTP requests, etc.
46- `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 connection-based communication protocol, involving functions such as connection multiplexing and connection management.
47- `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 the `Dispatcher` to determine whether the current request to be sent uses the connection it manages.
48- `Connections`: 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.
49- `Connector`: Responsible for creating connection objects. Connector is also a trait that users can use to define the behavior when creating a connection.
50
51`Util` contains the common capabilities of synchronous and asynchronous HTTP clients, such as:
52- `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.
53- `Proxy`: HTTP proxy capability. When an HTTP request is sent, it is sent to a proxy instead of directly to the origin server, and the proxy server then returns the origin server's response.
54- `Pool`: Universal connection pool implementation, supports the management of multiple synchronous or asynchronous connections, facilitates the reuse of existing connections by upper-layer synchronous or asynchronous clients, reduces the number of repeated connection creations, and improves performance.
55- `OpenSSL_adapter`: HTTPS needs to use TLS capability on the basis of HTTP, and OpenSSL is used on OpenHarmony, so the OpenSSL interface needs to be encapsulated in Rust.
56
57The `ylong_http` module is responsible for providing the basic capabilities of HTTP, such as HTTP2's HPACK, HTTP3's QPACK, etc. It mainly includes the following key modules:
58- `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.
59- `Response`: The basic capability of HTTP response, which implements all the content and behavior of HTTP response according to `RFC9110`. The HTTP response is basically the server's response to the client's request.
60- `Body`:
61 HTTP message body capability, according to `RFC9110` regulations to achieve all the content and behavior of the HTTP message body. The HTTP message body holds the main data content for client and server communication.
62 The HTTP message body has various forms in the protocol, and there are corresponding implementations in the `ylong_http` library. For example, `EmptyBody` corresponds to an empty message body, `TextBody` corresponds to a plaintext message body, and `ChunkBody` corresponds to a chunked message body. `Mime` corresponds to the Multipart message body.
63- `H1`: All basic capabilities of HTTP1, such as encoders and decoders for requests and responses in HTTP1 format.
64- `H2`: All basic capabilities of HTTP2, such as encoders and decoders for requests and responses in HTTP2 format, HTTP2 frame encoders and decoders, HPACK, etc.
65- `H3`: All basic capabilities of HTTP3, such as encoders and decoders for requests and responses in HTTP3 format, QPACK, etc.
66
67## Build
68
69`GN` is supported. User should add dependencies in `deps` of `BUILD.gn` to build this crate.
70
71```gn
72deps += ["//example_path/ylong_http_client:ylong_http_client"]
73```
74
75`Cargo` is supported. User should add dependencies in ```Cargo.toml``` to build this crate.
76
77```toml
78[dependencies]
79ylong_http_client = { path = "/example_path/ylong_http_client" }
80```
81
82## Directory
83
84```text
85ylong_http
86├── docs # User's guide
87├── figures # Resources
88├── patches # Patches for ci
89├── ylong_http
90│ ├── examples # Examples of ylong_http
91│ ├── src # Source code ylong_http
92│ │ ├── body # Body trait and body types
93│ │ ├── h1 # HTTP/1.1 components
94│ │ ├── h2 # HTTP/2 components
95│ │ ├── h3 # HTTP/3 components
96│ │ ├── huffman # Huffman
97│ │ ├── request # Request type
98│ │ └── response # Response type
99│ └── tests # Tests of ylong_http
100│
101└── ylong_http_client
102 ├── examples # Examples of ylong_http_client
103 ├── src # Source code of ylong_http_client
104 │ ├── async_impl # Asynchronous client implementation
105 │ │ ├── conn # Asynchronous connection layer
106 │ │ ├── downloader # Asynchronous downloader layer
107 │ │ ├── ssl_stream # Asynchronous TLS layer
108 │ │ └── uploader # Asynchronous uploader layer
109 │ ├── sync_impl # Synchronous client implementation
110 │ │ └── conn # Synchronous connection layer
111 │ └── util # Components of ylong_http_client
112 │ ├── c_openssl # OpenSSL adapter
113 │ │ ├── ffi # OpenSSL ffi adapter
114 │ │ └── ssl # OpenSSL ssl adapter
115 │ └── config # Configures
116 │ └── tls # TLS Configures
117 │ └── alpn # ALPN Configures
118 └── tests # Tests of ylong_http_client
119```
