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.

24.4 KB
Raw Blame
#![deny(missing_docs)]

//! Macro service URL values with per-environment defaults and environment
//! variable overrides.
//!
//! Use [`service_url!`] to define a newtype whose default value is selected
//! from [`macro_env::Environment`]. The generated type also checks an override
//! environment variable derived from the type name. For example,
//! `DocumentStorageServiceUrl` checks `OVERRIDE_DOCUMENT_STORAGE_SERVICE_URL`
//! before falling back to its `local`, `dev`, or `prod` default.

use std::{borrow::Cow, fmt, ops::Deref};

#[doc(hidden)]
pub use macro_env;
#[doc(hidden)]
pub use paste;
use thiserror::Error;
pub use url::{ParseError as UrlParseError, Url};

#[cfg(test)]
mod test;

#[cfg(test)]
mod testing_harness {
    use super::ServiceUrlVarErr;
    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 ResetMockEnv;

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

    #[doc(hidden)]
    pub fn read_override_env(var_name: &'static str) -> Result<Option<String>, ServiceUrlVarErr> {
        let cur_getter = MOCK_VAR_GETTER.replace(None);
        match cur_getter {
            Some(mock) => {
                let out = mock(var_name);
                MOCK_VAR_GETTER.replace(Some(mock));
                out
            }
            None => std::env::var(var_name),
        }
        .map(Some)
        .or_else(|err| match err {
            std::env::VarError::NotPresent => Ok(None),
            err => Err(ServiceUrlVarErr { var_name, err }),
        })
    }

    pub(crate) fn with_mock_override_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 = ResetMockEnv;
        cb()
    }
}

#[cfg(test)]
#[doc(hidden)]
pub use testing_harness::read_override_env;

/// Read an override environment variable for a service URL.
#[cfg(not(test))]
#[doc(hidden)]
#[allow(
    clippy::disallowed_methods,
    reason = "Used when running locally to override service urls"
)]
pub fn read_override_env(var_name: &'static str) -> Result<Option<String>, ServiceUrlVarErr> {
    std::env::var(var_name).map(Some).or_else(|err| match err {
        std::env::VarError::NotPresent => Ok(None),
        err => Err(ServiceUrlVarErr { var_name, err }),
    })
}

/// A service URL string that can either borrow an existing string slice or own
/// a runtime override value.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ServiceUrl<'a>(Cow<'a, str>);

impl<'a> ServiceUrl<'a> {
    /// Create a service URL that borrows a string slice.
    pub const fn borrowed(url: &'a str) -> Self {
        Self(Cow::Borrowed(url))
    }

    /// Create a service URL that owns a runtime string.
    pub fn owned(url: impl Into<String>) -> ServiceUrl<'static> {
        ServiceUrl(Cow::Owned(url.into()))
    }

    /// Return the URL as a string slice.
    pub fn as_str(&self) -> &str {
        self.0.as_ref()
    }

    /// Parse the URL string into a [`Url`].
    pub fn parse_url(&self) -> Result<Url, UrlParseError> {
        Url::parse(self.as_str())
    }

    /// Return a cheaply copied borrowed view of this URL.
    pub fn copied(&self) -> ServiceUrl<'_> {
        ServiceUrl(Cow::Borrowed(self.as_str()))
    }

    /// Convert this URL into an owned `'static` value.
    pub fn into_owned(self) -> ServiceUrl<'static> {
        ServiceUrl(Cow::Owned(self.0.into_owned()))
    }

    /// Convert this URL into its internal [`Cow`].
    pub fn into_cow(self) -> Cow<'a, str> {
        self.0
    }

    /// Return the borrowed string if this URL is currently borrowed.
    pub fn borrowed_inner(&self) -> Option<&'a str> {
        match &self.0 {
            Cow::Borrowed(url) => Some(*url),
            Cow::Owned(_) => None,
        }
    }

    /// Return the owned string if this URL is currently owned.
    pub fn owned_inner(&self) -> Option<&String> {
        match &self.0 {
            Cow::Borrowed(_) => None,
            Cow::Owned(url) => Some(url),
        }
    }
}

impl<'a> From<&'a str> for ServiceUrl<'a> {
    fn from(value: &'a str) -> Self {
        Self::borrowed(value)
    }
}

impl From<String> for ServiceUrl<'static> {
    fn from(value: String) -> Self {
        Self(Cow::Owned(value))
    }
}

impl<'a> From<Cow<'a, str>> for ServiceUrl<'a> {
    fn from(value: Cow<'a, str>) -> Self {
        Self(value)
    }
}

