Documentation
¶
Overview ¶
Package providerns answers one question for every configuration validator in the framework: does this key belong to the private subtree of a REGISTERED provider, rather than to app.Config's schema?
It exists because that question was answered twice, differently. The builder path exempted `storage.<provider>.*` for a registered provider; app.LoadConfig — the path every CLI command takes — did not, so a Ceph deployment that booted fine had `nucleus check`, `doctor` and `config print` all reporting an unknown key against the file the server was running on. That is the "same file, two verdicts" class, and the fix is not to teach the second validator the same rule but to leave exactly one place where the rule lives.
The exemption is per REGISTERED name and never for the namespace: a misspelling under `storage.` or `auth.` is still an unknown key. A namespace-wide exemption would turn these into the one place in the configuration where any typo passes unseen.
Index ¶
- func Capture(k *koanf.Koanf, ns, name string) map[string]any
- func CaptureAll(k *koanf.Koanf, ns string, names []string) map[string]map[string]any
- func CaptureStorage(k *koanf.Koanf, provider string) map[string]any
- func IsProviderKey(key string, d Declared) bool
- func Namespaces() map[string][]string
- func NamespacesWith(d Declared) map[string][]string
- func OrphanAuthSubtreeError(orphans []string) error
- func OrphanAuthSubtrees(k *koanf.Koanf, chain []string) []string
- func StripKeys(keys []string, d Declared) []string
- type Declared
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Capture ¶
Capture cuts `<ns>.<name>.*` out of a merged koanf so it can be handed to the provider that owns it. The framework never interprets the contents; the provider binds them into its own typed struct.
koanf appears here and not in any exported signature on purpose: a third-party provider must not inherit a dependency on the framework's configuration decoder (ADR-015).
func CaptureAll ¶
CaptureAll captures the subtree of every name in names, skipping the ones that turn out to be empty.
func CaptureStorage ¶
CaptureStorage captures a storage provider's subtree, skipping the built-ins.
The built-ins bind through their own typed fields (storage.s3.*, storage.local.*), so there is nothing to capture for them — and capturing anyway would hand a provider a subtree the schema already owns. The list lives here and not at either call site because both configuration paths need the same answer.
func IsProviderKey ¶
IsProviderKey reports whether key sits under `<namespace>.<registered name>.` for one of the namespaces above.
A key with only two segments (`storage.ceph`) is NOT a provider key: the subtree is what a provider owns, and the bare name is either a schema field or a typo.
func Namespaces ¶
Namespaces returns every config namespace that can hold a registered provider's own subtree, mapped to the names currently registered in it.
This is the single table both validators read. A registry whose providers can declare open-ended configuration belongs here; one whose factory takes a typed struct the framework owns (mail, the session store) does not, because there is no subtree to exempt.
func NamespacesWith ¶
NamespacesWith is Namespaces for a caller that has read the file and therefore knows which federated instances were declared.
func OrphanAuthSubtreeError ¶
OrphanAuthSubtreeError renders the orphans as the error both configuration paths return, so the same file cannot get two verdicts.
func OrphanAuthSubtrees ¶
OrphanAuthSubtrees returns the `auth.<name>.*` sections that belong to a registered backend which the chain does not name.
The unknown-key guard cannot see these: the name IS registered, so the section is legitimately exempt — and then nothing reads it, because the chain is its only consumer. An operator who configures a directory and forgets the `auth_backends` entry gets a clean boot, a green `check`, and a login page that never consults the directory. That is the "exit 0 without the effect" class, and it is worth an error rather than a warning: there is no reading of this configuration under which it does something.
Storage deliberately gets no equivalent. `storage.s3.*` while `storage.provider` is `local` is a stanza kept for another environment, and the schema has always allowed it; a third-party section is the same thing and must not be treated more harshly than the built-in one.
Types ¶
type Declared ¶
type Declared struct {
// FederatedAuth are the instance names declared in auth_federated.
FederatedAuth []string
}
Declared carries the parts of the rule that come from the CONFIGURATION rather than from a registry.
A credential backend is exempted by its REGISTERED name, because the name an operator writes is the name the package registered. A federated identity provider is not: its registry is keyed by protocol ("oidc") while the subtree is keyed by the INSTANCE the operator named ("corp"), so the only place that knows "corp" is legitimate is the declaration in auth_federated. Passing it here rather than teaching each validator keeps the rule in one place, which is the entire reason this package exists — the exemption already lived in two validators once, and only one of them had it.
Source Files