Neutralinojs Documentation

You can intercept requests at different stages of the lifecycle:

1. set_pre_routing_handler: Runs before route matching and before the body is read. Use this to reject requests as early as possible. Returns Server::HandlerResponse::Handled to stop processing or Unhandled to continue.
2. set_pre_request_handler: Runs after the route is matched (so req.matched_route and req.path_params are available) but before the request body is read. Ideal for authentication/authorization checks without buffering large bodies.
3. set_post_routing_handler: Runs after the route handler completes. Useful for adding headers to the response.
4. set_post_routing_handler: Runs after the route handler completes. Useful for adding headers to the response.

// Pre-routing: Reject early
svr.set_pre_routing_handler([](const auto& req, auto& res) {
  if (req.path == "/forbidden") {
    res.status = StatusCode::Forbidden_403;
    return Server::HandlerResponse::Handled;
  }
  return Server::HandlerResponse::Unhandled;
});

// Pre-request: Check route-specific params before reading body
svr.set_pre_request_handler([](const auto& req, auto& res) {
  if (req.matched_route == "/user/:user") {
    if (req.path_params.at("user") != "admin") {
      res.status = StatusCode::Unauthorized_401;
      return Server::HandlerResponse::Handled;
    }
  }
  return Server::HandlerResponse::Unhandled;
});

You can create an HTTP server by instantiating a Server object and defining routes using methods like Get, Post, Put, Patch, Delete, and Options. Each handler receives a Request and a Response object. You can use regular expressions for path matching or named path parameters (e.g., :id).

#include <httplib.h>

int main(void)
{
  using namespace httplib;

  Server svr;

  // Simple GET route
  svr.Get("/hi", [](const Request& req, Response& res) {
    res.set_content("Hello World!", "text/plain");
  });

  // Route with path parameter
  svr.Get("/users/:id", [&](const Request& req, Response& res) {
    auto user_id = req.path_params.at("id");
    res.set_content(user_id, "text/plain");
  });

  // Route with regex and captures
  svr.Get(R"(/numbers/(\d+))", [&](const Request& req, Response& res) {
    auto numbers = req.matches[1];
    res.set_content(numbers, "text/plain");
  });

  svr.listen("localhost", 1234);
}

The library supports WebSockets via the WebSocket method on the server and the httplib::ws::WebSocketClient on the client.

Important Considerations:

• Threading: WebSocket connections occupy a thread for their entire lifetime. For large-scale workloads, configure a dynamic thread pool using svr.new_task_queue.
• Extensions: WebSocket extensions (like permessage-deflate) are not supported. The server will silently decline them.
• Liveness: You can detect unresponsive peers by setting set_websocket_max_missed_pongs(n). If the client misses n consecutive pings, the connection is closed.
• SSL: Supported via the wss:// scheme.

// Server
httplib::Server svr;

svr.WebSocket("/ws", [](const httplib::Request &req, httplib::ws::WebSocket &ws) {
    httplib::ws::Message msg;
    while (ws.read(msg)) {
        if (msg.is_text()) {
            ws.send("Echo: " + msg.data);
        }
    }
});

svr.listen("localhost", 8080);

// Client
httplib::ws::WebSocketClient ws("ws://localhost:8080/ws");

if (ws.connect()) {
    ws.send("Hello, WebSocket!");

    std::string msg;
    if (ws.read(msg)) {
        std::cout << "Received: " << msg << std::endl;
    }

    ws.close();
}

To monitor file system changes, inherit from efsw::FileWatchListener and override the handleFileAction method. You can then use an efsw::FileWatcher instance to add paths to watch and start the asynchronous monitoring process.

Key components:

• efsw::FileWatchListener: The base class for receiving file events.
• efsw::FileWatcher: The main engine that manages watches and runs the monitoring loop.
• efsw::WatchID: A unique identifier returned when adding a watch, used to remove it later.
• efsw::Actions: An enumeration representing the type of event (Add, Delete, Modified, Moved).

// 1. Implement the listener
class UpdateListener : public efsw::FileWatchListener {
  public:
    void handleFileAction( efsw::WatchID watchid, const std::string& dir,
                           const std::string& filename, efsw::Action action,
                           std::string oldFilename ) override {
        switch ( action ) {
            case efsw::Actions::Add:
                std::cout << "Added: " << filename << std::endl;
                break;
            case efsw::Actions::Delete:
                std::cout << "Deleted: " << filename << std::endl;
                break;
            case efsw::Actions::Modified:
                std::cout << "Modified: " << filename << std::endl;
                break;
            case efsw::Actions::Moved:
                std::cout << "Moved: " << filename << " from " << oldFilename << std::endl;
                break;
            default:
                break;
        }
    }
};

// 2. Setup and start watching
efsw::FileWatcher* fileWatcher = new efsw::FileWatcher();
UpdateListener* listener = new UpdateListener();

// Add a recursive watch
efsw::WatchID watchID = fileWatcher->addWatch( "/tmp", listener, true );

// Start watching asynchronously
fileWatcher->watch();

// 3. Cleanup
fileWatcher->removeWatch( watchID );