DeterministicESPAsyncWebServer.cpp

Go to the documentation of this file.

// Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file DeterministicESPAsyncWebServer.cpp
 * @brief Layer 7 (Application) — HTTP routing and request handler implementation.
 *
 * **Dispatch pipeline (called from DetWebServer::handle())**
 * ```
 * handle()
 *   └─ server_tick()                 ← drain FreeRTOS event queue
 *   └─ for each slot:
 *        PARSE_COMPLETE          → match_and_execute()
 *        PARSE_ERROR             → send(400)
 *        PARSE_ENTITY_TOO_LARGE  → send(413)
 *        PARSE_URI_TOO_LONG      → send(414)
 * ```
 *
 * **Route table**
 * Routes are stored in a fixed-size array of `Route` structs.  Both exact
 * and wildcard (suffix `*`) routes are supported; exact routes always take
 * priority because the loop checks them in insertion order and returns on
 * the first match.
 *
 * **PCB lifecycle in send() / send_empty()**
 * Before writing to the PCB the slot is set to `CONN_FREE` and the pcb
 * pointer is nulled.  This mirrors the pattern in transport.cpp:
 *   1. Save a local copy of the pcb pointer.
 *   2. Detach our slot from it (`tcp_arg(pcb, nullptr)`).
 *   3. Null out `conn->pcb` and set `conn->state = CONN_FREE`.
 *   4. Do the write + close/abort on the saved local pointer.
 *
 * This means any lwIP error callback that fires mid-write sees the slot as
 * already free and takes no action — preventing a double-free scenario.
 */
 
#include "DeterministicESPAsyncWebServer.h"
#if DETWS_ENABLE_WEBSOCKET
#include "network_drivers/sha1.h"
#include "network_drivers/base64.h"
#elif DETWS_ENABLE_AUTH
#include "network_drivers/base64.h"
#endif
#include <string.h>
#include <stdio.h>
 
#if DETWS_ENABLE_WEBSOCKET
// Magic GUID concatenated to the client key for the WS accept hash (RFC 6455 §4.2.2)
static const char WS_MAGIC[] = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
#endif
 
/**
 * @brief Convert an HTTP status code to its standard reason phrase.
 *
 * Covers the 18 codes that arise in typical REST micro-server usage.
 * Unknown codes produce "Unknown" so callers never receive a null pointer.
 *
 * @param code HTTP status integer.
 * @return Pointer to a string-literal reason phrase; never null.
 */
static const char *status_text(int code)
{
    switch (code)
    {
    case 200:
        return "OK";
    case 201:
        return "Created";
    case 204:
        return "No Content";
    case 301:
        return "Moved Permanently";
    case 302:
        return "Found";
    case 304:
        return "Not Modified";
    case 400:
        return "Bad Request";
    case 401:
        return "Unauthorized";
    case 403:
        return "Forbidden";
    case 404:
        return "Not Found";
    case 405:
        return "Method Not Allowed";
    case 408:
        return "Request Timeout";
    case 409:
        return "Conflict";
    case 413:
        return "Payload Too Large";
    case 414:
        return "URI Too Long";
    case 429:
        return "Too Many Requests";
    case 500:
        return "Internal Server Error";
    case 501:
        return "Not Implemented";
    case 503:
        return "Service Unavailable";
    default:
        return "Unknown";
    }
}
 
/**
 * @brief Map a method string (from the parsed request line) to an HttpMethod enum.
 *
 * Falls through to HTTP_GET for any unrecognised method.  This keeps the
 * no-match path simple: the route table will fail to find an exact method
 * match and will return 404 (or invoke the not-found handler).
 *
 * @param m Null-terminated method string, e.g. "POST".
 * @return Matching HttpMethod enum value.
 */
static HttpMethod parse_method(const char *m)
{
    if (strcmp(m, "POST") == 0)
        return HTTP_POST;
    if (strcmp(m, "PUT") == 0)
        return HTTP_PUT;
    if (strcmp(m, "DELETE") == 0)
        return HTTP_DELETE;
    if (strcmp(m, "PATCH") == 0)
        return HTTP_PATCH;
    if (strcmp(m, "HEAD") == 0)
        return HTTP_HEAD;
    if (strcmp(m, "OPTIONS") == 0)
        return HTTP_OPTIONS;
    return HTTP_GET;
}
 
