Crow C++ Framework

To ensure your Crow application runs automatically on system startup and restarts upon failure, you can create a Systemd service unit file.

1. Create a new file in /etc/systemd/system/ with a .service extension (e.g., crowthing.service).
2. Populate the file with the configuration below, ensuring you replace /absolute/path/to/your/executable with the actual path to your compiled Crow binary.
3. Set the appropriate permissions using chmod 640.
4. Use systemctl to manage the service (e.g., enable to run at startup, start to run it immediately).

# 1. Create the service file
# Edit /etc/systemd/system/crowthing.service with the following content:

[Unit]
Description=My revolutionary Crow application

Wants=network.target
After=syslog.target network-online.target

[Service]
Type=simple
ExecStart=/absolute/path/to/your/executable
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

# 2. Set permissions
chmod 640 /etc/systemd/system/crowthing.service

# 3. Manage the service
systemctl enable crowthing.service
systemctl start crowthing.service

To implement WebSockets, use the CROW_WEBSOCKET_ROUTE(app, "/url") macro. This macro allows you to chain event handlers that respond to different stages of the WebSocket lifecycle.

Available event handlers (in order of execution):

• onaccept: Triggered during the handshake. Must return a boolean. If false is returned, the connection is terminated.
• onopen: Triggered when the connection is successfully opened.
• onmessage: Triggered when a message is received. Provides the message content and a bool indicating if the data is binary.
• onerror: Triggered when an error occurs.
• onclose: Triggered when the connection is closed, providing a reason and a status code.

Security Note: By default, Crow allows unmasked messages (violating protocol specs). For production, add #define CROW_ENFORCE_WS_SPEC to your source code to enforce the protocol.

CROW_WEBSOCKET_ROUTE(app, "/ws")
    .onopen([&](crow::websocket::connection& conn){
            do_something();
            })
    .onclose([&](crow::websocket::connection& conn, const std::string& reason, uint16_t){
            do_something();
            })
    .onmessage([&](crow::websocket::connection& /*conn*/, const std::string& data, bool is_binary){
                if (is_binary)
                    do_something(data);
                else
                    do_something_else(data);
            });

By default, middleware is global. To restrict middleware to specific handlers or blueprints, your middleware struct must inherit from crow::ILocalMiddleware.

Execution Order: Global middleware is run first, followed by the enabled local middleware for the current handler. In both cases, they follow the order specified in the crow::App definition.

To apply local middleware to a route, use .CROW_MIDDLEWARES(app, MiddlewareName). To apply it to a blueprint, use bp.CROW_MIDDLEWARES(app, MW1, MW2).

// 1. Define the local middleware
struct LocalMiddleware : crow::ILocalMiddleware
{
    struct context {};
    void before_handle(crow::request& req, crow::response& res, context& ctx) {}
    void after_handle(crow::request& req, crow::response& res, context& ctx) {}
};

// 2. Apply to a specific route
CROW_ROUTE(app, "/with_middleware")
.CROW_MIDDLEWARES(app, LocalMiddleware)
([]() {
    return "Hello world!";
});

// 3. Apply to a blueprint
Blueprint bp("with_middleware");
bp.CROW_MIDDLEWARES(app, FistLocalMiddleware, SecondLocalMiddleware);

Middleware allows you to inspect or alter requests before and after the handler is called. To implement a middleware, you must define a struct containing three members:

1. A context struct: Used for storing data local to the request.
2. A before_handle method: Executed before the handler.
3. An after_handle method: Executed after the handler.

Important: If res.end() is called within a middleware, no further handlers or middleware will run, except for the after_handle methods of middleware that have already been visited.

struct AdminAreaGuard
{
    struct context
    {};

    void before_handle(crow::request& req, crow::response& res, context& ctx)
    {
        if (req.remote_ip_address != ADMIN_IP)
        {
            res.code = 403;
            res.end();
        }
    }

    void after_handle(crow::request& req, crow::response& res, context& ctx)
    {}
};