Pingora

https://docs.rs/pingora/0.8.0
Admin
Pingora is a framework to build fast, reliable, and programmable networked systems at Internet...
Tokens:348,887
Snippets:5,389
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### start

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/struct.LoadBalancer.html?search=std%3A%3Avec

Starts the LoadBalancer service.

```APIDOC
## fn start

### Description
This function is called when the pingora server tries to start all the services. The background service can return at anytime or wait for the `shutdown` signal.

### Parameters
- **shutdown** (Receiver<bool>) - Required - A channel receiver to listen for shutdown signals.
```

--------------------------------

### start

Source: https://docs.rs/pingora/0.8.0/pingora/lb/prelude/struct.LoadBalancer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts the LoadBalancer service without a ready notifier.

```APIDOC
## fn start

### Description
This function is called when the pingora server starts the service. It allows the service to run until it returns or receives a shutdown signal.

### Parameters
- **shutdown** (Receiver<bool>) - Channel to receive shutdown signals.

### Returns
- **Future<Output = ()>** - A pinned future that completes when the service finishes or receives a shutdown signal.
```

--------------------------------

### fn start

Source: https://docs.rs/pingora/0.8.0/pingora/lb/struct.LoadBalancer.html?search=u32+-%3E+bool

Starts the LoadBalancer service without a ready notifier.

```APIDOC
## fn start

### Description
This function is called when the Pingora server starts the service. The service can return at any time or wait for the shutdown signal.

### Parameters
- **shutdown** (Receiver<bool>) - Required - Channel to receive shutdown signals.
```

--------------------------------

### Server::bootstrap

Source: https://docs.rs/pingora/0.8.0/pingora/server/struct.Server.html?search=std%3A%3Avec

Prepares the server to start, including handling zero-downtime upgrades.

```APIDOC
## pub fn bootstrap(&mut self)

### Description
Prepares the server to start. If performing a zero-downtime upgrade, this function attempts to take over listening sockets from the previously running server process.
```

--------------------------------

### Server::run

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/struct.Server.html?search=u32+-%3E+bool

Starts the server and runs it until shutdown.

```APIDOC
## pub fn run(self, run_args: RunArgs)

### Description
Runs the server until it is instructed to shut down via a signal. It waits for all services to finish and runtimes to exit.

### Parameters
- **run_args** (RunArgs) - Required - Arguments defining the execution behavior of the server.
```

--------------------------------

### Create a new Tag

Source: https://docs.rs/pingora/0.8.0/pingora/cache/trace/struct.Tag.html?search=

Example showing how to instantiate a new Tag with a name and value.

```rust
use cf_rustracing::tag::{Tag, TagValue};

let tag = Tag::new("foo", "bar");
assert_eq!(tag.name(), "foo");
assert_eq!(tag.value(), &TagValue::from("bar"));
```

--------------------------------

### start_with_ready_notifier

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/struct.LoadBalancer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts the background service and signals readiness via a notifier once initialization is complete.

```APIDOC
## fn start_with_ready_notifier(&self, shutdown: Receiver<bool>, ready: ServiceReadyNotifier) -> Pin<Box<dyn Future<Output = ()> + Send>>

### Description
This function is called when the Pingora server starts the service. It allows the service to perform initialization and signal readiness using the provided notifier, while monitoring for a shutdown signal.

### Parameters
- **shutdown** (Receiver<bool>) - A channel receiver to listen for shutdown signals.
- **ready** (ServiceReadyNotifier) - A notifier used to signal that the service is ready to handle requests.
```

--------------------------------

### start_with_ready_notifier

Source: https://docs.rs/pingora/0.8.0/pingora/lb/prelude/struct.LoadBalancer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts the LoadBalancer service and notifies the system when initialization is complete using a ready notifier.

```APIDOC
## fn start_with_ready_notifier

### Description
This function is called when the pingora server starts the service. It requires a shutdown receiver and a ready notifier to signal when the service is fully initialized.

### Parameters
- **shutdown** (Receiver<bool>) - Channel to receive shutdown signals.
- **ready** (ServiceReadyNotifier) - Notifier to signal that the service is ready.

### Returns
- **Future<Output = ()>** - A pinned future that completes when the service finishes or receives a shutdown signal.
```

--------------------------------

### start

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/struct.LoadBalancer.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts the background service and waits for a shutdown signal.

```APIDOC
## fn start(&self, shutdown: Receiver<bool>) -> Pin<Box<dyn Future<Output = ()> + Send>>

### Description
This function is called when the Pingora server starts the service. The service runs until it completes its task or receives a shutdown signal.

### Parameters
- **shutdown** (Receiver<bool>) - A channel receiver to listen for shutdown signals.
```