size_t DetWebServer::heap_needed()    { return DeterministicAsyncTCP::heap_needed(); }
bool   DetWebServer::heap_available() { return DeterministicAsyncTCP::heap_available(); }
 
DetWebServer::DetWebServer() : _route_count(0), _port(0), _not_found_handler(nullptr), _cors_enabled(false)
{
    for (int i = 0; i < MAX_ROUTES; i++)
        _routes[i] = {};  // zero all fields (auth_required, handlers, flags, etc.)
    _cors_header_buf[0] = '\0';
}
 
int32_t DetWebServer::begin(uint16_t port, const WebServerConfig *cfg)
{
    _port = port;
    for (uint8_t i = 0; i < MAX_CONNS; i++)
        http_reset(i);
#if DETWS_ENABLE_WEBSOCKET
    ws_init();
#endif
#if DETWS_ENABLE_SSE
    sse_init();
#endif
    return DeterministicAsyncTCP::init(port, cfg);
}
 
int32_t DetWebServer::restart(const WebServerConfig *cfg)
{
    if (_port == 0)
        return -1;
    stop();
    return begin(_port, cfg);
}
 
void DetWebServer::stop()
{
    DeterministicAsyncTCP::stop();
    for (uint8_t i = 0; i < MAX_CONNS; i++)
        http_reset(i);
#if DETWS_ENABLE_WEBSOCKET
    ws_init();
#endif
#if DETWS_ENABLE_SSE
    sse_init();
#endif
}
 
/**
 * @brief Register a route in the route table.
 *
 * Paths are stored null-terminated and truncated to MAX_PATH_LEN.  The
 * trailing character of the stored path is inspected to detect wildcard
 * routes: any path ending in `*` is treated as a prefix match.
 *
 * Registrations beyond MAX_ROUTES are silently ignored — callers should
 * verify return values if overflow is a concern.
 *
 * @param path     URL path to match, e.g. "/api/*".
 * @param method   HTTP method that triggers this route.
 * @param callback Handler invoked with (slot_id, request).
 */
static void fill_route_base(Route *r, const char *path)
{
    strncpy(r->path, path, MAX_PATH_LEN - 1);
    r->path[MAX_PATH_LEN - 1] = '\0';
    r->is_active   = true;
    size_t len     = strlen(r->path);
    r->is_wildcard = (len > 0 && r->path[len - 1] == '*');
}
 
void DetWebServer::on(const char *path, HttpMethod method, Handler callback)
{
    if (_route_count >= MAX_ROUTES)
        return;
    Route *r    = &_routes[_route_count++];
    fill_route_base(r, path);
    r->type     = ROUTE_HTTP;
    r->method   = method;
    r->callback = callback;
}
 
#if DETWS_ENABLE_AUTH
void DetWebServer::on(const char *path, HttpMethod method, Handler callback,
                      const char *realm, const char *user, const char *pass)
{
    if (_route_count >= MAX_ROUTES)
        return;
    Route *r    = &_routes[_route_count++];
    fill_route_base(r, path);
    r->type          = ROUTE_HTTP;
    r->method        = method;
    r->callback      = callback;
    r->auth_required = true;
    strncpy(r->auth_realm, realm, MAX_AUTH_LEN - 1);
    r->auth_realm[MAX_AUTH_LEN - 1] = '\0';
    strncpy(r->auth_user, user, MAX_AUTH_LEN - 1);
    r->auth_user[MAX_AUTH_LEN - 1] = '\0';
    strncpy(r->auth_pass, pass, MAX_AUTH_LEN - 1);
    r->auth_pass[MAX_AUTH_LEN - 1] = '\0';
}
#endif // DETWS_ENABLE_AUTH
 
