qt_websocket_server.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
#include <QHostAddress>
#include <QObject>
#include <QPointer>
#ifndef QT_NO_SSL
#include <QSslSocket>
#endif
#ifndef QT_NO_SSL
#include <QSslConfiguration>
#endif
#include <QTimer>
#include <QWebSocket>
#include <QWebSocketServer>
#include <atomic>
#include <chrono>
#include <cstddef>
#include <memory>
#include <morph/core/remote.hpp>
#include <morph/core/wire.hpp>
#include <morph/qt/detail/outbound_ledger.hpp>
#include <optional>
#include <string>
#include <unordered_map>
 
namespace morph::qt {
 
/// @brief Per-connection resource limits and bind/exposure policy enforced by
/// `QtWebSocketServer`.
///
/// Declared outside `QtWebSocketServer` so its default member initialisers are
/// fully parsed before any constructor default argument that names `Config{}`
/// is evaluated (same rationale as `morph::qt::QtWebSocketBackendConfig` and
/// `morph::offline::NetworkMonitorConfig`).
struct QtWebSocketServerConfig {
    /// @brief Max simultaneous live client connections. `0` = unbounded.
    ///
    /// A new connection beyond this count is closed immediately in `onNewConnection`,
    /// before any message exchange and before it is tracked internally.
    std::size_t maxConnections = 0;
 
    /// @brief Per-frame size cap enforced before a message reaches `RemoteServer::handle()`.
    ///
    /// Defaults to `morph::wire::kMaxEnvelopeBytes`, the wire layer's own bound, so an
    /// unconfigured server is capped only there. Set lower to reject oversized frames
    /// earlier, before the cost of a pool round-trip and JSON decode.
    std::size_t maxMessageBytes = ::morph::wire::kMaxEnvelopeBytes;
 
    /// @brief Per-connection token-bucket rate limit, in messages per second. `0` = unbounded.
    ///
    /// The bucket capacity equals `messagesPerSecond` (an immediate one-second
    /// burst is allowed right after connecting), refilling continuously at that
    /// rate. A frame that arrives with an empty bucket is **refused, not
    /// queued**: it never reaches `RemoteServer`, and the sender is answered
    /// with an `err "rate limited"` addressed to that frame's own `callId`, so
    /// a caller's `Completion` fails rather than waiting forever. The
    /// connection stays open — throttling slows a client down, it does not
    /// evict one. See `docs/spec/core/backend.md`.
    std::size_t messagesPerSecond = 0;
 
    /// @brief Time allowed for a newly-accepted connection to send its first text
    ///        frame before it is closed. `0` = disabled.
    ///
    /// `QWebSocketServer::newConnection()` fires only after the WebSocket (and, in
    /// `SecureMode`, TLS) opening handshake has already completed, so in practice
    /// this bounds time-to-first-frame after that point, not the handshake itself
    /// — Qt exposes no earlier hook at this layer.
    std::chrono::milliseconds handshakeTimeout{0};
 
    /// @brief Time a connection may go without sending any frame before it is
    ///        closed. `0` = disabled.
    ///
    /// Checked by a periodic housekeeping sweep (roughly once per second), so the
    /// actual close can lag the configured value by up to that sweep interval.
    std::chrono::milliseconds idleTimeout{0};
 
    /// @brief Time a frame handed to a connection may stay unwritten before
    ///        the connection is closed. `0` = disabled.
    ///
    /// A peer that stops reading leaves the oldest frame queued on its socket;
    /// once that frame is older than this, the socket is aborted, so the
    /// connection is retired — its models reclaimed, its events no longer
    /// written — instead of holding frames it will never read. The same bound,
    /// with the same default, as `morph::net::SocketServerConfig::sendTimeout`.
    std::chrono::milliseconds sendTimeout{30000};
 
    /// @brief Address `listen()` binds to. Default `QHostAddress::LocalHost`.
    QHostAddress bindAddress = QHostAddress::LocalHost;
 
