Crate cookiebox

A type safe cookie management crate for the Actix Web framework.

Cookiebox provides a type safe and flexible approach to managing cookies in Actix web based applications. It allows you to define, configure, and manage cookies with minimal boilerplate.

Features

• This crate uses biscotti under the hood, which inherit most of it’s features.
• Offers the ability to configure settings on a per cookie basis.
• Enforces type definitions for deserializing cookie values upon retrieval.
• Allows customization of both the data type and data serialization.
• Provides a straightforward and type safe interface for managing cookies.

Usage

To start using the cookiebox in your web application, you must register CookieMiddleware in your App.

use actix_web::{web, App, HttpServer, HttpResponse, Error};
use cookiebox::{Processor, ProcessorConfig, CookieMiddleware};

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    // Start by creating a `Processor` from the `ProcessorConfig`
    // This decides which cookie needs to decrypted or verified.
    let processor: Processor = ProcessorConfig::default().into();
   
    HttpServer::new(move ||
            App::new()
            // Add cookie middleware
            .wrap(CookieMiddleware::new(processor.clone()))
            .default_service(web::to(|| HttpResponse::Ok())))
        .bind(("127.0.0.1", 8080))?
        .run()
        .await
}

Define your desired cookie types with customizable configurations.

use actix_web::HttpMessage;
use cookiebox::cookiebox_macros::{cookie, FromRequest};
use cookiebox::cookies::{Cookie, CookieName, IncomingConfig, OutgoingConfig};
use cookiebox::{Attributes, SameSite};
use serde_json::json;

// Define a cookie type
#[cookie(name = "__my-cookie")]
pub struct MyCookie;

// IncomingConfig gives the cookie type get and get_all cookies with similar name
// You may opt out if don't want read cookie data
impl IncomingConfig for MyCookie {
    // Configure the get return to any custom type
    type Get = String;
}
// OutgoingConfig gives the cookie type insert and remove cookies
// You may opt out if don't want insert or remove a cookie
impl OutgoingConfig for MyCookie {
    // Configure the insert to any custom type
    type Insert = (String, i32);
    
    // In most cases, the default serialization should be sufficient. However, if needed,
    // you can customize the way the cookie value is serialized by implementing this method.
    fn serialize(values: Self::Insert) -> serde_json::Value {
        json!(
             format!("String: {} - i32: {}", values.0, values.1)
        )
    }
    
    // Set the appropriate attribute for the cookie, check `Attributes` for more details
    fn attributes<'c>() -> Attributes<'c> {
        Attributes::new().same_site(SameSite::Lax).http_only(false)
    }
}
// Once defined, you need to add these cookies in a collection struct and use derive macro to implement FromRequest
// Note: The macro only allows struct with either a single unnamed field or multiple named fields
#[derive(FromRequest)]
pub struct CookieCollection<'c>(Cookie<'c, MyCookie>);

Now, your cookies can be accessed in request handlers by using CookieCollection as a parameter.

If you would like to see an example, click here.

Re-exports

pub use biscotti::time;

pub use cookiebox_macros;

Modules

config

Configuration for a Processor.

cookies

cookiebox’s core functionality

Structs

Attributes

Simple builder for cookie attributes

CookieMiddleware

cookiebox’s cookie middleware

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.

Storage

Holds a collection of both request and response cookies

Enums

Expiration

A cookie’s expiration: either a date-time or session.

SameSite

The SameSite cookie attribute.