#if DETWS_ENABLE_WEBSOCKET
void DetWebServer::on_ws(const char *path,
                         WsConnectHandler on_connect,
                         WsMessageHandler on_message,
                         WsCloseHandler   on_close)
{
    if (_route_count >= MAX_ROUTES)
        return;
    Route *r       = &_routes[_route_count++];
    fill_route_base(r, path);
    r->type        = ROUTE_WS;
    r->ws_connect  = on_connect;
    r->ws_message  = on_message;
    r->ws_close    = on_close;
}
#endif // DETWS_ENABLE_WEBSOCKET
 
#if DETWS_ENABLE_SSE
void DetWebServer::on_sse(const char *path, SseConnectHandler on_connect)
{
    if (_route_count >= MAX_ROUTES)
        return;
    Route *r       = &_routes[_route_count++];
    fill_route_base(r, path);
    r->type        = ROUTE_SSE;
    r->sse_connect = on_connect;
}
#endif // DETWS_ENABLE_SSE
 
void DetWebServer::on_not_found(Handler callback)
{
    _not_found_handler = callback;
}
 
/**
 * @brief Enable CORS and pre-build the Access-Control response header block.
 *
 * The header string is constructed once here rather than at response time to
 * avoid repeated snprintf calls on the hot path.  It is stored in
 * `_cors_header_buf[]` and injected verbatim into every response when
 * `_cors_enabled` is true.
 *
 * Passing an empty or null origin disables CORS without clearing the buffer —
 * only the `_cors_enabled` flag matters at dispatch time.
 *
 * @param origin Value for the Access-Control-Allow-Origin header, e.g. "*".
 */
void DetWebServer::set_cors(const char *origin)
{
    if (!origin || origin[0] == '\0')
    {
        _cors_enabled = false;
        _cors_header_buf[0] = '\0';
        return;
    }
    snprintf(_cors_header_buf, CORS_HDR_BUF_SIZE,
             "Access-Control-Allow-Origin: %s\r\n"
             "Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS\r\n"
             "Access-Control-Allow-Headers: Content-Type\r\n",
             origin);
    _cors_enabled = true;
}
 
/**
 * @brief Test whether a route path matches an incoming request path.
 *
 * Exact routes use strcmp (full-string equality).  Wildcard routes use
 * strncmp against the prefix up to (but not including) the trailing `*`.
 *
 * @param route       Registered route path, potentially ending in `*`.
 * @param is_wildcard True when the route was registered with a trailing `*`.
 * @param req_path    Incoming request path from the parsed HTTP request line.
 * @return True if the route matches the request path.
 */
bool DetWebServer::path_matches(const char *route, bool is_wildcard, const char *req_path)
{
    if (!is_wildcard)
        return strcmp(route, req_path) == 0;
 
    // Prefix match: compare everything up to (but not including) the '*'
    size_t prefix_len = strlen(route) - 1;
    return strncmp(route, req_path, prefix_len) == 0;
}
 
/**
 * @brief Main application tick — tick the session layer then dispatch completed requests.
 *
 * Call this repeatedly from loop().  Each call:
 *   1. Calls server_tick() which runs timeout sweeps + drains the event queue.
 *   2. Walks all slots; any in PARSE_COMPLETE is dispatched via match_and_execute().
 *   3. Any slot left in PARSE_COMPLETE after dispatch (i.e., callback did not
 *      send a response) is reset so it doesn't block the slot.
 *   4. Any slot in PARSE_ERROR receives an automatic 400 response.
 *   5. Any slot in PARSE_ENTITY_TOO_LARGE receives an automatic 413 response.
 *   6. Any slot in PARSE_URI_TOO_LONG receives an automatic 414 response.
 */
