elm-pages 3.0.0-beta.14 → 3.0.0-beta.16

package/src/ApiRoute.elm

@@ -173,7 +173,7 @@ You define your ApiRoute's in `app/Api.elm`. Here's a simple example:
 -}
 
 import BackendTask exposing (BackendTask)
-import Exception exposing (Throwable)
+import FatalError exposing (FatalError)
 import Head
 import Internal.ApiRoute exposing (ApiRoute(..), ApiRouteBuilder(..))
 import Json.Decode as Decode
@@ -192,14 +192,14 @@ type alias ApiRoute response =
 {-| Same as [`preRender`](#preRender), but for an ApiRoute that has no dynamic segments. This is just a bit simpler because
 since there are no dynamic segments, you don't need to provide a BackendTask with the list of dynamic segments to pre-render because there is only a single possible route.
 -}
-single : ApiRouteBuilder (BackendTask Throwable String) (List String) -> ApiRoute Response
+single : ApiRouteBuilder (BackendTask FatalError String) (List String) -> ApiRoute Response
 single handler =
     handler
         |> preRender (\constructor -> BackendTask.succeed [ constructor ])
 
 
 {-| -}
-serverRender : ApiRouteBuilder (Server.Request.Parser (BackendTask Never (Server.Response.Response Never Never))) constructor -> ApiRoute Response
+serverRender : ApiRouteBuilder (Server.Request.Parser (BackendTask FatalError (Server.Response.Response Never Never))) constructor -> ApiRoute Response
 serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
     ApiRoute
         { regex = Regex.fromString ("^" ++ pattern ++ "$") |> Maybe.withDefault Regex.never
@@ -218,14 +218,13 @@ serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
                                 |> BackendTask.onError
                                     (\stringError ->
                                         -- TODO make error with title and better context/formatting
-                                        Exception.fromString stringError |> BackendTask.fail
+                                        FatalError.fromString stringError |> BackendTask.fail
                                     )
                                 |> BackendTask.andThen
                                     (\rendered ->
                                         case rendered of
                                             Just (Ok okRendered) ->
                                                 okRendered
-                                                    |> BackendTask.onError never
 
                                             Just (Err errors) ->
                                                 errors
@@ -233,13 +232,11 @@ serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
                                                     |> Server.Response.plainText
                                                     |> Server.Response.withStatusCode 400
                                                     |> BackendTask.succeed
-                                                    |> BackendTask.onError never
 
                                             Nothing ->
                                                 Server.Response.plainText "No matching request handler"
                                                     |> Server.Response.withStatusCode 400
                                                     |> BackendTask.succeed
-                                                    |> BackendTask.onError never
                                     )
                         )
                     |> Maybe.map (BackendTask.map (Server.Response.toJson >> Just))
@@ -263,10 +260,10 @@ serverRender ((ApiRouteBuilder patterns pattern _ _ _) as fullHandler) =
 
 
 {-| -}
-preRenderWithFallback : (constructor -> BackendTask Throwable (List (List String))) -> ApiRouteBuilder (BackendTask Throwable (Server.Response.Response Never Never)) constructor -> ApiRoute Response
+preRenderWithFallback : (constructor -> BackendTask FatalError (List (List String))) -> ApiRouteBuilder (BackendTask FatalError (Server.Response.Response Never Never)) constructor -> ApiRoute Response
 preRenderWithFallback buildUrls ((ApiRouteBuilder patterns pattern _ toString constructor) as fullHandler) =
     let
-        buildTimeRoutes__ : BackendTask Throwable (List String)
+        buildTimeRoutes__ : BackendTask FatalError (List String)
         buildTimeRoutes__ =
             buildUrls (constructor [])
                 |> BackendTask.map (List.map toString)
@@ -305,15 +302,15 @@ encodeStaticFileBody fileBody =
 
 
 {-| -}
-preRender : (constructor -> BackendTask Throwable (List (List String))) -> ApiRouteBuilder (BackendTask Throwable String) constructor -> ApiRoute Response
+preRender : (constructor -> BackendTask FatalError (List (List String))) -> ApiRouteBuilder (BackendTask FatalError String) constructor -> ApiRoute Response
 preRender buildUrls ((ApiRouteBuilder patterns pattern _ toString constructor) as fullHandler) =
     let
-        buildTimeRoutes__ : BackendTask Throwable (List String)
+        buildTimeRoutes__ : BackendTask FatalError (List String)
         buildTimeRoutes__ =
             buildUrls (constructor [])
                 |> BackendTask.map (List.map toString)
 
-        preBuiltMatches : BackendTask Throwable (List (List String))
+        preBuiltMatches : BackendTask FatalError (List (List String))
         preBuiltMatches =
             buildUrls (constructor [])
     in
@@ -326,7 +323,7 @@ preRender buildUrls ((ApiRouteBuilder patterns pattern _ toString constructor) a
                     matches =
                         Internal.ApiRoute.pathToMatches path fullHandler
 
-                    routeFound : BackendTask Throwable Bool
+                    routeFound : BackendTask FatalError Bool
                     routeFound =
                         preBuiltMatches
                             |> BackendTask.map (List.member matches)
@@ -434,19 +431,19 @@ capture (ApiRouteBuilder patterns pattern previousHandler toString constructor)
 
 {-| For internal use by generated code. Not so useful in user-land.
 -}
-getBuildTimeRoutes : ApiRoute response -> BackendTask Throwable (List String)
+getBuildTimeRoutes : ApiRoute response -> BackendTask FatalError (List String)
 getBuildTimeRoutes (ApiRoute handler) =
     handler.buildTimeRoutes
 
 
 {-| Include head tags on every page's HTML.
 -}
-withGlobalHeadTags : BackendTask Throwable (List Head.Tag) -> ApiRoute response -> ApiRoute response
+withGlobalHeadTags : BackendTask FatalError (List Head.Tag) -> ApiRoute response -> ApiRoute response
 withGlobalHeadTags globalHeadTags (ApiRoute handler) =
     ApiRoute { handler | globalHeadTags = Just globalHeadTags }
 
 
 {-| -}
-getGlobalHeadTagsBackendTask : ApiRoute response -> Maybe (BackendTask Throwable (List Head.Tag))
+getGlobalHeadTagsBackendTask : ApiRoute response -> Maybe (BackendTask FatalError (List Head.Tag))
 getGlobalHeadTagsBackendTask (ApiRoute handler) =
     handler.globalHeadTags

package/src/BackendTask/Env.elm

@@ -8,22 +8,23 @@ down into the final `Data` value, it won't end up in the client!
 
     import BackendTask exposing (BackendTask)
     import BackendTask.Env
+    import FatalError exposing (FatalError)
 
     type alias EnvVariables =
         { sendGridKey : String
         , siteUrl : String
         }
 
-    sendEmail : Email -> BackendTask ()
+    sendEmail : Email -> BackendTask FatalError ()
     sendEmail email =
         BackendTask.map2 EnvVariables
-            (BackendTask.Env.expect "SEND_GRID_KEY")
+            (BackendTask.Env.expect "SEND_GRID_KEY" |> BackendTask.allowFatal)
             (BackendTask.Env.get "BASE_URL"
                 |> BackendTask.map (Maybe.withDefault "http://localhost:1234")
             )
             |> BackendTask.andThen (sendEmailBackendTask email)
 
-    sendEmailBackendTask : Email -> EnvVariables -> BackendTask ()
+    sendEmailBackendTask : Email -> EnvVariables -> BackendTask FatalError ()
     sendEmailBackendTask email envVariables =
         Debug.todo "Not defined here"
 
@@ -39,7 +40,7 @@ down into the final `Data` value, it won't end up in the client!
 import BackendTask exposing (BackendTask)
 import BackendTask.Http
 import BackendTask.Internal.Request
-import Exception exposing (Catchable)
+import FatalError exposing (FatalError)
 import Json.Decode as Decode
 import Json.Encode as Encode
 import TerminalText
@@ -50,7 +51,8 @@ type Error
     = MissingEnvVariable String
 
 
-{-| Get an environment variable, or Nothing if there is no environment variable matching that name.
+{-| Get an environment variable, or Nothing if there is no environment variable matching that name. This `BackendTask`
+will never fail, but instead will return `Nothing` if the environment variable is missing.
 -}
 get : String -> BackendTask error (Maybe String)
 get envVariableName =
@@ -63,9 +65,9 @@ get envVariableName =
         }
 
 
-{-| Get an environment variable, or a BackendTask failure if there is no environment variable matching that name.
+{-| Get an environment variable, or a BackendTask FatalError if there is no environment variable matching that name.
 -}
-expect : String -> BackendTask (Catchable Error) String
+expect : String -> BackendTask { fatal : FatalError, recoverable : Error } String
 expect envVariableName =
     envVariableName
         |> get
@@ -73,7 +75,7 @@ expect envVariableName =
             (\maybeValue ->
                 maybeValue
                     |> Result.fromMaybe
-                        (Exception.Catchable (MissingEnvVariable envVariableName)
+                        (FatalError.recoverable
                             { title = "Missing Env Variable"
                             , body =
                                 [ TerminalText.text "BackendTask.Env.expect was expecting a variable `"
@@ -82,6 +84,7 @@ expect envVariableName =
                                 ]
                                     |> TerminalText.toString
                             }
+                            (MissingEnvVariable envVariableName)
                         )
                     |> BackendTask.fromResult
             )

package/src/BackendTask/File.elm

@@ -51,7 +51,7 @@ plain old JSON in Elm.
 import BackendTask exposing (BackendTask)
 import BackendTask.Http
 import BackendTask.Internal.Request
-import Exception exposing (Catchable)
+import FatalError exposing (FatalError)
 import Json.Decode as Decode exposing (Decoder)
 import TerminalText
 
@@ -141,7 +141,15 @@ It's common to parse the body with a markdown parser or other format.
                 )
 
 -}
-bodyWithFrontmatter : (String -> Decoder frontmatter) -> String -> BackendTask (Catchable (FileReadError Decode.Error)) frontmatter
+bodyWithFrontmatter :
+    (String -> Decoder frontmatter)
+    -> String
+    ->
+        BackendTask
+            { fatal : FatalError
+            , recoverable : FileReadError Decode.Error
+            }
+            frontmatter
 bodyWithFrontmatter frontmatterDecoder filePath =
     read filePath
         (body
@@ -213,7 +221,15 @@ the [`BackendTask`](BackendTask) API along with [`BackendTask.Glob`](BackendTask
             |> BackendTask.resolve
 
 -}
-onlyFrontmatter : Decoder frontmatter -> String -> BackendTask (Catchable (FileReadError Decode.Error)) frontmatter
+onlyFrontmatter :
+    Decoder frontmatter
+    -> String
+    ->
+        BackendTask
+            { fatal : FatalError
+            , recoverable : FileReadError Decode.Error
+            }
+            frontmatter
 onlyFrontmatter frontmatterDecoder filePath =
     read filePath
         (frontmatter frontmatterDecoder)
@@ -240,7 +256,14 @@ Hey there! This is my first post :)
 Then data will yield the value `"Hey there! This is my first post :)"`.
 
 -}
-bodyWithoutFrontmatter : String -> BackendTask (Catchable (FileReadError decoderError)) String
+bodyWithoutFrontmatter :
+    String
+    ->
+        BackendTask
+            { fatal : FatalError
+            , recoverable : FileReadError decoderError
+            }
+            String
 bodyWithoutFrontmatter filePath =
     read filePath
         body
@@ -264,7 +287,7 @@ You could read a file called `hello.txt` in your root project directory like thi
         File.rawFile "hello.txt"
 
 -}
