Quickstart docs fix - pingora version number failing over v0.3

[will-x86]

Quickstart documentation uses v0.3, and suggests adding via:

async-trait="0.1"
pingora = { version = "0.3", features = [ "lb" ] }

If using any later version than v0.3 (i.e., v0.4...0.7) then the quick start example silently fails. ( as needs "openssl" feature)

Reproducing

use async_trait::async_trait;
use pingora::prelude::*;
use std::sync::Arc;

pub struct LB(Arc<LoadBalancer<RoundRobin>>);

#[async_trait]
impl ProxyHttp for LB {
    type CTX = ();
    fn new_ctx(&self) -> () {
        ()
    }
    async fn upstream_peer(&self, _session: &mut Session, _ctx: &mut ()) -> Result<Box<HttpPeer>> {
        let upstream = self
            .0
            .select(b"", 256) // hash doesn't matter for round robin
            .unwrap();

        println!("upstream peer is: {upstream:?}");

        // Set SNI to one.one.one.one
        let peer = Box::new(HttpPeer::new(upstream, true, "one.one.one.one".to_string()));
        Ok(peer)
    }
    async fn upstream_request_filter(
        &self,
        _session: &mut Session,
        upstream_request: &mut RequestHeader,
        _ctx: &mut Self::CTX,
    ) -> Result<()> {
        upstream_request
            .insert_header("Host", "one.one.one.one")
            .unwrap();
        Ok(())
    }
}
fn main() {
    let mut my_server = Server::new(None).unwrap();
    my_server.bootstrap();

    let upstreams = LoadBalancer::try_from_iter(["1.1.1.1:443", "1.0.0.1:443"]).unwrap();

    let mut lb = http_proxy_service(&my_server.configuration, LB(Arc::new(upstreams)));
    lb.add_tcp("0.0.0.0:6188");

    my_server.add_service(lb);

    my_server.run_forever();
}

Expected results

Expected curl output as such:

Observed results

Even running with RUST_LOG=TRACE no errors are logged.

More context

Upon using the quickstart docs, I saw that the latest release was 0.7.0 & decided to run:

cargo add pingora --features lb 
cargo add async-trait

which lead to:

# XXXXXXX
[dependencies]
async-trait = "0.1.89"
pingora = { version = "0.7.0", features = ["lb", "openssl"] }

My initial debugging lead me to #61 which assumes it's an intentional 502 as 127... ( a non-existent proxy) is used in the later example in quick start docs.

Solution

Change quickstart docs to have:

pingora = { version = "0.7.0", features = ["lb", "openssl"] }

or

pingora = { version = "0.3.0", features = ["lb", "openssl"] }

Admittedly this is a niche use-case, but seems like something that as realistically happened to others.

pingora = { version = "0.3.0", features = ["lb"] }  # works

pingora = { version = "0.4.0", features = ["lb"] }  # doesn't work 
pingora = { version = "0.4.0", features = ["lb", "openssl"] }  # works

pingora = { version = "0.7.0", features = ["lb"] }  # doesn't work
pingora = { version = "0.7.0", features = ["lb", "openssl"]}  # works

[will-x86]

As my commit introduced a version change ( v0.3 -> v0.7) I figured I'd take a look and see if that broke any other examples.

I tested: ( all on pingora v0.7)

• The code in pingora-proxy/examples
• Read through docs/user_guide
• The code in pingora-ketama/examples/health_aware_selector.rs
• pingora-core/examples/client_cert.rs

1

docs/user_guide/rate_limiter.md link
This has:

async-trait="0.1"
pingora = { version = "0.3", features = [ "lb" ] }
pingora-limits = "0.3.0"
once_cell = "1.19.0"

Which will lead to same failure if using version over 0.3.

Additionally the example code here leads to a compile-time error, though a minor error, the current docs still fail

More info

error[E0433]: failed to resolve: use of undeclared type `ResponseHeader`
  --> src/main.rs:99:30
   |
99 |             let mut header = ResponseHeader::build(429, None).unwrap();
   |                              ^^^^^^^^^^^^^^ use of undeclared type `ResponseHeader`
   |
help: consider importing this struct
   |
 1 + use pingora::http::ResponseHeader;
   |

For more information about this error, try `rustc --explain E0433`.
error: could not compile `bdns` (bin "bdns") due to 1 previous error

Cargo.toml:

[dependencies]
async-trait="0.1"
pingora = { version = "0.3", features = [ "lb" ] }
pingora-limits = "0.3.0"
once_cell = "1.19.0"

2

pingora-proxy/examples/connection_filter.rs link

This fails to compile under version 0.7, due to:

 cargo run                                                   
   Compiling bdns v0.1.0 (XXXX)
error[E0195]: lifetime parameters or bounds on method `should_accept` do not match the trait declaration
  --> src/main.rs:52:14
   |
52 |     async fn should_accept(&self, addr: &std::net::SocketAddr) -> bool {
   |              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ lifetimes do not match method in trait
   |
  ::: /home/will/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/pingora-core-0.7.0/src/listeners/mod.rs:60:5
   |
60 |     fn should_accept(&self, _addr: &std::net::SocketAddr) -> bool {
   |     ------------------------------------------------------------- lifetimes in impl do not match this method in trait

For more information about this error, try `rustc --explain E0195`.
error: could not compile `bdns` (bin "bdns") due to 1 previous error

Fixed via changing from

    async fn should_accept(&self, addr: &std::net::SocketAddr) -> bool {

to

    fn should_accept(&self, addr: &std::net::SocketAddr) -> bool {

Please let me know what's more preferred, I assume updating all the docs is the right way to go, I'll add a commit that fixes these issues if needed.

[drcaramelsyrup]

LGTM aside from the version update.

[will-x86]

Version is updated to 0.8.0