howdy - v1.0.0

howdy/cookie

Cookie extraction and response helpers.

Reading uses use, like howdy/query. Missing required cookies, duplicate names, and invalid value encoding return JSON 400 responses. Malformed cookie pairs are ignored by the HTTP parser. Values are percent-encoded when set and percent-decoded when read. These helpers do not sign cookies or validate sessions.

use theme <- cookie.string_or(ctx, "theme", default: "system")
controller.text(ctx, theme)
|> cookie.set("theme", theme, cookie.defaults())

Types

Options

opaque </>

Build with defaults and the option setters.

pub opaque type Options

SameSite

</> 
pub type SameSite {
  Lax
  Strict
  None
}

Constructors 

  • Lax
  • Strict
  • None

Values

defaults

</> 
pub fn defaults() -> Options

Secure, HttpOnly, SameSite=Lax, Path=/, with no Domain or Max-Age. Without Max-Age the cookie lasts for the browser session.

delete

</> 
pub fn delete(
  res: response.Response(body),
  name: String,
  options: Options,
) -> response.Response(body)

Expire a cookie using an empty value, Max-Age=0, and an expiry in the past. Use the same path and domain as when setting it. Other headers are preserved. Invalid names or incompatible options panic as configuration errors.

domain

</> 
pub fn domain(options: Options, value: String) -> Options

Set the domain. Omit this to keep the cookie limited to the current host. Accepts ASCII letters, digits, dots, and hyphens; invalid input panics.

http_only

</> 
pub fn http_only(options: Options, enabled: Bool) -> Options

Set HttpOnly. Disable only when browser JavaScript needs the value.

max_age

</> 
pub fn max_age(options: Options, seconds: Int) -> Options

Set the lifetime in seconds. Zero or negative values expire the cookie.

optional_string

</> 
pub fn optional_string(
  ctx: context.Context(guarded),
  name: String,
  next: fn(option.Option(String)) -> response.Response(
    content.Content,
  ),
) -> response.Response(content.Content)

Read an optional cookie. Empty values remain Some(“”). Duplicate names or invalid percent encoding return a JSON 400.

path

</> 
pub fn path(options: Options, value: String) -> Options

Set the cookie path. Must start with / and contain printable ASCII without semicolons. Invalid configuration panics.

same_site

</> 
pub fn same_site(options: Options, policy: SameSite) -> Options

Set SameSite. None requires Secure when setting or deleting a cookie.

secure

</> 
pub fn secure(options: Options, enabled: Bool) -> Options

Set Secure. Use secure(False) explicitly for local HTTP development.

set

</> 
pub fn set(
  res: response.Response(body),
  name: String,
  value: String,
  options: Options,
) -> response.Response(body)

Append a cookie as a separate Set-Cookie header, preserving the response. Values are percent-encoded, including literal percent signs. Invalid names or incompatible options panic as configuration errors.

string

</> 
pub fn string(
  ctx: context.Context(guarded),
  name: String,
  next: fn(String) -> response.Response(content.Content),
) -> response.Response(content.Content)

Read a required cookie, returning a JSON 400 when absent.

string_or

</> 
pub fn string_or(
  ctx: context.Context(guarded),
  name: String,
  default default: String,
  next next: fn(String) -> response.Response(content.Content),
) -> response.Response(content.Content)

Use the default only when the cookie is absent.

valid_name

</> 
pub fn valid_name(name: String) -> Bool

Whether name is a valid cookie name: one or more RFC 6265 token characters. set and delete treat an invalid name as a programming error and panic, like a malformed route pattern would, since names are normally literals; an app that builds a name from data should check it with this first.

✨ Search Document