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. Nothing here writes; an override is only ever read.

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 cannot change without a deploy; reset_cache/0 exists for tests and dev reloads.

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.