Configuration

Config Classes

Since app configs are used as the CLIs entrypoint into an app and a replacement of environment files, config classes are used alongside them to configure and influence the runtime of your app.

The core concept

Config classes define and / or overwrite the settings of your app. One example for that is the SESSION_COOKIE_SECURE variable we mentioned while setting up our first app. Those settings are set up using config classes, then parsed when your Fluid instance gets initialized and can be accessed via the fluid.config dict later on.

Registering your first config

You've got multiple options on how to register a config class. All of them rely on the register_config decorator. To keep things simple, we will use our main.py file from getting started and expand it with a minimal example of registering a config:

main.py python 
from webfluid import Fluid
from webfluid.core.config import register_config
from fastapi.responses import HTMLResponse


@register_config(10)
class MyConfig:
    SESSION_COOKIE_SECURE = True

fluid = Fluid(__name__)


@fluid.get("/", response_class=HTMLResponse)
async def home():
    return await fluid.render(
        "index.html",
        title="Hello World!",
        name="my friend"
    )


@fluid.get("/health")
async def health():
    return {"status": "ok"}


if __name__ == "__main__":
    fluid.mix()

What just happened

There are two major details we need to take a look at:

  • We've registered the config before the app will get initialized. This is important because the decorator function must be executed before the app gets initialized. Otherwise, your config will never be parsed.
  • There is a number passed as a parameter to the decorator. This is the priority of the config. If you have multiple configs registered, the one with the highest priority will overwrite the others. Default (if noting is passed) is 1. Possible values are 1 to 10. So 10 is the highest possible priority.

The second way to register your config

Now you may not want to ensure manually that the config registration decorator is executed before initializing your app. Thankfully, there's some magic happening behind the scenes. Because if you just create a config.py file inside the fluid directory, you can outsource the registration of your to the initialization process.

Every key is always there

There is one detail worth internalising before we look at the values themselves. DefaultConfig is the single source of truth for every framework default: your registered classes are merged on top of it, so by the time your app is initialized fluid.config carries every key the framework knows about.

That means you can reach for fluid.config["SESSION_COOKIE_SECURE"] directly instead of fluid.config.get("SESSION_COOKIE_SECURE", not debug) — and you should, because repeating a default inline is exactly how two of them quietly drifted apart during the alpha. Only keys you invent (like the MYEXT_* ones we will add in the next chapter) need a get with a fallback.

Important config values

When configuring your app, there are some important settings you need to know:

  • APP_CONFIG — A dictionary that stores the FastAPI initialization parameters as keyword arguments. Default (if not defined in a config class) is { "title": "WebFluid Application", "version": "1.0.0" }.
  • APP_FRONTEND — The Frontend configuration dictionary of your main app. More about that in the "Frontend" chapter.
  • BASE_URL — The public base url of your app. Default "http://localhost:8000".
  • SESSION_COOKIE_* — There are three SessionMiddleware configuration values: NAME, SAMESITE and SECURE. Default values are "session", "lax" and not debug. That means session cookies are marked secure whenever you are not running in debug mode.
  • PROXY_FIX — If set to true, your app gets a ProxyHeadersMiddleware so client ips survive a reverse proxy. PROXY_TRUSTED_HOSTS decides which peers are allowed to set those headers; default "127.0.0.1".
  • STATIC_MAX_AGE — The Cache-Control lifetime for served static files, in seconds. Default 31536000 (a year), and 0 in debug mode so your assets never go stale while you work on them.
  • GLOBAL_THEME — The theme used when a visitor has not picked one. Default is the framework's own theme. More about that in the "Frontend" chapter.
  • RATELIMIT_* — Three values for setting up ratelimiting: ENABLED, STORAGE_URI and DEFAULT. WebFluid uses slowapi for ratelimiting. Default values are True, f"{os.getenv('REDIS_URI', 'redis://localhost:6379')}/1" and ["500/day", "100/hour"].
  • Further configuration values are used by the framework extensions to load their settings. More about them and their defaults in the next chapter.
 

One caveat on rate limiting: RATELIMIT_DEFAULT does not apply on its own. slowapi only evaluates the application-wide defaults from a middleware the framework does not install, so a route without a fluid.limit decorator is never checked — and a route with one replaces the defaults rather than adding to them. Treat the value as documentation of your intent and put the limit you want on the route.

Continue reading

From here you can continue straight with Fluid Extensions.