WireSocket operates a globally distributed network of WebSocket Nodes. While your app’s configuration is anchored in a License Region, your users connect to these regional nodes for the actual data synchronization.
Regional Coding
| Type | Format | Example |
|---|
| License Region | aws-{provider-region} | aws-eu-west-1 |
| WebSocket Region | {region-name}-{cluster-id} | eu-central-1 |
Cluster Numbering
Unlike License Regions, WebSocket regions include a trailing number (e.g., -1, -2). This represents a specific Sync Cluster within that geographic area.
- Domain Assignment: Each cluster is assigned its own unique subdomain (e.g.,
eu-central-1.wiresocket.net).
- Scaling: As demand grows, WireSocket may deploy additional clusters in the same region (
eu-central-2, etc.) to provide horizontal scale and isolation.
Available License Regions
| Code | Location |
|---|
aws-ap-northeast-1 | Asia Pacific (Tokyo) |
aws-ap-south-1 | Asia Pacific (Mumbai) |
aws-eu-west-1 | Europe (Ireland) |
aws-us-east-1 | US East (N. Virginia) |
aws-us-east-2 | US East (Ohio) |
aws-us-west-2 | US West (Oregon) |
Available WebSocket Regions
| Region | URL | Status |
|---|
| Europe (Central) | wss://eu-central-1.wiresocket.net | ✅ Live |
| US East | wss://us-east-1.wiresocket.net | 🔜 Coming soon |
Architecture Logic
Your License Region (dbCode) is the database “home” for your app’s metadata. When a user connects to a node, that node queries the dbCode database to see if the document is already active elsewhere.
This allows a user to hit a node in London (eu-central-1) and be automatically redirected if the document is already pinned to a node in New York (us-east-1).
Regional Routing & Pinning
To ensure all users on a document see the same state, WireSocket employs a Document Pinning architecture.
- First Connection: When a user opens a document that isn’t currently active, the node they connect to becomes the Pinned Region for that document.
- Session Registry: The node registers itself as the
active_region in your application’s metadata database (located in the dbCode region).
- Subsequent Connections: Any other user attempting to connect to that document will be checked against this registry and routed to the pinned region.
Proactive Discovery (Recommended)
Before establishing a WebSocket connection, your client should call the Discovery API. This returns the exact node URL (including the document ID) to connect to.
GET https://{region-code}.wiresocket.net/discovery?documentName=my-document
Authorization: Bearer YOUR_TOKEN
Reactive Redirection
If a client connects to the “wrong” region directly (e.g., they hit eu-central-1 but the doc is pinned to us-east-1), the Data Plane rejects the connection with a redirect instruction:
- Close Code:
4009
- Reason:
REDIRECT:wss://us-east-1.wiresocket.net/my-document
Technical Implementation
The JWT Claims
Your JWT includes two critical routing claims:
dbCode: Tells the Data Plane where to find your app’s metadata and limits. This matches your License Region (e.g., aws-eu-west-1).regionCode: The region closest to the user. This is where the client should attempt to connect if it doesn’t use Discovery.
Pinning Expiration
A document remains pinned to a region as long as there is at least one active connection. Once the last user disconnects, a 10-second grace period starts. If no one reconnects within that window, the document is “unpinned,” allowing the next connection to pin it to any available region. Last modified on March 3, 2026
