Proposal: Configuration file support

[joseluisq]

One of the initial goal of this servers was/is to be able to getting started as soon as possible and without thinking hard on setup.

That's why CLI arguments and environment variables with sensitive defaults take place, for example on container environments or similar.
However there are situations where one wants to adjust on demand certain features (that actually are not possible to do) or even simply for convenience reasons like one place to setup all.

Motivation comes from #30 and by some users concerned about this.

Advantages

Right now I see some advantages like it can be more easy to use than arguments or envs, easy to track changes (E.g Git), it can offer an opportunity for providing future and more advanced features and others advantages.

Proposal

The server should be able to be configured also via a config.toml (TOML format).
This requires one new --config-file argument (SEVER_CONFIG_FILE equivalent env) which should map to the config file on the underlying file system.

Precedence over CLI arguments & Envs

TODO (help here)

Config file (TOML)

We prefer a config.toml (TOML format) since is more convenient and there is good support for it (E.g via Serde).
Here how it could look like.

[general]

#### Address & Root dir
host = "::"
port = 8087
root = "docker/public"

#### Logging
log-level = "trace"

#### Cache Control headers
cache-control-headers = true

#### Auto Compression
compression = true

#### Error pages
page404 = "docker/public/404.html"
page50x = "docker/public/50x.html"

#### HTTP/2 + TLS
http2 = false
http2-tls-cert = ""
http2-tls-key = ""

#### CORS & Security headers
security-headers = true
cors-allow-origins = ""

#### Directoy listing
directory-listing = false

#### Basich Authentication
basic-auth = ""

#### File descriptor binding
# fd = ""

#### Worker threads
threads-multiplier = 1

#### Grace period after a graceful shutdown
grace-period = 0

#### Page fallback for 404s
page-fallback = ""

[advanced]

#### HTTP Headers customization

#### a. Oneline version
[[advanced.headers]]
source = "**/*.{js,css}"
headers = { Access-Control-Allow-Origin = "*", X-XSS-PROTECTION = "1; mode=block" }

# #### b. Multiline version
[[advanced.headers]]
  source = "*.html"
  [advanced.headers.headers]
  Cache-Control = "public, max-age=36000"
  Content-Security-Policy = "frame-ancestors 'self'"
  Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"

#### c. Multiline version with explicit key (dotted)
[[advanced.headers]]
source = "**/*.{jpg,jpeg,png,ico,gif}"
headers.Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"

NOTE: This proposal in general as well as the Toml file structure are not final so your feedback will be appreciated.

[phartenfeller]

Hey, a config file would be great 😃!

What do you think about cache-control and even more headers being changable on route basis with regex. I guess this was also mentioned in #30 .

For example the Gatsby Caching Guide specifies rules for different file types, folders where the files sit in and even file names.

Something like this could work:

[headers]
  [headers.staticFiles]
  regex = "\\/static\\/.*"
  headers = [ "cache-control: public, max-age=31536000, immutable" ]

  [headers.displayPDFinline]
  regex = "\\/public\\/\\w+\\.pdf"
  headers = [
    "Content-Type: application/pdf",
    "Content-Disposition: inline"
  ]

  [headers.css]
  ....

[joseluisq]

Sure, we will keep in mind.
But generally, the idea of a config file is to help with more advanced things like this.

[rockwotj]

I'd be really excited about a config file and the ability to configure rewrites and headers. An example config file for static file serving I really like is Firebase Hosting: https://firebase.google.com/docs/hosting/full-config#firebase-json_example

[joseluisq]

Good to know. In fact I was interested in some ideas to have into account for "fine tune" the proposal.

[joseluisq]

Update: I have just started a draft PR #101 to play around with ideas from this feature request. The PR will receive Continuous updates from now.

[joseluisq]

Update: Regarding HTTP headers customization

I ended up with a Toml structure like this:

# HTTP Headers customization

# a. Oneline version
[[headers]]
source = "**/*.@(eot|otf|ttf|ttc|woff|font.css)"
headers = { Access-Control-Allow-Origin = "*", X-XSS-PROTECTION = "1; mode=block" }

# b. Multiline version
[[headers]]
  source = "**/*.@(jpg|jpeg|gif|png)"
[headers.headers]
  Cache-Control = "max-age=7200"
  Content-Security-Policy = "frame-ancestors 'self'"

# c. Multiline version with explicit key (dotted)
[[headers]]
source = "404.html"
headers.Cache-Control = "max-age=300"
headers.Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"

I have not evaluated the viability of the source prop yet (glob or regex pattern) but I will check it later.

The full config file content was updated in PR description above.

[joseluisq]

PR #101 is almost ready to be included in a beta release soon for testing.
It will also provide custom HTTP headers.

Have a look the PR description for more details.
Stay tuned

[joseluisq]

PR #101 was merged today and this feature as well as the custom headers one will be available on next v2.8.0 release soon.

[joseluisq]

Released on v2.8.0