local_warning_server.hpp

1. Overview

The local_warning_server.hpp header defines the LocalWarningServer class, a lightweight embedded HTTP/HTTPS server built on libsoup and GLib. The component is intended to serve a local warning/interstitial page (e.g., for phishing or unsafe navigation events) by binding to a controlled loopback address and handling incoming requests through a dedicated main loop running in a background thread.

Functionally, LocalWarningServer provides:

  • Local HTTP and HTTPS endpoints for serving security warning pages
  • Configurable bind address and ports for isolation and collision avoidance
  • TLS support via configurable certificate and private key paths
  • Non-blocking operation by running a GLib main loop in a dedicated thread
  • Request handling via a libsoup server callback

2. Dependencies and Includes

#include <string>
#include <thread>
#include <libsoup/soup.h>
#include <glib.h>
  • <string> – storage of bind address, file paths, and configuration values
  • <thread> – background thread hosting the GLib main loop
  • libsoup/soup.h – HTTP server primitives (SoupServer, messages, callbacks)
  • glib.h – main loop and GLib data structures (GMainLoop, GHashTable)

3. Class Declaration and Scope

class LocalWarningServer

The LocalWarningServer class encapsulates the lifecycle of an embedded web server, including initialization, start/stop control, and threaded event loop management.

4. Construction and Destruction

4.1 Constructor

LocalWarningServer(int http_port = 81,
                   int https_port = 444,
                   const std::string& bind_address = "127.0.0.2",
                   const std::string& cert_file = "",
                   const std::string& key_file = "",
                   const std::string& page_warning_path = "");

Initializes server configuration, including the listening ports, bind address, optional TLS certificate/key paths, and the path to the warning page resource to be served.

4.2 Destructor

~LocalWarningServer();

Ensures the server is stopped and all resources are released, including the GLib main loop, libsoup server object, and the background thread.

5. Public Interface

5.1 Start Server

void start();

Starts the local warning server. This typically initializes the libsoup server, registers request handlers, creates a GMainLoop, and runs it in a dedicated thread.

5.2 Stop Server

void stop();

Stops the local warning server by terminating the GLib main loop, shutting down the server, and joining the background thread to ensure clean teardown.

6. Request Handling

static void on_request(SoupServer*,
                       SoupServerMessage*,
                       const char*,
                       GHashTable*,
                       gpointer);

Static callback invoked by libsoup when an HTTP request is received. The handler is responsible for generating and sending the response, typically by returning the warning page content and appropriate headers (content type, cache control, etc.).

7. Internal State and Runtime Components

SoupServer* server_;
int http_port_;
int https_port_;
std::string bind_address_;
std::string cert_file_;
std::string key_file_;
std::string page_warning_path_;
bool running_;
GMainLoop* loop_;
std::thread loop_thread_;
  • server_ – libsoup server instance
  • http_port_ – TCP port for HTTP listener
  • https_port_ – TCP port for HTTPS listener
  • bind_address_ – address to bind the listeners (default: 127.0.0.2)
  • cert_file_ – TLS certificate file path (optional, for HTTPS)
  • key_file_ – TLS private key file path (optional, for HTTPS)
  • page_warning_path_ – filesystem path to the warning/interstitial page content
  • running_ – flag indicating whether the server is currently active
  • loop_ – GLib main loop driving request processing
  • loop_thread_ – thread hosting the main loop to avoid blocking the caller

8. Typical Use Cases

  • Serving a phishing or malware interstitial page for blocked navigation attempts
  • Redirect targets for PAC/DNS-based blocking flows
  • Local “explainer” pages for security policy enforcement decisions
  • Providing a controlled local endpoint for browser extension integrations

9. Security and Deployment Considerations

  • Bind isolation: binding to a loopback alias (127.0.0.2) reduces exposure, but the service should still restrict itself to local-only interfaces
  • Port collisions: default ports (81/444) may conflict with other services; deployments should validate availability and provide override configuration
  • TLS hygiene: if HTTPS is enabled, certificates and private keys must be stored securely with restrictive permissions; avoid shipping private keys in insecure locations
  • Content safety: warning page content should be served with appropriate headers (e.g., no-cache, CSP if applicable) to prevent abuse or content injection
  • Threading correctness: start/stop should be synchronized to avoid races with the GLib main loop and libsoup callbacks
  • Fail-safe behavior: if the warning server cannot start, blocking components should fall back to a safe default (e.g., deny navigation with clear user feedback)
Published on:
Last updated on: