elm-pages 3.0.0-beta.1 → 3.0.0-beta.10

package/src/Pages/Internal/Platform/CompatibilityKey.elm

@@ -0,0 +1,6 @@
+module Pages.Internal.Platform.CompatibilityKey exposing (currentCompatibilityKey)
+
+
+currentCompatibilityKey : Int
+currentCompatibilityKey =
+    1

package/src/Pages/Internal/Platform.elm

@@ -58,7 +58,7 @@ type alias Program userModel userMsg pageData actionData sharedData errorPage =
 mainView :
     ProgramConfig userMsg userModel route pageData actionData sharedData effect (Msg userMsg pageData actionData sharedData errorPage) errorPage
     -> Model userModel pageData actionData sharedData
-    -> { title : String, body : Html (Pages.Msg.Msg userMsg) }
+    -> { title : String, body : List (Html (Pages.Msg.Msg userMsg)) }
 mainView config model =
     case model.notFound of
         Just info ->
@@ -95,7 +95,7 @@ mainView config model =
                 Err error ->
                     { title = "Page Data Error"
                     , body =
-                        Html.div [] [ Html.text error ]
+                        [ Html.div [] [ Html.text error ] ]
                     }
 
 
@@ -124,9 +124,9 @@ view config model =
     { title = title
     , body =
         [ onViewChangeElement model.url
-        , body |> Html.map UserMsg
         , AriaLiveAnnouncer.view model.ariaNavigationAnnouncement
         ]
+            ++ List.map (Html.map UserMsg) body
     }
 
 
@@ -423,9 +423,7 @@ update config appMsg model =
                         )
 
                     else
-                        ( { model
-                            | url = url
-                          }
+                        ( model
                         , NoEffect
                         )
                             -- TODO is it reasonable to always re-fetch route data if you re-navigate to the current route? Might be a good
@@ -605,27 +603,32 @@ update config appMsg model =
                                 , actionData = newActionData
                                 }
 
-                            ( userModel, _ ) =
+                            ( userModel, userEffect ) =
                                 -- TODO if urlWithoutRedirectResolution is different from the url with redirect resolution, then
                                 -- instead of calling update, call pushUrl (I think?)
                                 -- TODO include user Cmd
-                                config.update model.pageFormState
-                                    (model.inFlightFetchers |> toFetcherState)
-                                    (model.transition |> Maybe.map Tuple.second)
-                                    newSharedData
-                                    newPageData
-                                    model.key
-                                    (config.onPageChange
-                                        { protocol = model.url.protocol
-                                        , host = model.url.host
-                                        , port_ = model.url.port_
-                                        , path = urlPathToPath urlWithoutRedirectResolution
-                                        , query = urlWithoutRedirectResolution.query
-                                        , fragment = urlWithoutRedirectResolution.fragment
-                                        , metadata = config.urlToRoute urlWithoutRedirectResolution
-                                        }
-                                    )
-                                    previousPageData.userModel
+                                if stayingOnSamePath then
+                                    ( previousPageData.userModel, NoEffect )
+
+                                else
+                                    config.update model.pageFormState
+                                        (model.inFlightFetchers |> toFetcherState)
+                                        (model.transition |> Maybe.map Tuple.second)
+                                        newSharedData
+                                        newPageData
+                                        model.key
+                                        (config.onPageChange
+                                            { protocol = model.url.protocol
+                                            , host = model.url.host
+                                            , port_ = model.url.port_
+                                            , path = urlPathToPath urlWithoutRedirectResolution
+                                            , query = urlWithoutRedirectResolution.query
+                                            , fragment = urlWithoutRedirectResolution.fragment
+                                            , metadata = config.urlToRoute urlWithoutRedirectResolution
+                                            }
+                                        )
+                                        previousPageData.userModel
+                                        |> Tuple.mapSecond UserCmd
 
                             updatedModel : Model userModel pageData actionData sharedData
                             updatedModel =
@@ -656,10 +659,13 @@ update config appMsg model =
                             , currentPath = newUrl.path
                           }
                         , if not stayingOnSamePath && scrollToTopWhenDone then
-                            ScrollToTop
+                            Batch
+                                [ ScrollToTop
+                                , userEffect
+                                ]
 
                           else
-                            NoEffect
+                            userEffect
                         )
                             |> (case maybeUserMsg of
                                     Just userMsg ->
@@ -1392,7 +1398,8 @@ loadDataAndUpdateUrl ( newPageData, newSharedData, newActionData ) maybeUserMsg
                     , actionData = newActionData
                     }
 
-                ( userModel, _ ) =
+                -- TODO use userEffect here?
+                ( userModel, userEffect ) =
                     -- TODO if urlWithoutRedirectResolution is different from the url with redirect resolution, then
                     -- instead of calling update, call pushUrl (I think?)
                     -- TODO include user Cmd

package/src/Pages/ProgramConfig.elm

@@ -65,7 +65,7 @@ type alias ProgramConfig userMsg userModel route pageData actionData sharedData
         -> pageData
         -> Maybe actionData
         ->
-            { view : userModel -> { title : String, body : Html (Pages.Msg.Msg userMsg) }
+            { view : userModel -> { title : String, body : List (Html (Pages.Msg.Msg userMsg)) }
             , head : List Head.Tag
             }
     , handleRoute : route -> DataSource (Maybe NotFoundReason)
@@ -88,7 +88,10 @@ type alias ProgramConfig userMsg userModel route pageData actionData sharedData
         }
         -> userMsg
     , apiRoutes :
