elm-pages 3.0.0-beta.2 → 3.0.0-beta.21

package/src/Server/Request.elm

@@ -86,11 +86,12 @@ module Server.Request exposing
 
 -}
 
+import BackendTask exposing (BackendTask)
 import CookieParser
-import DataSource exposing (DataSource)
 import Dict exposing (Dict)
+import FatalError exposing (FatalError)
 import Form
-import Form.Validation exposing (Validation)
+import Form.Validation as Validation
 import FormData
 import Internal.Request
 import Json.Decode
@@ -118,17 +119,17 @@ Note that this data is not available for pre-rendered pages or pre-rendered API
 This is because when a page is pre-rendered, there _is_ no incoming HTTP request to respond to, it is rendered before a user
 requests the page and then the pre-rendered page is served as a plain file (without running your Route Module).
 
-That's why `RouteBuilder.preRender` has `data : RouteParams -> DataSource Data`:
+That's why `RouteBuilder.preRender` has `data : RouteParams -> BackendTask Data`:
 
-    import DataSource exposing (DataSource)
+    import BackendTask exposing (BackendTask)
     import RouteBuilder exposing (StatelessRoute)
 
     type alias Data =
         {}
 
-    data : RouteParams -> DataSource Data
+    data : RouteParams -> BackendTask Data
     data routeParams =
-        DataSource.succeed Data
+        BackendTask.succeed Data
 
     route : StatelessRoute RouteParams Data ActionData
     route =
@@ -141,7 +142,7 @@ That's why `RouteBuilder.preRender` has `data : RouteParams -> DataSource Data`:
 
 A server-rendered Route Module _does_ have access to a user's incoming HTTP request because it runs every time the page
 is loaded. That's why `data` is a `Request.Parser` in server-rendered Route Modules. Since you have an incoming HTTP request for server-rendered routes,
-`RouteBuilder.serverRender` has `data : RouteParams -> Request.Parser (DataSource (Response Data))`. That means that you
+`RouteBuilder.serverRender` has `data : RouteParams -> Request.Parser (BackendTask (Response Data))`. That means that you
 can use the incoming HTTP request data to choose how to respond. For example, you could check for a dark-mode preference
 cookie and render a light- or dark-themed page and render a different page.
 
@@ -151,7 +152,7 @@ That's a mouthful, so let's unpack what it means.
 
 data from the request payload using a Server Request Parser.
 
-    import DataSource exposing (DataSource)
+    import BackendTask exposing (BackendTask)
     import RouteBuilder exposing (StatelessRoute)
     import Server.Request as Request exposing (Request)
     import Server.Response as Response exposing (Response)
@@ -161,11 +162,11 @@ data from the request payload using a Server Request Parser.
 
     data :
         RouteParams
-        -> Request.Parser (DataSource (Response Data))
+        -> Request.Parser (BackendTask (Response Data))
     data routeParams =
         {}
             |> Server.Response.render
-            |> DataSource.succeed
+            |> BackendTask.succeed
             |> Request.succeed
 
     route : StatelessRoute RouteParams Data ActionData
@@ -225,7 +226,7 @@ succeed value =
 
 {-| TODO internal only
 -}
-getDecoder : Parser (DataSource response) -> Json.Decode.Decoder (Result ( ValidationError, List ValidationError ) (DataSource response))
+getDecoder : Parser (BackendTask error response) -> Json.Decode.Decoder (Result ( ValidationError, List ValidationError ) (BackendTask error response))
 getDecoder (Internal.Request.Parser decoder) =
     decoder
         |> Json.Decode.map
@@ -881,8 +882,8 @@ fileField_ name =
 
 {-| -}
 formDataWithServerValidation :
-    Form.ServerForms error (DataSource (Validation error combined kind constraints))
-    -> Parser (DataSource (Result (Form.Response error) ( Form.Response error, combined )))
+    Form.ServerForms error (BackendTask FatalError (Validation.Validation error combined kind constraints))
+    -> Parser (BackendTask FatalError (Result (Form.Response error) ( Form.Response error, combined )))
 formDataWithServerValidation formParsers =
     rawFormData
         |> andThen
