|
| 1 | +<!-- |
| 2 | +Licensed to the Apache Software Foundation (ASF) under one |
| 3 | +or more contributor license agreements. See the NOTICE file |
| 4 | +distributed with this work for additional information |
| 5 | +regarding copyright ownership. The ASF licenses this file |
| 6 | +to you under the Apache License, Version 2.0 (the |
| 7 | +"License"); you may not use this file except in compliance |
| 8 | +with the License. You may obtain a copy of the License at |
| 9 | +
|
| 10 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 11 | +
|
| 12 | +Unless required by applicable law or agreed to in writing, |
| 13 | +software distributed under the License is distributed on an |
| 14 | +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | +KIND, either express or implied. See the License for the |
| 16 | +specific language governing permissions and limitations |
| 17 | +under the License. |
| 18 | +--> |
| 19 | +# Superset WebSocket Server |
| 20 | + |
| 21 | +A Node.js WebSocket server for sending async event data to the Superset web application frontend. |
| 22 | + |
| 23 | +## Requirements |
| 24 | + |
| 25 | +- Node.js 12+ (not tested with older versions) |
| 26 | +- Redis 5+ |
| 27 | + |
| 28 | +To use this feature, Superset needs to be configured to enable global async queries and to use WebSockets as the transport (see below). |
| 29 | + |
| 30 | +## Architecture |
| 31 | + |
| 32 | +This implementation is based on the architecture defined in [SIP-39](https://github.com/apache/superset/issues/9190). |
| 33 | + |
| 34 | +### Streams |
| 35 | + |
| 36 | +Async events are pushed to [Redis Streams](https://redis.io/topics/streams-intro) from the [Superset Flask app](https://github.com/preset-io/superset/blob/master/superset/utils/async_query_manager.py). An event for a particular user is published to two streams: 1) the global event stream that includes events for all users, and 2) a channel/session-specific stream only for the user. This approach provides a good balance of performance (reading off of a single global stream) and fault tolerance (dropped connections can "catch up" by reading from the channel-specific stream). |
| 37 | + |
| 38 | +Note that Redis Stream [consumer groups](https://redis.io/topics/streams-intro#consumer-groups) are not used here due to the fact that each group receives a subset of the data for a stream, and WebSocket clients have a persistent connection to each app instance, requiring access to all data in a stream. Horizontal scaling of the WebSocket app requires having multiple WebSocket servers, each with full access to the Redis Stream data. |
| 39 | + |
| 40 | +### Connection |
| 41 | + |
| 42 | +When a user's browser initially connects to the WebSocket server, it does so over HTTP, which includes the JWT authentication cookie, set by the Flask app, in the request. _Note that due to the cookie-based authentication method, the WebSocket server must be run on the same host as the web application._ The server validates the JWT token by using the shared secret (config: `jwtSecret`), and if valid, proceeds to upgrade the connection to a WebSocket. The user's session-based "channel" ID is contained in the JWT, and serves as the basis for sending received events to the user's connected socket(s). |
| 43 | + |
| 44 | +A user may have multiple WebSocket connections under a single channel (session) ID. This would be the case if the user has multiple browser tabs open, for example. In this scenario, **all events received for a specific channel are sent to all connected sockets**, leaving it to the consumer to decide which events are relevant to the current application context. |
| 45 | + |
| 46 | +### Reconnection |
| 47 | + |
| 48 | +It is expected that a user's WebSocket connection may be dropped or interrupted due to fluctuating network conditions. The Superset frontend code keeps track of the last received async event ID, and attempts to reconnect to the WebSocket server with a `last_id` query parameter in the initial HTTP request. If a connection includes a valid `last_id` value, events that may have already been received and sent unsuccessfully are read from the channel-based Redis Stream and re-sent to the new WebSocket connection. The global event stream flow then assumes responsibility for sending subsequent events to the connected socket(s). |
| 49 | + |
| 50 | +### Connection Management |
| 51 | + |
| 52 | +The server utilizes the standard WebSocket [ping/pong functionality](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#pings_and_pongs_the_heartbeat_of_websockets) to determine if active WebSocket connections are still alive. Active sockets are sent a _ping_ regularly (config: `pingSocketsIntervalMs`), and the internal _sockets_ registry is updated with a timestamp when a _pong_ response is received. If a _pong_ response has not been received before the timeout period (config: `socketResponseTimeoutMs`), the socket is terminated and removed from the internal registry. |
| 53 | + |
| 54 | +In addition to periodic socket connection cleanup, the internal _channels_ registry is regularly "cleaned" (config: `gcChannelsIntervalMs`) to remove stale references and prevent excessive memory consumption over time. |
| 55 | + |
| 56 | +## Install |
| 57 | + |
| 58 | +Install dependencies: |
| 59 | +``` |
| 60 | +npm install |
| 61 | +``` |
| 62 | + |
| 63 | +## WebSocket Server Configuration |
| 64 | + |
| 65 | +Copy `config.example.json` to `config.json` and adjust the values for your environment. |
| 66 | + |
| 67 | +## Superset Configuration |
| 68 | + |
| 69 | +Configure the Superset Flask app to enable global async queries (in `superset_config.py`): |
| 70 | + |
| 71 | +Enable the `GLOBAL_ASYNC_QUERIES` feature flag: |
| 72 | +``` |
| 73 | +"GLOBAL_ASYNC_QUERIES": True |
| 74 | +``` |
| 75 | + |
| 76 | +Configure the following Superset values: |
| 77 | +``` |
| 78 | +GLOBAL_ASYNC_QUERIES_TRANSPORT = "ws" |
| 79 | +GLOBAL_ASYNC_QUERIES_WEBSOCKET_URL = "ws://<host>:<port>/" |
| 80 | +``` |
| 81 | + |
| 82 | +Note that the WebSocket server must be run on the same hostname (different port) for cookies to be shared between the Flask app and the WebSocket server. |
| 83 | + |
| 84 | +The following config values must contain the same values in both the Flask app config and `config.json`: |
| 85 | +``` |
| 86 | +GLOBAL_ASYNC_QUERIES_REDIS_CONFIG |
| 87 | +GLOBAL_ASYNC_QUERIES_REDIS_STREAM_PREFIX |
| 88 | +GLOBAL_ASYNC_QUERIES_JWT_COOKIE_NAME |
| 89 | +GLOBAL_ASYNC_QUERIES_JWT_SECRET |
| 90 | +``` |
| 91 | + |
| 92 | +More info on Superset configuration values for async queries: https://github.com/apache/superset/blob/master/CONTRIBUTING.md#async-chart-queries |
| 93 | + |
| 94 | +## Running |
| 95 | + |
| 96 | +Running locally via dev server: |
| 97 | +``` |
| 98 | +npm run dev-server |
| 99 | +``` |
| 100 | + |
| 101 | +Running in production: |
| 102 | +``` |
| 103 | +npm run build && npm start |
| 104 | +``` |
| 105 | + |
| 106 | +*TODO: containerization* |
0 commit comments