ExESDB Gater
The ExESDB Gateway API
Features
ExESDGater is a high-availability gateway service that provides secure, load-balanced access to ExESDB clusters. It acts as a proxy layer between client applications and the ExESDB event store cluster, offering simplified API access and automatic cluster discovery.
Core Functionality
Event Store Operations
- Stream Management: Create, read, and manage event streams
- Event Appending: Append events to streams with version control
- Event Retrieval: Query events from streams with support for forward/backward traversal
- Stream Versioning: Get and track stream versions for optimistic concurrency control
Subscription Management
- Multiple Subscription Types:
:by_stream
- Subscribe to specific streams:by_event_type
- Subscribe to events by type:by_event_pattern
- Subscribe using pattern matching:by_event_payload
- Subscribe based on event payload content
- Persistent Subscriptions: Durable subscriptions that survive restarts
- Transient Subscriptions: Temporary subscriptions for short-lived operations
- Event Acknowledgment: ACK/NACK support for reliable event processing
- Replay Capability: Start subscriptions from any stream version
Snapshot Management
- Snapshot Recording: Store aggregate snapshots for performance optimization
- Snapshot Retrieval: Read snapshots by source UUID, stream UUID, and version
- Snapshot Deletion: Remove outdated snapshots
- Snapshot Listing: Query available snapshots with filtering
Cluster Discovery & High Availability
LibCluster Integration
ExESDGater uses LibCluster for automatic cluster discovery and formation:
- Strategy: Gossip-based multicast discovery
- Protocol: UDP multicast on configurable port (default: 45892)
- Network: Automatic discovery on shared Docker networks
- Security: Shared secret authentication for cluster joining
- Broadcast Address: Configurable multicast address (default: 255.255.255.255)
Cluster Formation Process
- Bootstrap: ExESDGater starts and initializes LibCluster
- Discovery: Uses gossip multicast to discover ExESDB nodes
- Authentication: Validates cluster membership using shared secrets
- Connection: Establishes Erlang distribution connections to cluster nodes
- Monitoring: Continuously monitors cluster health and node availability
High Availability Features
- Load Balancing: Automatically distributes requests across available gateway workers
- Failover: Seamless handling of node failures and network partitions
- Health Monitoring: Real-time cluster status monitoring with detailed logging
- Auto-Recovery: Automatic reconnection to recovered cluster nodes
- Split-Brain Prevention: Coordinated cluster formation to prevent inconsistencies
Configuration
Environment Variables
EX_ESDB_GATER_CONNECT_TO
: Target cluster node (default: current node)EX_ESDB_PUB_SUB
: PubSub process name (default: :ex_esdb_pubsub)EX_ESDB_CLUSTER_SECRET
: Shared secret for cluster authenticationEX_ESDB_COOKIE
: Erlang distribution cookieRELEASE_COOKIE
: Release-specific distribution cookie
LibCluster Configuration
config :libcluster,
topologies: [
ex_esdb_gater: [
strategy: Cluster.Strategy.Gossip,
config: [
port: 45_892,
if_addr: "0.0.0.0",
multicast_addr: "255.255.255.255",
broadcast_only: true,
secret: System.get_env("EX_ESDB_CLUSTER_SECRET")
]
]
]
Architecture
Components
- ExESDBGater.API: Main API interface and request router
- ExESDBGater.ClusterMonitor: Monitors cluster node connections and health
- ExESDBGater.System: Supervisor managing all gateway components
- Gateway Workers: Distributed workers using Swarm for cluster-wide coordination
- Phoenix.PubSub: Event broadcasting and subscription management
Worker Distribution
- Swarm Integration: Uses Swarm for distributed process management
- Random Load Balancing: Requests distributed randomly across available workers
- Fault Tolerance: Worker failures handled gracefully with automatic redistribution
- Cluster-Wide Coordination: Workers can run on any node in the cluster
Network Topology
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ExESDB Node │ │ ExESDB Node │ │ ExESDB Node │
│ (node0) │◄──►│ (node1) │◄──►│ (node2) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
▲ ▲ ▲
│ │ │
│ Gossip Multicast Network (UDP:45892) │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ExESDGater │ │ ExESDGater │ │ ExESDGater │
│ (gateway-1) │◄──►│ (gateway-2) │◄──►│ (gateway-3) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Deployment Scenarios
Containerized Deployment
- Docker Compose: Multi-container setup with shared networks
- Network Isolation: Secure communication within Docker bridge networks
- Service Discovery: Automatic discovery of ExESDB containers
- Health Checks: Container-level health monitoring
Production Deployment
- Multiple Gateways: Deploy multiple ExESDGater instances for redundancy
- Load Balancers: Use external load balancers for client request distribution
- Monitoring: Comprehensive logging and metrics collection
- Security: Network-level security with firewall rules and VPNs