@@ -897,27 +898,25 @@ formDataWithServerValidation formParsers =
                     ( Just decoded, Nothing ) ->
                         succeed
                             (decoded
-                                |> DataSource.map
+                                |> BackendTask.map
                                     (\(Validation _ _ ( maybeParsed, errors2 )) ->
                                         case ( maybeParsed, errors2 |> Dict.toList |> List.filter (\( _, value ) -> value |> List.isEmpty |> not) |> List.NonEmpty.fromList ) of
                                             ( Just decodedFinal, Nothing ) ->
                                                 Ok
-                                                    ( Form.Response
+                                                    ( Pages.Internal.Form.Response
                                                         { fields = rawFormData_
                                                         , errors = Dict.empty
+                                                        , clientErrors = Dict.empty
                                                         }
                                                     , decodedFinal
                                                     )
 
-                                            ( _, maybeErrors ) ->
+                                            _ ->
                                                 Err
-                                                    (Form.Response
+                                                    (Pages.Internal.Form.Response
                                                         { fields = rawFormData_
-                                                        , errors =
-                                                            maybeErrors
-                                                                |> Maybe.map List.NonEmpty.toList
-                                                                |> Maybe.withDefault []
-                                                                |> Dict.fromList
+                                                        , errors = errors2
+                                                        , clientErrors = errors
                                                         }
                                                     )
                                     )
@@ -925,16 +924,17 @@ formDataWithServerValidation formParsers =
 
                     ( _, maybeErrors ) ->
                         Err
-                            (Form.Response
+                            (Pages.Internal.Form.Response
                                 { fields = rawFormData_
                                 , errors =
                                     maybeErrors
                                         |> Maybe.map List.NonEmpty.toList
                                         |> Maybe.withDefault []
                                         |> Dict.fromList
+                                , clientErrors = Dict.empty
                                 }
                             )
-                            |> DataSource.succeed
+                            |> BackendTask.succeed
                             |> succeed
             )
 
@@ -942,7 +942,7 @@ formDataWithServerValidation formParsers =
 {-| -}
 formData :
     Form.ServerForms error combined
-    -> Parser (Result { fields : List ( String, String ), errors : Dict String (List error) } combined)
+    -> Parser ( Form.Response error, Result { fields : List ( String, String ), errors : Dict String (List error), clientErrors : Dict String (List error) } combined )
 formData formParsers =
     rawFormData
         |> andThen
@@ -955,18 +955,27 @@ formData formParsers =
                 in
                 case ( maybeDecoded, errors |> Dict.toList |> List.filter (\( _, value ) -> value |> List.isEmpty |> not) |> List.NonEmpty.fromList ) of
                     ( Just decoded, Nothing ) ->
-                        Ok decoded
+                        ( Pages.Internal.Form.Response { fields = [], errors = Dict.empty, clientErrors = Dict.empty }
+                        , Ok decoded
+                        )
                             |> succeed
 
                     ( _, maybeErrors ) ->
-                        Err
-                            { fields = rawFormData_
-                            , errors =
-                                maybeErrors
-                                    |> Maybe.map List.NonEmpty.toList
-                                    |> Maybe.withDefault []
-                                    |> Dict.fromList
-                            }
+                        let
+                            record : { fields : List ( String, String ), errors : Dict String (List error), clientErrors : Dict String (List error) }
+                            record =
+                                { fields = rawFormData_
+                                , errors = Dict.empty
+                                , clientErrors =
+                                    maybeErrors
+                                        |> Maybe.map List.NonEmpty.toList
+                                        |> Maybe.withDefault []
+                                        |> Dict.fromList
+                                }
+                        in
+                        ( Pages.Internal.Form.Response record
+                        , Err record
+                        )
                             |> succeed
             )
 

package/src/Server/Session.elm

@@ -1,19 +1,119 @@
-module Server.Session exposing (Decoder, NotLoadedReason(..), Session(..), Value(..), clearFlashCookies, empty, expectSession, flashPrefix, get, insert, remove, setValues, succeed, unwrap, update, withFlash, withSession)
+module Server.Session exposing
+    ( withSession
+    , 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.
+
+
+## Using Sessions in a Request.Parser
+
+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
+                                    )
+                        )
+            )
+
+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
+signed with your secrets. Of course you need to provide secure secrets and treat your secrets with care.
+
+
+### Rotating Secrets
+
+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 =
+            BackendTask.map List.singleton
+                (Env.expect "SESSION_SECRET2022-09-01")
+        , options = cookieOptions
+        }
+
+Then you add a second secret
 
