This module provides a set of types and functions that allow you to manage cookies in your elm-express application. This includes setting, reading, and deleting cookies during requests. The module offers a range of options for working with cookies, such as setting the expiration date and domain for a cookie. By using the functions provided in this module, you can ensure that cookies are managed securely and efficiently within your application.
It aims to provide a straightforward way to work with cookies in Elm that is based on the Express API, while also including some slight adaptations when necessary. To a more comprehensive understanding it is recommended to read the Express documentation surrounding cookie setting.
The SameSite type describe the three possible values for the sameSite key in the cookie definition. To better
understand the effects of each value we recommend this article from the
OWASP website.
Creates a new Cookie. It tries to use the most sensible defaults optimized for security. That means that:
domain is defined using the request's URL hostpath is the root /httpOnly is Truesecure is defined according to the request's URL protocolsigned is True andsameSite is StrictAll of these parameters you can later change with functions from this module.
The maxAge needs to be informed in milliseconds. If omitted by passing in a Nothing value, the cookie will be set as
a session cookie.
cookie =
-- expires in 30 minutes
Express.Cookie.new "cookieName" "cookieValue" (Just 1800000)If you need to store more complex data, make sure to encode it to a string before creating the cookie itself.
Sets the domain property of the cookie. Defaults to the host of the request's URL.
newCookie =
Express.Cookie.domain "subdomain.example.com" oldCookieSets or unsets the maxAge property of the cookie. Passing a Nothing value will turn the cookie into a session
cookie.
newCookie =
Express.Cookie.maxAge (Just 3600000) oldCookieSets the httpOnly property of the cookie. If httpOnly is True the cookie is only accessible through the web
server, making it impossible to fetch the cookie via JavaScript in the client side. True is the default value when you
create a new Cookie.
newCookie =
-- The contents of this cookie will be accessible in client side JavaScript code
Express.Cookie.httpOnly False oldCookieSets the path property of the cookie. Defaults to the root /. Changing this value will make the cookie only
available in the specified path and its subdirectories.
newCookie =
Express.Cookie.path "/api" oldCookieSets the secure property of the cookie. If secure is True than the cookie will only be readable from secure
(https) connections. The default value depends on the protocol from the request's URL. If it is Https, than secure
will be True.
newCookie =
Express.Cookie.secure True oldCookieSets the signed property of the cookie. Signed cookies can only be read when the secrets match. You can set a
secret when creating an elmExpress application in the JavaScript land code. This prevents tampering of data, making
the cookie unavailable if it was not signed with the correct secret.
It is important to note that this does not encrypt the cookies value, as it will be exposed somehow. Defaults to True.
newCookie =
Express.Cookie.signed True oldCookieSets the sameSite property of the cookie. To better understand what each value means check
this reference from the OWASP website. Defaults to Strict.
newCookie =
Express.Cookie.sameSite Express.Cookie.Lax oldCookie
The
Cookietype is an opaque type that describes a cookie according with Express APIs. It contains all the required information on the Express documentation to define a cookie.One particular difference is that we don't use the
expireskey, only themaxAgekey. That means you can't specify a precise date and time in which the cookie will expire, only how long it will live from the current server time when the cookie is set.This difference exists to simplify the interface as dealing with dates would be more troublesome (while still completely possible).