    /// @brief Deliberate opt-out of the exposure guard: set `true` only to
    /// knowingly serve plaintext (no TLS) on a non-loopback `bindAddress`.
    bool allowPlaintextExposure = false;
};
 
/// @brief Qt WebSocket server that bridges incoming connections to a `RemoteServer`.
///
/// Listens for WebSocket clients, receives their text messages, and forwards each
/// one to `RemoteServer::handle()`. Replies are sent back to the originating client.
///
/// @par TLS
/// Pass a `QSslConfiguration` to enable `wss://`. The configuration should be built
/// from a certificate file, a Qt resource, or a byte array before being passed in.
///
/// @par SSL-less Qt builds (`QT_NO_SSL`, including the standard Qt-for-WebAssembly build)
/// The constructor's `tls` parameter does not exist at all when Qt itself was
/// configured without SSL — `QSslConfiguration` isn't a type Qt provides in that
/// configuration. Such a server always constructs in `NonSecureMode`; see
/// `QtWebSocketBackend`'s equivalent doc comment for the client-side rationale.
///
/// @par Resource limits
/// Pass a `QtWebSocketServerConfig` to bound connection count, per-frame size,
/// per-connection message rate, handshake/idle time, and how long a frame may
/// stay unwritten. All fields default to unbounded, except `maxMessageBytes`,
/// which defaults to the wire-layer cap, and `sendTimeout`, which defaults to
/// 30 s.
///
/// @par Bind address & plaintext-exposure guard
/// `listen()` refuses — returns `false` and logs at `morph::log::LogLevel::error`
/// — when `cfg.bindAddress` is not loopback, no TLS configuration was passed to
/// the constructor, and `cfg.allowPlaintextExposure` is `false`. See
/// `QtWebSocketServerConfig` and security.md's "Transport security" section.
///
/// @par Server-initiated events
/// Each connection is handed to `RemoteServer::setConnectionWriter` as it is
/// accepted, so `RemoteServer::post` reaches it. Every frame the server writes
/// to a connection, replies and events alike, counts toward that connection's
/// backlog by the size of its encoded envelope until the socket has written
/// it; when the backlog falls below `backend::kEventBacklogLow`, the server is
/// told through `RemoteServer::connectionDrained`. A connection whose oldest
/// unwritten frame is older than `QtWebSocketServerConfig::sendTimeout` is
/// aborted.
///
/// @par Usage
/// Call `listen()` to start accepting connections, and `port()` to discover the
/// bound port (useful when @p port was 0 — let the OS assign a free port).
/// Call `close()` or destroy the object to stop the server.
class QtWebSocketServer : public QObject {
    Q_OBJECT
public:
    /// @brief Alias for the per-connection limits configuration struct.
    using Config = QtWebSocketServerConfig;
 
    /// @brief Constructs the server and prepares it to listen on @p port.
    ///
    /// The server does not start accepting connections until `listen()` is called.
    ///
    /// @param server  `RemoteServer` instance that processes incoming messages.
    /// @param port    TCP port to listen on. Pass 0 to let the OS pick a free port.
    /// @param tls     If non-null, enables TLS (`wss://`) with this configuration. Not
    ///                declared at all on an SSL-less Qt build (`QT_NO_SSL`) — see the
    ///                class doc comment's "SSL-less Qt builds" section.
    /// @param cfg     Per-connection resource limits. Default: everything unbounded
    ///                except `maxMessageBytes`, which defaults to the wire-layer cap.
    /// @param parent  Optional Qt parent object.
    explicit QtWebSocketServer(::morph::backend::RemoteServer& server, quint16 port = 0,
#ifndef QT_NO_SSL
                               std::optional<QSslConfiguration> tls = std::nullopt,
#endif
                               QtWebSocketServerConfig cfg = QtWebSocketServerConfig{}, QObject* parent = nullptr);
 
    /// @brief Closes the server and disconnects all clients.
    ~QtWebSocketServer() override;
 
    // Neither copyable nor movable: a QObject with signal/slot connections bound
    // to this address, holding per-client state keyed by QWebSocket pointer.
    QtWebSocketServer(const QtWebSocketServer&) = delete;
    QtWebSocketServer& operator=(const QtWebSocketServer&) = delete;
    QtWebSocketServer(QtWebSocketServer&&) = delete;
    QtWebSocketServer& operator=(QtWebSocketServer&&) = delete;
 
    /// @brief Starts listening for incoming WebSocket connections.
    ///
    /// Refuses — returns `false` without binding, and logs at
    /// `morph::log::LogLevel::error` — when the configured `bindAddress` is not
    /// loopback, no TLS configuration was passed to the constructor, and
    /// `allowPlaintextExposure` is `false`. See `QtWebSocketServerConfig`.
    ///
    /// @return `true` if the server successfully bound to the requested port.
    bool listen();
 
