ambient_authority/lib.rs
1//! Ambient Authority
2//!
3//! Capability-oriented library APIs should re-export the [`ambient_authority`]
4//! function and [`AmbientAuthority`] type in their own API, and include this
5//! type as an argument to any function which utilizes ambient authority.
6//!
7//! For example:
8//!
9//! ```rust
10//! // Re-export the `AmbientAuthority` type.
11//! pub use ambient_authority::{ambient_authority, AmbientAuthority};
12//!
13//! // Declare functions that use ambient authority with an `AmbientAuthority`
14//! // argument.
15//! pub fn do_a_thing(_: AmbientAuthority) {
16//! println!("hello world");
17//! }
18//! ```
19//!
20//! To use an API that uses [`AmbientAuthority`], call [`ambient_authority`]
21//! and pass the result:
22//!
23//! ```rust,ignore
24//! use ambient_authority::ambient_authority;
25//!
26//! do_a_thing(ambient_authority());
27//! ```
28
29#![deny(missing_docs)]
30#![deny(clippy::disallowed_method)]
31#![forbid(unsafe_code)]
32#![no_std]
33
34/// Instances of this `AmbientAuthority` type serve to indicate that the
35/// [`ambient_authority`] function has been called, indicating that the user
36/// has explicitly opted into using ambient authority.
37#[derive(Copy, Clone)]
38pub struct AmbientAuthority(());
39
40/// Return an `AmbientAuthority` value, which allows use of functions that
41/// include an `AmbientAuthority` argument.
42#[inline]
43#[must_use]
44#[allow(clippy::missing_const_for_fn)]
45pub fn ambient_authority() -> AmbientAuthority {
46 AmbientAuthority(())
47}
48
49/// Internal implementation detail for macros.
50///
51/// For users concerned about resource names such as file names or network
52/// addresses being influenced by untrusted code, file names in static string
53/// literals and network addresses in integer literals are ok. This function
54/// is similar to `ambient_authority` but is meant to be used in macros that
55/// verify that the resource identifiers are known at compile time. Users of
56/// the `disallowed_method` clippy lint can opt to allow or disallow this
57/// function separately from the general `ambient_authority` function.
58#[inline]
59#[must_use]
60#[doc(hidden)]
61pub const fn ambient_authority_known_at_compile_time() -> AmbientAuthority {
62 AmbientAuthority(())
63}