Struct CapabilityProfile 

#[non_exhaustive]
pub struct CapabilityProfile {
    pub oa: AlwaysOn,
    pub metadata: MetadataAccess,
    pub tdm_elsevier: Option<TdmGrant>,
    pub tdm_aps: Option<TdmGrant>,
    pub tdm_springer: Option<TdmGrant>,
    pub rate_limits: RateLimits,
}

Runtime gate for which sources may be invoked. See docs/CAPABILITY.md.

Marked #[non_exhaustive] so adding new capability classes is non-breaking. Pattern-match only against the documented variants and use a wildcard arm.

Construction: external callers use CapabilityProfile::from_env(). Struct-literal construction is blocked outside this crate by #[non_exhaustive]; this is intentional — the type’s safety guarantees rely on the resolution rules in from_env. Default is not yet implemented; Phase 1 will add it once the field set stabilizes.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

oa: AlwaysOn

Tier 1 OA sources are always permitted.

metadata: MetadataAccess

Tier 2 metadata access (Phase 4+).

tdm_elsevier: Option<TdmGrant>

Tier 3 grants are populated only when both env var and feature compile-in are set.

tdm_aps: Option<TdmGrant>

Tier 3 grants are populated only when both env var and feature compile-in are set.

tdm_springer: Option<TdmGrant>

Tier 3 grants are populated only when both env var and feature compile-in are set.

rate_limits: RateLimits

Hard-coded rate limits for this process.

Implementations

impl CapabilityProfile

pub fn from_env() -> Result<Self, CapabilityError>

Read the runtime profile from environment variables.

Implements the resolution algorithm specified in docs/CAPABILITY.md §2.

Tier 1 (Open Access)

Always permitted; not gated on any env var or feature.

Tier 2 (metadata)

Each metadata source becomes available when its env var is set (presence-checked, value ignored) and the metadata Cargo feature was compiled in. If the env var is set but the feature is not compiled in, a tracing::warn! is emitted and the source is left disabled — this is not an error so that users can move binaries between machines (or switch feature sets between cargo invocations) without breaking startup. See docs/CAPABILITY.md §3 for the env var list.

Tier 3 (TDM)

For each publisher in {ELSEVIER, APS, SPRINGER}, the DOIGET_AGREE_TDM_<X> agreement env var is paired with DOIGET_KEY_<X>. Resolution rules (per docs/CAPABILITY.md §2):

• both unset → tdm_<x> = None (no error);
• agree == "1" and key set → Some(TdmGrant { .. }) (subject to the feature gate below);
• agree == "1" and key unset → CapabilityError::AgreedButNoKey;
• key set but agree unset (or agree != "1") → CapabilityError::KeyButNotAgreed.

When both env vars are set correctly but the corresponding tdm-<x> Cargo feature is not compiled in, this function emits a tracing::warn! and sets the grant to None rather than returning an error — same rationale as for the Tier 2 warn-and-skip behavior.

Precondition: tracing subscriber must be installed first

Warn breadcrumbs are delivered via tracing::warn!. Callers MUST install a tracing-subscriber (or equivalent) before invoking this function, otherwise warnings are silently dropped. The doiget-cli binary does this in main.rs.

Errors

Returns CapabilityError::AgreedButNoKey or CapabilityError::KeyButNotAgreed when the TDM env-var pair for any publisher is misconfigured. See the variant docs for the precise trigger conditions.

Note on api_key storage

When a tdm-* feature is compiled in, TdmGrant carries the validated key as secrecy::SecretString (issue #153). The key is read exactly once here, at startup; TDM sources consume it from the grant and never re-read the env var at fetch time. This makes the grant a true startup attestation — an env mutation between startup and fetch can no longer silently change the credential in flight. See the TdmGrant doc-comment and docs/CAPABILITY.md §1/§2.

Trait Implementations

impl Clone for CapabilityProfile

fn clone(&self) -> CapabilityProfile

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CapabilityProfile

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.