Cookies

Волга обеспечивает полную поддержку cookie посредством интеграции с библиотекой cookie. В этом руководстве объясняется, как включить и использовать функциональность cookie в вашем приложении, включая базовое использование, настройку и безопасные (подписанные и закрытые) файлы cookie.

Чтобы использовать cookie в вашем приложении, вам необходимо включить соответствующие флаги функций в вашем Cargo.toml. Если вы не используете full набор функций, добавьте флаг cookie вручную:

[dependencies]
volga = { version = "0.5.8", features = ["cookie"] }

# Необязательно: явно добавить библиотеку cookie
cookie = "0.18.1"

Информацию о подписанных или закрытых cookie см. в разделе Signed & Private Cookies.

Пример использования

use volga::{
    App, HttpResult,
    http::Cookies,
    headers::{Header, Authorization},
    error::Error,
    status, ok, see_other
};

async fn login(cookies: Cookies, auth: Header<Authorization>) -> Result<(HttpResult, Cookies), Error> {
    let session_id = authorize(auth)?;
    Ok((see_other!("/me"), cookies.add(("session-id", session_id))))
}

async fn me(cookies: Cookies) -> HttpResult {
    if cookies.get("session-id").is_some() {
        ok!("Success")
    } else {
        status!(401, "Unauthorized")
    }
}

fn authorize(auth: Header<Authorization>) -> Result<String, Error> {
    // Фиктивная реализация. Замените своей логикой.
    Ok("generated-session-id".to_string())
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut app = App::new();

    app.map_post("/login", login);
    app.map_get("/me", me);

    app.run().await
}

Примечания:

Экстрактор Cookies обрабатывает чтение из заголовков Cookie и автоматически устанавливает заголовки Set-Cookie для ответов.
Вы можете связать несколько добавлений cookie с помощью метода .add(...).

Создание защищенных Cookies

Для защищенных или настраиваемых cookie (например, HttpOnly, Secure, кастомный домен/путь) используйте CookieBuilder:

use cookie::{Cookie, time::Duration};

let cookie = Cookie::build(("session-id", session_id))
    .domain("www.example.org")
    .path("/")
    .secure(true)
    .http_only(true)
    .max_age(Duration::days(1))
    .build();

cookies.add(cookie);

Совет

Cookie::build(...) принимает либо кортеж имя/значение, либо просто имя, в зависимости от ваших потребностей.

Чтение Cookies

Вот как можно получить cookie по имени:

if let Some(cookie) = cookies.get("session-id") {
    println!("Session ID: {}", cookie.value());
}

Signed & Private Cookies

Для защиты целостности или конфиденциальности cookie Волга поддерживает два безопасных режима:

Type	Use Case	Crate Feature	API
Signed	Обнаружение несанкционированного доступа (читаемо)	`signed-cookie`	`SignedCookies`
Private	Защищен от несанкционированного доступа и зашифрован (скрыт)	`private-cookie`	`PrivateCookies`

Обновите Cargo.toml, подключив желаемый флаг, а так же Внедрение зависимостей (di):

# Для signed cookies
volga = { version = "0.5.8", features = ["signed-cookie", "di"] }

# Для private cookies
volga = { version = "0.5.8", features = ["private-cookie", "di"] }

# Для всех cookies
volga = { version = "0.5.8", features = ["cookie-full", "di"] }

Регистрация секретных ключей

Подписанные и закрыте файлы cookie требуют секретных ключей, предоставляемых через DI:

use volga::http::SignedKey;

app.add_singleton(SignedKey::generate());

Alternatively, for private cookies:

use volga::http::PrivateKey;

app.add_singleton(PrivateKey::generate());

После регистрации вы можете извлечь SignedCookies или PrivateCookies точно так же, как Cookies.

Best Practices

Используйте флаги HttpOnly и Secure для сессионных или аутентификационных cookie, чтобы предотвратить XSS и перехват.
Установите политику SameSite (через cookie::CookieBuilder) для межсайтовой защиты.
Периодически меняйте ключи подписи/шифрования, если используете SignedCookies или PrivateCookies.
Избегайте хранения конфиденциальных данных непосредственно в cookie, если они не зашифрованы с помощью закрытых cookie.