Struct axum_extra::extract::cookie::PrivateCookieJar

source ·

pub struct PrivateCookieJar<K = Key> { /* private fields */ }

Available on crate features cookie-private and cookie only.

Expand description

Extractor that grabs private cookies from the request and manages the jar.

All cookies will be private and encrypted with a Key. This makes it suitable for storing private data.

Note that methods like PrivateCookieJar::add, PrivateCookieJar::remove, etc updates the PrivateCookieJar and returns it. This value must be returned from the handler as part of the response for the changes to be propagated.

§Example

use axum::{
    Router,
    routing::{post, get},
    extract::FromRef,
    response::{IntoResponse, Redirect},
    http::StatusCode,
};
use axum_extra::{
    TypedHeader,
    headers::authorization::{Authorization, Bearer},
    extract::cookie::{PrivateCookieJar, Cookie, Key},
};

async fn set_secret(
    jar: PrivateCookieJar,
) -> (PrivateCookieJar, Redirect) {
    let updated_jar = jar.add(Cookie::new("secret", "secret-data"));
    (updated_jar, Redirect::to("/get"))
}

async fn get_secret(jar: PrivateCookieJar) {
    if let Some(data) = jar.get("secret") {
        // ...
    }
}

// our application state
#[derive(Clone)]
struct AppState {
    // that holds the key used to sign cookies
    key: Key,
}

// this impl tells `SignedCookieJar` how to access the key from our state
impl FromRef<AppState> for Key {
    fn from_ref(state: &AppState) -> Self {
        state.key.clone()
    }
}

let state = AppState {
    // Generate a secure key
    //
    // You probably don't wanna generate a new one each time the app starts though
    key: Key::generate(),
};

let app = Router::new()
    .route("/set", post(set_secret))
    .route("/get", get(get_secret))
    .with_state(state);

If you have been using Arc<AppState> you cannot implement FromRef<Arc<AppState>> for Key. You can use a new type instead:

use std::sync::Arc;
use std::ops::Deref;

#[derive(Clone)]
struct AppState(Arc<InnerState>);

// deref so you can still access the inner fields easily
impl Deref for AppState {
    type Target = InnerState;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

struct InnerState {
    key: Key
}

impl FromRef<AppState> for Key {
    fn from_ref(state: &AppState) -> Self {
        state.0.key.clone()
    }
}

Implementations§

source §

impl PrivateCookieJar

source

pub fn from_headers(headers: &HeaderMap, key: Key) -> Self

Create a new PrivateCookieJar from a map of request headers.

The valid cookies in headers will be added to the jar.

This is intended to be used in middleware and other where places it might be difficult to run extractors. Normally you should create PrivateCookieJars through FromRequestParts.

source

pub fn new(key: Key) -> Self

Create a new empty PrivateCookieJarIter.

This is intended to be used in middleware and other places where it might be difficult to run extractors. Normally you should create PrivateCookieJars through FromRequestParts.

source §

impl<K> PrivateCookieJar<K>

source

pub fn get(&self, name: &str) -> Option<Cookie<'static>>

Get a cookie from the jar.

If the cookie exists and can be decrypted then it is returned in plaintext.

§Example

use axum_extra::extract::cookie::PrivateCookieJar;
use axum::response::IntoResponse;

async fn handle(jar: PrivateCookieJar) {
    let value: Option<String> = jar
        .get("foo")
        .map(|cookie| cookie.value().to_owned());
}

source

pub fn remove<C: Into<Cookie<'static>>>(self, cookie: C) -> Self

Remove a cookie from the jar.

§Example

use axum_extra::extract::cookie::{PrivateCookieJar, Cookie};
use axum::response::IntoResponse;

async fn handle(jar: PrivateCookieJar) -> PrivateCookieJar {
    jar.remove(Cookie::from("foo"))
}

source

pub fn add<C: Into<Cookie<'static>>>(self, cookie: C) -> Self

Add a cookie to the jar.

The value will automatically be percent-encoded.

§Example

use axum_extra::extract::cookie::{PrivateCookieJar, Cookie};
use axum::response::IntoResponse;

async fn handle(jar: PrivateCookieJar) -> PrivateCookieJar {
    jar.add(Cookie::new("foo", "bar"))
}

source