--------------------------------

### Initialize Downstream Modules

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/trait.ProxyHttp.html

Provided method to configure HttpModules before the server starts.

```rust
fn init_downstream_modules(&self, modules: &mut HttpModules)
```

--------------------------------

### Create empty String

Source: https://docs.rs/pingora/0.8.0/pingora/cache/cache_control/type.DirectiveKey.html

Example of creating a new empty String.

```rust
let s = String::new();
```

--------------------------------

### Signaling Service Readiness

Source: https://docs.rs/pingora/0.8.0/pingora/services/struct.ServiceReadyNotifier.html?search=std%3A%3Avec

Example demonstrating how to use ServiceReadyNotifier to signal that a service has completed initialization.

```rust
use pingora_core::services::ServiceReadyNotifier;

async fn my_service(ready_notifier: ServiceReadyNotifier) {
    // Perform initialization...

    // Signal that the service is ready
    ready_notifier.notify_ready();

    // Continue with main service loop...
}
```

--------------------------------

### Managing Box::into_non_null memory

Source: https://docs.rs/pingora/0.8.0/pingora/cache/storage/type.HitHandler.html?search=std%3A%3Avec

Examples demonstrating how to handle memory after converting a Box to a NonNull pointer.

```rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
let x = unsafe { Box::from_non_null(non_null) };
```

```rust
#![feature(box_vec_non_null)]

use std::alloc::{dealloc, Layout};

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    non_null.drop_in_place();
    dealloc(non_null.as_ptr().cast::<u8>(), Layout::new::<String>());
}
```

```rust
#![feature(box_vec_non_null)]

let x = Box::new(String::from("Hello"));
let non_null = Box::into_non_null(x);
unsafe {
    drop(Box::from_non_null(non_null));
}
```

--------------------------------

### Box Initialization with Custom Allocator

Source: https://docs.rs/pingora/0.8.0/pingora/type.BError.html?search=u32+-%3E+bool

Examples of creating boxed values with uninitialized or zeroed memory using the System allocator.

```rust
let five = Box::try_new_in(5, System)?;
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::new_uninit_in(System);
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5)
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let mut five = Box::<u32, _>::try_new_uninit_in(System)?;
// Deferred initialization:
five.write(5);
let five = unsafe { five.assume_init() };

assert_eq!(*five, 5);
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)
```

```rust
#![feature(allocator_api)]

use std::alloc::System;

let zero = Box::<u32, _>::try_new_zeroed_in(System)?;
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0);
```

--------------------------------

### Server::new

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/struct.Server.html?search=u32+-%3E+bool

Creates a new Server instance using provided command line options.

```APIDOC
## pub fn new(opt: impl Into<Option<Opt>>) -> Result<Server, Box<Error>>

### Description
Creates a new `Server` instance. Only one `Server` should be created per process. It can hold multiple independent services.

### Parameters
- **opt** (impl Into<Option<Opt>>) - Required - Command line options, which can be parsed via `Opt::parse_args()` or generated manually.
```

--------------------------------

### Backend Creation Methods

Source: https://docs.rs/pingora/0.8.0/pingora/lb/struct.Backend.html

Methods to initialize a new Backend instance, either with default or custom weight.

```rust
pub fn new(addr: &str) -> Result<Backend, Box<Error>>
```

```rust
pub fn new_with_weight(addr: &str, weight: usize) -> Result<Backend, Box<Error>>
```

--------------------------------

### follower

Source: https://docs.rs/pingora/0.8.0/pingora/cache/trace/type.SpanHandle.html?search=std%3A%3Avec

Starts a follower span.

```APIDOC
## pub fn follower<N, F>(&self, operation_name: N, f: F) -> Span<T>

### Description
Starts a FollowsFrom span if this span is sampled.

### Parameters
- **operation_name** (N) - The name of the operation for the new span.
- **f** (F) - A closure to configure the span options.
```

--------------------------------

### child

Source: https://docs.rs/pingora/0.8.0/pingora/cache/trace/type.SpanHandle.html?search=std%3A%3Avec

Starts a child span.

```APIDOC
## pub fn child<N, F>(&self, operation_name: N, f: F) -> Span<T>

### Description
Starts a ChildOf span if this span is sampled.

### Parameters
- **operation_name** (N) - The name of the operation for the new span.
- **f** (F) - A closure to configure the span options.
```

--------------------------------

### BufRef::new

Source: https://docs.rs/pingora/0.8.0/pingora/utils/struct.BufRef.html?search=u32+-%3E+bool

