Guide ยท v0.5
Introduction
crocket is a C++ web framework in the same spirit as Rocket. It's not a port. Handlers are functions. Path captures and extractors are arguments. The return value is the response. You declare a route with a C++26 annotation, and reflect_routes discovers it. The wire layer is h2o: HTTP/1.1, HTTP/2, and TLS.
This guide describes that model. The code samples match crocket as of commit 9b446f8, which is the tree this site was checked against. The current stable release is 0.5.1. Static files, which this site uses, are in that commit and are listed as unreleased relative to the 0.5.1 tag.
What you write
A route is an ordinary function with one route annotation. Mounting a namespace picks up every annotated function in it. Helpers with no annotation stay helpers.
namespace api {
[[= http::get("/hello/{name}/{age}")]]
auto hello(std::string_view name, std::uint8_t age) -> std::string {
return std::format("Hello, {} year old named {}!", age, name);
}
} // namespace api
crocket::build()
.attach(Logger{})
.mount("/", reflect_routes<^^api>())
.launch({.listen = "0.0.0.0:8000"});/hello/Ada/36 calls hello. /hello/Ada/400 does not, because 400 is not a uint8_t. The response is 404 path.invalid, and the handler never runs.
Why reflection
Most C++ web frameworks bind routes with a runtime registration call, a macro, or a code generator. crocket uses C++26 static reflection instead. reflect_routes<^^api>() reads the functions, their annotations, and their parameter names at compile time.
- Nothing to register. You can't forget to add a route to a list, because there isn't a list.
- A mismatch is a compile error that names both identifiers. Reflection can see parameter names, which templates alone cannot.
- Reflection runs only in the compiler. Each route becomes a function pointer. A request does not pay for a string lookup, RTTI, or type erasure per argument.
- The same signatures and structs produce the JSON mapping, the OpenAPI document, and, for gRPC, the
.proto.
The trade-off is the toolchain. You need a compiler with C++26 reflection. crocket is developed on GCC 16.2 with -freflection. See Getting started.
Goals
These are the rules the framework is built around.
- A handler is a function.
{id}in the path is a parameter namedid.Json<T>,Auth, andState<T>are more parameters. The return type is the response. - Route metadata lives on the function. You mount a namespace or a controller class, not a handwritten list.
- Cross-cutting behavior belongs to the application.
attachadds fairings.manageadds typed singletons. - Production behavior is built in: request ids, structured errors, deadlines, readiness, limits, ignite checks, and a drain on shutdown. Logging and metrics are there when you attach them.
- One wire engine, h2o. Handlers never include h2o headers.
Non-goals
crocket is not an ORM and not a plugin ABI. It does not reload application code without a restart. Reloading a TLS certificate is supported, because that is configuration. It does not discover routes by scanning a whole translation unit. It does not do reflection, string lookups, or type erasure per argument on the request path.
WebSockets, server-sent events, and streamed bodies are not built. What's planned on the way to 1.0 is tracked in issue 37.
Where to go next
If you want a running process as fast as possible, start with the quickstart. The overview is the map of the rest of the guide.