Struct RequestContext 

pub struct RequestContext<'a> {
    pub method: &'a str,
    pub uri: &'a str,
    pub body: Option<&'a [u8]>,
    pub headers: &'a [(&'a str, &'a str)],
    pub peer_addr: Option<SocketAddr>,
}

The request fields the Digest response hash covers (RFC 7616 §3.4.1 / RFC 2326 §14): the method, the request URI, and — for qop=auth-int — the body. Also carries the request’s headers and transport peer address, so a server-side crate::Verifier scheme can see beyond the Authorization header — e.g. a reverse-proxy forwarded-auth scheme reading X-Forwarded-User/X-Forwarded-For (issue #663 extensibility wave part 1). Client-side use (crate::respond/crate::Authenticator) needs neither field; Self::new defaults both to empty/None.

The uri is scheme-specific: an HTTP absolute/relative URL for HTTP clients, or the RTSP request URI (e.g. rtsp://host/stream) for RTSP — never translate one into the other (RFC 2326 §14).

Fields

method: &'a str

The request method ("GET", "DESCRIBE", …).

uri: &'a str

The request URI, in the caller’s protocol’s own form.

body: Option<&'a [u8]>

The request body, needed only for Digest qop=auth-int. Some(&[]) for a bodyless request still lets auth-int be computed.

headers: &'a [(&'a str, &'a str)]

Every request header, as (name, value) pairs — Self::header looks one up case-insensitively (header names are case-insensitive, RFC 7230 §3.2). Empty for client-side use (Self::new’s default): a client answering a challenge computes Authorization from method/uri/body alone. Server-side (crate::Verifier::verify) this is how every scheme — including a future one — reads whatever header it needs, not just Authorization.

peer_addr: Option<SocketAddr>

The transport-layer peer address (e.g. the accepted TCP connection’s remote address), if the caller has one to attach. This is the actual connection peer — which, behind a reverse proxy, is the proxy itself, not the original client (see X-Forwarded-For in Self::headers for that). None for client-side use and whenever the caller has no transport peer to attach.

Implementations

impl<'a> RequestContext<'a>

pub fn new(method: &'a str, uri: &'a str) -> Self

Builds a context for a bodyless request with no headers/peer attached (the common client-side case) — use Self::with_headers/ Self::with_peer_addr to attach either.

Examples found in repository

examples/server_verify.rs (line 41)

fn digest() {
    let verifier = Verifier::new(
        Credentials::Digest {
            username: "admin".into(),
            password: "hunter2".into(),
        },
        REALM,
    );
    let challenge = verifier.challenge();
    println!("[digest] challenge: {challenge}");

    let ctx = RequestContext::new("DESCRIBE", "rtsp://cam/live");

    // Correct credential: respond() answers the challenge, verify() accepts.
    let correct = respond(&challenge, &ctx, Credentials::new("admin", "hunter2"))
        .expect("respond computes an Authorization value");
    let outcome = verify(&verifier, &correct, &ctx);
    println!("[digest] correct password  -> {outcome:?}");
    assert_eq!(outcome, AuthResult::Ok);

    // Wrong credential: same challenge, wrong password -> rejected.
    let wrong = respond(&challenge, &ctx, Credentials::new("admin", "WRONG"))
        .expect("respond computes an Authorization value even for a wrong password");
    let outcome = verify(&verifier, &wrong, &ctx);
    println!("[digest] wrong password    -> {outcome:?}");
    assert_eq!(outcome, AuthResult::Unauthorized);
}

/// Basic (RFC 7617): same accept/reject shape, briefly.
fn basic() {
    let verifier = Verifier::new(
        Credentials::Basic {
            username: "admin".into(),
            password: "hunter2".into(),
        },
        REALM,
    );
    let challenge = verifier.challenge();
    println!("[basic] challenge: {challenge}");

    let ctx = RequestContext::new("GET", "/stream/media.m3u8");
    let correct =
        respond(&challenge, &ctx, Credentials::new("admin", "hunter2")).expect("responds");
    assert_eq!(verify(&verifier, &correct, &ctx), AuthResult::Ok);
    println!("[basic] correct password   -> Ok");

    let wrong = respond(&challenge, &ctx, Credentials::new("admin", "WRONG")).expect("responds");
    assert_eq!(verify(&verifier, &wrong, &ctx), AuthResult::Unauthorized);
    println!("[basic] wrong password     -> Unauthorized");
}

/// Bearer (RFC 6750): no challenge round-trip needed, but still an
/// accept/reject pair — a wrong token must not verify.
fn bearer() {
    let verifier = Verifier::new(Credentials::bearer("right-token"), REALM);
    let challenge = verifier.challenge();
    println!("[bearer] challenge: {challenge}");

    let ctx = RequestContext::new("GET", "/stream/media.m3u8");
    let correct = respond(&challenge, &ctx, Credentials::bearer("right-token")).expect("responds");
    assert_eq!(verify(&verifier, &correct, &ctx), AuthResult::Ok);
    println!("[bearer] correct token     -> Ok");

    let wrong = respond(&challenge, &ctx, Credentials::bearer("wrong-token")).expect("responds");
    assert_eq!(verify(&verifier, &wrong, &ctx), AuthResult::Unauthorized);
    println!("[bearer] wrong token       -> Unauthorized");
}

/// Reverse-proxy forwarded-auth (`Verifier::forwarded`): no credential at
/// all — authenticated iff the proxy-set user header is present and
/// non-empty. See `Verifier::forwarded`'s doc for the trust assumption this
/// scheme relies on (only safe behind a proxy that strips client-supplied
/// copies of the header).
fn forwarded() {
    let verifier = Verifier::forwarded("X-Forwarded-User", Some("X-Forwarded-For".to_string()));
    println!("[forwarded] challenge: {}", verifier.challenge());

    let headers: &[(&str, &str)] = &[("X-Forwarded-User", "alice")];
    let ctx = RequestContext::new("GET", "/stream/media.m3u8").with_headers(headers);
    assert_eq!(verifier.verify(&ctx), AuthResult::Ok);
    println!("[forwarded] header present -> Ok");

    let ctx_no_header = RequestContext::new("GET", "/stream/media.m3u8");
    assert_eq!(verifier.verify(&ctx_no_header), AuthResult::Unauthorized);
    println!("[forwarded] header absent  -> Unauthorized");
}

/// Builds a request context carrying `authorization` as the `Authorization`
/// header, then verifies it against `verifier`.
fn verify(verifier: &Verifier, authorization: &str, ctx: &RequestContext<'_>) -> AuthResult {
    let headers: &[(&str, &str)] = &[("authorization", authorization)];
    let ctx_with_auth = RequestContext::new(ctx.method, ctx.uri).with_headers(headers);
    verifier.verify(&ctx_with_auth)
}

examples/client_respond.rs (line 22)

fn main() {
    // --- Basic (RFC 7617): a one-shot respond(), no session state needed.
    let value = respond(
        "Basic realm=\"cameras\"",
        &RequestContext::new("GET", "/stream/media.m3u8"),
        Credentials::new("admin", "hunter2"),
    )
    .expect("Basic responds to any challenge shape");
    println!("[basic]  Authorization: {value}");
    assert!(value.starts_with("Basic "));

    // --- Digest (RFC 7616): parses the server's nonce/realm/qop out of the
    // challenge, then computes HA1/HA2/response. Demonstrated with an
    // Authenticator (not the one-shot respond()) since a real session reuses
    // it across requests so the nonce count (`nc`) advances correctly.
    let digest_challenge = "Digest realm=\"cameras\", \
        nonce=\"dcd98b7102dd2f0e8b11d0f600bfb0c093\", qop=\"auth\", algorithm=MD5";
    let mut auth =
        Authenticator::from_challenge(digest_challenge, Credentials::new("admin", "hunter2"))
            .expect("challenge parses");
    let value = auth
        .authorization(&RequestContext::new(
            "DESCRIBE",
            "rtsp://camera.example.com/live",
        ))
        .expect("computes a Digest Authorization value");
    println!("[digest] Authorization: {value}");
    assert!(value.starts_with("Digest "));

    // A second request on the same Authenticator advances `nc` — the
    // computed value differs even though nothing else about the request
    // changed (RFC 7616 §3.3 requires a fresh `nc` per request).
    let second = auth
        .authorization(&RequestContext::new(
            "DESCRIBE",
            "rtsp://camera.example.com/live",
        ))
        .expect("computes a second Digest Authorization value");
    assert_ne!(value, second, "nc must advance across requests");
    println!("[digest] Authorization (2nd request, nc advanced): {second}");

    // --- Bearer (RFC 6750): no challenge round-trip needed at all — the
    // challenge value is ignored, the token is sent verbatim.
    let value = respond(
        "ignored — Bearer needs no challenge round-trip",
        &RequestContext::new("GET", "/stream/media.m3u8"),
        Credentials::bearer("mytoken123"),
    )
    .expect("Bearer always responds");
    println!("[bearer] Authorization: {value}");
    assert_eq!(value, "Bearer mytoken123");
}

pub fn with_body(self, body: &'a [u8]) -> Self

Attaches a request body (for qop=auth-int).

pub fn with_headers(self, headers: &'a [(&'a str, &'a str)]) -> Self

Attaches the request’s headers (server-side use — see Self::headers).

Examples found in repository

examples/server_verify.rs (line 108)

fn forwarded() {
    let verifier = Verifier::forwarded("X-Forwarded-User", Some("X-Forwarded-For".to_string()));
    println!("[forwarded] challenge: {}", verifier.challenge());

    let headers: &[(&str, &str)] = &[("X-Forwarded-User", "alice")];
    let ctx = RequestContext::new("GET", "/stream/media.m3u8").with_headers(headers);
    assert_eq!(verifier.verify(&ctx), AuthResult::Ok);
    println!("[forwarded] header present -> Ok");

    let ctx_no_header = RequestContext::new("GET", "/stream/media.m3u8");
    assert_eq!(verifier.verify(&ctx_no_header), AuthResult::Unauthorized);
    println!("[forwarded] header absent  -> Unauthorized");
}

/// Builds a request context carrying `authorization` as the `Authorization`
/// header, then verifies it against `verifier`.
fn verify(verifier: &Verifier, authorization: &str, ctx: &RequestContext<'_>) -> AuthResult {
    let headers: &[(&str, &str)] = &[("authorization", authorization)];
    let ctx_with_auth = RequestContext::new(ctx.method, ctx.uri).with_headers(headers);
    verifier.verify(&ctx_with_auth)
}

pub fn with_peer_addr(self, peer_addr: SocketAddr) -> Self

Attaches the transport peer address (server-side use — see Self::peer_addr).

pub fn header(&self, name: &str) -> Option<&'a str>

Looks up a header by name, case-insensitively (RFC 7230 §3.2). Returns the first match if Self::headers carries more than one with the same name.

Trait Implementations

impl<'a> Clone for RequestContext<'a>

fn clone(&self) -> RequestContext<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for RequestContext<'a>

impl Debug for RequestContext<'_>

Manual Debug (rather than #[derive(Debug)]): Self::headers carries whatever the caller attached, which — server-side — includes the real Authorization/Proxy-Authorization header the request was authenticated with. Basic’s value is a reversible base64 user:pass (RFC 7617 §2); a bare tracing::debug!(?ctx, ...) call must not dump it to logs. Every other header (name and value) is rendered normally — only the value of an auth header is redacted, and only that header’s name is enough to tell which one.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.