Initializes a new BufRef instance that references a slice starting at a specific index with a given length.

```APIDOC
## pub fn new(start: usize, len: usize) -> BufRef

### Description
Creates a new BufRef pointing to a slice starting at `start` with length `len`.

### Parameters
- **start** (usize) - The starting index of the slice.
- **len** (usize) - The length of the slice.
```

--------------------------------

### fn init(&self) -> Box<dyn HttpModule + Sync + Send>

Source: https://docs.rs/pingora/0.8.0/pingora/modules/http/trait.HttpModuleBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes and returns the per-request module context.

```APIDOC
### Method
`init(&self) -> Box<dyn HttpModule + Sync + Send>`

### Description
Initializes and returns the per-request module context for the HTTP module.
```

--------------------------------

### get

Source: https://docs.rs/pingora/0.8.0/pingora/http/struct.HMap.html?search=

Returns a reference to the value associated with the key.

```APIDOC
## pub fn get<K>(&self, key: K) -> Option<&T>

### Description
Returns a reference to the value associated with the key. If multiple values exist, the first one is returned.

### Parameters
- **key** (K: AsHeaderName) - Required - The header key to look up.

### Returns
- **Option<&T>** - The value associated with the key, or None if not found.
```

--------------------------------

### Get Module Order

Source: https://docs.rs/pingora/0.8.0/pingora/modules/http/compression/struct.ResponseCompressionBuilder.html

Retrieves the execution order for the module.

```rust
fn order(&self) -> i16
```

--------------------------------

### Get length of extensions

Source: https://docs.rs/pingora/0.8.0/pingora/cache/meta/struct.Extensions.html

Returns the count of stored extensions.

```rust
let mut ext = Extensions::new();
assert_eq!(ext.len(), 0);
ext.insert(5i32);
assert_eq!(ext.len(), 1);
```

--------------------------------

### Static::new

Source: https://docs.rs/pingora/0.8.0/pingora/lb/discovery/struct.Static.html?search=std%3A%3Avec

Creates a new boxed Static service discovery instance initialized with a provided set of backends.

```APIDOC
## pub fn new(backends: BTreeSet<Backend>) -> Box<Static>

### Description
Creates a new boxed Static service discovery instance with the given backends.

### Parameters
- **backends** (BTreeSet<Backend>) - Required - The set of backends to be managed by this discovery instance.
```

--------------------------------

### Borrowing a Value

Source: https://docs.rs/pingora/0.8.0/pingora/server/type.ShutdownWatch.html

Example of retrieving the current value from the receiver.

```rust
use tokio::sync::watch;

let (_, rx) = watch::channel("hello");
assert_eq!(*rx.borrow(), "hello");
```

--------------------------------

### Concatenate Strings

Source: https://docs.rs/pingora/0.8.0/pingora/cache/cache_control/type.DirectiveKey.html

Examples of concatenating strings using the + operator.

```rust
let a = String::from("hello");
let b = String::from(" world");
let c = a + &b;
// `a` is moved and can no longer be used here.
```

```rust
let a = String::from("hello");
let b = String::from(" world");
let c = a.clone() + &b;
// `a` is still valid here.
```

```rust
let a = "hello";
let b = " world";
let c = a.to_string() + b;
```

--------------------------------

### Backend::new

Source: https://docs.rs/pingora/0.8.0/pingora/lb/struct.Backend.html?search=

Creates a new Backend instance with a default weight of 1.

```APIDOC
## pub fn new(addr: &str) -> Result<Backend, Box<Error>>

### Description
Creates a new Backend with a default weight of 1. The function attempts to parse the provided address string into a std::net::SocketAddr.

### Parameters
- **addr** (&str) - Required - The address string to be parsed into a SocketAddr.
```

--------------------------------

### follower

Source: https://docs.rs/pingora/0.8.0/pingora/cache/trace/type.SpanHandle.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a new follower span if the current span is sampled.

```APIDOC
## pub fn follower<N, F>(&self, operation_name: N, f: F) -> Span<T>

### Description
Starts a `FollowsFrom` span if this span is sampled.
```

--------------------------------

### Initialize HttpProxy

Source: https://docs.rs/pingora/0.8.0/pingora/proxy/struct.HttpProxy.html

Create a new HttpProxy instance and initialize its modules before use in a custom accept loop.

```rust
use pingora_proxy::HttpProxy;
use std::sync::Arc;

let mut proxy = HttpProxy::new(my_proxy_app, server_conf);
proxy.handle_init_modules();
let proxy = Arc::new(proxy);
// Use proxy.process_new_http() in your custom accept loop
```

