File source

The file source reads mappings from a plain text file on the local filesystem. It is the simplest store to operate, has no external dependencies, and is well suited to deployments where the set of mappings is managed by configuration management or generated by a migration script. The file is loaded into memory at startup and can be reloaded at runtime, so lookups never touch the disk on the hot path.

[mapping]
source = "file"
normalize = "lowercase"

[mapping.file]
path = "/etc/proxy/mappings.tsv"

The only key is path, the location of the mapping file.

File format

Each line maps one identifier to one destination, separated by whitespace (a tab or spaces). Blank lines and lines beginning with # are ignored, so the file can be commented. The destination on each line must be the name of a declared destination; a line referencing an unknown destination causes the proxy to refuse to start, which catches typos before they can affect routing.

# identifier            destination
[email protected]    legacy
[email protected]       stalwart
[email protected]        stalwart

Identifiers are stored after the configured normalization is applied, so with normalize = "lowercase" the keys are lowercased as the file is read; the identifiers written in the file should match the normalization in use.

Runtime updates

The file source is writable, which means the management API can add and remove mappings as well as read them. When a mapping is changed through the API, the proxy rewrites the file atomically by writing to a temporary file and renaming it into place, so the file on disk always remains a complete and consistent snapshot. Entries are written sorted, one per line, separated by a tab.

The file can also be edited directly and then reloaded without restarting the proxy, by issuing a POST /mappings/reload request to the management API. A reload re-reads the file from disk and validates every destination, replacing the in-memory table only if the new file is valid; a file with an unknown destination is rejected and the previous table is kept. This makes bulk updates safe: a migration tool can regenerate the file and trigger a reload, and a malformed regeneration will not take the proxy out of service. Note that a reload replaces the table wholesale, so the cache may still hold previously resolved entries until they expire or are invalidated.