Cookie

Read, set, and clear cookies in HTTP requests and responses.

type Insecure

A cookie without the Secure attribute, as returned by create. Use withSecure to produce a Cookie Secure a.
type Secure

A cookie with the Secure attribute, produced by withSecure. This state allows withSameSiteNone to be used.
create :
{ name : String
, encoder : Encoder a
, decoder : Value a
}
-> Cookie Insecure a

Create a cookie with a name and the functions used to encode and decode its values.

visitCookie : Cookie.Cookie Cookie.Insecure Int
visitCookie =
    Cookie.create
        { name = "visits"
        , encoder = Cookie.Encode.int
        , decoder = Cookie.Decode.int
        }

New cookies use Path=/, have no Domain attribute (host-only), and have no Max-Age (a browser-session cookie). Secure, HttpOnly, and SameSite are also absent. Use the configuration functions to set those attributes.

If a semicolon is in the given name String, it's removed along with all text after it.

Configuring cookies

Configuration functions return an updated cookie. Use a pipeline to combine them, then keep the resulting cookie in your application settings.

withSecure and withHttpOnly enable attributes that cannot be turned off. The other functions replace their respective settings when called again.

type SameSite
= Strict
| Lax

A SameSite policy for withSameSite.

Use withSameSiteNone for SameSite=None; it requires Cookie Secure a.
withSecure : Cookie Insecure a -> Cookie Secure a

Turn on the Secure attribute, asking the browser to send this cookie only over HTTPS.

visitCookie |> Cookie.withSecure
-- Cookie.Cookie Cookie.Secure Int

This changes a Cookie Insecure a into a Cookie Secure a. Once a cookie is marked as secure, it cannot be marked as insecure again.
withHttpOnly : Cookie security a -> Cookie security a

Turn on HttpOnly, preventing browser JavaScript from reading the cookie through document.cookie. The browser can still include it in HTTP requests.

hostSession |> Cookie.withHttpOnly

This attribute is absent by default and cannot be turned off once enabled.
withSameSite : SameSite -> Cookie security a -> Cookie security a

Set the SameSite policy to Strict or Lax, replacing any previous policy.

visitCookie 
    |> Cookie.withSameSite Cookie.Lax

New cookies have no explicit SameSite policy. Use withSameSiteNone to set None.
withSameSiteNone : Cookie Secure a -> Cookie Secure a

Set SameSite=None, allowing the cookie in cross-site requests subject to the browser's other cookie policies.

visitCookie
    |> Cookie.withSecure
    |> Cookie.withSameSiteNone

This function accepts only a Cookie Secure a, so SameSite=None cannot be combined with an insecure cookie. It replaces any previous SameSite policy.
withPath : String -> Cookie security a -> Cookie security a

Set the path the browser uses to decide which requests receive the cookie. The default is /.

visitCookie |> Cookie.withPath "/account"

If a semicolon is in the given String, it's removed along with all text after it.
withDomain : String -> Cookie security a -> Cookie security a

Set a Domain attribute. Without this attribute, the cookie is host-only.

visitCookie |> Cookie.withDomain ".Example.COM"
-- Uses Domain=.Example.COM

If a semicolon is in the given String, it's removed along with all text after it.
withMaxAge : Int -> Cookie security a -> Cookie security a

Set the cookie's lifetime in whole seconds, replacing any previous Max-Age.

visitCookie |> Cookie.withMaxAge 3600

New cookies have no Max-Age and last for the browser session. Any negative values passed to this function are clamped to 0. If given a Max-Age of 0, the browser expires the cookie immediately. Alternatively, you can use clear to empty the cookie value in the browser.

Reading cookies

fromRequest : Cookie security a -> Request -> Result Error a

Read a cookie from a request using the name and decoder in its definition.

Accepts an HttpServer.Request from the gren-lang/node package.

Cookie.fromRequest visitCookie request
-- Result Cookie.Decode.Error Int

Missing or duplicate cookies, invalid percent-encoding, and rejected values return an Error. The value is percent-decoded once before the configured decoder runs.

Setting and clearing cookies

set : Cookie security a -> a -> Response -> Response

Encode a value and append a Set-Cookie field to the response.

Accepts and returns an HttpServer.Response.Response from the gren-lang/node package.

response
    |> Cookie.set visitCookie 42

This function percent-encodes the encoded value so it's safe to transport.
clear : Cookie security a -> Response -> Response

Clear a cookie by appending an empty value with Max-Age=0 to the response.

response
    |> Cookie.clear visitCookie

This just sets the Max-Age=0 for the cookie to send to the browser. This will clear the cookie immediately.

String values

toString : Cookie security a -> a -> String

Transform a Cookie into a String. This can be sent with a Set-Cookie header to the browser. For an easier way to do this, just use the set function.

Cookie.toString visitCookie 42
-- "visits=42; Path=/"
clearString : Cookie security a -> String

Produce the Set-Cookie header string for clearing a cookie.

Transform a Cookie into a String. This can be sent with a Set-Cookie header to the browser. For an easier way to do this, just use the clear function.

Cookie.clearString visitCookie
-- "visits=; Path=/; Max-Age=0"