Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
#![deny(missing_docs)]
//! Macro queue name values with per-environment defaults and environment
//! variable overrides.
//!
//! Use [`queue!`] 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,
//! `EmailScheduledQueue` checks `OVERRIDE_EMAIL_SCHEDULED_QUEUE` before falling
//! back to its `local`, `dev`, or `prod` default.
//!
//! Queue values are opaque strings (SQS queue names or, in some cases, full
//! queue URLs); this crate does not parse or validate them.
use std::{borrow::Cow, fmt, ops::Deref};
#[doc(hidden)]
pub use macro_env;
#[doc(hidden)]
pub use paste;
#[doc(hidden)]
pub use serde;
#[cfg(test)]
mod test;
#[cfg(test)]
mod testing_harness {
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)]
#[allow(
clippy::disallowed_methods,
reason = "Test harness fallback used when no mock override is set"
)]
pub fn read_override_env(var_name: &'static str) -> Option<String> {
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),
}
.ok()
}
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 queue. Returns `None` if the
/// variable is unset or cannot be read.
#[cfg(not(test))]
#[doc(hidden)]
#[allow(
clippy::disallowed_methods,
reason = "Used when running locally to override queues"
)]
pub fn read_override_env(var_name: &'static str) -> Option<String> {
std::env::var(var_name).ok()
}
/// A queue name 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 Queue<'a>(Cow<'a, str>);
impl<'a> Queue<'a> {
/// Create a queue that borrows a string slice.
pub const fn borrowed(queue: &'a str) -> Self {
Self(Cow::Borrowed(queue))
}
/// Create a queue that owns a runtime string.
pub fn owned(queue: impl Into<String>) -> Queue<'static> {
Queue(Cow::Owned(queue.into()))
}
/// Return the queue name as a string slice.
pub fn as_str(&self) -> &str {
self.0.as_ref()
}
/// Return a cheaply copied borrowed view of this queue.
pub fn copied(&self) -> Queue<'_> {
Queue(Cow::Borrowed(self.as_str()))
}
/// Convert this queue into an owned `'static` value.
pub fn into_owned(self) -> Queue<'static> {
Queue(Cow::Owned(self.0.into_owned()))
}
/// Convert this queue into its internal [`Cow`].
pub fn into_cow(self) -> Cow<'a, str> {
self.0
}
/// Return the borrowed string if this queue is currently borrowed.
pub fn borrowed_inner(&self) -> Option<&'a str> {
match &self.0 {
Cow::Borrowed(queue) => Some(*queue),
Cow::Owned(_) => None,
}
}
/// Return the owned string if this queue is currently owned.
pub fn owned_inner(&self) -> Option<&String> {
match &self.0 {
Cow::Borrowed(_) => None,
Cow::Owned(queue) => Some(queue),
}
}
}
impl<'a> From<&'a str> for Queue<'a> {
fn from(value: &'a str) -> Self {
Self::borrowed(value)
}
}
impl From<String> for Queue<'static> {
fn from(value: String) -> Self {
Self(Cow::Owned(value))
}
}
impl<'a> From<Cow<'a, str>> for Queue<'a> {
fn from(value: Cow<'a, str>) -> Self {
Self(value)
}
}
impl<'a> From<Queue<'a>> for String {
fn from(value: Queue<'a>) -> Self {
value.0.into_owned()
}
}
impl<'a> Deref for Queue<'a> {
type Target = str;
fn deref(&self) -> &Self::Target {
self.as_str()
}
}
impl<'a> AsRef<str> for Queue<'a> {
fn as_ref(&self) -> &str {
self.as_str()
}
}
impl<'a> fmt::Display for Queue<'a> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
/// Define typed queue name values with per-environment defaults and override
/// environment variables.
///
/// The override environment variable name is derived from the struct name:
/// `EmailScheduledQueue` checks `OVERRIDE_EMAIL_SCHEDULED_QUEUE`. If that
/// override is not set, [`macro_env::Environment`] selects one of the provided
/// `local`, `dev`, or `prod` defaults.
///
/// # Example
///
/// ```
/// macro_queues::queue! {
/// #[derive(Debug, Clone)]
/// pub struct ExampleQueue {
/// local: "example-queue",
/// dev: "example-queue-dev",
/// prod: "example-queue-prod",
/// }
/// }
///
/// let queue = ExampleQueue::new();
/// assert_eq!(queue.override_env_var_name(), "OVERRIDE_EXAMPLE_QUEUE");
/// ```
#[macro_export]
macro_rules! queue {
(
$(#[$attr:meta])*
$v:vis struct $n:ident {
local: $local:literal,
dev: $dev:literal,
prod: $prod:literal $(,)?
}
) => {
$crate::paste::paste! {
#[doc = "Typed queue name loaded from `OVERRIDE_" $n:snake:upper "` or selected from per-environment defaults."]
$(#[$attr])*
$v struct $n($crate::Queue<'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 queue name for [`macro_env::Environment::Local`]."]
$v const LOCAL: &'static str = $local;
#[doc = "Default queue name for [`macro_env::Environment::Develop`]."]
$v const DEV: &'static str = $dev;
#[doc = "Default queue name 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, clippy::new_without_default)]
$v fn new() -> Self {
Self::new_for_environment($crate::macro_env::Environment::new_or_prod())
}
#[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) -> Self {
if let Some(value) = $crate::read_override_env(Self::OVERRIDE_ENV_VAR_NAME) {
return Self($crate::Queue::owned(value));
}
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 queue name."]
#[allow(dead_code)]
$v const fn local() -> Self {
Self::from_static(Self::LOCAL)
}
#[doc = "Create a new instance of [`Self`] from the dev default queue name."]
#[allow(dead_code)]
$v const fn dev() -> Self {
Self::from_static(Self::DEV)
}
#[doc = "Create a new instance of [`Self`] from the prod default queue name."]
#[allow(dead_code)]
$v const fn prod() -> Self {
Self::from_static(Self::PROD)
}
#[doc = "Create a new instance of [`Self`] from a static queue name."]
#[allow(dead_code)]
$v const fn from_static(queue: &'static str) -> Self {
Self($crate::Queue::borrowed(queue))
}
#[doc = "Create a new instance of [`Self`] from an owned runtime queue name."]
#[allow(dead_code)]
$v fn from_owned(queue: impl Into<String>) -> Self {
Self($crate::Queue::owned(queue))
}
#[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 [`Queue`]."]
#[allow(dead_code)]
$v fn into_inner(self) -> $crate::Queue<'static> {
self.0
}
#[doc = "Return a reference to the contained [`Queue`]."]
#[allow(dead_code)]
$v fn inner(&self) -> &$crate::Queue<'static> {
&self.0
}
#[doc = "Return the queue name as a string slice."]
#[allow(dead_code)]
$v fn as_str(&self) -> &str {
self.0.as_str()
}
#[doc = "Return a cheaply copied borrowed view of this queue."]
#[allow(dead_code)]
$v fn copied(&self) -> $crate::Queue<'_> {
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::Queue<'static>> for $n {
fn from(value: $crate::Queue<'static>) -> Self {
Self(value)
}
}
impl std::convert::From<$n> for $crate::Queue<'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)
}
}
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($crate::Queue::owned(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::queue!(
$(#[$field_attr])*
$field_vis struct $field_name {
local: $field_local,
dev: $field_dev,
prod: $field_prod,
}
);
)*
#[doc = "A collection of typed queues."]
$(#[$attr])*
$v struct $n {
$(
#[doc = "Typed queue 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 queues resolved for the current macro environment."]
#[allow(dead_code, clippy::new_without_default)]
$v fn new() -> Self {
let environment = $crate::macro_env::Environment::new_or_prod();
Self::new_for_environment(environment)
}
#[doc = "Create a new instance of [`Self`] with all queues resolved for a specific environment."]
#[allow(dead_code)]
$v fn new_for_environment(environment: $crate::macro_env::Environment) -> Self {
Self {
$(
[<$field_name:snake>]: $field_name::new_for_environment(environment),
)*
}
}
#[doc = "Create a new instance of [`Self`] with all queues 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),
)*
}
}
}
}
};
}
queue! {
/// Common SQS queues used by Macro services.
///
/// Default values mirror what infrastructure provisions: `local` uses the
/// bare queue names emitted by the xtask local environment, while `dev` and
/// `prod` use the `{base}-queue-{stack}` names provisioned by Pulumi.
pub struct Queues {
/// Queue for Slack archive conversation imports.
pub SlackImportQueue {
local: "slack-import-queue",
dev: "slack-import-queue-dev",
prod: "slack-import-queue-prod",
},
/// Dead-letter queue provisioned by the shared Pulumi Queue component.
pub SlackImportDlq {
local: "slack-import-dlq",
dev: "slack-import-dlq-dev",
prod: "slack-import-dlq-prod",
},
/// Queue for document text extraction jobs.
pub DocumentTextExtractorQueue {
local: "document-text-extractor-lambda-queue",
dev: "document-text-extractor-lambda-queue-dev",
prod: "document-text-extractor-lambda-queue-prod",
},
/// Queue for chat delete jobs.
pub ChatDeleteQueue {
local: "delete-chat-handler-queue",
dev: "delete-chat-handler-queue-dev",
prod: "delete-chat-handler-queue-prod",
},
/// Queue for scheduled email sends.
pub EmailScheduledQueue {
local: "email-service-scheduled-queue",
dev: "email-service-scheduled-queue-dev",
prod: "email-service-scheduled-queue-prod",
},
/// Queue for async Gmail label/sync operations.
pub GmailOpsQueue {
local: "email-service-gmail-ops-queue",
dev: "email-service-gmail-ops-queue-dev",
prod: "email-service-gmail-ops-queue-prod",
},
/// Queue for retrying rate-limited Gmail operations.
pub GmailOpsRetryQueue {
local: "email-service-gmail-ops-retry-queue",
dev: "email-service-gmail-ops-retry-queue-dev",
prod: "email-service-gmail-ops-retry-queue-prod",
},
/// Queue for egress notification delivery.
pub NotificationQueue {
local: "notification-queue",
dev: "notification-queue-dev",
prod: "notification-queue-prod",
},
/// Queue for ingress notification creation.
pub NotificationIngressQueue {
local: "notification-ingress-queue",
dev: "notification-ingress-queue-dev",
prod: "notification-ingress-queue-prod",
},
/// Queue for search index events.
pub SearchEventQueue {
local: "search-event-queue",
dev: "search-event-queue-dev",
prod: "search-event-queue-prod",
},
/// Queue for AI projection materialization jobs.
pub AiProjectionQueue {
local: "ai-projection-queue",
dev: "ai-projection-queue-dev",
prod: "ai-projection-queue-prod",
},
/// Queue for document conversion jobs.
pub ConvertQueue {
local: "convert-service-queue",
dev: "convert-service-queue-dev",
prod: "convert-service-queue-prod",
},
/// Queue for document delete jobs.
pub DocumentDeleteQueue {
local: "delete-document-handler-queue",
dev: "delete-document-handler-queue-dev",
prod: "delete-document-handler-queue-prod",
},
/// Queue for static-file-service deletion messages.
pub SfsDeleteQueue {
local: "email-sfs-delete-queue",
dev: "email-sfs-delete-queue-dev",
prod: "email-sfs-delete-queue-prod",
},
/// Queue for static-file-service uploader jobs.
pub SfsUploaderQueue {
local: "email-service-sfs-mapper-queue",
dev: "email-service-sfs-mapper-queue-dev",
prod: "email-service-sfs-mapper-queue-prod",
},
/// Queue for the contacts service.
pub ContactsQueue {
local: "contacts-queue",
dev: "contacts-queue-dev",
prod: "contacts-queue-prod",
},
/// Queue for push notification delivery events.
pub PushNotificationEventHandlerQueue {
local: "push-delivery-queue",
dev: "push-delivery-queue-dev",
prod: "push-delivery-queue-prod",
},
/// FIFO queue for webhook event delivery.
pub WebhookEventQueue {
local: "webhook-event-queue.fifo",
dev: "webhook-event-queue-dev.fifo",
prod: "webhook-event-queue-prod.fifo",
},
/// Queue for static-file-service S3 upload event notifications.
///
/// Note: this value is consumed as a full SQS URL in deployed
/// environments (`queueQueue.url`), not a bare name. The bare name is
/// baked here for consistency; see `queue-migration.md` for how the
/// static-file-service migration must resolve the name to a URL.
pub StaticFileServiceS3EventQueueUrl {
local: "static-file-s3-event-notification-queue",
dev: "static-file-s3-event-notification-queue-dev",
prod: "static-file-s3-event-notification-queue-prod",
},
/// Queue for the email link manager / refresh handler.
pub LinkManagerQueue {
local: "email-service-refresh-queue",
dev: "email-service-refresh-queue-dev",
prod: "email-service-refresh-queue-prod",
},
/// Queue for Gmail inbox update processing.
///
/// Note: the local queue name uses the `gmail-inbox-sync` base while
/// dev/prod derive from the `gmail-webhook` base. This divergence is
/// intentional and matches the existing infrastructure.
pub GmailInboxSyncQueue {
local: "email-service-gmail-inbox-sync-queue",
dev: "email-service-gmail-webhook-queue-dev",
prod: "email-service-gmail-webhook-queue-prod",
},
/// Queue for Gmail inbox update retries.
///
/// Note: the local queue name uses the `gmail-inbox-retry` base while
/// dev/prod derive from the `gmail-webhook-retry` base. This divergence
/// is intentional and matches the existing infrastructure.
pub GmailInboxSyncRetryQueue {
local: "email-service-gmail-inbox-retry-queue",
dev: "email-service-gmail-webhook-retry-queue-dev",
prod: "email-service-gmail-webhook-retry-queue-prod",
},
/// Queue for the email backfill process (authentication_service
/// `EMAIL_BACKFILL_QUEUE` and email_service `BACKFILL_QUEUE`).
pub EmailBackfillQueue {
local: "email-service-backfill-queue",
dev: "email-service-backfill-queue-dev",
prod: "email-service-backfill-queue-prod",
},
/// Queue for the nightly CRM cleanup job (email_service).
pub EmailCrmCleanupQueue {
local: "email-service-crm-cleanup-queue",
dev: "email-service-crm-cleanup-queue-dev",
prod: "email-service-crm-cleanup-queue-prod",
},
/// Queue for the bulk upload extractor lambda
/// (upload_extractor_lambda_trigger `UPLOAD_EXTRACTOR_QUEUE`).
pub UploadExtractorQueue {
local: "bulk-upload-queue",
dev: "bulk-upload-queue-dev",
prod: "bulk-upload-queue-prod",
},
/// Queue for document upload finalization events.
pub DocumentUploadFinalizerQueue {
local: "document-upload-finalizer-queue",
dev: "document-upload-finalizer-queue-dev",
prod: "document-upload-finalizer-queue-prod",
},
/// Queue for reminder dispatch.
///
/// Carries both the minutely sweep tick, which an EventBridge rule
/// publishes directly, and the per-firing messages that sweep fans out.
pub ReminderDispatchQueue {
local: "reminder-dispatch-queue",
dev: "reminder-dispatch-queue-dev",
prod: "reminder-dispatch-queue-prod",
},
/// Queue for calendar event reminder dispatch.
///
/// Carries both the minutely sweep tick, which an EventBridge rule
/// publishes directly, and the per-firing messages that sweep fans out.
pub CalendarReminderDispatchQueue {
local: "calendar-reminder-dispatch-queue",
dev: "calendar-reminder-dispatch-queue-dev",
prod: "calendar-reminder-dispatch-queue-prod",
},
/// Queue for the Google Calendar sync backfill process (calendar_service).
///
/// Calendar keeps its own backfill queue rather than sharing the email
/// backfill queue, so its sync deploy lifecycle is independent of email.
pub CalendarServiceBackfillQueue {
local: "calendar-service-backfill-queue",
dev: "calendar-service-backfill-queue-dev",
prod: "calendar-service-backfill-queue-prod",
},
/// Queue for the organization retention handler
/// (organization_retention_trigger `ORGANIZATION_RETENTION_QUEUE`).
pub OrganizationRetentionQueue {
local: "organization-retention-handler-queue",
dev: "organization-retention-handler-queue-dev",
prod: "organization-retention-handler-queue-prod",
},
}
}