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
connection_gateway
What it is
Shared infrastructure: manages per-entity WebSocket connections so other services can push messages to a specific connected entity without holding the socket themselves.
Start here
src/api/connection.rs: WebSocket upgrade endpoint and connection lifecycle.src/api/message.rs: HTTP endpoints other services call to send a message to a connected entity, or (/message/broadcast) to every open connection.src/service/connection.rs+src/service/dynamodb.rs: connection registry, backed by DynamoDB (tracks which entity is on which instance).src/service/sender.rs+src/service/redis.rs: cross-instance message relay (Redis pub/sub) so a send reaches a connection on another instance.src/service/entity_grants.rs: which entities a connection may subscribe to (track_entity,stream_events), checked throughentity_access.scripts/stale_connections.rs(stale_connectionsbin): scans DynamoDB for connections past the 60s timeout;README.mdhas usage.
Scope
- Owns: WebSocket connection tracking and message delivery to a connected entity, across instances, and authorizing which entities a connection may subscribe to.
- Not here: the message/event payloads themselves, or who is authorized to send to whom — callers decide that before calling in.
Boundaries
- Depends on:
connection_gateway_models,macro_authorization,entity_access. - Used by: nearly every other service, through
connection_gateway_client(document_storage_service, document_cognition_service, email_service, calendar_service, agent_harness_service, mcp_service, scheduled_action, agent_trigger_service, preview_gateway, and domain crates likechannels,messages,databases,ai_tools).
Recipes
- Add a message/event type sendable over the gateway:
src/model/message.rs→src/api/message.rs→connection_gateway_client(the crate callers use). - Debug/clean stale connections:
scripts/stale_connections.rs(seeREADME.md).
Checks
cargo test -p connection_gateway(SQLX_OFFLINEunset).cargo run --features local_auththen connect on port 8085 (seeREADME.md).
Gotchas
- A send can target a connection on a different instance — it always goes
through the Redis relay in
src/service/redis.rs, never a direct in-process lookup; don't bypass it when adding a new send path. - Every subscription frame is authorized: a
userentity only for that user, any other type for any permissionEntityAccessServicegrants on it. Types it has no check for (static_file,skill,channel_message) are refused, so a new entity type clients track needs an access check first. Grants are cached per connection and rechecked every 5 minutes. - Presence (
user_tracking_change) counts an entity row as active for 60s after its lastopenorping, compared across instances' clocks. Apingfor a row that is gone re-creates it, so a lostopenheals on the next heartbeat. - Reads skip rows that do not parse as a connection entry, so one bad row never fails delivery to the rest of an entity or a batch. A row missing entry attributes (left by pings before they checked their row exists) is deleted on read, conditioned on those attributes still being absent; a whole row this instance cannot read (e.g. an entity type from a newer deploy) is kept. Keep every write of a new attribute conditional on the row existing.
- Broadcasts use their own Redis channel (
BROADCAST_CHANNEL): each instance forwards them to every connection it holds, with no DynamoDB lookup and no receipts. Keep them rare (e.g. the platform status banner); a broadcast is one message per open tab.
Related
Rules:
.agents/rules/config-and-service-urls.mdThe HTTP boundary validates optional signed agent correlation without changing existing authorization.