void DetWebServer::handle()
{
    server_tick();
 
    for (uint8_t i = 0; i < MAX_CONNS; i++)
    {
#if DETWS_ENABLE_WEBSOCKET
        // WebSocket slot — drain ring buffer and dispatch ready frames
        WsConn *ws = ws_find(i);
        if (ws)
        {
            ws_parse(ws);
 
            if (ws->parse_state == WS_FRAME_READY)
            {
                for (uint8_t r = 0; r < _route_count; r++)
                {
                    if (_routes[r].type == ROUTE_WS && _routes[r].ws_message)
                    {
                        _routes[r].ws_message(ws->ws_id);
                        break;
                    }
                }
                ws_reset_frame(ws);
            }
            else if (ws->parse_state == WS_CLOSED || ws->parse_state == WS_ERROR)
            {
                for (uint8_t r = 0; r < _route_count; r++)
                {
                    if (_routes[r].type == ROUTE_WS && _routes[r].ws_close)
                    {
                        _routes[r].ws_close(ws->ws_id);
                        break;
                    }
                }
                ws_free(i);
                http_reset(i);
            }
            continue; // slot is owned by WS; skip HTTP dispatch
        }
#endif // DETWS_ENABLE_WEBSOCKET
 
#if DETWS_ENABLE_SSE
        // SSE slot — connection stays open, nothing to parse from client
        if (sse_find(i))
            continue;
#endif // DETWS_ENABLE_SSE
 
        // HTTP slot
        if (http_pool[i].parse_state == PARSE_COMPLETE)
        {
            match_and_execute(i);
            if (http_pool[i].parse_state == PARSE_COMPLETE)
                http_reset(i);
        }
        else if (http_pool[i].parse_state == PARSE_ERROR)
        {
            send(i, 400, "text/plain", "Bad Request");
        }
        else if (http_pool[i].parse_state == PARSE_ENTITY_TOO_LARGE)
        {
            send(i, 413, "text/plain", "Payload Too Large");
        }
        else if (http_pool[i].parse_state == PARSE_URI_TOO_LONG)
        {
            send(i, 414, "text/plain", "URI Too Long");
        }
    }
}
 
// ---------------------------------------------------------------------------
// Diagnostic endpoint
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_DIAG
void DetWebServer::diag(uint8_t slot_id)
{
    send(slot_id, 200, "application/json", DETWS_DIAG_JSON);
}
#endif
 
// ---------------------------------------------------------------------------
// WebSocket handshake helpers
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_WEBSOCKET
/**
 * @brief Compute the Sec-WebSocket-Accept value for the HTTP 101 response.
 *
 * Concatenates the client key with the RFC 6455 magic GUID, SHA-1 hashes
 * the result, and base64-encodes the 20-byte digest into @p out.
 * @p out must be at least 29 bytes (28 base64 chars + null terminator).
 */
static const size_t WS_MAX_KEY_LEN = 64;
 
static bool ws_accept_key(const char *client_key, char *out)
{
    size_t key_len = strnlen(client_key, WS_MAX_KEY_LEN + 1);
    if (key_len > WS_MAX_KEY_LEN)
    {
        out[0] = '\0';
        return false;
    }
    size_t magic_len = sizeof(WS_MAGIC) - 1;
    char concat[WS_MAX_KEY_LEN + sizeof(WS_MAGIC)];
    memcpy(concat,           client_key, key_len);
    memcpy(concat + key_len, WS_MAGIC,   magic_len);
 
    uint8_t digest[SHA1_DIGEST_LEN];
    sha1((const uint8_t *)concat, key_len + magic_len, digest);
    base64_encode(digest, SHA1_DIGEST_LEN, out);
    return true;
}
 
/**
 * @brief Send the HTTP 101 Switching Protocols handshake and upgrade the slot.
 *
 * Does NOT close the TCP connection -- that is intentional.  The slot moves
 * from HTTP parse ownership to WS frame parse ownership.
 */
