Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

22.4 KB
Raw Blame
// Re-export paste and serde so users don't need to depend on them directly
pub use paste;
pub use serde;
use thiserror::Error;

const APP_SECRETS_JSON_ENV: &str = "APP_SECRETS_JSON";

#[allow(dead_code)]
#[allow(
    clippy::disallowed_methods,
    reason = "macro_env_var is the sanctioned wrapper around std::env::var"
)]
fn read_std_env(s: &'static str) -> Result<String, std::env::VarError> {
    std::env::var(s)
}

fn read_from_app_secrets_json_with<F>(key: &'static str, read_var: F) -> Option<String>
where
    F: Fn(&'static str) -> Result<String, std::env::VarError>,
{
    let secrets_json = read_var(APP_SECRETS_JSON_ENV).ok()?;
    let secrets = serde_json::from_str::<serde_json::Value>(&secrets_json).ok()?;
    let value = secrets.get(key)?;

    match value {
        serde_json::Value::String(value) => Some(value.clone()),
        value => Some(value.to_string()),
    }
}

fn read_env_var_with<F>(s: &'static str, read_var: F) -> Result<String, std::env::VarError>
where
    F: Fn(&'static str) -> Result<String, std::env::VarError>,
{
    match read_from_app_secrets_json_with(s, &read_var) {
        Some(value) => Ok(value),
        None => read_var(s),
    }
}

fn optional_read_env_var_with<F>(
    s: &'static str,
    read_var: F,
) -> Result<Option<String>, std::env::VarError>
where
    F: Fn(&'static str) -> Result<String, std::env::VarError>,
{
    match read_env_var_with(s, read_var) {
        Ok(value) => Ok(Some(value)),
        Err(std::env::VarError::NotPresent) => Ok(None),
        Err(err) => Err(err),
    }
}

fn read_env_with<F>(s: &'static str, read_var: F) -> Result<String, VarNameErr>
where
    F: Fn(&'static str) -> Result<String, std::env::VarError>,
{
    read_env_var_with(s, read_var).map_err(|err| VarNameErr { var_name: s, err })
}

fn maybe_read_env_with<F>(s: &'static str, read_var: F) -> Option<String>
where
    F: Fn(&'static str) -> Result<String, std::env::VarError>,
{
    optional_read_env_var_with(s, read_var).ok().flatten()
}

#[cfg(test)]
mod tests;

#[cfg(test)]
mod testing_harness {
    use super::{
        VarNameErr, maybe_read_env_with, optional_read_env_var_with, read_env_var_with,
        read_env_with,
    };
    use std::cell::Cell;

    type MockValue = Cell<Option<Box<dyn Fn(&'static str) -> Result<String, std::env::VarError>>>>;
    thread_local! {
        static MOCK_VAR_GETTER: MockValue = const { Cell::new(None) };
    }

    struct MockEnvGuard;

    impl Drop for MockEnvGuard {
        fn drop(&mut self) {
            MOCK_VAR_GETTER.replace(None);
        }
    }

    #[allow(
        clippy::disallowed_methods,
        reason = "test harness falls back to the same sanctioned std::env::var wrapper behavior"
    )]
    fn get_env(s: &'static str) -> Result<String, std::env::VarError> {
        let cur_getter = MOCK_VAR_GETTER.replace(None);
        match cur_getter {
            Some(mock) => {
                let out = mock(s);
                MOCK_VAR_GETTER.replace(Some(mock));
                out
            }
            None => std::env::var(s),
        }
    }

    pub(crate) fn read_env(s: &'static str) -> Result<String, VarNameErr> {
        read_env_with(s, get_env)
    }

    pub(crate) fn maybe_read_env(s: &'static str) -> Option<String> {
        maybe_read_env_with(s, get_env)
    }

    pub(crate) fn read_env_var(s: &'static str) -> Result<String, std::env::VarError> {
        read_env_var_with(s, get_env)
    }

    pub(crate) fn optional_read_env_var(
        s: &'static str,
    ) -> Result<Option<String>, std::env::VarError> {
        optional_read_env_var_with(s, get_env)
    }

    pub(crate) fn with_mock_env<F, Cb, U>(f: F, cb: Cb) -> U
    where
        F: Fn(&'static str) -> Result<String, std::env::VarError> + 'static,
        Cb: FnOnce() -> U,
    {
        MOCK_VAR_GETTER.replace(Some(Box::new(f)));
        let _guard = MockEnvGuard;
        cb()
    }
}

#[cfg(test)]
pub(crate) use testing_harness::maybe_read_env;
#[cfg(test)]
pub(crate) use testing_harness::optional_read_env_var;
#[cfg(test)]
pub(crate) use testing_harness::read_env;
#[cfg(test)]
pub(crate) use testing_harness::read_env_var;

#[cfg(not(test))]
pub fn read_env(s: &'static str) -> Result<String, VarNameErr> {
    read_env_with(s, read_std_env)
}

/// Read an environment variable from `APP_SECRETS_JSON` or the process environment.
///
/// This uses the same lookup order as generated [`env_var!`] types, but returns the raw
/// [`std::env::VarError`] so callers can map errors into their own error types.
#[cfg(not(test))]
pub fn read_env_var(s: &'static str) -> Result<String, std::env::VarError> {
    read_env_var_with(s, read_std_env)
}

/// Read an optional environment variable from `APP_SECRETS_JSON` or the process environment.
///
/// Missing variables return `Ok(None)`. Values present in `APP_SECRETS_JSON` take precedence over
/// process environment variables. Non-Unicode process environment values are returned as errors.
#[cfg(not(test))]
pub fn optional_read_env_var(s: &'static str) -> Result<Option<String>, std::env::VarError> {
    optional_read_env_var_with(s, read_std_env)
}

#[cfg(not(test))]
#[doc(hidden)]
pub fn maybe_read_env(s: &'static str) -> Option<String> {
    maybe_read_env_with(s, read_std_env)
}

/// The type of error that is produced by this crate
#[derive(Debug, Error)]
#[error("An error occurred while reading envvar: {var_name}. Err: {err}")]
pub struct VarNameErr {
    var_name: &'static str,
    err: std::env::VarError,
}

#[macro_export]
macro_rules! env_var {
    (
        $(#[$attr:meta])*
        $v:vis struct $n:ident;
    ) => {
        $crate::paste::paste! {
            #[doc = "struct which represents the existence of the `" $n:snake:upper "` environment variable.
            this can be used as a sentinel value to guarantee the existence of the variable.
            See [`" $n "`::new] and [`" $n "`::unwrap_new] for usage methods"]
            $(#[$attr])*
            $v enum $n {
                #[doc = "This environment var is allocated and read at runtime"]
                Runtime(std::sync::Arc<str>),
                #[doc = "This environment var was present at compile time. It may or may not currently exist at runtime."]
                Comptime(&'static str)
            }

            impl $n {
                #[doc = "Attempt to create a new instance of [Self] by reading `" $n:snake:upper "` from the environment variables.
                     If this value does not exist this returns a [std::env::VarError]"]
                #[allow(dead_code)]
                #[tracing::instrument(err, level = tracing::Level::TRACE)]
                $v fn new() -> Result<Self, $crate::VarNameErr> {
                    let res = $crate::read_env($crate::paste::paste! { stringify!([<$n:snake:upper>]) })?;
                    Ok(Self::Runtime(std::sync::Arc::from(res)))
                }

                #[doc = "This calls [Self::new] put panics if the result is an error"]
                #[allow(dead_code)]
                $v fn unwrap_new() -> Self {
                    $crate::paste::paste! {
                        Self::new().expect(concat!("Failed to find the ", stringify!([<$n:snake:upper>]), " variable in environment"))
                    }
                }


                #[doc = "Function used for testing purposes. Allows the caller to create a new Self via a static str"]
                #[cfg(test)]
                #[allow(dead_code)]
                $v const fn new_testing(s: &'static str) -> Self {
                    Self::Comptime(s)
                }

                #[allow(dead_code)]
                #[doc = "Get a reference to the internal [std::sync::Arc] if this is a runtime allocated env var"]
                $v fn runtime_inner(&self) -> Option<&std::sync::Arc<str>> {
                    match self {
                        Self::Runtime(i) => Some(i),
                        Self::Comptime(_) => None
                    }
                }

                #[allow(dead_code)]
                #[doc = "Get a reference to the static string slice that was present at compile time"]
                $v fn comptime_inner(&self) -> Option<&'static str> {
                    match self {
                        Self::Comptime(i) => Some(i),
                        Self::Runtime(_) => None
                    }
                }

                #[allow(dead_code)]
                #[doc = "Returns an Arc<str> of the contained value"]
                $v fn as_arc(&self) -> std::sync::Arc<str> {
                    match self {
                        Self::Comptime(i) => std::sync::Arc::from(*i),
                        Self::Runtime(i) => i.clone()
                    }
                }
            }

            impl std::ops::Deref for $n {
                type Target = str;

                fn deref(&self) -> &Self::Target {
                    match self {
                        Self::Runtime(i) => &*i,
                        Self::Comptime(i) => i
                    }
                }
            }

            impl std::convert::AsRef<str> for $n {
                fn as_ref(&self) -> &str {
                    match self {
                        Self::Runtime(i) => &*i,
                        Self::Comptime(i) => i
                    }
                }
            }

            impl<'de> $crate::serde::Deserialize<'de> for $n {
                fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
                where
                    D: $crate::serde::Deserializer<'de>,
                {
                    let value = <String as $crate::serde::Deserialize>::deserialize(deserializer)?;
                    Ok(Self::Runtime(std::sync::Arc::from(value)))
                }
            }
        }
    };
    (
        $(#[$attr:meta])*
        $v:vis struct $n:ident {
            $(
                $(#[$field_attr:meta])*
                $field_vis:vis $field_name:ident
            ),* $(,)?
        }
    ) => {
        $crate::paste::paste! {
            $(
                $crate::env_var!(
                    $(#[$field_attr])*
                    $field_vis struct $field_name;
                );
            )*

            $(#[$attr])*
            pub struct $n {
                $(
                    pub [<$field_name:snake>]: $field_name,
                )*
            }

            impl $n {
                #[doc = "Create a new instance of self with all the internal env vals retrieved. Returns an error if one of the values cannot be found"]
                #[allow(dead_code)]
                $v fn new() -> Result<Self, $crate::VarNameErr> {
                    Ok(Self {
                        $(
                            [<$field_name:snake>]: $field_name::new()?,
                        )*
                    })
                }


                #[doc = "Create a new instance of self with all the internal env vals retrieved. Panics if any of the values cannot be found"]
                #[allow(dead_code)]
                $v fn unwrap_new() -> Self {
                    Self {
                        $(
                            [<$field_name:snake>]: $field_name::unwrap_new(),
                        )*
                    }
                }
            }
        }
    };
}

/// A macro for defining multiple environment variable structs in a single invocation.
///
/// Each definition expands exactly as if it were passed to [`env_var!`] on its own.
///
/// # Example
///
/// ```
/// use macro_env_var::env_vars;
///
/// env_vars! {
///     pub struct BaseUrl;
///     pub struct DatabaseUrl;
///     #[derive(Debug, Clone)]
///     pub struct RedisUri;
/// }
///
/// let _url: Result<BaseUrl, _> = BaseUrl::new();
/// ```
#[macro_export]
macro_rules! env_vars {
    (
        $(
            $(#[$attr:meta])*
            $v:vis struct $n:ident;
        )*
    ) => {
        $(
            $crate::env_var! {
                $(#[$attr])*
                $v struct $n;
            }
        )*
    };
}

/// A macro for defining multiple optional environment variable structs in a single invocation.
///
/// Each definition expands exactly as if it were passed to [`maybe_env_var!`] on its own.
///
/// # Example
///
/// ```
/// use macro_env_var::maybe_env_vars;
///
/// maybe_env_vars! {
///     pub struct OptionalApiKey;
///     pub struct OptionalFeatureFlag;
/// }
///
/// let _key: Option<OptionalApiKey> = OptionalApiKey::new();
/// ```
#[macro_export]
macro_rules! maybe_env_vars {
    (
        $(
            $(#[$attr:meta])*
            $v:vis struct $n:ident;
        )*
    ) => {
        $(
            $crate::maybe_env_var! {
                $(#[$attr])*
                $v struct $n;
            }
        )*
    };
}

/// A macro for defining optional environment variables that return `Option` instead of `Result`.
///
/// Use this when an environment variable is optional and its absence is expected behavior,
/// not an error condition.
///
/// # Example
///
/// ```
/// use macro_env_var::maybe_env_var;
///
/// maybe_env_var! {
///     pub struct OptionalApiKey;
/// }
///
/// // Returns None if OPTIONAL_API_KEY is not set
/// let _key: Option<OptionalApiKey> = OptionalApiKey::new();
/// ```
///
/// # Deserialization
///
/// When deserialized (for example as a field of a `macro_config::MacroConfig` struct), a missing
/// or `null` value produces the `Unset` variant instead of an error, so the generated type can be
/// used directly as a config field without wrapping it in `Option`. Use `value()` to read it:
///
/// ```
/// use macro_env_var::maybe_env_var;
///
/// maybe_env_var! {
///     pub struct OptionalToken;
/// }
///
/// let set: OptionalToken = serde_json::from_str(r#""abc""#).unwrap();
/// let unset: OptionalToken = serde_json::from_str("null").unwrap();
/// assert_eq!(set.value(), Some("abc"));
/// assert_eq!(unset.value(), None);
/// ```
#[macro_export]
macro_rules! maybe_env_var {
    (
        $(#[$attr:meta])*
        $v:vis struct $n:ident;
    ) => {
        $crate::paste::paste! {
            #[doc = "struct which represents the optional `" $n:snake:upper "` environment variable.
            This returns `Option<Self>` when the variable may or may not be present.
            When deserialized (e.g. by `macro_config`), a missing variable produces [`" $n "`::Unset]
            instead of an error, so this type can be used as a bare config field without wrapping it
            in `Option`. Use [`" $n "`::value] to access the value.
            See [`" $n "`::new] for usage methods"]
            $(#[$attr])*
            $v enum $n {
                #[doc = "This environment var is allocated and read at runtime"]
                Runtime(std::sync::Arc<str>),
                #[doc = "This environment var was present at compile time. It may or may not currently exist at runtime."]
                Comptime(&'static str),
                #[doc = "This environment var was not set. Produced by deserialization when the variable is absent or `null`."]
                Unset
            }

            impl $n {
                #[doc = "Attempt to create a new instance of [Self] by reading `" $n:snake:upper "` from the environment variables.
                     Returns `None` if the variable is not set."]
                #[allow(dead_code)]
                $v fn new() -> Option<Self> {
                    let res = $crate::maybe_read_env($crate::paste::paste! { stringify!([<$n:snake:upper>]) })?;
                    Some(Self::Runtime(std::sync::Arc::from(res)))
                }

                #[doc = "Function used for testing purposes. Allows the caller to create a new Self via a static str"]
                #[cfg(test)]
                #[allow(dead_code)]
                $v const fn new_testing(s: &'static str) -> Self {
                    Self::Comptime(s)
                }

                #[doc = "Create an instance representing an unset `" $n:snake:upper "` variable"]
                #[allow(dead_code)]
                $v const fn new_unset() -> Self {
                    Self::Unset
                }

                #[doc = "Get the value as a string slice, or `None` if the variable was not set"]
                #[allow(dead_code)]
                $v fn value(&self) -> Option<&str> {
                    match self {
                        Self::Runtime(i) => Some(i),
                        Self::Comptime(i) => Some(i),
                        Self::Unset => None
                    }
                }

                #[doc = "Whether the variable was set"]
                #[allow(dead_code)]
                $v fn is_set(&self) -> bool {
                    !matches!(self, Self::Unset)
                }

                #[allow(dead_code)]
                #[doc = "Get a reference to the internal [std::sync::Arc] if this is a runtime allocated env var"]
                $v fn runtime_inner(&self) -> Option<&std::sync::Arc<str>> {
                    match self {
                        Self::Runtime(i) => Some(i),
                        Self::Comptime(_) | Self::Unset => None
                    }
                }

                #[allow(dead_code)]
                #[doc = "Get a reference to the static string slice that was present at compile time"]
                $v fn comptime_inner(&self) -> Option<&'static str> {
                    match self {
                        Self::Comptime(i) => Some(i),
                        Self::Runtime(_) | Self::Unset => None
                    }
                }

                #[allow(dead_code)]
                #[doc = "Returns an Arc<str> of the contained value, or `None` if the variable was not set"]
                $v fn as_arc(&self) -> Option<std::sync::Arc<str>> {
                    match self {
                        Self::Comptime(i) => Some(std::sync::Arc::from(*i)),
                        Self::Runtime(i) => Some(i.clone()),
                        Self::Unset => None
                    }
                }
            }

            #[doc = "Panics when the variable is [`" $n "`::Unset]; use [`" $n "`::value] when the
            value may be unset (e.g. when loaded through `macro_config`)."]
            impl std::ops::Deref for $n {
                type Target = str;

                fn deref(&self) -> &Self::Target {
                    match self {
                        Self::Runtime(i) => &*i,
                        Self::Comptime(i) => i,
                        Self::Unset => panic!(concat!(
                            "dereferenced unset env var `",
                            stringify!([<$n:snake:upper>]),
                            "`; use `.value()` to handle the unset case"
                        ))
                    }
                }
            }

            #[doc = "Panics when the variable is [`" $n "`::Unset]; use [`" $n "`::value] when the
            value may be unset (e.g. when loaded through `macro_config`)."]
            impl std::convert::AsRef<str> for $n {
                fn as_ref(&self) -> &str {
                    match self {
                        Self::Runtime(i) => &*i,
                        Self::Comptime(i) => i,
                        Self::Unset => panic!(concat!(
                            "read unset env var `",
                            stringify!([<$n:snake:upper>]),
                            "` as a str; use `.value()` to handle the unset case"
                        ))
                    }
                }
            }

            impl<'de> $crate::serde::Deserialize<'de> for $n {
                fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
                where
                    D: $crate::serde::Deserializer<'de>,
                {
                    struct __MaybeEnvVarVisitor;

                    impl<'de> $crate::serde::de::Visitor<'de> for __MaybeEnvVarVisitor {
                        type Value = $n;

                        fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                            formatter.write_str("an optional string")
                        }

                        fn visit_none<E>(self) -> Result<Self::Value, E>
                        where
                            E: $crate::serde::de::Error,
                        {
                            Ok($n::Unset)
                        }

                        fn visit_unit<E>(self) -> Result<Self::Value, E>
                        where
                            E: $crate::serde::de::Error,
                        {
                            Ok($n::Unset)
                        }

                        fn visit_some<D>(self, deserializer: D) -> Result<Self::Value, D::Error>
                        where
                            D: $crate::serde::Deserializer<'de>,
                        {
                            let value = <String as $crate::serde::Deserialize>::deserialize(deserializer)?;
                            Ok($n::Runtime(std::sync::Arc::from(value)))
                        }

                        fn visit_str<E>(self, value: &str) -> Result<Self::Value, E>
                        where
                            E: $crate::serde::de::Error,
                        {
                            Ok($n::Runtime(std::sync::Arc::from(value)))
                        }

                        fn visit_string<E>(self, value: String) -> Result<Self::Value, E>
                        where
                            E: $crate::serde::de::Error,
                        {
                            Ok($n::Runtime(std::sync::Arc::from(value)))
                        }
                    }

                    deserializer.deserialize_option(__MaybeEnvVarVisitor)
                }
            }
        }
    };
    (
        $(#[$attr:meta])*
        $v:vis struct $n:ident {
            $(
                $(#[$field_attr:meta])*
                $field_vis:vis $field_name:ident
            ),* $(,)?
        }
    ) => {
        $crate::paste::paste! {
            $(
                $crate::maybe_env_var!(
                    $(#[$field_attr])*
                    $field_vis struct $field_name;
                );
            )*

            $(#[$attr])*
            pub struct $n {
                $(
                    pub [<$field_name:snake>]: Option<$field_name>,
                )*
            }

            impl $n {
                #[doc = "Create a new instance of self with all the internal env vals retrieved. Each field is `Option<T>` since values may not be set."]
                #[allow(dead_code)]
                $v fn new() -> Self {
                    Self {
                        $(
                            [<$field_name:snake>]: $field_name::new(),
                        )*
                    }
                }
            }
        }
    };
}