github.com/tinywideclouds/go-routing-service

📬 go-routing-service

Role: The high-performance "Traffic Controller" for the secure messaging platform.

The go-routing-service is responsible for ingesting encrypted envelopes, determining the recipient's presence status, and routing the data to the appropriate delivery queue (Hot vs. Cold). It implements the "Sealed Sender" pattern, ensuring the service never sees the message content.

🏗 Architecture

The service uses a Smart Router pipeline with a tiered queue system:

• Ingestion: Messages arrive via HTTP (/api/send) or Pub/Sub.
• Routing Processor:
  • Generates a definitive MessageID.
  • Checks User Presence (Redis/Memory).
  • Online: Routes to Hot Queue (Redis) and emits a "Poke" signal via WebSocket.
  • Offline: Routes to Cold Queue (Firestore) and triggers a Push Notification.
• Delivery (Poke-then-Pull):
  • Clients maintain a WebSocket connection.
  • Upon receiving a "Poke", clients call GET /messages to drain the queue.
• Migration: If a user disconnects while messages are pending in the Hot Queue, the service automatically migrates them to the Cold Queue to ensure durability.

🚀 API Endpoints

1. Send Message

POST /api/send Accepts a sealed envelope.

• Body: SecureEnvelope (JSON/Proto)
• Auth: Required (Sender Identity)

2. Fetch Messages

GET /api/messages?limit=50 Retrieves pending messages from the queue (Hot or Cold).

• Response: QueuedMessageList
  • messages: Array of objects containing { id: string, envelope: SecureEnvelope }.
  • Note: The id returned here is the Definitive ID generated by the router.

3. Acknowledge (Delete)

POST /api/messages/ack Confirms receipt. The router immediately deletes the messages from the queue.

• Body: { "messageIds": ["uuid-1", "uuid-2"] }

🔌 Configuration

The service is configured via a 2-stage loader (YAML Base -> Env Overrides).

Env Variable	Description
GCP_PROJECT_ID	Google Cloud Project ID.
IDENTITY_SERVICE_URL	URL for OIDC/JWKS validation.
REDIS_ADDR	Address of the Redis instance (Hot Queue/Presence).
API_PORT	Port for the REST API (default 8080).
WEBSOCKET_PORT	Port for the WebSocket Service (default 8081).

🛠️ Development

Prerequisites

• Go 1.22+
• Docker (for Redis/Firestore Emulators)

Running Tests

This service relies heavily on Integration Tests using go-test/emulators.

# Run all tests (including emulators)
go test ./... -tags=integration