Server.Static

Serve static files from a provided directory

type alias Config =
{ fileSystemPermission : Permission
, httpResponse : Response
, directory : String
, mode : Mode
}

Configuration options required to find files and generate responses.

  • fileSystemPermission is the permission you get from the FileSystem module of the gren-lang/node package for accessing the file system. This module needs read access to the file system to get any requested files.
  • httpResponse is the Response type you get from the HttpResponse module of the gren-lang/node package. This is required for this module to construct and return an HTTP Response.
  • directory is the directory that will be looked into to find any requested files. This module will only search the file system for files in this directory.
  • mode describes how this module will search for and find static files. Check out the docs for the Mode type for more details.
type Mode
= Normal
| SinglePageApp
| PrettyUrl

The Mode dictates what files will be searched for and in what order. Modes are meant to support common use-cases without any configuration. If there's a use-case this does not support, leave feedback on Github!

Normal Mode

Normal mode attempts to find a file with the exact path given. If a file is not found, it fails with a 404 Response.

SinglePageApp Mode

SinglePageApp mode attempts to find the file on the given path. If it fails, it looks for an index.html file at the root of the static file directory and returns it instead. If there is no such file, it fails and with a 404 Response.

As the mode name suggests, this allows for serving single-page apps which have a single index.html file for the entire application and want to route most (if not all) traffic through it.

PrettyUrl Mode

PrettyUrl mode attempts to find the file on the given path. If it fails, append index.html to the given path to try and find that file. If this fails, return a 404 Response.

This mode supports many static-site generators who generate urls like about/index.html rather than about.html for each generated file.
type ReadFileError
= AccessError AccessError
| UnknownFileSystemError UnknownFileSystemError

Possible errors when trying to read a static file from disk. Wraps both the known (FileSystem.AccessError) and unknown (FileSystem.UnknownFileSystemError) errors into one type so no mapping between them is needed.
response : Config -> Url -> Task ReadFileError Response

Try to get a file from a folder given a passed Url.

This function takes a Url and uses its path to know what file to look for. This decision makes it simple to integrate with received requests from the HttpServer module of the gren/node package.

When the task is successful, this function will produce a Response that contains the requested files contents as a String. If the task fails, it will produce an error.
responseWithNotFound : Config -> Url -> Task Response Response

Try to get a file from a folder given a passed Url.

This function just maps the error produced by the response function, ignores is, and uses a 404 response in its place. It's implementation is simple and can be copied or modified to suite your needs.

response config url
    |> Task.mapError (\_ -> HttpServer.Response.setStatus 404 config.httpResponse)