--------------------------------

### BufRef Struct Definition

Source: https://docs.rs/pingora/0.8.0/pingora/utils/struct.BufRef.html?search=

The definition of the BufRef struct containing two usize fields for start index and length.

```rust
pub struct BufRef(pub usize, pub usize);
```

--------------------------------

### child

Source: https://docs.rs/pingora/0.8.0/pingora/cache/trace/type.SpanHandle.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a new child span if the current span is sampled.

```APIDOC
## pub fn child<N, F>(&self, operation_name: N, f: F) -> Span<T>

### Description
Starts a `ChildOf` span if this span is sampled.
```

--------------------------------

### pub async fn connect<P>

Source: https://docs.rs/pingora/0.8.0/pingora/protocols/raw_connect/fn.connect.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Establishes a CONNECT proxy via the given stream. It requires a stream, request headers, and a peer definition.

```APIDOC
## Function: connect

### Description
Try to establish a CONNECT proxy via the given `stream`. When successful, a `Stream` is returned representing the established CONNECT proxy connection.

### Signature
`pub async fn connect<P>(stream: Box<dyn IO>, request_header: &Parts, peer: &P) -> Result<(Box<dyn IO>, ProxyDigest), Box<Error>> where P: Peer`

### Parameters
- **stream** (Box<dyn IO>) - The underlying IO stream to use for the connection.
- **request_header** (&Parts) - The request headers required for the CONNECT protocol.
- **peer** (&P) - The peer configuration implementing the `Peer` trait.

### Returns
- **Result<(Box<dyn IO>, ProxyDigest), Box<Error>>** - Returns a tuple containing the established IO stream and a `ProxyDigest` on success, or a `Box<Error>` on failure.
```

--------------------------------

### CachePutCtx::cache_put

Source: https://docs.rs/pingora/0.8.0/pingora/cache/put/struct.CachePutCtx.html?search=

Starts the cache put logic for a given request.

```APIDOC
### async fn cache_put(&mut self, session: &mut Session) -> Result<Option<NoCacheReason>, Box<Error>>

Starts the cache put logic for the given request by reading the request body. Returns `Ok(None)` if the payload will be cached, or `Ok(Some(reason))` if the payload is not cacheable.
```

--------------------------------

### Backend::new

Source: https://docs.rs/pingora/0.8.0/pingora/lb/struct.Backend.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new Backend instance with a default weight of 1 by parsing the provided address string.

```APIDOC
## pub fn new(addr: &str) -> Result<Backend, Box<Error>>

### Description
Creates a new Backend with a default weight of 1. The function attempts to parse the provided address string into a std::net::SocketAddr.

### Parameters
- **addr** (&str) - Required - The address string to parse into a SocketAddr.
```

--------------------------------

### Get string capacity

Source: https://docs.rs/pingora/0.8.0/pingora/cache/cache_control/type.DirectiveKey.html

Returns the current capacity of the String in bytes.

```rust
let s = String::with_capacity(10);

assert!(s.capacity() >= 10);
```

--------------------------------

### Cloning Result Contents

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/type.Result.html

Examples of using .cloned() on Result references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Server::new

Source: https://docs.rs/pingora/0.8.0/pingora/server/struct.Server.html?search=u32+-%3E+bool

Creates a new Server instance. Only one Server should be created per process.

```APIDOC
## pub fn new(opt: impl Into<Option<Opt>>) -> Result<Server, Box<Error>>

### Description
Creates a new Server instance. Only one Server needs to be created for a process. A Server can hold multiple independent services.

### Parameters
- **opt** (impl Into<Option<Opt>>) - Required - Command line options, which can be parsed via Opt::parse_args() or generated manually.
```

--------------------------------

### Copying Result Contents

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/type.Result.html

Examples of using .copied() on Result references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Initialize MemCache

Source: https://docs.rs/pingora/0.8.0/pingora/cache/struct.MemCache.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Create a new instance of MemCache.

```rust
pub fn new() -> MemCache
```

--------------------------------

### Implement Provided Methods

Source: https://docs.rs/pingora/0.8.0/pingora/proxy/trait.ProxyHttp.html

Methods for configuring modules and handling request/response lifecycles.