-rawFile : String -> BackendTask (Catchable (FileReadError decoderError)) String
+rawFile : String -> BackendTask { fatal : FatalError, recoverable : FileReadError decoderError } String
 rawFile filePath =
     read filePath (Decode.field "rawFile" Decode.string)
 
@@ -286,7 +309,15 @@ The Decode will strip off any unused JSON data.
             "elm.json"
 
 -}
-jsonFile : Decoder a -> String -> BackendTask (Catchable (FileReadError Decode.Error)) a
+jsonFile :
+    Decoder a
+    -> String
+    ->
+        BackendTask
+            { fatal : FatalError
+            , recoverable : FileReadError Decode.Error
+            }
+            a
 jsonFile jsonFileDecoder filePath =
     rawFile filePath
         |> BackendTask.andThen
@@ -295,13 +326,14 @@ jsonFile jsonFileDecoder filePath =
                     |> Decode.decodeString jsonFileDecoder
                     |> Result.mapError
                         (\jsonDecodeError ->
-                            Exception.Catchable (DecodingError jsonDecodeError)
+                            FatalError.recoverable
                                 { title = "JSON Decoding Error"
                                 , body =
                                     [ TerminalText.text (Decode.errorToString jsonDecodeError)
                                     ]
                                         |> TerminalText.toString
                                 }
+                                (DecodingError jsonDecodeError)
                         )
                     |> BackendTask.fromResult
             )
