//! Ambient Authority

//!

//! Capability-oriented library APIs should re-export the [`ambient_authority`]

//! function and [`AmbientAuthority`] type in their own API, and include this

//! type as an argument to any function which utilizes ambient authority.

//!

//! For example:

//!

//! ```rust

//! // Re-export the `AmbientAuthority` type.

//! pub use ambient_authority::{ambient_authority, AmbientAuthority};

//!

//! // Declare functions that use ambient authority with an `AmbientAuthority`

//! // argument.

//! pub fn do_a_thing(_: AmbientAuthority) {

//!     println!("hello world");

//! }

//! ```

//!

//! To use an API that uses [`AmbientAuthority`], call [`ambient_authority`]

//! and pass the result:

//!

//! ```rust,ignore

//! use ambient_authority::ambient_authority;

//!

//! do_a_thing(ambient_authority());

//! ```

#![deny(missing_docs)]

#![deny(clippy::disallowed_method)]

#![forbid(unsafe_code)]

#![no_std]

/// Instances of this `AmbientAuthority` type serve to indicate that the

/// [`ambient_authority`] function has been called, indicating that the user

/// has explicitly opted into using ambient authority.

#[derive(Copy, Clone)]

pub struct AmbientAuthority(());

/// Return an `AmbientAuthority` value, which allows use of functions that

/// include an `AmbientAuthority` argument.

#[inline]

#[must_use]

#[allow(clippy::missing_const_for_fn)]

pub fn ambient_authority() -> AmbientAuthority {

    AmbientAuthority(())

}

/// Internal implementation detail for macros.

///

/// For users concerned about resource names such as file names or network

/// addresses being influenced by untrusted code, file names in static string

/// literals and network addresses in integer literals are ok. This function

/// is similar to `ambient_authority` but is meant to be used in macros that

/// verify that the resource identifiers are known at compile time. Users of

/// the `disallowed_method` clippy lint can opt to allow or disallow this

/// function separately from the general `ambient_authority` function.

#[inline]

#[must_use]

#[doc(hidden)]

pub const fn ambient_authority_known_at_compile_time() -> AmbientAuthority {

    AmbientAuthority(())

}