```rust
fn init_downstream_modules(&self, modules: &mut HttpModules)
fn request_filter<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session: &'life1 mut Session, _ctx: &'life2 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<bool, Box<Error>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'life2, 'async_trait, 'life2: 'async_trait, Self::CTX: Send + Sync, Self: Sync + 'async_trait,
fn early_request_filter<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _session: &'life1 mut Session, _ctx: &'life2 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<(), Box<Error>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self::CTX: Send + Sync, Self: Sync + 'async_trait,
fn allow_spawning_subrequest( &self, _session: &Session, _ctx: &Self::CTX, ) -> bool
where Self::CTX: Send + Sync,
fn request_body_filter<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, _session: &'life1 mut Session, _body: &'life2 mut Option<Bytes>, _end_of_stream: bool, _ctx: &'life3 mut Self::CTX, ) -> Pin<Box<dyn Future<Output = Result<(), Box<Error>>> + Send + 'async_trait>>
where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, Self::CTX: Send + Sync, Self: Sync + 'async_trait,
```

--------------------------------

### Method Usage Examples

Source: https://docs.rs/pingora/0.8.0/pingora/http/struct.Method.html

Demonstrates basic usage of the Method struct, including parsing from bytes, checking idempotency, and converting to a string.

```rust
use http::Method;

assert_eq!(Method::GET, Method::from_bytes(b"GET").unwrap());
assert!(Method::GET.is_idempotent());
assert_eq!(Method::POST.as_str(), "POST");
```

--------------------------------

### Using http_proxy in a Custom Accept Loop

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/fn.http_proxy.html?search=

Demonstrates initializing an HttpProxy and using it within a custom accept loop to handle TLS termination.

```rust
use pingora_proxy::http_proxy;
use std::sync::Arc;

// Create the proxy
let proxy = Arc::new(http_proxy(&server_conf, my_proxy_app));

// In your custom accept loop:
loop {
    let (stream, addr) = listener.accept().await?;

    // Peek SNI, decide routing...
    if should_terminate_tls {
        let tls_stream = my_acceptor.accept(stream).await?;
        let session = HttpSession::new_http1(Box::new(tls_stream));
        proxy.process_new_http(session, &shutdown).await;
    }
}
```

--------------------------------

### Defining Service Dependencies

Source: https://docs.rs/pingora/0.8.0/pingora/services/struct.ServiceHandle.html?search=std%3A%3Avec

Demonstrates how to add services to a server and establish dependencies between them using ServiceHandle.

```rust
let db_handle = server.add_service(database_service);
let cache_handle = server.add_service(cache_service);

let api_handle = server.add_service(api_service);
api_handle.add_dependency(&db_handle);
api_handle.add_dependency(&cache_handle);
```

--------------------------------

### get<T>

Source: https://docs.rs/pingora/0.8.0/pingora/protocols/tls/struct.SslDigestExtension.html?search=std%3A%3Avec

Retrieves a reference to the user-defined TLS data if it matches the specified type.

```APIDOC
### pub fn get<T>(&self) -> Option<&T>

#### Description
Retrieves a reference to the user-defined TLS data if it matches the specified type. Returns `None` if no data has been set or if the data is not of type `T`.

#### Type Parameters
- **T** (Send + Sync + 'static) - The type of the data to retrieve.

#### Returns
- **Option<&T>** - A reference to the data if found, otherwise None.
```

--------------------------------

### BufRef::new

Source: https://docs.rs/pingora/0.8.0/pingora/utils/struct.BufRef.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Initializes a new BufRef instance.

```APIDOC
## pub fn new(start: usize, len: usize) -> BufRef

### Description
Creates a new BufRef that references a slice starting at the specified index with a given length.

### Parameters
- **start** (usize) - The starting index of the buffer slice.
- **len** (usize) - The length of the buffer slice.

### Returns
- **BufRef** - A new instance of BufRef.
```

--------------------------------

### Checking for Changes

Source: https://docs.rs/pingora/0.8.0/pingora/server/type.ShutdownWatch.html

Example demonstrating how to check if the channel has received a new message.

```rust
use tokio::sync::watch;

#[tokio::main]
async fn main() {
    let (tx, mut rx) = watch::channel("hello");

    tx.send("goodbye").unwrap();

    assert!(rx.has_changed().unwrap());
    assert_eq!(*rx.borrow_and_update(), "goodbye");

    // The value has been marked as seen
    assert!(!rx.has_changed().unwrap());

    drop(tx);
    // The `tx` handle has been dropped
    assert!(rx.has_changed().is_err());
}
```

--------------------------------

### pub async fn connect<P>

Source: https://docs.rs/pingora/0.8.0/pingora/protocols/raw_connect/fn.connect.html?search=

Establishes a CONNECT proxy connection via the given stream.

