Locates a host application's override file for one part of one template.

A host customizes a message by dropping a file into its own repo, where it is version-controlled and reviewable, instead of editing a database row through an admin UI. Rendering only ever reads an override; write/5, delete/4, delete_template/2, copy_template/3 and list/1 exist for a host that edits its own files from a screen of its own — see "Writing" below.

Layout

name is a DIRECTORY, never a filename. Files inside it are named for the part they supply, optionally carrying a locale:

<root>/<name>/<part>.<locale>.<ext>       text.en-GB.txt
<root>/<name>/<part>.<ext>                text.txt

Worked:

priv/phoenix_kit_templates/     <- <root>
└── new_login_alert/            <- <name>
    ├── subject.txt
    ├── subject.de.txt
    └── text.txt

subject, text and layout are .txt; html is .html; markdown is .md. A root is typically Application.app_dir(:my_app, "priv/phoenix_kit_templates"), but this module takes roots as an argument and reads no configuration of its own — it must not know which application is using it.

layout is the one part with no locale: it names a layout group, which is chosen per message rather than per language, so only layout.txt is ever read and layout.<locale>.txt is ignored.

Lookup runs most- to least-specific and stops at the first file that exists:

text.en-GB.txt   →   text.en.txt   →   text.txt

so a host that only cares about one language writes text.txt and is done, while one that translates its overrides gets dialect precision. Roots are tried in order, so an earlier root shadows a later one.

Each part is looked up separately: in the tree above, a German reader gets subject.de.txt and text.txt, and an Italian reader gets subject.txt and text.txt. A part with no file at all resolves to nil, and the caller falls back to its own default.

locate/4 is read/4 that also returns the path of the file it read — {path, content} — for callers that need to say where content came from. read/4 is built on it, so the two always agree.

Reserved names

A name may start with one underscore (_layout). Such names are reserved for shared parts that the caller assembles around a message — the first is core's email layout, _layout. This package knows nothing about layouts and wraps nothing: it finds _layout/html.html (and html.<locale>.html) exactly as it finds any other name. The underscore is meant to keep such a directory from colliding with a template name: by convention ordinary names should not start with one, but this module does not enforce that.

Runtime, not compile time

Overrides live in the host application, which is compiled separately from this package — there is no point in this package's compilation at which they could be read. So they are read at runtime and cached in :persistent_term, including the absence of a file, since a missing override is the common case and would otherwise cost a File.stat on every send. Files change through a deploy, which starts a fresh VM, or through the write functions below, which reset the cache for their own root; reset_cache/0 covers the rest — tests, dev reloads, files edited by hand.

Path safety

name and locale are matched against strict patterns before they are ever joined onto a root. A name is [a-z0-9][a-z0-9_-]* with an optional single leading underscore; dots and slashes never match. They are literals at every current call site, but this module turns a name into a filesystem read, and that is not a boundary to leave to the caller's good behaviour — ../../../etc/passwd resolves to no override rather than to a file.

Writing

write/5, delete/4, delete_template/2, copy_template/3 and list/1 work on one root — the host's own directory, never a package's — and on the same layout. They are plain File calls for a host-side editor; rendering does not use them.

• Same validation as reading, but refusing instead of falling back. The name must match the pattern above; a locale must be nil or a well-formed tag (reading treats a junk locale as nil, which for a write would silently target the locale-less file); layout takes no locale.
• One more part, label (label[.locale].txt): a human-readable caption for an editor's list. Rendering never reads it and parts/0 does not include it.
• The path stays inside the root, symlinks included (Path.safe_relative/2), and the root must already exist.
• Atomic: the content goes to a temporary file in the same directory, is synced, and is renamed over the target, so a concurrent read sees the old file or the new one, never half of one. A replaced file keeps its permission bits. The directory is not synced after the rename: a crash right after a write may lose the rename and keep the old file, but never leaves the new name on an empty file.
• Two narrow races are left to the caller, both surfacing as an error, neither losing data: delete/4 removing a directory its last file left empty while a concurrent write/5 is creating a file in it (that write fails with {:error, :enoent}), and copy_template/3 checking that the target is absent before its final rename (an empty directory created at the target in between is replaced).
• At most max_bytes/0 (256 KiB) of UTF-8 per file.
• The cache is reset for the root (reset_cache([root])) after every change, so the next render sees it. Pass the same root string the renderer gets in :paths — the cache is keyed on it. A first lookup that was already reading the old file when the change landed can still cache what it read, after the reset; that window is one file read long, and the next change or reset_cache/1 for the root clears it.

Every refusal is an {:error, reason}; nothing raises on bad input. write/5 returns the paths it created — the template directory first, when the write is its first part file, then the file — and copy_template/3 the new directory and its files, so a host can, for example, fix their ownership.