-{-|
+    Session.withSession
+        { name = "mysession"
+        , secrets =
+            BackendTask.map2
+                (\newSecret oldSecret -> [ newSecret, oldSecret ])
+                (Env.expect "SESSION_SECRET2022-12-01")
+                (Env.expect "SESSION_SECRET2022-09-01")
+        , options = cookieOptions
+        }
 
-@docs Decoder, NotLoadedReason, Session, Value, clearFlashCookies, empty, expectSession, flashPrefix, get, insert, remove, setValues, succeed, unwrap, update, withFlash, withSession
+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
+whenever a new request comes in (even if the Session key-value pairs are unchanged), so these cookies get "refreshed" with the latest
+signing secret when a new request comes in.
+
+However, incoming requests with a cookie signed using the old secret (`2022-09-01`) will still successfully be unsigned
+because they are still in the rotation (and then subsequently "refreshed" and signed using the new secret).
+
+This allows you to rotate your session secrets (for security purposes). When a secret goes out of the rotation,
+it will invalidate all cookies signed with that. For example, if we remove our old secret from the rotation:
+
+    Session.withSession
+        { name = "mysession"
+        , secrets =
+            BackendTask.map List.singleton
+                (Env.expect "SESSION_SECRET2022-12-01")
+        , options = cookieOptions
+        }
+
+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 NotLoadedReason
+
+
+## Creating and Updating Sessions
+
+@docs Session, empty, get, insert, remove, update, withFlash
 
 -}
 
-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 Dict.Extra
 import Json.Decode
 import Json.Encode
-import Server.Request as Request exposing (Parser)
+import Server.Request
 import Server.Response exposing (Response)
 import Server.SetCookie as SetCookie
 
@@ -23,11 +123,6 @@ type Session
     = Session (Dict String Value)
 
 
-{-| -}
-type alias Decoder decoded =
-    Json.Decode.Decoder decoded
-
-
 {-| -}
 type Value
     = Persistent String
@@ -113,20 +208,13 @@ empty =
 
 {-| -}
 type NotLoadedReason
-    = NoCookies
-    | MissingHeaders
-
-
-{-| -}
-succeed : constructor -> Decoder constructor
-succeed constructor =
-    constructor
-        |> Json.Decode.succeed
+    = NoSessionCookie
+    | InvalidSessionCookie
 
 
 {-| -}
-setValues : Session -> Json.Encode.Value
-setValues (Session session) =
+encodeNonExpiringPairs : Session -> Json.Encode.Value
+encodeNonExpiringPairs (Session session) =
     session
         |> Dict.toList
         |> List.filterMap
@@ -151,100 +239,78 @@ flashPrefix =
     "__flash__"
 
 
-{-| -}
-clearFlashCookies : Dict String String -> Dict String String
-clearFlashCookies dict =
-    Dict.Extra.removeWhen
-        (\key _ ->
-            key |> String.startsWith flashPrefix
-        )
-        dict
-
-
-{-| -}
-expectSession :
-    { name : String
-    , secrets : DataSource (List String)
-    , sameSite : String
-    }
-    -> Parser request
-    -> (request -> Result () Session -> DataSource ( Session, Response data errorPage ))
-    -> Parser (DataSource (Response data errorPage))
-expectSession config userRequest toRequest =
-    Request.map2
-        (\sessionCookie userRequestData ->
-            sessionCookie
-                |> decryptCookie config
-                |> DataSource.andThen
-                    (encodeSessionUpdate config toRequest userRequestData)
-        )
-        (Request.expectCookie config.name)
-        userRequest
-
-
 {-| -}
 withSession :
     { name : String
-    , secrets : DataSource (List String)
-    , sameSite : String
+    , secrets : BackendTask error (List String)
+    , options : SetCookie.Options
     }