```APIDOC
## Function: connect

### Description
Try to establish a CONNECT proxy via the given `stream`. When successful, a `Stream` is returned representing the established CONNECT proxy connection.

### Signature
`pub async fn connect<P>(stream: Box<dyn IO>, request_header: &Parts, peer: &P) -> Result<(Box<dyn IO>, ProxyDigest), Box<Error>> where P: Peer`

### Parameters
- **stream** (Box<dyn IO>) - The IO stream to establish the connection over.
- **request_header** (&Parts) - The request headers required for the CONNECT protocol.
- **peer** (&P) - The peer information, must implement the `Peer` trait.

### Returns
- **Result<(Box<dyn IO>, ProxyDigest), Box<Error>>** - Returns a tuple containing the established IO stream and a `ProxyDigest` on success, or a `Box<Error>` on failure.
```

--------------------------------

### ServiceHandle::add_dependency

Source: https://docs.rs/pingora/0.8.0/pingora/services/struct.ServiceHandle.html?search=std%3A%3Avec

Declares a single dependency for the service, preventing it from starting until the dependency is ready.

```APIDOC
## pub fn add_dependency(&self, dependency: impl Borrow<ServiceHandle>)

### Description
Declares that this service depends on another service. This service will not start until the specified dependency has started and signaled readiness.

### Parameters
- **dependency** (impl Borrow<ServiceHandle>) - Required - The service handle that this service depends on.
```

--------------------------------

### Backends implementation methods

Source: https://docs.rs/pingora/0.8.0/pingora/lb/struct.Backends.html?search=std%3A%3Avec

Methods for initializing, configuring, and interacting with the Backends collection.

```rust
pub fn new(discovery: Box<dyn ServiceDiscovery + Sync + Send>) -> Backends
```

```rust
pub fn set_health_check(&mut self, hc: Box<dyn HealthCheck + Sync + Send>)
```

```rust
pub fn ready(&self, backend: &Backend) -> bool
```

```rust
pub fn set_enable(&self, backend: &Backend, enabled: bool)
```

```rust
pub fn get_backend(&self) -> Arc<BTreeSet<Backend>>
```

```rust
pub async fn update<F>(&self, callback: F) -> Result<(), Box<Error>>
where F: Fn(Arc<BTreeSet<Backend>>),
```

```rust
pub async fn run_health_check(&self, parallel: bool)
```

--------------------------------

### ServerConf Configuration Methods

Source: https://docs.rs/pingora/0.8.0/pingora/server/configuration/struct.ServerConf.html?search=std%3A%3Avec

Methods for initializing, loading, and manipulating ServerConf instances.

```APIDOC
## pub fn load_from_yaml<P>(path: P) -> Result<ServerConf, Box<Error>>
Loads a ServerConf instance from a YAML file path.

## pub fn load_yaml_with_opt_override(opt: &Opt) -> Result<ServerConf, Box<Error>>
Loads a ServerConf instance with optional command-line overrides.

## pub fn new() -> Option<ServerConf>
Creates a new default ServerConf instance.

## pub fn new_with_opt_override(opt: &Opt) -> Option<ServerConf>
Creates a new ServerConf instance with optional command-line overrides.

## pub fn from_yaml(conf_str: &str) -> Result<ServerConf, Box<Error>>
Parses a ServerConf instance from a YAML string.

## pub fn to_yaml(&self) -> String
Serializes the current ServerConf instance to a YAML string.

## pub fn validate(self) -> Result<ServerConf, Box<Error>>
Validates the current ServerConf configuration.

## pub fn merge_with_opt(&mut self, opt: &Opt)
Merges command-line options into the current ServerConf instance.
```

--------------------------------

### entry()

Source: https://docs.rs/pingora/0.8.0/pingora/http/struct.HMap.html?search=

Gets the given key’s corresponding entry in the map for in-place manipulation.

```APIDOC
## pub fn entry<K>(&mut self, key: K) -> Entry<'_, T>

### Description
Gets the given key’s corresponding entry in the map for in-place manipulation. Panics if capacity exceeds max HeaderMap capacity.
```

--------------------------------

### Checking Result Status

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/type.Result.html

Examples of using is_ok and is_err to check the variant of a Result.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_err(), false);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_err(), true);
```

--------------------------------

### ServerConf Configuration Methods

Source: https://docs.rs/pingora/0.8.0/pingora/server/configuration/struct.ServerConf.html?search=u32+-%3E+bool

Methods for initializing, loading, and managing server configuration objects.

```APIDOC
## pub fn load_from_yaml<P>(path: P) -> Result<ServerConf, Box<Error>>

### Description
Loads the server configuration from a YAML file located at the specified path.

## pub fn load_yaml_with_opt_override(opt: &Opt) -> Result<ServerConf, Box<Error>>

