守mamori守り

Error kinds

Every resolve failure carries a coarse, provider-independent classification you read with mamori.ErrorKind(err). It exists so diagnostics can tell a misconfiguration from an outage.

Kind values

The typed Kind values, each paired with the sentinel errors.Is matches:

KindWire valueSentinel (errors.Is)Meaning
KindNotFoundnot_foundErrNotFoundMissing key, secret, path, or version. The only kind that drives resolution behavior.
KindPermissionDeniedpermission_deniedErrPermissionDeniedAuthenticated but not authorized (IAM deny, Vault policy, Kubernetes RBAC).
KindUnauthenticatedunauthenticatedErrUnauthenticatedCredentials missing, malformed, or expired; identity not proven.
KindUnavailableunavailableErrUnavailableBackend unreachable or unresponsive (network, DNS, timeout, 5xx, open breaker).
KindRateLimitedrate_limitedErrRateLimitedThrottled or quota-exhausted by the backend.
KindInvalidinvalidErrInvalidRef malformed for the provider, or payload could not be parsed.
KindUnknownunknown(none)An error the provider could not map. A legal outcome, not a failure.

Only not_found changes behavior by default, since it is what triggers a field’s default: or optional handling. The rest are diagnostic. The one opt-in exception is onfail:"default" on a source chain, which explicitly treats a non-not_found error like absence too (see Source chains and precedence).

Reaching the sentinels

errors.Is reaches the sentinels through the error chain, so you can branch on a specific condition:

if errors.Is(err, mamori.ErrPermissionDenied) {
    // the credential is fine, the authorization is not
}

ErrorKind(nil) returns the empty Kind; an error carrying no recognizable sentinel returns KindUnknown. A context.DeadlineExceeded is reported as KindUnavailable (the backend did not respond in time), while a context.Canceled stays KindUnknown (the caller withdrew the request, which says nothing about the backend). KindUnknown and the empty Kind have no sentinel of their own.

SentinelFor(k) is the inverse: it turns a Kind back into its sentinel error, or nil for KindUnknown and the empty Kind. A nil return means “no sentinel corresponds to this kind,” never “the operation succeeded.”

See also