elm-pages 3.0.0-beta.40 → 3.0.0-beta.42

package/src/Server/Session.elm

@@ -4,43 +4,48 @@ module Server.Session exposing
     , Session, empty, get, insert, remove, update, withFlash
     )
 
-{-| You can manage server state with HTTP cookies using this Server.Session API. Server-rendered pages define a `Server.Request.Parser`
-to choose which requests to respond to and how to extract structured data from the incoming request.
+{-| You can manage server state with HTTP cookies using this Server.Session API. Server-rendered routes have a `Server.Request.Request`
+argument that lets you inspect the incoming HTTP request, and return a response using the `Server.Response.Response` type.
 
+This API provides a higher-level abstraction for extracting data from the HTTP request, and setting data in the HTTP response.
+It manages the session through key-value data stored in cookies, and lets you [`insert`](#insert), [`update`](#update), and [`remove`](#remove)
+values from the Session. It also provides an abstraction for flash session values through [`withFlash`](#withFlash).
 
-## Using Sessions in a Request.Parser
+
+## Using Sessions
 
 Using these functions, you can store and read session data in cookies to maintain state between requests.
-For example, TODO:
-
-    action : RouteParams -> Request.Parser (BackendTask (Response ActionData ErrorPage))
-    action routeParams =
-        MySession.withSession
-            (Request.formDataWithServerValidation (form |> Form.initCombinedServer identity))
-            (\nameResultData session ->
-                nameResultData
-                    |> BackendTask.map
-                        (\nameResult ->
-                            case nameResult of
-                                Err errors ->
-                                    ( session
-                                        |> Result.withDefault Nothing
-                                        |> Maybe.withDefault Session.empty
-                                    , Response.render
-                                        { errors = errors
-                                        }
-                                    )
 
-                                Ok ( _, name ) ->
-                                    ( session
-                                        |> Result.withDefault Nothing
-                                        |> Maybe.withDefault Session.empty
-                                        |> Session.insert "name" name
-                                        |> Session.withFlash "message" ("Welcome " ++ name ++ "!")
-                                    , Route.redirectTo Route.Greet
-                                    )
-                        )
-            )
+    import Server.Session as Session
+
+    secrets : BackendTask FatalError (List String)
+    secrets =
+        Env.expect "SESSION_SECRET"
+            |> BackendTask.allowFatal
+            |> BackendTask.map List.singleton
+
+    type alias Data =
+        { darkMode : Bool }
+
+    data : RouteParams -> Request -> BackendTask (Response Data ErrorPage)
+    data routeParams request =
+        request
+            |> Session.withSession
+                { name = "mysession"
+                , secrets = secrets
+                , options = Nothing
+                }
+                (\session ->
+                    let
+                        darkMode : Bool
+                        darkMode =
+                            (session |> Session.get "mode" |> Maybe.withDefault "light")
+                                == "dark"
+                    in
+                    ( session
+                    , { darkMode = darkMode }
+                    )
+                )
 
 The elm-pages framework will manage signing these cookies using the `secrets : BackendTask (List String)` you pass in.
 That means that the values you set in your session will be directly visible to anyone who has access to the cookie
@@ -113,12 +118,17 @@ import BackendTask.Internal.Request
 import Dict exposing (Dict)
 import Json.Decode
 import Json.Encode
-import Server.Request
+import Server.Request exposing (Request)
 import Server.Response exposing (Response)
 import Server.SetCookie as SetCookie
 
 
-{-| -}
+{-| Represents a Session with key-value Strings.
+
+Use with `withSession` to read in the `Session`, and encode any changes you make to the `Session` back through cookie storage
+via the outgoing HTTP response.
+
+-}
 type Session
     = Session (Dict String Value)
 
@@ -130,7 +140,12 @@ type Value
     | NewFlash String
 
 
-{-| -}
+{-| Flash session values are values that are only available for the next request.
+
+    session
+        |> Session.withFlash "message" "Your payment was successful!"
+
+-}
 withFlash : String -> String -> Session -> Session
 withFlash key value (Session session) =
     session
@@ -138,7 +153,12 @@ withFlash key value (Session session) =
         |> Session
 
 
-{-| -}
+{-| Insert a value under the given key in the `Session`.
+
+    session
+        |> Session.insert "mode" "dark"
+
+-}
 insert : String -> String -> Session -> Session
 insert key value (Session session) =
     session
@@ -146,7 +166,15 @@ insert key value (Session session) =
         |> Session
 
 
-{-| -}
+{-| Retrieve a String value from the session for the given key (or `Nothing` if the key is not present).
+
+    (session
+        |> Session.get "mode"
+        |> Maybe.withDefault "light"
+    )
+        == "dark"
+
+-}
 get : String -> Session -> Maybe String
 get key (Session session) =
     session
@@ -168,7 +196,25 @@ unwrap value =
             string
 
 
-{-| -}
+{-| Update the `Session`, given a `Maybe String` of the current value for the given key, and returning a `Maybe String`.
+
+If you return `Nothing`, the key-value pair will be removed from the `Session` (or left out if it didn't exist in the first place).
+
+    session
+        |> Session.update "mode"
+            (\mode ->
+                case mode of
+                    Just "dark" ->
+                        Just "light"
+
+                    Just "light" ->
+                        Just "dark"
+
+                    Nothing ->
+                        Just "dark"
+            )
+
+-}
 update : String -> (Maybe String -> Maybe String) -> Session -> Session
 update key updateFn (Session session) =
     session
@@ -192,7 +238,8 @@ update key updateFn (Session session) =
         |> Session
 
 
-{-| -}
+{-| Remove a key from the `Session`.
+-}
 remove : String -> Session -> Session
 remove key (Session session) =
     session
@@ -200,13 +247,15 @@ remove key (Session session) =
         |> Session
 
 
-{-| -}
+{-| An empty `Session` with no key-value pairs.
+-}
 empty : Session
 empty =
     Session Dict.empty
 
 
-{-| -}
+{-| [`withSessionResult`](#withSessionResult) will return a `Result` with this type if it can't load a session.
+-}
 type NotLoadedReason
     = NoSessionCookie
     | InvalidSessionCookie
@@ -239,65 +288,67 @@ flashPrefix =
     "__flash__"
 
 
-{-| -}
+{-| The main function for using sessions. If you need more fine-grained control over cases where a session can't be loaded, see
+[`withSessionResult`](#withSessionResult).
+-}
 withSession :
     { name : String
     , secrets : BackendTask error (List String)
     , options : Maybe SetCookie.Options
     }
-    -> (request -> Session -> BackendTask error ( Session, Response data errorPage ))
-    -> Server.Request.Parser request
-    -> Server.Request.Parser (BackendTask error (Response data errorPage))
-withSession config toRequest userRequest =
-    withSessionResult config
-        (\request session ->
-            toRequest request
-                (session
+    -> (Session -> BackendTask error ( Session, Response data errorPage ))
+    -> Request
+    -> BackendTask error (Response data errorPage)
+withSession config toRequest request_ =
+    request_
+        |> withSessionResult config
+            (\session ->
+                session
                     |> Result.withDefault empty
-                )
-        )
-        userRequest
+                    |> toRequest
+            )
 
 
-{-| -}
+{-| Same as `withSession`, but gives you an `Err` with the reason why the Session couldn't be loaded instead of
+using `Session.empty` as a default in the cases where there is an error loading the session.
+
+A session won't load if there is no session, or if it cannot be unsigned with your secrets. This could be because the cookie was tampered with
+or otherwise corrupted, or because the cookie was signed with a secret that is no longer in the rotation.
+
+-}
 withSessionResult :
     { name : String
     , secrets : BackendTask error (List String)
     , options : Maybe SetCookie.Options
     }
-    -> (request -> Result NotLoadedReason Session -> BackendTask error ( Session, Response data errorPage ))
-    -> Server.Request.Parser request
-    -> Server.Request.Parser (BackendTask error (Response data errorPage))
-withSessionResult config toRequest userRequest =
-    Server.Request.map2
-        (\maybeSessionCookie userRequestData ->
-            let
-                unsigned : BackendTask error (Result NotLoadedReason Session)
-                unsigned =
-                    case maybeSessionCookie of
-                        Just sessionCookie ->
-                            sessionCookie
-                                |> unsignCookie config
-                                |> BackendTask.map
-                                    (\unsignResult ->
-                                        case unsignResult of
-                                            Ok decoded ->
-                                                Ok decoded
-
-                                            Err () ->
-                                                Err InvalidSessionCookie
-                                    )
+    -> (Result NotLoadedReason Session -> BackendTask error ( Session, Response data errorPage ))
+    -> Request
+    -> BackendTask error (Response data errorPage)
+withSessionResult config toTask request =
+    let
+        unsigned : BackendTask error (Result NotLoadedReason Session)
+        unsigned =
+            case Server.Request.cookie config.name request of
+                Just sessionCookie ->
+                    sessionCookie
+                        |> unsignCookie config
+                        |> BackendTask.map
+                            (\unsignResult ->
+                                case unsignResult of
+                                    Ok decoded ->
+                                        Ok decoded
+
+                                    Err () ->
+                                        Err InvalidSessionCookie
+                            )
 
-                        Nothing ->
-                            Err NoSessionCookie
-                                |> BackendTask.succeed
-            in
-            unsigned
-                |> BackendTask.andThen
-                    (encodeSessionUpdate config toRequest userRequestData)
-        )
-        (Server.Request.cookie config.name)
-        userRequest
+                Nothing ->
+                    Err NoSessionCookie
+                        |> BackendTask.succeed
+    in
+    unsigned
+        |> BackendTask.andThen
+            (encodeSessionUpdate config toTask)
 
 
 encodeSessionUpdate :
@@ -305,20 +356,19 @@ encodeSessionUpdate :
     , secrets : BackendTask error (List String)
     , options : Maybe SetCookie.Options
     }
-    -> (c -> d -> BackendTask error ( Session, Response data errorPage ))
-    -> c
+    -> (d -> BackendTask error ( Session, Response data errorPage ))
     -> d
     -> BackendTask error (Response data errorPage)
-encodeSessionUpdate config toRequest userRequestData sessionResult =
+encodeSessionUpdate config toRequest sessionResult =
     sessionResult
-        |> toRequest userRequestData
+        |> toRequest
         |> BackendTask.andThen
             (\( sessionUpdate, response ) ->
                 BackendTask.map
                     (\encoded ->
                         response
                             |> Server.Response.withSetCookieHeader
-                                (SetCookie.setCookie config.name encoded (config.options |> Maybe.withDefault SetCookie.initOptions))
+                                (SetCookie.setCookie config.name encoded (config.options |> Maybe.withDefault SetCookie.options))
                     )
                     (sign config.secrets
                         (encodeNonExpiringPairs sessionUpdate)

package/src/Server/SetCookie.elm

@@ -1,8 +1,8 @@
 module Server.SetCookie exposing
-    ( SetCookie
-    , SameSite(..)
-    , Options, initOptions
-    , withImmediateExpiration, makeVisibleToJavaScript, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withoutPath, withSameSite
+    ( SetCookie, setCookie
+    , Options, options
+    , SameSite(..), withSameSite
+    , withImmediateExpiration, makeVisibleToJavaScript, nonSecure, withDomain, withExpiration, withMaxAge, withPath, withoutPath
     , toString
     )
 
@@ -20,16 +20,29 @@ You can learn more about the basics of cookies in the Web Platform in these help
   - <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie>
   - <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies>
 
-@docs SetCookie
+@docs SetCookie, setCookie
 
-@docs SameSite
 
+## Building Options
 
-## Options
+Usually you'll want to start by creating default `Options` with `options` and then overriding defaults using the `with...` helpers.
 
-@docs Options, initOptions
+    import Server.SetCookie as SetCookie
 
-@docs withImmediateExpiration, makeVisibleToJavaScript, nonSecure, setCookie, withDomain, withExpiration, withMaxAge, withPath, withoutPath, withSameSite
+    options : SetCookie.Options
+    options =
+        SetCookie.options
+            |> SetCookie.nonSecure
+            |> SetCookie.withMaxAge 123
+            |> SetCookie.makeVisibleToJavaScript
+            |> SetCookie.withoutPath
+            |> SetCookie.setCookie "id" "a3fWa"
+
+@docs Options, options
+
+@docs SameSite, withSameSite
+
+@docs withImmediateExpiration, makeVisibleToJavaScript, nonSecure, withDomain, withExpiration, withMaxAge, withPath, withoutPath
 
 
 ## Internal
@@ -51,7 +64,8 @@ type alias SetCookie =
     }
 
 
-{-| -}
+{-| The set of possible configuration options. You can configure this record directly, or use the `with...` helpers.
+-}
 type alias Options =
     { expiration : Maybe Time.Posix
     , visibleToJavaScript : Bool
@@ -63,7 +77,15 @@ type alias Options =
     }
 
 
-{-| -}
+{-| Possible values for [the cookie's same-site value](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value).
+
+The default option is [`Lax`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#lax) (Lax does not send
+cookies in cross-origin requests so it is a good default for most cases, but [`Strict`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#strict)
+is even more restrictive).
+
+Override the default option using [`withSameSite`](#withSameSite).
+
+-}
 type SameSite
     = Strict
     | Lax
@@ -95,24 +117,24 @@ toString builder =
             else
                 ""
 
-        options : Options
-        options =
+        options_ : Options
+        options_ =
             builder.options
 
         httpOnly : Bool
         httpOnly =
-            not options.visibleToJavaScript
+            not options_.visibleToJavaScript
     in
     builder.name
         ++ "="
         ++ Url.percentEncode builder.value
-        ++ option "Expires" (options.expiration |> Maybe.map Utc.fromTime)
-        ++ option "Max-Age" (options.maxAge |> Maybe.map String.fromInt)
-        ++ option "Path" options.path
-        ++ option "Domain" options.domain
-        ++ option "SameSite" (options.sameSite |> Maybe.map sameSiteToString)
+        ++ option "Expires" (options_.expiration |> Maybe.map Utc.fromTime)
+        ++ option "Max-Age" (options_.maxAge |> Maybe.map String.fromInt)
+        ++ option "Path" options_.path
+        ++ option "Domain" options_.domain
+        ++ option "SameSite" (options_.sameSite |> Maybe.map sameSiteToString)
         ++ boolOption "HttpOnly" httpOnly
-        ++ boolOption "Secure" options.secure
+        ++ boolOption "Secure" options_.secure
 
 
 sameSiteToString : SameSite -> String
@@ -128,18 +150,22 @@ sameSiteToString sameSite =
             "None"
 
 
-{-| -}
+{-| Create a `SetCookie` record with the given name, value, and [`Options`](Options]. To add a `Set-Cookie` header, you can
+pass this value with [`Server.Response.withSetCookieHeader`](Server-Response#withSetCookieHeader). Or for more low-level
+uses you can stringify the value manually with [`toString`](#toString).
+-}
 setCookie : String -> String -> Options -> SetCookie
-setCookie name value options =
+setCookie name value options_ =
     { name = name
     , value = value
-    , options = options
+    , options = options_
     }
 
 
-{-| -}
-initOptions : Options
-initOptions =
+{-| Initialize the default `SetCookie` `Options`. Can be configured directly through a record update, or with `withExpiration`, etc.
+-}
+options : Options
+options =
     { expiration = Nothing
     , visibleToJavaScript = False
     , maxAge = Nothing
@@ -158,7 +184,9 @@ withExpiration time builder =
     }
 
 
-{-| -}
+{-| Sets [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#expiresdate) to `Time.millisToPosix 0`,
+which effectively tells the browser to delete the cookie immediately (by giving it an expiration date in the past).
+-}
 withImmediateExpiration : Options -> Options
 withImmediateExpiration builder =
     { builder
@@ -184,7 +212,8 @@ makeVisibleToJavaScript builder =
     }
 
 
-{-| -}
+{-| Sets the `Set-Cookie`'s [`Max-Age`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#max-agenumber).
+-}
 withMaxAge : Int -> Options -> Options
 withMaxAge maxAge builder =
     { builder
@@ -192,7 +221,11 @@ withMaxAge maxAge builder =
     }
 
 
-{-| -}
+{-| Sets the `Set-Cookie`'s [`Path`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value).
+
+The default value is `/`, which will match any sub-directories or the root directory. See also [\`withoutPath](#withoutPath)
+
+-}
 withPath : String -> Options -> Options
 withPath path builder =
     { builder
@@ -200,7 +233,13 @@ withPath path builder =
     }
 
 
-{-| -}
+{-|
+
+> If the server omits the Path attribute, the user agent will use the "directory" of the request-uri's path component as the default value.
+
+Source: <https://www.rfc-editor.org/rfc/rfc6265>. See <https://stackoverflow.com/a/43336097>.
+
+-}
 withoutPath : Options -> Options
 withoutPath builder =
     { builder
@@ -208,7 +247,8 @@ withoutPath builder =
     }
 
 
-{-| -}
+{-| Sets the `Set-Cookie`'s [`Domain`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#domaindomain-value).
+-}
 withDomain : String -> Options -> Options
 withDomain domain builder =
     { builder

package/src/{Path.elm → UrlPath.elm}

@@ -1,5 +1,5 @@
-module Path exposing
-    ( Path, join, fromString
+module UrlPath exposing
+    ( UrlPath, join, fromString
     , toAbsolute, toRelative, toSegments
     )
 
@@ -9,27 +9,27 @@ This helper lets you combine together path parts without worrying about having t
 These two examples will result in the same URL, even though the first example has trailing and leading slashes, and the
 second does not.
 
-    Path.join [ "/blog/", "/post-1/" ]
-        |> Path.toAbsolute
+    UrlPath.join [ "/blog/", "/post-1/" ]
+        |> UrlPath.toAbsolute
     --> "/blog/post-1"
 
-    Path.join [ "blog", "post-1" ]
-        |> Path.toAbsolute
+    UrlPath.join [ "blog", "post-1" ]
+        |> UrlPath.toAbsolute
     --> "/blog/post-1"
 
 We can also safely join Strings that include multiple path parts, a single path part per string, or a mix of the two:
 
-    Path.join [ "/articles/archive/", "1977", "06", "10", "post-1" ]
-        |> Path.toAbsolute
+    UrlPath.join [ "/articles/archive/", "1977", "06", "10", "post-1" ]
+        |> UrlPath.toAbsolute
     --> "/articles/archive/1977/06/10/post-1"
 
 
-## Creating Paths
+## Creating UrlPaths
 
-@docs Path, join, fromString
+@docs UrlPath, join, fromString
 
 
-## Turning Paths to String
+## Turning UrlPaths to String
 
 @docs toAbsolute, toRelative, toSegments
 
@@ -40,35 +40,35 @@ import Pages.Internal.String exposing (chopEnd, chopStart)
 
 {-| The path portion of the URL, normalized to ensure that path segments are joined with `/`s in the right places (no doubled up or missing slashes).
 -}
-type alias Path =
+type alias UrlPath =
     List String
 
 
 {-| Turn a Path to a relative URL.
 -}
-join : Path -> Path
+join : UrlPath -> UrlPath
 join parts =
     parts
         |> List.filter (\segment -> segment /= "/")
         |> List.map normalize
 
 
-{-| Turn a Path to a relative URL.
+{-| Turn a UrlPath to a relative URL.
 -}
-toRelative : Path -> String
+toRelative : UrlPath -> String
 toRelative parts =
     join parts
         |> String.join "/"
 
 
-{-| Create a Path from a path String.
+{-| Create a UrlPath from a path String.
 
-    Path.fromString "blog/post-1/"
-        |> Path.toAbsolute
+    UrlPath.fromString "blog/post-1/"
+        |> UrlPath.toAbsolute
         |> Expect.equal "/blog/post-1"
 
 -}
-fromString : String -> Path
+fromString : String -> UrlPath
 fromString path =
     path
         |> toSegments
@@ -80,9 +80,9 @@ toSegments path =
     path |> String.split "/" |> List.filter ((/=) "")
 
 
-{-| Turn a Path to an absolute URL (with no trailing slash).
+{-| Turn a UrlPath to an absolute URL (with no trailing slash).
 -}
-toAbsolute : Path -> String
+toAbsolute : UrlPath -> String
 toAbsolute path =
     "/" ++ toRelative path