static bool ws_do_upgrade(uint8_t slot_id, HttpReq *req,
                          WsConnectHandler on_connect)
{
    const char *client_key = http_get_header(req, "Sec-WebSocket-Key");
    if (!client_key)
        return false;
 
    char accept[32];
    if (!ws_accept_key(client_key, accept))
        return false;
 
    TcpConn *conn = &conn_pool[slot_id];
    if (conn->state != CONN_ACTIVE || !conn->pcb)
        return false;
 
    char hdr[WS_HDR_BUF_SIZE];
    int  hlen = snprintf(hdr, sizeof(hdr),
        "HTTP/1.1 101 Switching Protocols\r\n"
        "Upgrade: websocket\r\n"
        "Connection: Upgrade\r\n"
        "Sec-WebSocket-Accept: %s\r\n\r\n",
        accept);
 
    tcp_write(conn->pcb, hdr, (u16_t)hlen, TCP_WRITE_FLAG_COPY);
    tcp_output(conn->pcb);
 
    // Reset HTTP parser but keep the TCP slot -- WS owns it now
    http_reset(slot_id);
 
    WsConn *ws = ws_alloc(slot_id);
    if (!ws)
    {
        // No WS slot available -- abort the connection
        tcp_arg(conn->pcb, nullptr);
        conn->state = CONN_FREE;
        conn->pcb   = nullptr;
        return false;
    }
 
    if (on_connect)
        on_connect(ws->ws_id);
 
    return true;
}
#endif // DETWS_ENABLE_WEBSOCKET
 
// ---------------------------------------------------------------------------
// SSE upgrade helper
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_SSE
/**
 * @brief Send the HTTP 200 + SSE headers and promote the slot to SSE mode.
 */
static bool sse_do_upgrade(uint8_t slot_id, HttpReq *req,
                           SseConnectHandler on_connect)
{
    TcpConn *conn = &conn_pool[slot_id];
    if (conn->state != CONN_ACTIVE || !conn->pcb)
        return false;
 
    static const char SSE_HDR[] =
        "HTTP/1.1 200 OK\r\n"
        "Content-Type: text/event-stream\r\n"
        "Cache-Control: no-cache\r\n"
        "Connection: keep-alive\r\n\r\n";
 
    tcp_write(conn->pcb, SSE_HDR, (u16_t)(sizeof(SSE_HDR) - 1),
              TCP_WRITE_FLAG_COPY);
    tcp_output(conn->pcb);
 
    // Reset HTTP parser; SSE keeps the TCP slot open
    const char *path = req->path;
    http_reset(slot_id);
 
    SseConn *sse = sse_alloc(slot_id, path);
    if (!sse)
    {
        tcp_arg(conn->pcb, nullptr);
        conn->state = CONN_FREE;
        conn->pcb   = nullptr;
        return false;
    }
 
    if (on_connect)
        on_connect(sse->sse_id);
 
    return true;
}
#endif // DETWS_ENABLE_SSE
 
// ---------------------------------------------------------------------------
// Route dispatch
// ---------------------------------------------------------------------------
 
void DetWebServer::match_and_execute(uint8_t slot_id)
{
    HttpReq   *req    = &http_pool[slot_id];
    HttpMethod method = parse_method(req->method);
 
    // CORS preflight
    if (method == HTTP_OPTIONS && _cors_enabled)
    {
        send_empty(slot_id, 204);
        return;
    }
 
    // RFC 7230 §3.3.1: reject Transfer-Encoding
    if (http_get_header(req, "Transfer-Encoding") != nullptr)
    {
        send(slot_id, 501, "text/plain", "Not Implemented");
        return;
    }
 
#if DETWS_ENABLE_WEBSOCKET
    const char *upgrade_hdr = http_get_header(req, "Upgrade");
    bool is_ws_upgrade = (method == HTTP_GET)
                      && upgrade_hdr
                      && (strcasecmp(upgrade_hdr, "websocket") == 0);
#endif
 
    for (uint8_t i = 0; i < _route_count; i++)
    {
        Route *r = &_routes[i];
        if (!r->is_active)
            continue;
        if (!path_matches(r->path, r->is_wildcard, req->path))
            continue;
 
#if DETWS_ENABLE_WEBSOCKET
        if (r->type == ROUTE_WS)
        {
            if (!is_ws_upgrade)
            {
                send(slot_id, 400, "text/plain", "WebSocket upgrade required");
                return;
            }
            if (!ws_do_upgrade(slot_id, req, r->ws_connect))
                send(slot_id, 503, "text/plain", "Service Unavailable");
            return;
        }
#endif // DETWS_ENABLE_WEBSOCKET
 
#if DETWS_ENABLE_SSE
        if (r->type == ROUTE_SSE)
        {
            if (!sse_do_upgrade(slot_id, req, r->sse_connect))
                send(slot_id, 503, "text/plain", "Service Unavailable");
            return;
        }
#endif // DETWS_ENABLE_SSE
 
        // ROUTE_HTTP
        if (r->method != method)
            continue;
#if DETWS_ENABLE_AUTH
        if (r->auth_required && !check_basic_auth(slot_id, req, r))
        {
            send_unauth(slot_id, r->auth_realm);
            return;
        }
#endif // DETWS_ENABLE_AUTH
        r->callback(slot_id, req);
        return;
    }
 
    if (_not_found_handler)
        _not_found_handler(slot_id, req);
    else
        send(slot_id, 404, "text/plain", "Not Found");
}
 
