Real-time gateway

edgerealtime-gateway

Holds long-lived client connections and pushes events.

Category: Edge
Properties: 11
Components: 20
Rules: 3

Properties · 11 defined by this kind

A node of this kind resolves each property from its own props, then the component's defaults, then the default below.

property	type	values	required	default
ackIntervalSeconds · advanced	integer	—	no	—
autoscaling	boolean	—	no	false
channelAssignment · advanced	enum	random \| hash \| sticky	no	random
drainOnScaleIn · advanced	boolean	—	no	false
managed	boolean	—	no	false
protocol	enum	websocket \| sse \| long-poll \| grpc-stream \| udp-multicast	no	websocket
pushFallback · advanced	boolean	—	no	false
sequenceNumbers · advanced	boolean	—	no	false
stampedeGuard · advanced	boolean	—	no	false
stateful	boolean	—	no	true
subscriptionsPerUser · advanced	integer	—	no	—

Rules for this kind · 3

Reconnect stampede without guarderror

reconnect-stampede-without-guard

When a gateway holding millions of sockets restarts, every client reconnects at once and the gateway asks the coordination service about each of them. Without a stampede guard that lookup storm takes the coordination service down too.

— all of these hold:
— the node has at least one synchronous outgoing edge to a coordination-service
— the node's `stampedeGuard` is false

Random channel placement under heavy-tail trafficerror

shared-host-per-channel-without-isolation

With heavy-tail traffic a few channels carry most of the load. Assigning channels at random lands those hot channels on arbitrary hosts, and every tenant sharing a host suffers for it.

— all of these hold:
— the node's `channelAssignment` is "random"
— the design requirement `traffic.skew` is "heavy-tail"

Stateful WebSocket scale-in without drainwarning

stateful-websocket-scale-in-without-drain

Scaling a gateway down kills every live WebSocket on the removed instance at once. Without a drain step those clients all reconnect together.

— all of these hold:
— the node's `autoscaling` is true
— the node's `drainOnScaleIn` is false

Components · 20

vendor-neutral

Generic real-time gatewayrealtime-gatewaygenericthe kind itself

aws

API Gateway WebSocket APIaws-api-gateway-websocket5 defaults AWS AppSync Events APIaws-appsync-events5 defaults Amazon IVS Chataws-ivs-chat4 defaults

azure

Azure Fluid Relayazure-fluid-relay4 defaults Azure SignalR Serviceazure-signalr5 defaults Azure Web PubSubazure-web-pubsub5 defaults

default

Ablyably6 defaults Centrifugocentrifugo4 defaults Liveblocksliveblocks4 defaults Mercuremercure4 defaults Multicast market-data feedmulticast-feed3 defaults PartyKitpartykit5 defaults Phoenix Channelsphoenix-channels2 defaults Pusher Channelspusher5 defaults Pushpinpushpin4 defaults ASP.NET Core SignalRsignalr5 defaults Socket.IO serversocket-io-server2 defaults Soketisoketi4 defaults WebSocket gatewaywebsocket-gateway2 defaults

Source

1# yaml-language-server: $schema=../schema/kind.schema.json
2# Holds long-lived client connections and pushes events (WebSocket gateways, chat servers, long-poll and multicast feeds).
3# stampedeGuard and drainOnScaleIn default false so reconnect and scale-in rules can fire.
4schemaVersion: "1"
5type: "kind"
6id: "realtime-gateway"
7category: "edge"
8properties:
9  protocol:
10    type: "enum"
11    values: ["websocket", "sse", "long-poll", "grpc-stream", "udp-multicast"]
12    default: "websocket"
13  stateful:
14    type: "boolean"
15    default: true
16  autoscaling:
17    type: "boolean"
18    default: false
19  channelAssignment:
20    type: "enum"
21    values: ["random", "hash", "sticky"]
22    default: "random"
23    advanced: true
24  drainOnScaleIn:
25    type: "boolean"
26    default: false
27    advanced: true
28  stampedeGuard:
29    type: "boolean"
30    default: false
31    advanced: true
32  sequenceNumbers:
33    type: "boolean"
34    default: false
35    advanced: true
36  ackIntervalSeconds:
37    type: "integer"
38    advanced: true
39  subscriptionsPerUser:
40    type: "integer"
41    advanced: true
42  pushFallback:
43    type: "boolean"
44    default: false
45    advanced: true
46  managed:
47    type: "boolean"
48    default: false

The same page as markdown, for an agent: /catalogue/kinds/realtime-gateway.md