Biscotti

用于在 Rust 服务器中处理 HTTP 饼干的 crate。

概述

您可以使用 biscotti 在您的服务器中处理饼干。

它支持

• 通过 RequestCookies 处理附加到传入请求的饼干
• 通过 ResponseCookies 构建传出响应的饼干
• 通过 Processor 加密、签名或编码饼干

特别是

• 它可以处理具有相同名称的多个请求饼干
• 它允许您添加具有相同名称但不同路径或域的多个饼干
• 默认情况下，饼干是百分编码/解码的（但您可以选择退出）
• 它具有内置的自动轮换签名/加密密钥的支持

非目标

biscotti 不设计用于在客户端处理饼干。
它不提供任何解析服务器响应中返回的 Set-Cookie 标头的逻辑。

快速入门

传入饼干

use biscotti::{Processor, ProcessorConfig, RequestCookies};

// Start by creating a `Processor` instance from a `Config`.
// It determines if (and which) cookies should be decrypted, verified or percent-decoded.
let processor: Processor = ProcessorConfig::default().into();
// You can then use `RequestCookies::parse_header` to parse the `Cookie` header
// you received from the client.
let cookies = RequestCookies::parse_header(
    "name=first%20value; name2=val; name=another%20value",
    &processor
).unwrap();

// You can now access the cookies!

// You can access the first cookie with a given name...
assert_eq!(cookies.get("name").unwrap().value(), "first value");
// ...or opt to retrieve all values associated with that cookie name.
assert_eq!(cookies.get_all("name").unwrap().len(), 2);

assert_eq!(cookies.get("name2").unwrap().value(), "val");
assert_eq!(cookies.get_all("name2").unwrap().len(), 1);

传出饼干

use std::collections::HashSet;
use biscotti::{Processor, ProcessorConfig, ResponseCookies, RemovalCookie, ResponseCookie};
use biscotti::SameSite;

// Start by creating a `ResponseCookies` instance to hold the cookies you want to send.
let mut cookies = ResponseCookies::new();

// You can add cookies to the `ResponseCookies` instance via the `insert` method.
cookies.insert(ResponseCookie::new("name", "a value"));
cookies.insert(ResponseCookie::new("name", "a value").set_path("/"));
// If you want to remove a cookie from the client's machine, you can use a `RemovalCookie`.
cookies.insert(RemovalCookie::new("another name"));

// You then convert obtain the respective `Set-Cookie` header values.
// A processor is required: it determines if (and which) cookies should be encrypted,
// signed or percent-encoded.
let processor: Processor = ProcessorConfig::default().into();
let header_values: HashSet<_> = cookies.header_values(&processor).collect();
assert_eq!(header_values, HashSet::from([
    "name=a%20value".to_string(),
    // Both `name` cookies are kept since they have different path attributes.
    "name=a%20value; Path=/".to_string(),
    // A removal cookie is a cookie with an empty value and an expiry in the past.
    "another%20name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT".to_string(),
]));

致谢

biscotti 严重受到 cookie crate [版权 (c) 2017 Sergio Benitez, 版权 (c) 2014 Alex Crichton] 的启发。
biscotti 从 cookie 分支开始，并包含其代码的非小部分。