/**
 * @brief Build and transmit an HTTP response with a body.
 *
 * Uses a 512-byte stack buffer for headers.  CORS headers are appended when
 * `_cors_enabled`.  The slot is freed (state → CONN_FREE, pcb → nullptr)
 * *before* the tcp_write + tcp_close sequence to ensure any error callback
 * that lwIP fires during the write sees the slot as already released.
 *
 * If the slot's connection is not active (e.g., already timed-out or the
 * PCB is null) the slot is reset and the function returns without writing.
 *
 * @param slot_id      Connection slot index.
 * @param code         HTTP status code, e.g. 200.
 * @param content_type MIME type string, e.g. "application/json".
 * @param payload      Null-terminated body string to send.
 */
void DetWebServer::send(uint8_t slot_id, int code, const char *content_type, const char *payload)
{
    TcpConn *conn = &conn_pool[slot_id];
    if (conn->state != CONN_ACTIVE || conn->pcb == nullptr)
    {
        http_reset(slot_id);
        return;
    }
 
    int payload_len = (int)strlen(payload);
 
    char header[RESP_HDR_BUF_SIZE];
    int hlen = snprintf(header, sizeof(header),
                        "HTTP/1.1 %d %s\r\n"
                        "Content-Type: %s\r\n"
                        "Content-Length: %d\r\n"
                        "%s"
                        "Connection: close\r\n\r\n",
                        code, status_text(code), content_type, payload_len,
                        _cors_enabled ? _cors_header_buf : "");
 
    struct tcp_pcb *pcb = conn->pcb;
    /*
     * Detach and free the slot before writing.  Any lwIP error callback
     * firing during tcp_write will see CONN_FREE and take no action.
     */
    tcp_arg(pcb, nullptr);
    conn->state = CONN_FREE;
    conn->pcb = nullptr;
 
    tcp_write(pcb, header, (u16_t)hlen, TCP_WRITE_FLAG_COPY);
    tcp_write(pcb, payload, (u16_t)payload_len, TCP_WRITE_FLAG_COPY);
    tcp_output(pcb);
 
    if (tcp_close(pcb) != ERR_OK)
        tcp_abort(pcb);
 
    http_reset(slot_id);
}
 
/**
 * @brief Build and transmit an HTTP response with no body.
 *
 * Used for CORS preflight (204) and any response where only status headers
 * are needed.  Behaves identically to send() regarding slot lifecycle and
 * PCB ownership transfer — the slot is freed before the lwIP write call.
 *
 * @param slot_id Connection slot index.
 * @param code    HTTP status code, e.g. 204.
 */