@@ -314,7 +346,7 @@ body =
     Decode.field "withoutFrontmatter" Decode.string
 
 
-read : String -> Decoder a -> BackendTask (Catchable (FileReadError error)) a
+read : String -> Decoder a -> BackendTask { fatal : FatalError, recoverable : FileReadError error } a
 read filePath decoder =
     BackendTask.Internal.Request.request
         { name = "read-file"
@@ -330,10 +362,16 @@ read filePath decoder =
         |> BackendTask.andThen BackendTask.fromResult
 
 
-errorDecoder : String -> Decoder (Catchable (FileReadError decoding))
+errorDecoder :
+    String
+    ->
+        Decoder
+            { fatal : FatalError.FatalError
+            , recoverable : FileReadError decoding
+            }
 errorDecoder filePath =
     Decode.succeed
-        (Exception.Catchable FileDoesntExist
+        (FatalError.recoverable
             { title = "File Doesn't Exist"
             , body =
                 [ TerminalText.text "Couldn't find file at path `"
@@ -342,4 +380,5 @@ errorDecoder filePath =
                 ]
                     |> TerminalText.toString
             }
+            FileDoesntExist
         )

package/src/BackendTask/Glob.elm

@@ -229,7 +229,7 @@ import BackendTask exposing (BackendTask)
 import BackendTask.Http
 import BackendTask.Internal.Glob exposing (Glob(..))
 import BackendTask.Internal.Request
-import Exception exposing (Catchable, Throwable)
+import FatalError exposing (FatalError, Recoverable)
 import Json.Decode as Decode
 import Json.Encode as Encode
 import List.Extra
@@ -1054,7 +1054,7 @@ so it's ideal to make this kind of assertion rather than having fallback behavio
 issues (like if we had instead ignored the case where there are two or more matching blog post files).
 
 -}
-expectUniqueMatch : Glob a -> BackendTask (Catchable String) a
+expectUniqueMatch : Glob a -> BackendTask (Recoverable String) a
 expectUniqueMatch glob =
     glob
         |> toBackendTask
@@ -1066,14 +1066,14 @@ expectUniqueMatch glob =
 
                     [] ->
                         BackendTask.fail <|
-                            Exception.fromStringWithValue
-                                ("No files matched the pattern: " ++ toPatternString glob)
+                            FatalError.recoverable
+                                { title = "Non-Unique Glob", body = "No files matched the pattern: " ++ toPatternString glob }
                                 ("No files matched the pattern: " ++ toPatternString glob)
 
                     _ ->
                         BackendTask.fail <|
-                            Exception.fromStringWithValue
-                                "More than one file matched."
+                            FatalError.recoverable
+                                { title = "Non-Unique Glob", body = "Expected a unique match, but more than one file matched." }
                                 "More than one file matched."
             )
 

