Cookies

HTML & web

Read and write cookie jars, and encode Set-Cookie header values.

Request cookies come from Server.cookies req. Session helpers in [Auth.Session] usually own the jar for login flows; use this module when you read a custom cookie in a `database module` or build a `Set-Cookie` yourself.

-- read in a database helper:
case Cookies.get cookies "u" Uuid.fromBase64 of
    Just userId ->
        Ok userId

    Nothing ->
        Err "not signed in"

-- write a response header:
Server.header "set-cookie"
    (Cookies.encode "u" secret Cookies.defaults)

defaults is HttpOnly, Path=/, SameSite=Lax, no Max-Age, not Secure (fine for local HTTP). Behind HTTPS use secureDefaults or { defaults | secure = True } so browsers only send the cookie on TLS. Use encodeClear to expire a cookie. See examples/03_todo_app (Users.selm) for session cookies as security tokens.

Types

Cookies

type Cookies = Cookies

A cookie jar attached to a request (or built in tests with empty / put).

Examples

empty

Attrs

type alias Attrs =
{ httpOnly : Bool
, secure : Bool
, path : String
, sameSite : String
, maxAge : Maybe Int
}

Attributes for a Set-Cookie header.

Examples

defaults

Values

empty

empty : Cookies

An empty cookie jar (handy in tests).

Examples

empty

put

put : Cookies -> String -> String -> Cookies

Set a cookie value in the jar.

Examples

put empty "u" "secret"

get

get : Cookies -> String -> (String -> Maybe a) -> Maybe a

Read a cookie and decode its value. Returns Nothing when the name is missing or the decoder fails.

Examples

get cookies "u" Just

defaults

defaults : Attrs

Default attrs: HttpOnly, Path=/, SameSite=Lax, no Max-Age, not Secure.

Examples

defaults

secureDefaults

secureDefaults : Attrs

Like defaults with secure = True for HTTPS deployments.

Examples

Auth.Session.withAttrs Cookies.secureDefaults session

encode

encode : String -> String -> Attrs -> String

Encode a Set-Cookie header value (name=value plus attrs). Pair with Server.header "set-cookie".

Examples

encode "u" secret defaults

encodeClear

encodeClear : String -> Attrs -> String

Encode a clearing Set-Cookie value (Max-Age=0).

Examples

encodeClear "u" defaults