-        (Html Never -> String)
+        (Maybe { indent : Int, newLines : Bool }
+         -> Html Never
+         -> String
+        )
         -> List (ApiRoute.ApiRoute ApiRoute.Response)
     , pathPatterns : List RoutePattern
     , basePath : List String
@@ -98,7 +101,7 @@ type alias ProgramConfig userMsg userModel route pageData actionData sharedData
     , encodeResponse : ResponseSketch pageData actionData sharedData -> Bytes.Encode.Encoder
     , encodeAction : actionData -> Bytes.Encode.Encoder
     , decodeResponse : Bytes.Decode.Decoder (ResponseSketch pageData actionData sharedData)
-    , globalHeadTags : Maybe ((Html Never -> String) -> DataSource (List Head.Tag))
+    , globalHeadTags : Maybe ((Maybe { indent : Int, newLines : Bool } -> Html Never -> String) -> DataSource (List Head.Tag))
     , cmdToEffect : Cmd userMsg -> effect
     , perform :
         { fetchRouteData :

package/src/Server/Session.elm

@@ -1,8 +1,109 @@
-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 (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
+                                    )
+                        )
+            )
+
+The elm-pages framework will manage signing these cookies using the `secrets : DataSource (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 : DataSource (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
+                (Env.expect "SESSION_SECRET2022-09-01")
+        , options = cookieOptions
+        }
+
+Then you add a second secret
+
+    Session.withSession
+        { name = "mysession"
+        , secrets =
+            DataSource.map2
+                (\newSecret oldSecret -> [ newSecret, oldSecret ])
+                (Env.expect "SESSION_SECRET2022-12-01")
+                (Env.expect "SESSION_SECRET2022-09-01")
+        , options = cookieOptions
+        }
 
-{-|
+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.
 
-@docs Decoder, NotLoadedReason, Session, Value, clearFlashCookies, empty, expectSession, flashPrefix, get, insert, remove, setValues, succeed, unwrap, update, withFlash, withSession
+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 =
+            DataSource.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
 
 -}
 
@@ -10,10 +111,9 @@ import DataSource exposing (DataSource)
 import DataSource.Http
 import DataSource.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
+    = NoSessionCookie
+    | InvalidSessionCookie
 
 
 {-| -}
-succeed : constructor -> Decoder constructor
-succeed constructor =
-    constructor
-        |> Json.Decode.succeed
-
-
-{-| -}
-setValues : Session -> Json.Encode.Value
-setValues (Session session) =
+encodeNonExpiringPairs : Session -> Json.Encode.Value
+encodeNonExpiringPairs (Session session) =
     session
         |> Dict.toList
         |> List.filterMap
@@ -151,71 +239,56 @@ 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
+    , 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 -> 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
-                decrypted : DataSource (Result () (Maybe Session))
-                decrypted =
+                unsigned : DataSource (Result NotLoadedReason Session)
+                unsigned =
                     case maybeSessionCookie of
                         Just sessionCookie ->
                             sessionCookie
-                                |> decryptCookie config
-                                |> DataSource.map (Result.map Just)
+                                |> unsignCookie config
+                                |> DataSource.map
+                                    (\unsignResult ->
+                                        case unsignResult of
+                                            Ok decoded ->
+                                                Ok decoded
+
+                                            Err () ->
+                                                Err InvalidSessionCookie
+                                    )
 
                         Nothing ->
-                            Ok Nothing
+                            Err NoSessionCookie
                                 |> DataSource.succeed
             in
-            decrypted
+            unsigned
                 |> DataSource.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 : DataSource (List String)
+    , options : SetCookie.Options
+    }
+    -> (c -> d -> DataSource ( Session, Response data errorPage ))
+    -> c
+    -> d
+    -> DataSource (Response data errorPage)
 encodeSessionUpdate config toRequest userRequestData sessionResult =
     sessionResult
         |> toRequest userRequestData
@@ -225,25 +298,18 @@ encodeSessionUpdate config toRequest userRequestData sessionResult =
                     (\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 : DataSource (List String) } -> String -> DataSource (Result () Session)
+unsignCookie config sessionCookie =
     sessionCookie
-        |> decrypt config.secrets (Json.Decode.dict Json.Decode.string)
+        |> unsign config.secrets (Json.Decode.dict Json.Decode.string)
         |> DataSource.map
             (Result.map
                 (\dict ->
@@ -265,8 +331,8 @@ decryptCookie config sessionCookie =
             )
 
 
-encrypt : DataSource (List String) -> Json.Encode.Value -> DataSource String
-encrypt getSecrets input =
+sign : DataSource (List String) -> Json.Encode.Value -> DataSource String
+sign getSecrets input =
     getSecrets
         |> DataSource.andThen
             (\secrets ->
@@ -293,8 +359,8 @@ encrypt getSecrets input =
             )
 
 
-decrypt : DataSource (List String) -> Json.Decode.Decoder a -> String -> DataSource (Result () a)
-decrypt getSecrets decoder input =
+unsign : DataSource (List String) -> Json.Decode.Decoder a -> String -> DataSource (Result () a)
+unsign getSecrets decoder input =
     getSecrets
         |> DataSource.andThen
             (\secrets ->