-    -> Parser request
-    -> (request -> Result () (Maybe Session) -> DataSource ( Session, Response data errorPage ))
-    -> Parser (DataSource (Response data errorPage))
-withSession config userRequest toRequest =
-    Request.map2
+    -> (request -> Result NotLoadedReason Session -> BackendTask error ( Session, Response data errorPage ))
+    -> Server.Request.Parser request
+    -> Server.Request.Parser (BackendTask error (Response data errorPage))
+withSession config toRequest userRequest =
+    Server.Request.map2
         (\maybeSessionCookie userRequestData ->
             let
-                decrypted : DataSource (Result () (Maybe Session))
-                decrypted =
+                unsigned : BackendTask error (Result NotLoadedReason Session)
+                unsigned =
                     case maybeSessionCookie of
                         Just sessionCookie ->
                             sessionCookie
-                                |> decryptCookie config
-                                |> DataSource.map (Result.map Just)
+                                |> unsignCookie config
+                                |> BackendTask.map
+                                    (\unsignResult ->
+                                        case unsignResult of
+                                            Ok decoded ->
+                                                Ok decoded
+
+                                            Err () ->
+                                                Err InvalidSessionCookie
+                                    )
 
                         Nothing ->
-                            Ok Nothing
-                                |> DataSource.succeed
+                            Err NoSessionCookie
+                                |> BackendTask.succeed
             in
-            decrypted
-                |> DataSource.andThen
+            unsigned
+                |> BackendTask.andThen
                     (encodeSessionUpdate config toRequest userRequestData)
         )
-        (Request.cookie config.name)
+        (Server.Request.cookie config.name)
         userRequest
 
 
-encodeSessionUpdate : { a | name : String, secrets : DataSource (List String) } -> (c -> d -> DataSource ( Session, Response data errorPage )) -> c -> d -> DataSource (Response data errorPage)
+encodeSessionUpdate :
+    { name : String
+    , secrets : BackendTask error (List String)
+    , options : SetCookie.Options
+    }
+    -> (c -> d -> BackendTask error ( Session, Response data errorPage ))
+    -> c
+    -> d
+    -> BackendTask error (Response data errorPage)
 encodeSessionUpdate config toRequest userRequestData sessionResult =
     sessionResult
         |> toRequest userRequestData
-        |> DataSource.andThen
+        |> BackendTask.andThen
             (\( sessionUpdate, response ) ->
-                DataSource.map
+                BackendTask.map
                     (\encoded ->
                         response
                             |> Server.Response.withSetCookieHeader
-                                (SetCookie.setCookie config.name encoded
-                                    |> SetCookie.httpOnly
-                                    |> SetCookie.withPath "/"
-                                 -- TODO set expiration time
-                                 -- TODO do I need to encrypt the session expiration as part of it
-                                 -- TODO should I update the expiration time every time?
-                                 --|> SetCookie.withExpiration (Time.millisToPosix 100000000000)
-                                )
+                                (SetCookie.setCookie config.name encoded config.options)
                     )
-                    (encrypt config.secrets
-                        (setValues sessionUpdate)
+                    (sign config.secrets
+                        (encodeNonExpiringPairs sessionUpdate)
                     )
             )
 
 
-decryptCookie : { a | secrets : DataSource (List String) } -> String -> DataSource (Result () Session)
-decryptCookie config sessionCookie =
+unsignCookie : { a | secrets : BackendTask error (List String) } -> String -> BackendTask error (Result () Session)
+unsignCookie config sessionCookie =
     sessionCookie
-        |> decrypt config.secrets (Json.Decode.dict Json.Decode.string)
-        |> DataSource.map
+        |> unsign config.secrets (Json.Decode.dict Json.Decode.string)
+        |> BackendTask.map
             (Result.map
                 (\dict ->
                     dict
@@ -265,15 +331,15 @@ decryptCookie config sessionCookie =
             )
 
 
-encrypt : DataSource (List String) -> Json.Encode.Value -> DataSource String
-encrypt getSecrets input =
+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"
@@ -287,21 +353,21 @@ encrypt getSecrets input =
                                 ]
                             )
                     , expect =
-                        DataSource.Http.expectJson
+                        BackendTask.Http.expectJson
                             Json.Decode.string
                     }
             )
 
 
-decrypt : DataSource (List String) -> Json.Decode.Decoder a -> String -> DataSource (Result () a)
-decrypt getSecrets decoder input =
+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 )
@@ -311,6 +377,6 @@ decrypt getSecrets decoder input =
                         decoder
                             |> Json.Decode.nullable
                             |> Json.Decode.map (Result.fromMaybe ())
-                            |> DataSource.Http.expectJson
+                            |> BackendTask.Http.expectJson
                     }
             )