API Reference

Server

Owns the listener, the route table and the middleware chain. Construct one, register routes, call start().

ServerConfig

HttpRequest

Handed to every handler and middleware by const reference.

HttpResponse

Defaults to status 200 with Content-Type: application/json. Prefer the static builders.

HttpResponse::json(body, code = 200);    // Content-Type: application/json
HttpResponse::text(body, code = 200);    // Content-Type: text/plain
HttpResponse::error(message, code = 500);

// Or build one by hand:
HttpResponse resp(201, "Created");
resp.headers["Location"] = "/api/posts/7";
resp.body = post.dump();

Handlers & middleware

using RouteHandler = std::function<boost::asio::awaitable<HttpResponse>(const HttpRequest&)>;
using NextFn       = std::function<boost::asio::awaitable<HttpResponse>()>;
using Middleware   = std::function<boost::asio::awaitable<HttpResponse>(HttpRequest&, NextFn)>;

Middleware executes around the request in an onion model, awaiting co_await next() to proceed down the chain or returning early to short-circuit.

Json

A thin value type over nlohmann/json. Header-only.

Json user = Json::parse(R"({"name":"Alice","age":30,"tags":["a","b"]})");

std::string name = user["name"].as_string();
int age          = user["age"].as_int();

Json out = json_object();
out["ok"]    = true;
out["name"]  = name;
out["count"] = static_cast<int>(user["tags"].as_array().size());

return HttpResponse::json(out.dump());

AuthService

Issues and verifies HS256 JWTs and authenticates users against an IUserDatabase.

Auth types

Guarding routes

create_auth_middleware() returns an AuthMiddleware, which is std::optional<std::string>(const std::string&) and maps a token to a user id. That signature is deliberately independent of HTTP, so it is not directly usable with Server::use. Wrap it, or call verify_token inline:

AuthService auth;

server.use([&](HttpRequest& req, NextFn next) -> boost::asio::awaitable<HttpResponse> {
    if (req.path.starts_with("/api/admin")) {
        std::string hdr = req.header("Authorization");
        std::string token = hdr.rfind("Bearer ", 0) == 0 ? hdr.substr(7) : hdr;

        AuthResult res = auth.verify_token(token);
        if (!res.success)
            co_return HttpResponse::error(res.error_message, 401);
    }

    co_return co_await next();   // authenticated, continue
});

IUserDatabase

Implement this to store users wherever you like. Two implementations ship with Prism: InMemoryUserDatabase (non-persistent, mutex-protected, used by default) and DatabaseUserDatabase (PostgreSQL, compiled in when ENABLE_POSTGRESQL is on).

virtual std::optional<User> find_by_username(const std::string& username) = 0;
virtual std::optional<User> find_by_email(const std::string& email)       = 0;
virtual std::optional<User> find_by_id(const std::string& id)             = 0;
virtual bool verify_password(const User& user, const std::string& password) = 0;
virtual User create_user(const std::string& username,
                         const std::string& email,
                         const std::string& password) = 0;

Passwords are stored as pbkdf2$<iterations>$<salt_hex>$<hash_hex>. Legacy unsalted SHA-256 digests still verify, so older stores keep working.

Logger

Loggers are named and retrieved with get_logger(name), which creates one on first use. Methods are instance methods. There is no static logging API.

// Macros capture __FILE__, __LINE__ and __FUNCTION__ for you:
LOG_INFO("Server starting on port 8080");
LOG_WARN("Rate limit approaching for " + req.remote_ip);
LOG_ERROR("Database connection failed");

// Or address a named logger directly:
auto& log = get_logger("auth");
log.set_level(LogLevel::DEBUG);
log.debug("token verified");

LoggerConfig fields: min_level (INFO), include_timestamp (true), include_thread_id (false), include_location (false), pattern ({timestamp} [{level}] {message}). Pattern placeholders: {timestamp} {level} {message} {thread} {file} {line} {function}. The last four only render when the matching config flag is on.

Log sinks

Implement ILogSink (write(const LogEntry&) and flush()) for anything else.

Database

Compiled in only when Prism is built with -DENABLE_POSTGRESQL=ON, which requires libpqxx. It is the persistence layer behind the bundled reference API rather than a general-purpose ORM: it owns a pooled libpqxx connection set, creates its schema on first start, and exposes the user/post/comment operations that API needs.

For anything beyond the reference API's needs, talk to libpqxx directly. Prism does not try to be your data-access layer.