### Description
Loads the server configuration while applying overrides from the provided Opt structure.

## pub fn new() -> Option<ServerConf>

### Description
Creates a new default ServerConf instance.

## pub fn new_with_opt_override(opt: &Opt) -> Option<ServerConf>

### Description
Creates a new ServerConf instance initialized with the provided Opt overrides.

## pub fn from_yaml(conf_str: &str) -> Result<ServerConf, Box<Error>>

### Description
Parses a ServerConf object from a YAML-formatted string.

## pub fn to_yaml(&self) -> String

### Description
Serializes the current ServerConf instance into a YAML string.

## pub fn validate(self) -> Result<ServerConf, Box<Error>>

### Description
Validates the current configuration settings.

## pub fn merge_with_opt(&mut self, opt: &Opt)

### Description
Merges configuration settings from the provided Opt structure into the current instance.
```

--------------------------------

### Result Copied and Cloned

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/type.Result.html?search=

Examples of copying or cloning the contents of a Result containing a reference.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### Discouraged provide delegation

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/trait.ErrorTrait.html?search=std%3A%3Avec

Example of a discouraged pattern where provide is delegated to a source error.

```rust
struct MyError {
    source: Error,
}

impl std::error::Error for MyError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.source)
    }

    fn provide<'a>(&'a self, request: &mut Request<'a>) {
        self.source.provide(request) // <--- Discouraged
    }
}
```

--------------------------------

### Static Implementation Methods

Source: https://docs.rs/pingora/0.8.0/pingora/lb/discovery/struct.Static.html?search=std%3A%3Avec

Methods for creating and interacting with a Static service discovery instance.

```rust
pub fn new(backends: BTreeSet<Backend>) -> Box<Static>
```

```rust
pub fn try_from_iter<A, T>(iter: T) -> Result<Box<Static>, Error>
where T: IntoIterator<Item = A>, A: ToSocketAddrs,
```

```rust
pub fn get(&self) -> BTreeSet<Backend>
```

--------------------------------

### Error display example

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/trait.ErrorTrait.html?search=std%3A%3Avec

Demonstrates how error messages are represented using the Display trait.

```rust
let err = "NaN".parse::<u32>().unwrap_err();
assert_eq!(err.to_string(), "invalid digit found in string");
```

--------------------------------

### GenBackgroundService::new

Source: https://docs.rs/pingora/0.8.0/pingora/services/background/struct.GenBackgroundService.html?search=

Creates a new instance of a background service.

```APIDOC
## pub fn new(name: String, task: Arc<A>) -> GenBackgroundService<A>

### Description
Generates a background service that can run in the pingora runtime.

### Parameters
- **name** (String) - The name of the service.
- **task** (Arc<A>) - The task to be executed by the service.

### Returns
- **GenBackgroundService<A>** - A new instance of the background service.
```

--------------------------------

### StatusCode Usage Examples

Source: https://docs.rs/pingora/0.8.0/pingora/http/struct.StatusCode.html?search=

Basic operations for creating and validating HTTP status codes.

```rust
use http::StatusCode;

assert_eq!(StatusCode::from_u16(200).unwrap(), StatusCode::OK);
assert_eq!(StatusCode::NOT_FOUND.as_u16(), 404);
assert!(StatusCode::OK.is_success());
```

--------------------------------

### http_proxy_service<SV>(conf: &Arc<ServerConf>, inner: SV) -> Service<HttpProxy<SV>>

Source: https://docs.rs/pingora/0.8.0/pingora/prelude/fn.http_proxy_service.html

Creates a Service from the user implemented ProxyHttp. The returned Service can be hosted by a pingora_core::server::Server directly.

```APIDOC
## http_proxy_service

### Description
Creates a Service from the user implemented ProxyHttp. The returned Service can be hosted by a pingora_core::server::Server directly.

### Signature
`pub fn http_proxy_service<SV>(conf: &Arc<ServerConf>, inner: SV) -> Service<HttpProxy<SV>> where SV: ProxyHttp`

### Parameters
- **conf** (&Arc<ServerConf>) - Required - The server configuration.
- **inner** (SV) - Required - The user-implemented ProxyHttp service.

### Returns
- **Service<HttpProxy<SV>>** - A service instance that can be hosted by the server.
```

--------------------------------

### ServerConf Configuration Methods

Source: https://docs.rs/pingora/0.8.0/pingora/server/configuration/struct.ServerConf.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Methods for initializing and managing server configuration objects.

```APIDOC
## ServerConf Methods

### load_from_yaml<P>(path: P) -> Result<ServerConf, Box<Error>>
Loads a configuration from a YAML file path.

