feat: include README.md inside mod doc

This commit is contained in:
somehowchris 2022-07-28 18:19:52 +02:00 committed by Felipe Noronha
parent 102d50a024
commit e73a76600c

View File

@ -1,113 +1,5 @@
//!
//! A simple reverse proxy, to be used with [Hyper].
//!
//! The implementation ensures that [Hop-by-hop headers] are stripped correctly in both directions,
//! and adds the client's IP address to a comma-space-separated list of forwarding addresses in the
//! `X-Forwarded-For` header.
//!
//! The implementation is based on Go's [`httputil.ReverseProxy`].
//!
//! [Hyper]: http://hyper.rs/
//! [Hop-by-hop headers]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html
//! [`httputil.ReverseProxy`]: https://golang.org/pkg/net/http/httputil/#ReverseProxy
//!
//! # Example
//!
//! Add these dependencies to your `Cargo.toml` file.
//!
//! ```toml
//! [dependencies]
//! hyper-reverse-proxy = "0.5"
//! hyper = { version = "0.14", features = ["full"] }
//! tokio = { version = "1", features = ["full"] }
//! ```
//!
//! To enable support for connecting to downstream HTTPS servers, enable the `https` feature:
//!
//! ```toml
//! hyper-reverse-proxy = { version = "0.4", features = ["https"] }
//! ```
//!
//! The following example will set up a reverse proxy listening on `127.0.0.1:13900`,
//! and will proxy these calls:
//!
//! * `"/target/first"` will be proxied to `http://127.0.0.1:13901`
//!
//! * `"/target/second"` will be proxied to `http://127.0.0.1:13902`
//!
//! * All other URLs will be handled by `debug_request` function, that will display request information.
//!
//! ```rust,no_run
//! use hyper::server::conn::AddrStream;
//! use hyper::service::{make_service_fn, service_fn};
//! use hyper::{Body, Request, Response, Server, StatusCode};
//! use hyper_reverse_proxy::ReverseProxy;
//! use hyper_trust_dns::{RustlsHttpsConnector, TrustDnsResolver};
//! use std::net::IpAddr;
//! use std::{convert::Infallible, net::SocketAddr};
//!
//! lazy_static::lazy_static! {
//! static ref PROXY_CLIENT: ReverseProxy<RustlsHttpsConnector> = {
//! ReverseProxy::new(
//! hyper::Client::builder().build::<_, hyper::Body>(TrustDnsResolver::default().into_rustls_webpki_https_connector()),
//! )
//! };
//! }
//!
//! fn debug_request(req: &Request<Body>) -> Result<Response<Body>, Infallible> {
//! let body_str = format!("{:?}", req);
//! Ok(Response::new(Body::from(body_str)))
//! }
//!
//! async fn handle(client_ip: IpAddr, req: Request<Body>) -> Result<Response<Body>, Infallible> {
//! if req.uri().path().starts_with("/target/first") {
//! match PROXY_CLIENT.call(client_ip, "http://127.0.0.1:13901", req)
//! .await
//! {
//! Ok(response) => {
//! Ok(response)
//! },
//! Err(_error) => {
//! Ok(Response::builder()
//! .status(StatusCode::INTERNAL_SERVER_ERROR)
//! .body(Body::empty())
//! .unwrap())},
//! }
//! } else if req.uri().path().starts_with("/target/second") {
//! match PROXY_CLIENT.call(client_ip, "http://127.0.0.1:13902", req)
//! .await
//! {
//! Ok(response) => Ok(response),
//! Err(_error) => Ok(Response::builder()
//! .status(StatusCode::INTERNAL_SERVER_ERROR)
//! .body(Body::empty())
//! .unwrap()),
//! }
//! } else {
//! debug_request(&req)
//! }
//! }
//!
//! #[tokio::main]
//! async fn main() {
//! let bind_addr = "127.0.0.1:8000";
//! let addr: SocketAddr = bind_addr.parse().expect("Could not parse ip:port.");
//!
//! let make_svc = make_service_fn(|conn: &AddrStream| {
//! let remote_addr = conn.remote_addr().ip();
//! async move { Ok::<_, Infallible>(service_fn(move |req| handle(remote_addr, req))) }
//! });
//!
//! let server = Server::bind(&addr).serve(make_svc);
//!
//! println!("Running server on {:?}", addr);
//!
//! if let Err(e) = server.await {
//! eprintln!("server error: {}", e);
//! }
//! }
//!
//! ```
#![doc = include_str!("../README.md")]
#[macro_use]
extern crate tracing;