void DetWebServer::send_empty(uint8_t slot_id, int code)
{
    TcpConn *conn = &conn_pool[slot_id];
    if (conn->state != CONN_ACTIVE || conn->pcb == nullptr)
    {
        http_reset(slot_id);
        return;
    }
 
    char header[RESP_HDR_BUF_SIZE];
    int hlen = snprintf(header, sizeof(header),
                        "HTTP/1.1 %d %s\r\n"
                        "Content-Length: 0\r\n"
                        "%s"
                        "Connection: close\r\n\r\n",
                        code, status_text(code), _cors_enabled ? _cors_header_buf : "");
 
    struct tcp_pcb *pcb = conn->pcb;
    tcp_arg(pcb, nullptr);
    conn->state = CONN_FREE;
    conn->pcb = nullptr;
 
    tcp_write(pcb, header, (u16_t)hlen, TCP_WRITE_FLAG_COPY);
    tcp_output(pcb);
 
    if (tcp_close(pcb) != ERR_OK)
        tcp_abort(pcb);
 
    http_reset(slot_id);
}
 
// ---------------------------------------------------------------------------
// WebSocket public API
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_WEBSOCKET
void DetWebServer::ws_send_text(uint8_t ws_id, const char *text)
{
    if (ws_id >= MAX_WS_CONNS || !ws_pool[ws_id].active)
        return;
    WsConn *ws = &ws_pool[ws_id];
    if (ws->parse_state == WS_CLOSED || ws->parse_state == WS_ERROR)
        return;
    uint16_t len = (uint16_t)strlen(text);
    if (ws_send_frame(ws, WS_OP_TEXT, (const uint8_t *)text, len))
    {
        TcpConn *conn = &conn_pool[ws->slot_id];
        if (conn->pcb)
            tcp_output(conn->pcb);
    }
}
 
void DetWebServer::ws_send_binary(uint8_t ws_id, const uint8_t *data, uint16_t len)
{
    if (ws_id >= MAX_WS_CONNS || !ws_pool[ws_id].active)
        return;
    WsConn *ws = &ws_pool[ws_id];
    if (ws->parse_state == WS_CLOSED || ws->parse_state == WS_ERROR)
        return;
    if (ws_send_frame(ws, WS_OP_BINARY, data, len))
    {
        TcpConn *conn = &conn_pool[ws->slot_id];
        if (conn->pcb)
            tcp_output(conn->pcb);
    }
}
 
void DetWebServer::ws_disconnect(uint8_t ws_id)
{
    if (ws_id >= MAX_WS_CONNS || !ws_pool[ws_id].active)
        return;
    WsConn *ws = &ws_pool[ws_id];
    ws_close(ws, WS_CLOSE_NORMAL);
    TcpConn *conn = &conn_pool[ws->slot_id];
    if (conn->pcb)
        tcp_output(conn->pcb);
    // handle() detects WS_CLOSED next tick and fires ws_close callback
}
#endif // DETWS_ENABLE_WEBSOCKET
 
// ---------------------------------------------------------------------------
// Server-Sent Events public API
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_SSE
void DetWebServer::sse_send(uint8_t sse_id, const char *data,
                            const char *event, const char *id)
{
    if (sse_id >= MAX_SSE_CONNS || !sse_pool[sse_id].active)
        return;
    SseConn *sse = &sse_pool[sse_id];
    if (sse_write(sse, data, event, id))
    {
        TcpConn *conn = &conn_pool[sse->slot_id];
        if (conn->pcb)
            tcp_output(conn->pcb);
    }
}
 
void DetWebServer::sse_broadcast(const char *path, const char *data,
                                 const char *event, const char *id)
{
    for (int i = 0; i < MAX_SSE_CONNS; i++)
    {
        if (!sse_pool[i].active)
            continue;
        if (strcmp(sse_pool[i].path, path) != 0)
            continue;
        SseConn *sse = &sse_pool[i];
        if (sse_write(sse, data, event, id))
        {
            TcpConn *conn = &conn_pool[sse->slot_id];
            if (conn->pcb)
                tcp_output(conn->pcb);
        }
    }
}
#endif // DETWS_ENABLE_SSE
 