package/src/BackendTask/Http.elm

@@ -71,7 +71,22 @@ and describe your use case!
 
 ## Caching Options
 
-`elm-pages` performs GET requests using a local HTTP cache by default.
+`elm-pages` performs GET requests using a local HTTP cache by default. These requests are not performed using Elm's `elm/http`,
+but rather are performed in NodeJS. Under the hood it uses [the NPM package `make-fetch-happen`](https://github.com/npm/make-fetch-happen).
+Only GET requests made with `get`, `getJson`, or `getWithOptions` use local caching. Requests made with [`BackendTask.Http.request`](#request)
+are not cached, even if the method is set to `GET`.
+
+In dev mode, assets are cached more aggressively by default, whereas for a production build assets use a default to revalidate each cached response's freshness before using it (the `ForceRevalidate` [`CacheStrategy`](#CacheStrategy)).
+
+The default caching behavior for GET requests is to use a local cache in `.elm-pages/http-cache`. This uses the same caching behavior
+that browsers use to avoid re-downloading content when it hasn't changed. Servers can set HTTP response headers to explicitly control
+this caching behavior.
+
+  - [`cache-control` HTTP response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) let you set a length of time before considering an asset stale. This could mean that the server considers it acceptable for an asset to be somewhat outdated, or this could mean that the asset is guaranteed to be up-to-date until it is stale - those semantics are up to the server.
+  - `Last-Modified` and `ETag` HTTP response headers can be returned by the server allow [Conditional Requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests). Conditional Requests let us send back the `Last-Modified` timestamp or `etag` hash for assets that are in our local cache to the server to check if the asset is fresh, and skip re-downloading it if it is unchanged (or download a fresh one otherwise).
+
+It's important to note that depending on how the server sets these HTTP response headers, we may have outdated data - either because the server explicitly allows assets to become outdated with their cache-control headers, OR because cache-control headers are not set. When these headers aren't explicitly set, [clients are allowed to cache assets for 10% of the amount of time since it was last modified](https://httpwg.org/specs/rfc7234.html#heuristic.freshness).
+For production builds, the default caching will ignore both the implicit and explicit information about an asset's freshness and _always_ revalidate it before using a locally cached response.
 
 @docs getWithOptions
 
@@ -89,7 +104,7 @@ import Base64
 import Bytes exposing (Bytes)
 import Bytes.Decode
 import Dict exposing (Dict)
-import Exception exposing (Catchable)
+import FatalError exposing (FatalError, Recoverable)
 import Json.Decode
 import Json.Encode as Encode
 import Pages.Internal.StaticHttpBody as Body
@@ -138,15 +153,16 @@ type alias Body =
     Body.Body
 
 
-{-| A simplified helper around [`BackendTask.Http.request`](#request), which builds up a BackendTask.Http GET request.
+{-| A simplified helper around [`BackendTask.Http.get`](#get), which builds up a BackendTask.Http GET request with `expectJson`.
 
     import BackendTask
     import BackendTask.Http
+    import FatalError exposing (FatalError)
     import Json.Decode as Decode exposing (Decoder)
 
-    getRequest : BackendTask Int
+    getRequest : BackendTask (FatalError Error) Int
     getRequest =
-        BackendTask.Http.get
+        BackendTask.Http.getJson
             "https://api.github.com/repos/dillonkearns/elm-pages"
             (Decode.field "stargazers_count" Decode.int)
 
@@ -154,7 +170,7 @@ type alias Body =
 getJson :
     String
     -> Json.Decode.Decoder a
-    -> BackendTask (Catchable Error) a
+    -> BackendTask (Recoverable Error) a
 getJson url decoder =
     getWithOptions
         { url = url
@@ -167,11 +183,25 @@ getJson url decoder =
         }
 
 
-{-| -}
+{-| A simplified helper around [`BackendTask.Http.getWithOptions`](#getWithOptions), which builds up a GET request with
+the default retries, timeout, and HTTP caching options. If you need to configure those options or include HTTP request headers,
+use the more flexible `getWithOptions`.
+
+    import BackendTask
+    import BackendTask.Http
+    import FatalError exposing (FatalError)
+
+    getRequest : BackendTask (FatalError Error) String
+    getRequest =
+        BackendTask.Http.get
+            "https://api.github.com/repos/dillonkearns/elm-pages"
+            BackendTask.Http.expectString
+
+-}
 get :
     String
     -> Expect a
-    -> BackendTask (Catchable Error) a
+    -> BackendTask { fatal : FatalError, recoverable : Error } a
 get url expect =
     getWithOptions
         { url = url
@@ -185,6 +215,12 @@ get url expect =
 
 
 {-| Perform a GET request, with some additional options for the HTTP request, including options for caching behavior.
+
+  - `retries` - Default is 0. Will try performing request again if set to a number greater than 0.
+  - `timeoutInMs` - Default is no timeout.
+  - `cacheStrategy` - The [caching options are passed to the NPM package `make-fetch-happen`](https://github.com/npm/make-fetch-happen#opts-cache)
+  - `cachePath` - override the default directory for the local HTTP cache. This can be helpful if you want more granular control to clear some HTTP caches more or less frequently than others. Or you may want to preserve the local cache for some requests in your build server, but not store the cache for other requests.
+
 -}
 getWithOptions :
     { url : String
@@ -195,7 +231,7 @@ getWithOptions :
     , timeoutInMs : Maybe Int
     , cachePath : Maybe String
     }
-    -> BackendTask (Catchable Error) a
+    -> BackendTask (Recoverable Error) a
 getWithOptions request__ =
     let
         request_ : HashRequest.Request
@@ -222,7 +258,7 @@ post :
     String
     -> Body
     -> Expect a
-    -> BackendTask (Catchable Error) a
+    -> BackendTask (Recoverable Error) a
 post url body expect =
     request
         { url = url
@@ -361,7 +397,7 @@ request :
     , timeoutInMs : Maybe Int
     }
     -> Expect a
-    -> BackendTask (Catchable Error) a
+    -> BackendTask (Recoverable Error) a
 request request__ expect =
     let
         request_ : HashRequest.Request
@@ -439,7 +475,7 @@ with this as a low-level detail, or you can use functions like [BackendTask.Http
 requestRaw :
     HashRequest.Request
     -> Expect a
-    -> BackendTask (Catchable Error) a
+    -> BackendTask (Recoverable Error) a
 requestRaw request__ expect =
     let
         request_ : HashRequest.Request
@@ -537,7 +573,7 @@ requestRaw request__ expect =
                 |> BackendTask.fromResult
                 |> BackendTask.mapError
                     (\error ->
-                        Exception.Catchable error (errorToString error)
+                        FatalError.recoverable (errorToString error) error
                     )
         )