Serverless elm-pages

[dillonkearns]

Right now elm-pages builds a set of compiled Elm, pre-rendered HTML, JSON files, files from fileGenerators, and copied assets from images/ and static/ during the build step. So right now the lifecycle is:

• Build time (generateFiles hooks are run, pages are pre-rendered, StaticHttp requests are performed and stored as JSON as a build artifact)
• Run time (a full-featured Browser.application Elm app is hydrated and takes over the initial pre-rendered HTML page)

I'm working on a prototype for supporting a new part of the lifecycle: On Server/Serverless Request.

There are a lot of design decisions involved in this architecture, so I'm laying out my current thoughts and goals here.

You can see a rough prototype live here:

• https://deploy-preview-168--elm-pages.netlify.app/
• Pull request draft Serverless #168

Main Areas

The main feature areas here are:

• Page Routes
• API Routes

The current mental model I have in mind for Pages Routes is that they are either server-rendered at request time, or pre-rendered at build time.

Page Routes

Use Cases

Some uses for server-rendered pages would be:

• You want to check if a user is logged in and include some user-specific data in the rendered HTML/hydrated Elm
• You want to have fresh data with a frequently changing data source, always giving the most up-to-date data in the rendered HTML (not just client side updates that will flash and override a loading spinner or outdated value)

Design Ideas

There are a few important design decisions to solidify here. I'll just list the decisions that I'm leaning towards now

• The StaticHttp requests for a server-rendered page are all fetched on-demand (no mixing of build-time and on-demand StaticHttp data as it would be bug prone and hard to understand for users, and hard to maintain)
• Don't give access to the StaticHttp data that comes from the Shared Template Modules StaticHttp request. The reason is that this could be confusing because this data is built up at build time (and if it was re-fetched, it could cause it to be out of sync with some data). For example, if you get the current GitHub Stars in the Shared staticData, then server rendered pages could have a different number in the header star count than static pages on subsequent client-side navigations
• Do two-passes - a prepare step which builds up Context for the request. The StaticHttp requests in prepare don't result in any data being bundled into the server-rendered payload. You provide a Codec to explicitly pick the context that you want to have in the bundle. Then you can make follow-up StaticHttp requests that will be included from there in the final payload.

type alias RequestPayload = { headers : Dict String String, queryParams : Dict String (List String) }

type alias Context = { user : User } -- template-specific context, this is user-defined

type alias StaticData = { } -- whatever data you want to render the page

prepareCodec : Codec Context

prepare : RequestPayload -> StaticHttp.Request Context

onDemandData : Context -> StaticHttp.Request StaticData

API Routes

For API Routes, my current thinking is that the existing withFileGenerator hook will remain the same. This allows you to generate arbitrary static files during the build.

    withRobotsTxt builder =
    builder
        |> Pages.Platform.withFileGenerator
            (\siteMetadata ->
                StaticHttp.succeed
                    [ Ok
                        { path = [ "robots.txt" ]
                        , content = """
User-agent: *
Disallow: /cgi-bin/
                        """
                        }
                    ]
            )

API Routes are similar to file generators, except they have access to the request payload. Another important distinction is that file generators are all executed during the build step. But with API Routes, we need to be able to execute a single specific one. So the current internals for generateFiles wouldn't work well because you need to resolve a StaticHttp.Request in order to find out its file path:

    { ...
    generateFiles :
        List
            { path : PagePath pathKey
            , frontmatter : metadata
            , body : String
            }
        ->
            StaticHttp.Request
                (List
                    (Result
                        String
                        { path : List String
                        , content : String
                        }
                    )
                )
    }

A file generator is generating a specific set of files during the build. API Routes could potentially register to handle arbitrary dynamic routes. So conceptually the route matcher is more of a "give me the request, and I'll decide whether I can handle it."

It might look something like this:

type alias User =
    { isPro : Bool }

getUser : RequestPayload -> StaticHttp.Request (Maybe User)

api : (RequestPayload -> Maybe (StaticHttp.Request Json.Encode.Value)) -> ApiHandler

feedGenerator : ApiHandler
feedGenerator =
    api
        (\payload ->
            if payload.path == [ "feed.xml" ] then
                Just
                    (getUser payload
                        |> StaticHttp.andThen
                            (\user ->
                                if user |> Maybe.map .isPro |> Maybe.withDefault False then
                                    generateProFeed paths
                                        |> StaticHttp.succeed

                                else
                                    generateXmlFeed paths
                                        |> StaticHttp.succeed
                            )
                    )

            else
                Nothing
        )

A few things to note here:

• You can register as many API route handlers as you want, and depending on the order in which they are registered, it will just respond with whichever one yields a Just first when given the incoming RequestPayload
• If a handler decides to handle a given incoming request, then it gives back a (StaticHttp.Request Json.Encode.Value)
  • That means that it can perform StaticHttp (and the chain of StaticHttp requests is performed on-demand, not a build-time)
  • Its StaticHttp.Request of type Json.Encode.Value because the response could be different types depending on which service you're hosting with under the hood (Netlify, Vercel, etc). See the section on Hosting Adapters. The encoded JSON response may include cache hints to give to the provider, the raw body, status code, etc.

Typed Elm API Handlers (possible idea for a future iteration)

The API Routing I described above is a pretty general purpose way of using StaticHttp functionality to respond on-demand to API requests. You could use that as the low-level building block for some higher-level functionality that makes some assumptions.

Some assumptions we could make:

• JSON endpoints to be consumed by an Elm app
• Since it's a JSON API, lets have the API route match the module name (Api.ShopSession would give you an API route //ShopSession.json
• The endpoint is matched up to a handler based on that API route/module name convention mapping
• You can only send back JSON in the response
• Must define a Codec so that we can get more confidence that we can decode responses safely

With those assumptions, we could add a higher-level feature for making API endpoints that users could use in addition to the low-level API Routing functionality. Here's what it might look like to define one of these Elm JSON API endpoints:

module Api.ShopSession exposing (template, Data)

template =
    { codec = codec
    , handler = handler
    }

type alias Data = { user : User, shoppingCart : ShoppingCart, productInventory : ProductInventory }

codec : Codec Data

handler : Json.Decode.Value -> StaticHttp.Request Data
-- the JSON is the serverless request payload

So then from some Elm code, you could consume it in a more type-safe way like this by leverage the Codec you defined.

Api.shopSession : ApiBuilder Api.ShopSesssion.Data -- this is generated, it just provides a little bit of glue

exampleRequest : String -> Cmd msg
exampleRequest auth0Token =
    Api.shopSession |> ApiBuilder.withHeader "auth-token" auth0Token |> ApiBuilder.get
    -- the Codec is used here just by building an Http request with Api.shopSession
    -- the path will be `${functionsBaseUrl}/ShopSession`

An example use case where you could use this:

You have an elm-pages route that you want to statically generate for performance reasons. But once the page is hydrated into an Elm app, you want to make an HTTP request on init to get some fresh data about things like inventory, etc.

Hosting Adapters

I've been following some of the designs that SvelteKit has been coming up with. Their Adapter layer for different hosting providers is the basis of my thinking for this design. For example, here's their current Netlify adapter. It's a Node script that writes out some configuration files and copies some compiled assets to the appropriate places for that hosting provider.

For the first iteration of this functionality, elm-pages might just run a specific file, like say hosting-adapter.js, if that file exists in the root folder. It would run it when it's doing running elm-pages build.

[dillonkearns]

StaticHttp in an On-Demand Context

One of the really interesting things about StaticHttp is that you don't have an Err state to handle in your app. If a StaticHttp request fails, your build stops and tells you the error. You then fix the issue and re-run it.

When running a StaticHttp.Request on-demand, like for Server-Side Rendered pages or API routes, you can't guarantee that everything decodes correctly, or that all HTTP requests succeeded. So you know have to handle the error case.

Handling HTTP Errors as data in StaticHttp requests

My current thinking for this is that the missing piece is a function like this:

StaticHttp.requestResult :
      Pages.Secrets.Value RequestDetails
   -> OptimizedDecoder.Decoder a
   -> StaticHttp.Request (Result Http.Error a)

For example, if you make an HTTP request that gives a 403 Unauthorized status code if a user doesn't have access to a resource, you may want to use that status code "as data" in your StaticHttp request. You could then check for that, and proceed to turn it into whatever data you want.

You can also respond in server-side rendered elm-pages Page Routes or API Routes with 404, or any arbitrary status code.

So the idea is that you have access to those errors as data, and then you can turn it into whatever resulting response that you want to.

StaticHttp errors

What if the user makes a StaticHttp.Request and assumes it will succeed, so they use something like StaticHttp.get. This doesn't expose the error as data like the above API would.

I have a few ideas on the different directions this could go:

1. Give a 500 error - if the user isn't opting in to handling these errors, then we can just treat it as an unexpected error. This would be the easiest option to implement, and also the least rigid for users.
2. Don't allow the user to "opt out" of handling Http Errors - through the API design, it would be possible to have a different type for StaticHttp requests that may fail. That could be done with a variety of API design techniques, like a phantom type, an entirely different base type (that wouldn't be interchangeable with regular StaticHttp). The downside is this would lead to types that are more confusing for users and have a harder learning curve. It would be harder to build and maintain. And it would lead to some cases that have you juggling data explicitly in a way that's more verbose, which may be less practical in some situations. It's the most explicit approach, but might not be the most pragmatic.
3. Offer an onError hook. That could let you take those errors which would have been a 500 in case (1), but do some special handling with them.

I'm leaning towards (1), but I'd be curious to hear thoughts on this.

[rolojf]

Regarding StatticHttp errors, I think also option one is the way to go. With so much on your plate right now, being this easier to implement is a big plus. Later, if it becomes a priority, then a breaking change would be acceptable. But for now, I think efficiency is first.

The learning curve is already very steep. I am just barely getting the hang of it. Everything that makes things simpler I think is the way to go for now.

And last, it is not a bad idea to make the user responsible to handle the errors. Not all the work has to be done by the framework (like with image processing).

Just my two cents.

[dillonkearns]

Thanks for sharing your thoughts @rolojf!

It's also worth noting that a similar approach to (1) seems to be working well enough for NextJS: https://nextjs.org/docs/advanced-features/custom-error-page#500-page. So that's always a good sign that it's been working well when a very popular tool has been doing it that way already.

The context is a little different because with JavaScript, implicit errors may be more of the norm. But still, it's good validation that it's a workable approach.

With this new realm of serverless where errors may be presented to the user (not just behind the scenes in a build), I have been thinking about whether an API similar to the Task API might make sense. So it could be something along the lines of StaticHttp.Request error success, for example. I'm going to keep those ideas in mind for the future, they could be worth exploring. One of the appealing things there is that we now, for example, that doing StaticHttp.succeed cannot fail. So it would be interesting to preserve that information.

Thanks again for sharing your thoughts!