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.

3.8 KB
Raw Blame

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 through entity_access.
  • scripts/stale_connections.rs (stale_connections bin): scans DynamoDB for connections past the 60s timeout; README.md has 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 like channels, 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 (see README.md).

Checks

  • cargo test -p connection_gateway (SQLX_OFFLINE unset).
  • cargo run --features local_auth then connect on port 8085 (see README.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 user entity only for that user, any other type for any permission EntityAccessService grants 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 last open or ping, compared across instances' clocks. A ping for a row that is gone re-creates it, so a lost open heals 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.md

  • The HTTP boundary validates optional signed agent correlation without changing existing authorization.