roadrunner_cookie (roadrunner v0.11.1)

View Source

HTTP cookie codec (RFC 6265).

Provides parse/1 for the request-side Cookie header and serialize/3 for the response-side Set-Cookie header.

Summary

Types

serialize_opts()

Optional attributes for the Set-Cookie header per RFC 6265 §4.1.

Functions

parse/1

Parse a Cookie header value into a list of {Name, Value} pairs in the order they appear on the wire.

serialize(Name, Value, Opts)

Build a Set-Cookie header value as iodata.

Types

serialize_opts()

-type serialize_opts() ::
          #{domain => binary(),
            path => binary(),
            max_age => non_neg_integer(),
            expires => binary(),
            secure => boolean(),
            http_only => boolean(),
            same_site => strict | lax | none}.

Optional attributes for the Set-Cookie header per RFC 6265 §4.1.

  • domain — explicit Domain attribute. Default is the response host (no Domain attribute emitted), which limits the cookie to that exact host.
  • path — explicit Path attribute. Default is no Path attribute, so the browser scopes the cookie to the request path's directory (RFC 6265 §5.1.4). Set path => ~"/" for a site-wide cookie.
  • max_age — seconds until the cookie expires. 0 deletes the cookie. Browsers prefer Max-Age over Expires when both are present (RFC 6265 §5.3 step 3).
  • expires — IMF-fixdate string for clients that ignore Max-Age (use roadrunner_http:format_http_date/1).
  • secure — restrict transmission to HTTPS.
  • http_only — hide from JavaScript (document.cookie).
  • same_site — cross-site request policy: strict, lax, or none. none requires secure => true.

Functions

parse/1

-spec parse(binary()) -> [{binary(), binary()}].

Parse a Cookie header value into a list of {Name, Value} pairs in the order they appear on the wire.

OWS (SP and HTAB) around each pair is trimmed. Pairs missing = or with an empty name are silently skipped (cowboy parity); empty values are accepted. Only the first = in a pair separates name from value, so a cookie like sid=a=b=c parses as a single pair with value a=b=c.

serialize(Name, Value, Opts)

-spec serialize(Name :: binary(), Value :: binary(), serialize_opts()) -> iodata().

Build a Set-Cookie header value as iodata.

Attributes are appended in this fixed order: Domain, Path, Max-Age, Expires, Secure, HttpOnly, SameSite. Boolean flags (secure, http_only) appear only when set to true; setting them to false is equivalent to omitting them. same_site accepts strict, lax, or none.

Each user-supplied binary is validated against the RFC 6265 §4.1.1 grammar before any iodata is produced; on a violation the call crashes with one of:

  • {invalid_cookie_name, Bin} — Name is empty or has a byte outside RFC 7230 §3.2.6 token
  • {invalid_cookie_value, Bin} — Value has a byte outside cookie-octet (CTL, SP, DQUOTE, ,, ;, \\)
  • {invalid_cookie_attr, AttrName, Bin} — Domain, Path, or Expires contains a CTL or ; (the bytes that would let a malicious caller smuggle attributes or split the header line)

Crashing matches the discipline applied elsewhere in the framework: a programmer bug echoing user input into a cookie turns into a 500, not a wire-level vulnerability.