pingora-error

Active contributors: yuchen, ewang

Purpose

The shared error type used across the Pingora workspace. One Error type, one Result alias. Includes a categorization (ErrorType), a source attribution (ErrorSource: Internal, Upstream, Downstream), an optional context string, and a retry flag.

Directory layout

pingora-error/src/
├── lib.rs              Error, ErrorType, ErrorSource, Result, OrErr
└── immut_str.rs        ImmutStr — interned static-or-owned string

Key abstractions

Type	File	What it is
Error	pingora-error/src/lib.rs	The error type. Boxed via BError = Box<Error>
Result<T>	pingora-error/src/lib.rs	core::result::Result<T, BError>
ErrorType	pingora-error/src/lib.rs	Wide enum: ConnectError, BindError, ReadError, WriteError, InvalidHTTPHeader, Custom(&'static str), etc.
ErrorSource	pingora-error/src/lib.rs	Internal, Upstream, Downstream, Unset
OrErr	pingora-error/src/lib.rs	Extension trait on Result<T, E> for tagging
ImmutStr	pingora-error/src/immut_str.rs	Cow<'static, str> lookalike used in ErrorType::Custom

How it works

The pattern across the codebase:

use pingora_error::{Error, ErrorType, OrErr, Result};

fn do_thing() -> Result<()> {
    something().or_err(InternalError, "context")?;
    Ok(())
}

fn fallible() -> Result<()> {
    if bad { return Error::e_explain(InvalidHTTPHeader, "header"); }
    Ok(())
}

Error carries:

• etype: ErrorType
• esource: ErrorSource — set on creation, used by the proxy to decide retry semantics
• retry: RetryType — whether the request can be retried on a different upstream
• cause: Option<Box<dyn Error + Send + Sync>>
• context: Option<ImmutStr>

The as_str methods return static strings for known ErrorTypes and ErrorSources — used heavily by Sentry integration and metrics labels (changed in 0.7.0 to ensure &'static str).

Integration points

• Imported by every other crate. Even pingora-error itself has no dependencies on other workspace crates.
• The proxy consults ErrorSource and RetryType to decide whether to retry an upstream peer or fail the request.

Entry points for modification

• New ErrorType variant → add it to the enum in lib.rs, update as_str, decide retry semantics.
• New ErrorSource → unlikely; the existing enum covers everything the proxy classifies on.

Key source files

File	Purpose
pingora-error/src/lib.rs	Error, ErrorType, ErrorSource, Result, OrErr
pingora-error/src/immut_str.rs	ImmutStr