### load_yaml_with_opt_override(opt: &Opt) -> Result<ServerConf, Box<Error>>
Loads a configuration with overrides from command-line options.

### new() -> Option<ServerConf>
Creates a new default ServerConf instance.

### new_with_opt_override(opt: &Opt) -> Option<ServerConf>
Creates a new ServerConf instance with command-line option overrides.

### from_yaml(conf_str: &str) -> Result<ServerConf, Box<Error>>
Parses a configuration from a YAML string.

### to_yaml(&self) -> String
Serializes the current configuration to a YAML string.

### validate(self) -> Result<ServerConf, Box<Error>>
Validates the current configuration settings.

### merge_with_opt(&mut self, opt: &Opt)
Merges command-line options into the existing configuration.
```

--------------------------------

### Create String with capacity

Source: https://docs.rs/pingora/0.8.0/pingora/cache/cache_control/type.DirectiveKey.html

Example of creating a String with pre-allocated capacity to avoid reallocations.

```rust
let mut s = String::with_capacity(10);

// The String contains no chars, even though it has capacity for more
assert_eq!(s.len(), 0);

// These are all done without reallocating...
let cap = s.capacity();
for _ in 0..10 {
    s.push('a');
}

assert_eq!(s.capacity(), cap);

// ...but this may make the string reallocate
s.push('a');
```

--------------------------------

### ServerConf Configuration Methods

Source: https://docs.rs/pingora/0.8.0/pingora/server/configuration/struct.ServerConf.html

Methods for initializing, loading, and serializing server configuration objects.

```APIDOC
## ServerConf Methods

### load_from_yaml<P>(path: P) -> Result<ServerConf, Box<Error>>
Loads a ServerConf instance from a YAML file path.

### load_yaml_with_opt_override(opt: &Opt) -> Result<ServerConf, Box<Error>>
Loads a ServerConf instance with optional command-line overrides.

### new() -> Option<ServerConf>
Creates a new default ServerConf instance.

### new_with_opt_override(opt: &Opt) -> Option<ServerConf>
Creates a new ServerConf instance with optional command-line overrides.

### from_yaml(conf_str: &str) -> Result<ServerConf, Box<Error>>
Parses a ServerConf instance from a YAML string.

### to_yaml(&self) -> String
Serializes the current ServerConf instance to a YAML string.

### validate(self) -> Result<ServerConf, Box<Error>>
Validates the current ServerConf instance.

### merge_with_opt(&mut self, opt: &Opt)
Merges command-line options into the current ServerConf instance.
```

--------------------------------

### ServiceHandle::add_dependencies

Source: https://docs.rs/pingora/0.8.0/pingora/services/struct.ServiceHandle.html?search=std%3A%3Avec

Declares multiple dependencies for the service, preventing it from starting until all specified dependencies are ready.

```APIDOC
## pub fn add_dependencies<'a, D>(&self, dependencies: impl IntoIterator<Item = D>)

### Description
Declares that this service depends on the given other services. This service will not start until the specified dependencies have started and signaled readiness.

### Parameters
- **dependencies** (impl IntoIterator<Item = D>) - Required - An iterator of service handles that this service depends on.
```

--------------------------------

### Backend::new_with_weight

Source: https://docs.rs/pingora/0.8.0/pingora/lb/struct.Backend.html?search=

Creates a new Backend instance with a specified weight.

```APIDOC
## pub fn new_with_weight(addr: &str, weight: usize) -> Result<Backend, Box<Error>>

### Description
Creates a new Backend with the specified weight. The function attempts to parse the provided address string into a std::net::SocketAddr.

### Parameters
- **addr** (&str) - Required - The address string to be parsed into a SocketAddr.
- **weight** (usize) - Required - The relative weight for load balancing distribution.
```

--------------------------------

### pub async fn connect<T, P>

Source: https://docs.rs/pingora/0.8.0/pingora/protocols/tls/noop_tls/connectors/fn.connect.html?search=std%3A%3Avec

Establishes a connection using the noop_tls connector. This function is available only when the any_tls feature is not enabled.

```APIDOC
## Function: connect<T, P>

### Description
Establishes a connection using the noop_tls connector. This function is intended for use when TLS is not required or explicitly disabled via feature flags.

### Signature
```rust
pub async fn connect<T, P>(
    _: T,
    _: &P,
    _: Option<ALPN>,
    _: &TlsConnector,
) -> Result<SslStream<T>, Box<Error>>
where
    T: IO,
    P: Peer + Send + Sync,
```

### Constraints
- Available only when the `any_tls` crate feature is disabled.
```
Tokens:
Raw