API Gateway WebSocket Failover: Keep Sessions Across Regions

A Regional outage doesn’t just slow a WebSocket app down: it severs every active connection, and for apps with shared state, such as a live auction or a collaborative editor, users lose their session too. A new AWS Architecture Blog pattern shows how to detect a Regional failure in about two minutes, move Amazon API Gateway WebSocket APIs to a second Region, and restore each user’s state automatically. For platform teams running real-time features on serverless, the key idea is that the connection is disposable and the state is not.

How It Works

The design is active-passive. Identical WebSocket API stacks run in a primary and a secondary Region behind one custom domain, and a Route 53 failover routing policy points that domain at the primary until it’s marked unhealthy. Application state lives in DynamoDB Global Tables, which replicate it to the secondary Region asynchronously, typically within a second. AWS notes the catch: writes made just before a failure may not reach the secondary.

Detection doesn’t rely on user traffic. An EventBridge rule runs a canary Lambda function every minute that opens a WebSocket connection, sends a heartbeat, and publishes 1 or 0 as a custom CloudWatch metric. The alarm treats missing data as a failure, so a canary that stops reporting counts as unhealthy. After two consecutive bad datapoints, the alarm trips the Route 53 health check and DNS shifts to the secondary. In AWS’s demo, the canary detects a failure within about two minutes, after which clients reconnect once DNS propagates.

Clients do the rest. They send their own heartbeat every 30 seconds and force a reconnect after two consecutive failed responses, which catches a degraded backend, such as throttled Lambda functions behind a connection that is technically still open, within 60 seconds. Reconnection uses exponential backoff with full jitter, so thousands of clients don’t hit the secondary Region at the same moment DNS changes. After reconnecting, the client asks the server for current state and gets it from the local DynamoDB replica. The sample repository includes CloudFormation templates and a React client.

What This Means for You

Three production details decide whether it works. First, WebSocket APIs authenticate on the $connect route, so the Lambda authorizer must be deployed in both Regions. Second, state should be keyed by user ID from the validated token, not by connection ID, which changes on every reconnect. Third, failback needs different thresholds: AWS suggests two datapoints to fail over but more than five to fail back, to avoid flapping while the primary recovers, with a DNS TTL of 60 to 120 seconds.

Teams on a relational database face a slower path. Aurora Global Database replicates in under a second, but failover requires promoting a replica, which typically adds one to two minutes. Stack Archive’s coverage of AWS’s open-source regional availability tools covers the broader question of which services exist in a second Region before you build this.

Source: AWS Architecture Blog

Content created with AI assistance and reviewed for accuracy.