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```