impl<'a> From<ServiceUrl<'a>> for String {
    fn from(value: ServiceUrl<'a>) -> Self {
        value.0.into_owned()
    }
}

impl<'a> Deref for ServiceUrl<'a> {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        self.as_str()
    }
}

impl<'a> AsRef<str> for ServiceUrl<'a> {
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

impl<'a> fmt::Display for ServiceUrl<'a> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Error returned when a service URL override environment variable cannot be
/// read.
#[derive(Debug, Error)]
#[error("failed to read service URL override env var `{var_name}`: {err}")]
pub struct ServiceUrlVarErr {
    var_name: &'static str,
    #[source]
    err: std::env::VarError,
}

impl ServiceUrlVarErr {
    /// The environment variable name that failed to load.
    pub const fn var_name(&self) -> &'static str {
        self.var_name
    }

    /// The underlying environment-variable error.
    pub const fn env_var_error(&self) -> &std::env::VarError {
        &self.err
    }
}

/// Define typed service URL values with per-environment defaults and override
/// environment variables.
///
/// The override environment variable name is derived from the struct name:
/// `DocumentStorageServiceUrl` checks `OVERRIDE_DOCUMENT_STORAGE_SERVICE_URL`.
/// If that override is not set, [`macro_env::Environment`] selects one of the
/// provided `local`, `dev`, or `prod` defaults.
///
/// # Example
///
/// ```
/// fn document_storage_service_url_example() -> Result<(), macro_service_urls::ServiceUrlVarErr> {
///     macro_service_urls::service_url! {
///         #[derive(Debug, Clone)]
///         pub struct DocumentStorageServiceUrl {
///             local: "http://localhost:8086",
///             dev: "https://dev-gateway.macro.com/dss",
///             prod: "https://gateway.macro.com/dss",
///         }
///     }
///
///     let url = DocumentStorageServiceUrl::new()?;
///     assert_eq!(
///         url.override_env_var_name(),
///         "OVERRIDE_DOCUMENT_STORAGE_SERVICE_URL",
///     );
///
///     Ok(())
/// }
///
/// document_storage_service_url_example().unwrap();
/// ```
#[macro_export]
macro_rules! service_url {
    (
        $(#[$attr:meta])*
        $v:vis struct $n:ident {
            local: $local:literal,
            dev: $dev:literal,
            prod: $prod:literal $(,)?
        }
    ) => {
        $crate::paste::paste! {
            #[doc = "Typed service URL loaded from `OVERRIDE_" $n:snake:upper "` or selected from per-environment defaults."]
            $(#[$attr])*
            $v struct $n($crate::ServiceUrl<'static>);

            impl $n {
                #[doc = "Override environment variable checked before falling back to per-environment defaults."]
                $v const OVERRIDE_ENV_VAR_NAME: &'static str = concat!("OVERRIDE_", stringify!([<$n:snake:upper>]));

                #[doc = "Default URL for [`macro_env::Environment::Local`]."]
                $v const LOCAL: &'static str = $local;

                #[doc = "Default URL for [`macro_env::Environment::Develop`]."]
                $v const DEV: &'static str = $dev;

                #[doc = "Default URL for [`macro_env::Environment::Production`]."]
                $v const PROD: &'static str = $prod;

                #[doc = "Create a new instance of [`Self`], using the override env var if set and otherwise selecting a default from [`macro_env::Environment::new_or_prod`]."]
                #[allow(dead_code)]
                $v fn new() -> Result<Self, $crate::ServiceUrlVarErr> {
                    if let Some(value) = $crate::read_override_env(Self::OVERRIDE_ENV_VAR_NAME)? {
                        return Ok(Self($crate::ServiceUrl::owned(value)));
                    }

                    Ok(Self::default_for_environment($crate::macro_env::Environment::new_or_prod()))
                }

                #[doc = "Create a new instance of [`Self`], panicking if the override env var is set but cannot be read."]
                #[allow(dead_code)]
                $v fn unwrap_new() -> Self {
                    Self::new().expect(concat!("Failed to resolve service URL for ", stringify!($n)))
                }

                #[doc = "Create a new instance of [`Self`] for a specific environment, using the override env var if set."]
                #[allow(dead_code)]
                $v fn new_for_environment(environment: $crate::macro_env::Environment) -> Result<Self, $crate::ServiceUrlVarErr> {
                    if let Some(value) = $crate::read_override_env(Self::OVERRIDE_ENV_VAR_NAME)? {
                        return Ok(Self($crate::ServiceUrl::owned(value)));
                    }

                    Ok(Self::default_for_environment(environment))
                }

                #[doc = "Create a new instance of [`Self`] for a specific environment without checking the override env var."]
                #[allow(dead_code)]
                $v const fn default_for_environment(environment: $crate::macro_env::Environment) -> Self {
                    match environment {
                        $crate::macro_env::Environment::Local => Self::from_static(Self::LOCAL),
                        $crate::macro_env::Environment::Develop => Self::from_static(Self::DEV),
                        $crate::macro_env::Environment::Production => Self::from_static(Self::PROD),
                    }
                }

                #[doc = "Create a new instance of [`Self`] from the local default URL."]
                #[allow(dead_code)]
                $v const fn local() -> Self {
                    Self::from_static(Self::LOCAL)
                }

                #[doc = "Create a new instance of [`Self`] from the dev default URL."]
                #[allow(dead_code)]
                $v const fn dev() -> Self {
                    Self::from_static(Self::DEV)
                }

                #[doc = "Create a new instance of [`Self`] from the prod default URL."]
                #[allow(dead_code)]
                $v const fn prod() -> Self {
                    Self::from_static(Self::PROD)
                }

                #[doc = "Create a new instance of [`Self`] from a static URL."]
                #[allow(dead_code)]
                $v const fn from_static(url: &'static str) -> Self {
                    Self($crate::ServiceUrl::borrowed(url))
                }

                #[doc = "Create a new instance of [`Self`] from an owned runtime URL."]
                #[allow(dead_code)]
                $v fn from_owned(url: impl Into<String>) -> Self {
                    Self($crate::ServiceUrl::owned(url))
                }

                #[doc = "Return the override environment variable name checked by [`Self::new`]."]
                #[allow(dead_code)]
                $v const fn override_env_var_name(&self) -> &'static str {
                    Self::OVERRIDE_ENV_VAR_NAME
                }

                #[doc = "Return the contained [`ServiceUrl`]."]
                #[allow(dead_code)]
                $v fn into_inner(self) -> $crate::ServiceUrl<'static> {
                    self.0
                }

                #[doc = "Return a reference to the contained [`ServiceUrl`]."]
                #[allow(dead_code)]
                $v fn inner(&self) -> &$crate::ServiceUrl<'static> {
                    &self.0
                }

                #[doc = "Return the URL as a string slice."]
                #[allow(dead_code)]
                $v fn as_str(&self) -> &str {
                    self.0.as_str()
                }

                #[doc = "Parse the URL string into a URL."]
                #[allow(dead_code)]
                $v fn parse_url(&self) -> Result<$crate::Url, $crate::UrlParseError> {
                    self.0.parse_url()
                }

                #[doc = "Return a cheaply copied borrowed view of this URL."]
                #[allow(dead_code)]
                $v fn copied(&self) -> $crate::ServiceUrl<'_> {
                    self.0.copied()
                }
            }

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

                fn deref(&self) -> &Self::Target {
                    self.as_str()
                }
            }

            impl std::convert::AsRef<str> for $n {
                fn as_ref(&self) -> &str {
                    self.as_str()
                }
            }

            impl std::fmt::Display for $n {
                fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    f.write_str(self.as_str())
                }
            }

            impl std::convert::From<$crate::ServiceUrl<'static>> for $n {
                fn from(value: $crate::ServiceUrl<'static>) -> Self {
                    Self(value)
                }
            }

            impl std::convert::From<$n> for $crate::ServiceUrl<'static> {
                fn from(value: $n) -> Self {
                    value.0
                }
            }

            impl std::convert::From<String> for $n {
                fn from(value: String) -> Self {
                    Self::from_owned(value)
                }
            }

            impl std::convert::From<&'static str> for $n {
                fn from(value: &'static str) -> Self {
                    Self::from_static(value)
                }
            }
        }
    };
    (
        $(#[$attr:meta])*
        $v:vis struct $n:ident {
            $(
                $(#[$field_attr:meta])*
                $field_vis:vis $field_name:ident {
                    local: $field_local:literal,
                    dev: $field_dev:literal,
                    prod: $field_prod:literal $(,)?
                }
            ),* $(,)?
        }
    ) => {
        $crate::paste::paste! {
            $(
                $crate::service_url!(
                    $(#[$field_attr])*
                    $field_vis struct $field_name {
                        local: $field_local,
                        dev: $field_dev,
                        prod: $field_prod,
                    }
                );
            )*

            #[doc = "A collection of typed service URLs."]
            $(#[$attr])*
            $v struct $n {
                $(
                    #[doc = "Typed service URL loaded from `OVERRIDE_" $field_name:snake:upper "` or selected from per-environment defaults."]
                    $field_vis [<$field_name:snake>]: $field_name,
                )*
            }

            impl $n {
                #[doc = "Create a new instance of [`Self`] with all service URLs resolved for the current macro environment."]
                #[allow(dead_code)]
                $v fn new() -> Result<Self, $crate::ServiceUrlVarErr> {
                    let environment = $crate::macro_env::Environment::new_or_prod();
                    Self::new_for_environment(environment)
                }

                #[doc = "Create a new instance of [`Self`] with all service URLs resolved for the current macro environment, panicking if an override env var is set but cannot be read."]
                #[allow(dead_code)]
                $v fn unwrap_new() -> Self {
                    Self::new().expect(concat!("Failed to resolve service URL collection for ", stringify!($n)))
                }

                #[doc = "Create a new instance of [`Self`] with all service URLs resolved for a specific environment."]
                #[allow(dead_code)]
                $v fn new_for_environment(environment: $crate::macro_env::Environment) -> Result<Self, $crate::ServiceUrlVarErr> {
                    Ok(Self {
                        $(
                            [<$field_name:snake>]: $field_name::new_for_environment(environment)?,
                        )*
                    })
                }

                #[doc = "Create a new instance of [`Self`] with all service URLs set to environment defaults without checking overrides."]
                #[allow(dead_code)]
                $v const fn default_for_environment(environment: $crate::macro_env::Environment) -> Self {
                    Self {
                        $(
                            [<$field_name:snake>]: $field_name::default_for_environment(environment),
                        )*
                    }
                }
            }
        }
    };
}

service_url! {
    /// Common service URLs used by Macro services.
    pub struct ServiceUrls {
        /// Main app URL.
        pub AppServiceUrl {
            local: "http://localhost:3000",
            dev: "https://dev.macro.com",
            prod: "https://macro.com",
        },
        /// Authentication service API URL.
        pub AuthServiceUrl {
            local: "http://localhost:8080",
            dev: "https://dev-gateway.macro.com/auth",
            prod: "https://gateway.macro.com/auth",
        },
        /// Document storage service API URL.
        pub DocumentStorageServiceUrl {
            local: "http://localhost:8086",
            dev: "https://dev-gateway.macro.com/dss",
            prod: "https://gateway.macro.com/dss",
        },
        /// Convert service API URL.
        pub ConvertServiceUrl {
            local: "http://localhost:8080",
            dev: "https://dev-gateway.macro.com/convert",
            prod: "https://gateway.macro.com/convert",
        },
        /// Search processing service API URL.
        pub SearchProcessingServiceUrl {
            local: "http://localhost:8092",
            dev: "https://dev-gateway.macro.com/search-processing",
            prod: "https://gateway.macro.com/search-processing",
        },
        /// Connection gateway HTTP API URL.
        pub ConnectionGatewayUrl {
            local: "http://localhost:8082",
            dev: "https://dev-gateway.macro.com/connection-gateway",
            prod: "https://gateway.macro.com/connection-gateway",
        },
        /// Connection gateway WebSocket URL.
        pub ConnectionGatewayWebsocketUrl {
            local: "ws://localhost:8082",
            dev: "wss://dev-gateway.macro.com/connection-gateway",
            prod: "wss://gateway.macro.com/connection-gateway",
        },
        /// Document cognition service API URL.
        pub DocumentCognitionServiceUrl {
            local: "http://localhost:8101/cognition",
            dev: "https://dev-gateway.macro.com/cognition",
            prod: "https://gateway.macro.com/cognition",
        },
        /// Notification service API URL.
        pub NotificationServiceUrl {
            local: "http://localhost:8089",
            dev: "https://dev-gateway.macro.com/notification",
            prod: "https://gateway.macro.com/notification",
        },
        /// Static file service/CDN URL.
        pub StaticFileServiceUrl {
            local: "http://localhost:8100",
            dev: "https://static-file-service-dev.macro.com",
            prod: "https://static-file-service.macro.com",
        },
        /// Browser-facing static file base that file links are stamped with.
        /// [`StaticFileServiceUrl`] is the address services call; on a local
        /// stack the two differ, since containers reach the service
        /// in-network while browsers go through the frontend proxy.
        pub StaticFilePublicUrl {
            local: "http://localhost:8100",
            dev: "https://static-file-service-dev.macro.com",
            prod: "https://static-file-service.macro.com",
        },
        /// Agent harness service API URL. Serves the agent-session control
        /// routes, which run in the process that owns the live sessions.
        pub AgentHarnessServiceUrl {
            local: "http://localhost:8101",
            dev: "https://dev-gateway.macro.com/agent-harness",
            prod: "https://gateway.macro.com/agent-harness",
        },
        /// Scheduled action service API URL.
        pub ScheduledActionServiceUrl {
            local: "http://localhost:8101/scheduled-action",
            dev: "https://dev-gateway.macro.com/scheduled-action",
            prod: "https://gateway.macro.com/scheduled-action",
        },
        /// Sandbox-facing agent harness egress proxy URL.
        /// Override the local default when sandbox clients need a Docker-network
        /// address or a public tunnel rather than the host's loopback address.
        pub AgentHarnessEgressUrl {
            local: "http://localhost:8102",
            dev: "https://dev-gateway.macro.com/agent-harness-egress",
            prod: "https://gateway.macro.com/agent-harness-egress",
        },
        /// Macro MCP service base URL. Append `/mcp` for its transport endpoint.
        pub McpServiceUrl {
            local: "http://localhost:8101",
            dev: "https://dev-gateway.macro.com/mcp",
            prod: "https://gateway.macro.com/mcp",
        },
        /// Public MCP OAuth issuer and callback base, distinct from gateway transport routing.
        pub McpPublicUrl {
            local: "http://localhost:8101",
            dev: "https://mcp-server-dev.macro.com",
            prod: "https://mcp-server.macro.com",
        },
        /// Public integration callback base, preserving registered OAuth redirect URIs.
        pub CognitionPublicUrl {
            local: "http://localhost:8101/cognition",
            dev: "https://document-cognition-dev.macro.com",
            prod: "https://document-cognition.macro.com",
        },
        /// Macro Connect API base URL: Macro's OAuth broker for MCP connectors.
        pub ConnectApiUrl {
            local: "http://localhost:8080",
            dev: "https://connect-dev.macro.com",
            prod: "https://connect.macro.com",
        },
        /// Link unfurl service API URL.
        pub UnfurlServiceUrl {
            local: "http://localhost:8095",
            dev: "https://dev-gateway.macro.com/unfurl",
            prod: "https://gateway.macro.com/unfurl",
        },
        /// Contacts service API URL.
        pub ContactsServiceUrl {
            local: "http://localhost:8083",
            dev: "https://dev-gateway.macro.com/contacts",
            prod: "https://gateway.macro.com/contacts",
        },
        /// Email service API URL.
        pub EmailServiceUrl {
            local: "http://localhost:8087",
            dev: "https://dev-gateway.macro.com/email",
            prod: "https://gateway.macro.com/email",
        },
        /// Calendar service API URL. The calendar write authority once
        /// `calendar_service` owns provider mutations; its API is mounted at
        /// the root and under the `/calendar` gateway prefix.
        pub CalendarServiceUrl {
            local: "http://localhost:8088",
            dev: "https://dev-gateway.macro.com/calendar",
            prod: "https://gateway.macro.com/calendar",
        },
        /// Image proxy service API URL.
        pub ImageProxyServiceUrl {
            local: "http://localhost:8097",
            dev: "https://dev-gateway.macro.com/image-proxy",
            prod: "https://gateway.macro.com/image-proxy",
        },
        /// Lexical conversion service API URL.
        pub LexicalServiceUrl {
            local: "http://localhost:8096",
            dev: "https://dev-gateway.macro.com/lexical",
            prod: "https://gateway.macro.com/lexical",
        },
        /// Sync service API URL.
        pub SyncServiceUrl {
            local: "http://localhost:8787",
            dev: "https://sync-service-dev3.macroverse.workers.dev",
            prod: "https://sync-service-prod2.macroverse.workers.dev",
        },
        /// AI editing worker API URL.
        pub AiEditingWorkerUrl {
            local: "http://localhost:8933",
            dev: "https://ai-editing-worker-dev.macroverse.workers.dev",
            prod: "https://ai-editing-worker.macroverse.workers.dev",
        },
    }
}

service_url! {
    /// Control and internal MCP surface of the live preview service.
    pub struct PreviewGatewayUrl {
        local: "http://localhost:8101/preview",
        dev: "https://dev-gateway.macro.com/preview",
        prod: "https://gateway.macro.com/preview",
    }
}