elm-pages 3.0.0-beta.9 → 3.0.0

package/src/Server/Session.elm

@@ -1,48 +1,53 @@
 module Server.Session exposing
-    ( withSession
+    ( withSession, withSessionResult
     , NotLoadedReason(..)
     , 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 (DataSource (Response ActionData ErrorPage))
-    action routeParams =
-        MySession.withSession
-            (Request.formDataWithServerValidation (form |> Form.initCombinedServer identity))
-            (\nameResultData session ->
-                nameResultData
-                    |> DataSource.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 : DataSource (List String)` you pass in.
+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
 (so don't directly store sensitive data in your session). Since the session cookie is signed using the secret you provide,
 the cookie will be invalidated if it is tampered with because it won't match when elm-pages verifies that it has been
@@ -51,15 +56,15 @@ signed with your secrets. Of course you need to provide secure secrets and treat
 
 ### Rotating Secrets
 
-The first String in `secrets : DataSource (List String)` will be used to sign sessions, while the remaining String's will
+The first String in `secrets : BackendTask (List String)` will be used to sign sessions, while the remaining String's will
 still be used to attempt to "unsign" the cookies. So if you have a single secret:
 
     Session.withSession
         { name = "mysession"
         , secrets =
-            DataSource.map List.singleton
+            BackendTask.map List.singleton
                 (Env.expect "SESSION_SECRET2022-09-01")
-        , options = cookieOptions
+        , options = Nothing
         }
 
 Then you add a second secret
@@ -67,11 +72,11 @@ Then you add a second secret
     Session.withSession
         { name = "mysession"
         , secrets =
-            DataSource.map2
+            BackendTask.map2
                 (\newSecret oldSecret -> [ newSecret, oldSecret ])
                 (Env.expect "SESSION_SECRET2022-12-01")
                 (Env.expect "SESSION_SECRET2022-09-01")
-        , options = cookieOptions
+        , options = Nothing
         }
 
 The new secret (`2022-12-01`) will be used to sign all requests. This API always re-signs using the newest secret in the list
@@ -87,16 +92,16 @@ it will invalidate all cookies signed with that. For example, if we remove our o
     Session.withSession
         { name = "mysession"
         , secrets =
-            DataSource.map List.singleton
+            BackendTask.map List.singleton
                 (Env.expect "SESSION_SECRET2022-12-01")
-        , options = cookieOptions
+        , options = Nothing
         }
 
 And then a user makes a request but had a session signed with our old secret (`2022-09-01`), the session will be invalid
 (so `withSession` would parse the session for that request as `Nothing`). It's standard for cookies to have an expiration date,
 so there's nothing wrong with an old session expiring (and the browser will eventually delete old cookies), just be aware of that when rotating secrets.
 
-@docs withSession
+@docs withSession, withSessionResult
 
 @docs NotLoadedReason
 
@@ -107,18 +112,23 @@ so there's nothing wrong with an old session expiring (and the browser will even
 
 -}
 
-import DataSource exposing (DataSource)
-import DataSource.Http
-import DataSource.Internal.Request
+import BackendTask exposing (BackendTask)
+import BackendTask.Http
+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,66 +288,87 @@ 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 : DataSource (List String)
-    , options : SetCookie.Options
+    , secrets : BackendTask error (List String)
+    , options : Maybe SetCookie.Options
     }
-    -> (request -> Result NotLoadedReason Session -> DataSource ( Session, Response data errorPage ))
-    -> Server.Request.Parser request
-    -> Server.Request.Parser (DataSource (Response data errorPage))
-withSession config toRequest userRequest =
-    Server.Request.map2
-        (\maybeSessionCookie userRequestData ->
-            let
-                unsigned : DataSource (Result NotLoadedReason Session)
-                unsigned =
-                    case maybeSessionCookie of
-                        Just sessionCookie ->
-                            sessionCookie
-                                |> unsignCookie config
-                                |> DataSource.map
-                                    (\unsignResult ->
-                                        case unsignResult of
-                                            Ok decoded ->
-                                                Ok decoded
-
-                                            Err () ->
-                                                Err InvalidSessionCookie
-                                    )
+    -> (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
+                    |> 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
+    }
+    -> (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
-                                |> DataSource.succeed
-            in
-            unsigned
-                |> DataSource.andThen
-                    (encodeSessionUpdate config toRequest userRequestData)
-        )
-        (Server.Request.cookie config.name)
-        userRequest
+                Nothing ->
+                    Err NoSessionCookie
+                        |> BackendTask.succeed
+    in
+    unsigned
+        |> BackendTask.andThen
+            (encodeSessionUpdate config toTask)
 
 
 encodeSessionUpdate :
     { name : String
-    , secrets : DataSource (List String)
-    , options : SetCookie.Options
+    , secrets : BackendTask error (List String)
+    , options : Maybe SetCookie.Options
     }
-    -> (c -> d -> DataSource ( Session, Response data errorPage ))
-    -> c
+    -> (d -> BackendTask error ( Session, Response data errorPage ))
     -> d
-    -> DataSource (Response data errorPage)
-encodeSessionUpdate config toRequest userRequestData sessionResult =
+    -> BackendTask error (Response data errorPage)
+encodeSessionUpdate config toRequest sessionResult =
     sessionResult
-        |> toRequest userRequestData
-        |> DataSource.andThen
+        |> toRequest
+        |> BackendTask.andThen
             (\( sessionUpdate, response ) ->
-                DataSource.map
+                BackendTask.map
                     (\encoded ->
                         response
                             |> Server.Response.withSetCookieHeader
-                                (SetCookie.setCookie config.name encoded config.options)
+                                (SetCookie.setCookie config.name encoded (config.options |> Maybe.withDefault SetCookie.options))
                     )
                     (sign config.secrets
                         (encodeNonExpiringPairs sessionUpdate)
@@ -306,11 +376,11 @@ encodeSessionUpdate config toRequest userRequestData sessionResult =
             )
 
 
-unsignCookie : { a | secrets : DataSource (List String) } -> String -> DataSource (Result () Session)
+unsignCookie : { a | secrets : BackendTask error (List String) } -> String -> BackendTask error (Result () Session)
 unsignCookie config sessionCookie =
     sessionCookie
         |> unsign config.secrets (Json.Decode.dict Json.Decode.string)
-        |> DataSource.map
+        |> BackendTask.map
             (Result.map
                 (\dict ->
                     dict
@@ -331,15 +401,15 @@ unsignCookie config sessionCookie =
             )
 
 
-sign : DataSource (List String) -> Json.Encode.Value -> DataSource String
+sign : BackendTask error (List String) -> Json.Encode.Value -> BackendTask error String
 sign getSecrets input =
     getSecrets
-        |> DataSource.andThen
+        |> BackendTask.andThen
             (\secrets ->
-                DataSource.Internal.Request.request
+                BackendTask.Internal.Request.request
                     { name = "encrypt"
                     , body =
-                        DataSource.Http.jsonBody
+                        BackendTask.Http.jsonBody
                             (Json.Encode.object
                                 [ ( "values", input )
                                 , ( "secret"
@@ -353,21 +423,21 @@ sign getSecrets input =
                                 ]
                             )
                     , expect =
-                        DataSource.Http.expectJson
+                        BackendTask.Http.expectJson
                             Json.Decode.string
                     }
             )
 
 
-unsign : DataSource (List String) -> Json.Decode.Decoder a -> String -> DataSource (Result () a)
+unsign : BackendTask error (List String) -> Json.Decode.Decoder a -> String -> BackendTask error (Result () a)
 unsign getSecrets decoder input =
     getSecrets
-        |> DataSource.andThen
+        |> BackendTask.andThen
             (\secrets ->
-                DataSource.Internal.Request.request
+                BackendTask.Internal.Request.request
                     { name = "decrypt"
                     , body =
-                        DataSource.Http.jsonBody
+                        BackendTask.Http.jsonBody
                             (Json.Encode.object
                                 [ ( "input", Json.Encode.string input )
                                 , ( "secrets", Json.Encode.list Json.Encode.string secrets )
@@ -377,6 +447,6 @@ unsign getSecrets decoder input =
                         decoder
                             |> Json.Decode.nullable
                             |> Json.Decode.map (Result.fromMaybe ())
-                            |> DataSource.Http.expectJson
+                            |> BackendTask.Http.expectJson
                     }
             )

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, 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, 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,22 +150,26 @@ 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
-    , path = Nothing
+    , path = Just "/"
     , domain = Nothing
     , secure = True
     , sameSite = 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
@@ -174,7 +202,7 @@ dynamically). In this API you opt into exposing a cookie you set to JavaScript t
 
 In general if you can accomplish your goal using HttpOnly cookies (i.e. not using `makeVisibleToJavaScript`) then
 it's a good practice. With server-rendered `elm-pages` applications you can often manage your session state by pulling
-in session data from cookies in a `DataSource` (which is resolved server-side before it ever reaches the browser).
+in session data from cookies in a `BackendTask` (which is resolved server-side before it ever reaches the browser).
 
 -}
 makeVisibleToJavaScript : Options -> Options
@@ -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,22 @@ 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
+        | path = Nothing
+    }
+
+
+{-| 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