Installation

The machinery required to manipulate cookies is not included by default in the project scaffolded by pavex new. You need to go through a few steps to set it up.

CookieKit

CookieKit bundles together all the components you need to manipulate cookies. Register it with your Blueprint to get started:

src/blueprint.rs

use pavex::blueprint::Blueprint;
use pavex::cookie::CookieKit;

pub fn blueprint() -> Blueprint {
    let mut bp = Blueprint::new();
    CookieKit::new().register(&mut bp);
    // [...]
}

You can customize each component inside CookieKit to suit your needs. Check out the "Kits" section for reference examples.

ProcessorConfig

ProcessorConfig determines how cookies (both incoming and outgoing) are processed by your application. Do they need to be percent-encoded? Should they be signed or encrypted? Using what key?

Once you register CookieKit against your Blueprint, you'll get an error:

ERROR: 
  × I can't find a constructor for `biscotti::ProcessorConfig`.
  │ I need an instance of `biscotti::ProcessorConfig` to
  │ invoke your constructor, `<pavex::cookie::Processor as
  │ std::convert::From::<pavex::cookie::ProcessorConfig>>::from`.
  │
  │     ╭─[../../../../../libs/pavex/src/cookie/kit.rs:80:1]
  │  80 │                     .error_handler(f!(super::errors::InjectResponseCookiesError::into_response));
  │  81 │ ╭─▶         let processor = Constructor::singleton(f!(<super::Processor as std::convert::From<
  │  82 │ │               super::ProcessorConfig,
  │  83 │ ├─▶         >>::from))
  │     · ╰──── The constructor was registered here
  │  84 │             .ignore(Lint::Unused);
  │     ╰────
  │   help: Register a constructor for `biscotti::ProcessorConfig`.
  │   help: Alternatively, use `Blueprint::prebuilt` to add a new input
  │         parameter of type `biscotti::ProcessorConfig` to the (generated)
  │         `build_application_state`.

Error: NonZeroExitCode(NonZeroExitCode { code: 1, command: "pavex [...] generate [...]" })
error: Failed to run `cookie_installation`, the code generator for package `cookie_installation_server_sdk`

To fix it, you need to give Pavex a way to work with a ProcessorConfig instance. You have two options:

1. Add ProcessorConfig as a field on your application's AppConfig struct, usually located in app/src/configuration.rs. Check out the "Realworld" example as a reference (1).

   1. If you annotate the field with #[serde(default)], it'll fall back on the default settings unless you override them in your configuration files or with environment variables.

2. Use ProcessorConfig::default as its constructor if you're happy with the default settings.

   src/blueprint.rs

   use pavex::blueprint::Blueprint;
   use pavex::cookie::CookieKit;
   
   pub fn blueprint() -> Blueprint {
       let mut bp = Blueprint::new();
       CookieKit::new()
           .with_default_processor_config()
           .register(&mut bp);
           // [...]
   }
   

The second option is the quickest way to get started.
You'll have to switch to the first approach if you need to customize ProcessorConfig. That'll be necessary, for example, if you rely on cookies for sensitive information, such as session tokens. You'll have to configure ProcessorConfig::crypto_rules to ensure those cookies are encrypted or signed.