    /// @brief Returns the port the server is currently bound to.
    ///
    /// When constructed with port 0, this returns the OS-assigned port after
    /// a successful `listen()` call.
    /// @return Bound TCP port number.
    [[nodiscard]] quint16 port() const;
 
    /// @brief Stops accepting new connections and closes the server socket.
    void close();
 
    /// @brief Gracefully stops the server: refuse new work, let in-flight
    ///        replies deliver, close each client with a proper WebSocket
    ///        close frame, then hard-stop anything still connected.
    ///
    /// Sequence: `QWebSocketServer::pauseAccepting()` (no new connections),
    /// `RemoteServer::beginShutdown()` (new `register`/`execute` now fail
    /// fast with `"server shutting down"`), waiting up to @p deadline for
    /// `RemoteServer::drainedWithin()` to report every in-flight execute has
    /// replied, sending each still-connected client a real close frame
    /// (`CloseCodeGoingAway`, reason `"server shutting down"`) instead of an
    /// abort, and finally running the `close()` hard stop for whatever
    /// @p deadline did not leave time to finish gracefully.
    ///
    /// Pumps the Qt event loop internally while it waits, so it is safe to
    /// call from the Qt thread — which is also the thread that must run
    /// `sendTextMessage` for replies and close frames to actually reach
    /// clients.
    ///
    /// @param deadline Total time budget for the whole sequence, measured
    ///                 from the moment this call starts. Whatever the drain
    ///                 and graceful-close steps have not finished within it
    ///                 is hard-stopped exactly as `close()` does.
    /// @return `true` if every in-flight execute drained before @p deadline
    ///         elapsed; `false` if the hard stop had to reclaim stragglers.
    bool closeGracefully(std::chrono::milliseconds deadline);
 
    /// @brief Qt slot called when a new client connects.
    Q_SLOT void onNewConnection();
 
    /// @brief Qt slot called when a connected client sends a text message.
    /// @param message Raw text frame received from the client.
    Q_SLOT void onTextMessage(const QString& message);
 
    /// @brief Qt slot called when a client disconnects.
    Q_SLOT void onDisconnected();
 
    /// @brief Qt slot called when a client's socket has written @p bytes.
    ///
    /// Releases from the connection's backlog every frame those bytes
    /// complete, and re-arms its send timeout for the oldest frame left.
    /// @param bytes Bytes the socket just wrote.
    Q_SLOT void onBytesWritten(qint64 bytes);
 
private:
    /// @brief Per-connection state tracked between accept and disconnect.
    struct ClientState {
        /// @brief The connection this state belongs to (for symmetry with the map key; unused for lookup).
        QWebSocket* socket = nullptr;
 
        /// @brief Current token-bucket balance for `messagesPerSecond`.
        double tokens = 0.0;
 
        /// @brief Last time `tokens` was refilled; the next frame's refill is computed from it.
        std::chrono::steady_clock::time_point lastRefill;
 
        /// @brief Last time any frame was received on this connection (drives `idleTimeout`).
        std::chrono::steady_clock::time_point lastActivity;
 
        /// @brief One-shot timer enforcing `handshakeTimeout`; `nullptr` once cancelled by the
        ///        first frame, or if `handshakeTimeout == 0`.
        QTimer* handshakeTimer = nullptr;
 
        /// @brief Connection scope `RemoteServer::openConnection()` assigned this
        ///        client at accept time, so its disconnect can reclaim every model
        ///        it registered (see `RemoteServer::closeConnection`).
        ::morph::backend::ConnectionId cid = 0;
 
        /// @brief Bytes of encoded envelopes handed to this connection and not
        ///        yet written: the backlog `RemoteServer` reads.
        ///
        /// Added to on whichever thread hands over a frame, before the frame is
        /// queued to the Qt thread, so the count covers frames still on their
        /// way to the socket. Held by `shared_ptr` so the writer, kept on the
        /// server strand, can read it without reaching this state.
        std::shared_ptr<std::atomic<std::size_t>> backlog = std::make_shared<std::atomic<std::size_t>>(0);
 
