Config

Quokka uses TOML for it's configuration format. Inside the config there are "config modules" defined. These modules may or may not be used to configure substates. They can also be used by Bundles. Either way they always consist of a "module" field and a "config" field.

These are the Quokka builtin config modules

[[modules]]
module = "database"
config = { url = "postgres://$USERNAME:$PASSWORD@$DATABASE_HOST/$DB_NAME" }

# Can be omitted when passing in an FD for listening
[[modules]]
module = "listen"
config = { endpoint = "[::]:8765" }

[[modules]]
module = "migrations"
config = { autorun = true }

[[modules]]
module = "resources"
config = { additional_cache_control = [ "pubilc" ], max_age = 21600 }

[[modules]]
module = "mailer"
config = { host = "127.0.0.1", port = 1025, ssl_mode = "plain", from_name = "My Website", from_email = "my-website@localhost" }

Multiple configs

Quokka allows you to merge multiple config files into a single one by putting them, joined by : in the CONFIG_PATH environment variable.

Listening might be special

Quokka comes by default with the ability to take a listen on a filedescriptor which is passed in from an outer "launch" process (like when using systemd's .socket units). It utilizes listenfd library for that.

This abstraction allows an Quokka application to be running as a non-root/system user and without extra permissions while still being able to run on a privileged port.

Implement TryFromConfig

The TryFromConfig trait is there to build bundles and substates from config modules. There is no derive macro for it, but it's easy enough to implement manually:

struct TestBundle {
    configured_field: String,
}

// Technically this can also be skipped and the bundle it self can be Deserialized, but with more complex bundles they might tend to
// contain non-deserializable types, so you can right away go with a custom config struct for it.
#[derive(serde::Deserialize)]
struct TestBundleConfig {
    configured_field: String,
}

impl quokka::config::TryFromConfig for TestBundle {
    type Error = quokka::config::Error;

    async fn try_from_config(config: &quokka::config::Config) -> quokka::Result<Option<Self>>
    where
        Self: Sized,
    {
        // This function will search a module called `test-bundle` and deserializes it into the `Testbundle`
        config.get_module("test-bundle")
    }
}