Struct CookieTemplate 

pub struct CookieTemplate { /* private fields */ }

Builder for secure authentication cookies used by Gate.

Provides secure defaults that are automatically adjusted based on build configuration:

• Production builds: Secure=true, HttpOnly=true, SameSite=Strict, session cookie
• Debug builds: Secure=false (for localhost), SameSite=Lax, HttpOnly=true, session cookie

Security Best Practices

The recommended approach is to start with CookieTemplate::recommended() and customize only what you need:

use axum_gate::cookie_template::CookieTemplate;
use cookie::{time::Duration, SameSite};

// Secure defaults with custom name and expiration
let template = CookieTemplate::recommended()
    .name("auth-token")
    .persistent(Duration::hours(24));

// For OAuth/redirect flows that need cross-site navigation
let oauth_template = CookieTemplate::recommended()
    .name("oauth-state")
    .same_site(SameSite::Lax);  // Allow cross-site for redirects

Security Features

• HttpOnly: Prevents JavaScript access to auth cookies (XSS protection)
• Secure: HTTPS-only in production (MITM protection)
• SameSite=Strict: Prevents CSRF attacks in production
• Session cookies: No persistent storage by default (privacy)

Common Customizations

• name("my-auth-cookie") - Set custom cookie name
• persistent(Duration::hours(24)) - Make cookie persist across browser sessions
• same_site(SameSite::Lax) - Allow cross-site navigation (OAuth flows)
• domain(".example.com") - Share cookies across subdomains

Convert to cookie::Cookie via CookieTemplate::builder then .build(), or use CookieTemplate::validate_and_build.

Implementations

impl CookieTemplate

pub fn recommended() -> Self

Secure recommended defaults.

pub fn name(self, name: impl Into<Cow<'static, str>>) -> Self

Set / override the cookie name.

Keep names short and avoid sensitive info.

pub fn value(self, value: impl Into<Cow<'static, str>>) -> Self

Provide an initial value (normally left empty – the login code will insert the JWT).

pub fn path(self, path: impl Into<Cow<'static, str>>) -> Self

Set the cookie path (default /).

pub fn domain(self, domain: impl Into<Cow<'static, str>>) -> Self

Set the cookie domain. Avoid setting for single‑domain apps to retain host-only semantics (slightly tighter).

pub fn clear_domain(self) -> Self

Unset the previously configured domain (host-only cookie).

pub fn secure(self, flag: bool) -> Self

Explicitly mark the cookie as secure (HTTPS only).

pub fn insecure_dev_only(self) -> Self

Convenience: DISABLE secure flag for local dev ONLY.

In release builds this will panic to prevent accidental insecure deployment. You must call this intentionally; no environment detection is performed here.

pub fn http_only(self, flag: bool) -> Self

Set / unset HttpOnly flag.

pub fn same_site(self, same_site: SameSite) -> Self

Set the SameSite attribute (default Strict).

Consider Lax for some OAuth / cross-site redirect flows. Only use None when you understand the CSRF implications and the need for Secure.

pub fn max_age(self, max_age: Duration) -> Self

Make persistent with a specific Max-Age.

pub fn clear_max_age(self) -> Self

Remove persistence (session cookie again).

pub fn persistent(self, duration: Duration) -> Self

Convenience for setting a persistent cookie lifetime.

pub fn short_lived(self) -> Self

Use a short-lived cookie (e.g. 15 minutes) – explicit for readability.

pub fn validate(&self) -> Result<(), CookieTemplateBuilderError>

Validate the template configuration. Returns Ok(()) if fine.

pub fn builder(&self) -> CookieBuilder<'static>

Convert into the underlying cookie::CookieBuilder<'static>.

pub fn validate_and_build( &self, ) -> Result<Cookie<'static>, CookieTemplateBuilderError>

Validate then build. Returns an error if invalid.

pub fn build_with_name_value(&self, name: &str, value: &str) -> Cookie<'static>

Build a cookie preserving all template attributes, having the name and value.

pub fn build_with_value(&self, value: &str) -> Cookie<'static>

Build a cookie preserving attributes, overriding only the value.

pub fn build_with_name(&self, name: &str) -> Cookie<'static>

Build a cookie preserving attributes, overriding only the name.

pub fn build_removal(&self) -> Cookie<'static>

Build a removal cookie preserving attributes, overriding the name.

pub fn cookie_name_ref(&self) -> &str

Get a reference to the configured cookie name without allocating.

Prefer this on hot paths (e.g., header extraction).

Trait Implementations

impl Clone for CookieTemplate

fn clone(&self) -> CookieTemplate

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CookieTemplate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CookieTemplate

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for CookieTemplate

fn eq(&self, other: &CookieTemplate) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for CookieTemplate

impl StructuralPartialEq for CookieTemplate