        /// @brief Frames on the socket and not yet written, released as
        ///        `QWebSocket::bytesWritten` reports them out.
        detail::OutboundLedger unwritten;
 
#ifndef QT_NO_SSL
        /// @brief The TLS socket under `socket`, on a `SecureMode` server.
        ///
        /// `QWebSocket` reports encrypted bytes written but holds back only
        /// the plaintext it has not yet encrypted; what is encrypted and still
        /// unsent is on this socket, so a frame's position must count it.
        QPointer<QSslSocket> tls;
#endif
 
        /// @brief One-shot timer enforcing `sendTimeout` on the oldest
        ///        unwritten frame; `nullptr` if `sendTimeout == 0`.
        QTimer* sendTimer = nullptr;
    };
 
    /// @brief Counts @p envelope against the connection's backlog, then
    ///        queues it to the Qt thread to be written to @p socket.
    ///
    /// Callable from any thread: replies arrive on the server's pool, events
    /// on its strand. Dropped, its count released, if the server or the
    /// socket is gone by the time it reaches the Qt thread.
    /// @param server   This server, held weakly.
    /// @param socket   The connection's socket, held weakly.
    /// @param backlog  The connection's backlog counter.
    /// @param envelope The encoded envelope.
    /// @return `false` if there is no Qt application to queue to; the
    ///         envelope is dropped and its count released.
    static bool queueEnvelope(QPointer<QtWebSocketServer> const& server, QPointer<QWebSocket> const& socket,
                              std::shared_ptr<std::atomic<std::size_t>> const& backlog, std::string envelope);
 
    /// @brief Writes @p envelope, already counted, to @p socket and tracks it
    ///        until the socket has written it. On the Qt thread.
    /// @param socket   A tracked socket.
    /// @param state    @p socket's state.
    /// @param envelope The encoded envelope.
    void writeCounted(QWebSocket* socket, ClientState& state, std::string const& envelope);
 
    /// @brief Counts @p envelope against @p socket's backlog and writes it.
    ///        On the Qt thread.
    /// @param socket   A tracked socket.
    /// @param state    @p socket's state.
    /// @param envelope The encoded envelope.
    void writeNow(QWebSocket* socket, ClientState& state, std::string const& envelope);
 
    /// @brief Takes @p bytes off @p state's backlog, and tells the server if
    ///        that takes it below `backend::kEventBacklogLow`.
    /// @param state The connection.
    /// @param bytes What a frame added when it was handed over.
    void releaseBacklog(ClientState const& state, std::size_t bytes);
 
    /// @brief Arms @p state's send timer for its oldest unwritten frame, or
    ///        stops it when none is left.
    /// @param state The connection.
    void armSendTimer(ClientState& state) const;
 
    /// @brief Aborts @p socket if its oldest unwritten frame has outlived
    ///        `sendTimeout`; otherwise re-arms the timer.
    /// @param socket The connection's socket.
    void onSendTimer(QWebSocket* socket);
 
    /// @brief Bytes @p state's socket stack still holds unsent: the
    ///        `QWebSocket`'s own, plus, over TLS, the ciphertext not yet sent.
    /// @param state The connection.
    /// @return The bytes held.
    static qint64 pendingBytes(ClientState const& state);
 
#ifndef QT_NO_SSL
    /// @brief Finds the `QSslSocket` a `SecureMode` server accepted
    ///        @p socket over.
    /// @param socket The upgraded connection.
    /// @return The TLS socket, or null when there is none or it cannot be found.
    [[nodiscard]] QSslSocket* findTlsSocket(QWebSocket const* socket) const;
#endif
 
    /// @brief Releases every frame @p state still holds and drops its timers.
    ///        Called when the connection goes away.
    /// @param state The connection.
    static void forgetConnection(ClientState& state);
 
    /// @brief Refills @p state's token bucket for elapsed time, then consumes one
    ///        token if available.
    /// @param state Per-connection state to update.
    /// @return `true` if a token was available (the frame is admitted), `false` if
    ///         the bucket was empty (the frame must be dropped).
    bool consumeToken(ClientState& state) const;
 
    /// @brief Qt slot: periodic sweep that closes any connection idle past `idleTimeout`.
    Q_SLOT void onHousekeepingTick();
 
    ::morph::backend::RemoteServer& _server;
    quint16 _requestedPort;
    QtWebSocketServerConfig _cfg;
    QWebSocketServer _wsServer;
    std::unordered_map<QWebSocket*, ClientState> _clients;
    QTimer _housekeepingTimer;
};
 
}  // namespace morph::qt