// ---------------------------------------------------------------------------
// Basic Auth helpers
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_AUTH
void DetWebServer::send_unauth(uint8_t slot_id, const char *realm)
{
    TcpConn *conn = &conn_pool[slot_id];
    if (conn->state != CONN_ACTIVE || !conn->pcb)
    {
        http_reset(slot_id);
        return;
    }
 
    static const char body[] = "Unauthorized";
    char header[RESP_HDR_BUF_SIZE];
    int hlen = snprintf(header, sizeof(header),
        "HTTP/1.1 401 Unauthorized\r\n"
        "WWW-Authenticate: Basic realm=\"%s\"\r\n"
        "Content-Type: text/plain\r\n"
        "Content-Length: %d\r\n"
        "%s"
        "Connection: close\r\n\r\n",
        realm, (int)(sizeof(body) - 1),
        _cors_enabled ? _cors_header_buf : "");
 
    struct tcp_pcb *pcb = conn->pcb;
    tcp_arg(pcb, nullptr);
    conn->state = CONN_FREE;
    conn->pcb   = nullptr;
 
    tcp_write(pcb, header, (u16_t)hlen, TCP_WRITE_FLAG_COPY);
    tcp_write(pcb, body, (u16_t)(sizeof(body) - 1), TCP_WRITE_FLAG_COPY);
    tcp_output(pcb);
 
    if (tcp_close(pcb) != ERR_OK)
        tcp_abort(pcb);
 
    http_reset(slot_id);
}
 
bool DetWebServer::check_basic_auth(uint8_t /*slot_id*/, HttpReq *req, const Route *r)
{
    const char *auth_hdr = http_get_header(req, "Authorization");
    if (!auth_hdr || strncmp(auth_hdr, "Basic ", 6) != 0)
        return false;
 
    uint8_t decoded[MAX_AUTH_LEN * 2 + 2];
    size_t  n = base64_decode(auth_hdr + 6, decoded);
    if (n == 0 || n >= sizeof(decoded))
        return false;
    decoded[n] = '\0';
 
    const char *colon = (const char *)memchr(decoded, ':', n);
    if (!colon)
        return false;
 
    size_t      ulen = (size_t)(colon - (const char *)decoded);
    const char *pass = colon + 1;
 
    return (ulen == strlen(r->auth_user))
        && (memcmp(decoded, r->auth_user, ulen) == 0)
        && (strcmp(pass, r->auth_pass) == 0);
}
#endif // DETWS_ENABLE_AUTH
 
// ---------------------------------------------------------------------------
// File serving
// ---------------------------------------------------------------------------
 
#if DETWS_ENABLE_FILE_SERVING
void DetWebServer::serve_file(uint8_t slot_id, fs::FS &file_sys,
                              const char *fs_path, const char *content_type)
{
    fs::File f = file_sys.open(fs_path, "r");
    if (!f)
    {
        send(slot_id, 404, "text/plain", "Not Found");
        return;
    }
 
    TcpConn *conn = &conn_pool[slot_id];
    if (conn->state != CONN_ACTIVE || !conn->pcb)
    {
        f.close();
        http_reset(slot_id);
        return;
    }
 
    size_t file_size = f.size();
 
    char header[RESP_HDR_BUF_SIZE];
    int hlen = snprintf(header, sizeof(header),
                        "HTTP/1.1 200 OK\r\n"
                        "Content-Type: %s\r\n"
                        "Content-Length: %d\r\n"
                        "%s"
                        "Connection: close\r\n\r\n",
                        content_type, (int)file_size,
                        _cors_enabled ? _cors_header_buf : "");
 
    struct tcp_pcb *pcb = conn->pcb;
    tcp_arg(pcb, nullptr);
    conn->state = CONN_FREE;
    conn->pcb   = nullptr;
 
    tcp_write(pcb, header, (u16_t)hlen, TCP_WRITE_FLAG_COPY);
 
    uint8_t chunk[FILE_CHUNK_SIZE];
    size_t  n;
    while ((n = f.read(chunk, sizeof(chunk))) > 0)
        tcp_write(pcb, chunk, (u16_t)n, TCP_WRITE_FLAG_COPY);
 
    tcp_output(pcb);
 
    if (tcp_close(pcb) != ERR_OK)
        tcp_abort(pcb);
 
    f.close();
    http_reset(slot_id);
}
#endif // DETWS_ENABLE_FILE_SERVING