Crate biscotti

Source
Expand description

A crate to handle HTTP cookies in a Rust server.

§Overview

You can use biscotti to handle cookies in your server.

It has support for:

In particular:

  • It can handle multiple request cookies with the same name
  • It lets you add multiple cookies with the same name but different paths or domains
  • Cookies are percent-encoded/decoded by default (but you can opt out)
  • It has built-in support for rotating signing/encryption keys over time

§Non-goals

biscotti is not designed to handle cookies on the client side. It doesn’t provide any logic to parse the Set-Cookie headers returned in a server response.

§Quickstart

§Incoming cookies

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);

§Outgoing cookies

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(),
]));

§Credits

biscotti is heavily inspired by the cookie crate [Copyright (c) 2017 Sergio Benitez, Copyright (c) 2014 Alex Crichton]. biscotti started as a cookie fork and it includes non-negligible portions of its code.

Re-exports§

pub use jiff as time;

Modules§

config
Configuration for a Processor.
errors
Errors that can occur when using biscotti.
request
Low-level types related to RequestCookies.
response
Low-level types related to ResponseCookies.

Structs§

Key
A cryptographic master key to sign or encrypt cookies.
Processor
Transforms cookies before they are sent to the client, or after they have been parsed from an incoming request.
ProcessorConfig
Config specifies how the server should handle incoming and outgoing cookies with respect to security and encoding.
RemovalCookie
A ResponseCookie that, when sent to the client, removes a cookie with the same ResponseCookieId from the client’s machine, if it exists.
RequestCookie
A cookie set by a client in an HTTP request using the Cookie header.
RequestCookies
A collection of RequestCookies attached to an HTTP request using the Cookie header.
ResponseCookie
A cookie set by a server in an HTTP response using the Set-Cookie header.
ResponseCookieId
A unique identifier for a ResponseCookie.
ResponseCookies
A collection of ResponseCookies to be attached to an HTTP response using the Set-Cookie header.

Enums§

Expiration
A cookie’s expiration: either a date-time or session.
SameSite
The SameSite cookie attribute.