Results¶

By default, returning a value from a handler makes Baldr serialize it for you — std::string becomes text/plain, JSON-serializable structs become application/json. When you need explicit control over status, content type, or body, return an IResult from the Result.hpp module.

Baldr ships two flavours of result:

• IResult subclasses — free-form results that populate the response from Apply(HttpResponse&). Use them when the response shape does not match a typed semantic (for example, status-only or arbitrary content types).
• TypedResult subclasses — status-specific results whose status code and (when applicable) default schema and content type are part of the type. Returning them — directly or inside a std::variant — turns into one responses entry per status in the generated OpenAPI document without any extra metadata.

Quick start¶

#include <Baldr/Baldr.hpp>

app->MapGet("/empty",    []() -> IResult { return Results::NoContent();    });
app->MapGet("/missing",  []() -> IResult { return Results::NotFound("…");  });
app->MapGet("/logo.png", []() -> IResult {
    return ContentResult(loadPngBytes(), "image/png");
});

Factory functions¶

Results is a small namespace of factory functions for the common cases. The semantic factories (Created, NoContent, NotFound, BadRequest, Unauthorized, Forbidden, Conflict, UnprocessableEntity, InternalServerError) return their matching TypedResult subclass so the OpenAPI generator emits one entry per status code; Ok, Json, and Status keep their back-compatible signatures.

Results::Json<T, Status> requires T to be a reflectable struct (or std::vector of one) whose non-static data members are all in the supported field set. The body is serialised lazily through simdjson::to_json_string when Apply runs.

struct CreateUserRequest { std::string username; std::string email; };
struct User             { int id; std::string username; std::string email; };

app->MapPost("/users",
    [](FromBody<CreateUserRequest> req) -> std::variant<JsonResult<User, Created>,
                                                          BadRequestResult> {
        if (req.value.username.empty())
            return Results::BadRequest("username is required");
        return JsonResult<User, Created>(createUser(req.value));
    });

Built-in result types¶

IResult and its non-typed subclasses — <Baldr/Http/Results/Result.hpp>¶

TypedResult subclasses — <Baldr/Http/Results/TypedResults.hpp>¶

All TypedResult subclasses fix the status code (and, for body-less 204, an empty Content-Type) in the type. That makes IsTypedResultV<T> true at compile time and lets route registration derive per-status OpenAPI metadata from the type alone — no instance required, no sample needed.

Typed JSON results — JsonResult<T, Status>¶

JsonResult<T, Status> is the typed JSON return. It keeps the payload as a structured T and serialises through simdjson on Apply, so the OpenAPI generator can register T in components.schemas and link the per-status response with a $ref.

struct Product { std::string id; std::string name; int price; };

app->MapGet("/products/:id",
    [](FromParams<IdParam> params) -> std::variant<JsonResult<Product, OK>,
                                                    NotFoundResult> {
        auto p = lookup(params.value.id);
        if (!p) return Results::NotFound();
        return JsonResult<Product, OK>(*p);          // 200 application/json  $ref: Product
    });

JsonResult has two construction paths:

The template parameter T must satisfy IsAutoDerivable<T> (or be std::vector<U> for some auto-derivable U); the static_assert fires when the constraint is violated, surfacing the failure at registration time.

Streaming and file results¶

Parser-side discriminated unions¶

These are not IResult subclasses — they describe the parsed side of an HTTP body or round-trip value.

Custom results¶

Derive from IResult and implement Apply(HttpResponse&) to mutate the response however you need. Handlers may return any concrete IResult subclass by value.

class HtmlResult final : public IResult
{
  public:
    explicit HtmlResult(std::string body) : mBody(std::move(body)) {}

    void Apply(HttpResponse& response) const override
    {
        response.body                   = mBody;
        response.statusCode             = StatusCode::OK;
        response.headers["Content-Type"] = "text/html; charset=utf-8";
    }

  private:
    std::string mBody;
};

For the OpenAPI generator to render a useful schema for a custom result, default-construct an instance and read its StatusFor() / ContentTypeFor() / SchemaJsonFor() accessors — the variant walker does exactly that for legacy IResult alternatives.

Variant returns¶

Handlers may return std::variant<...> to model responses that take one of several shapes — for example a product or a not-found marker. Baldr unwraps the active alternative and dispatches it through the same rules as a non-variant return: IResult subclasses go through Apply, JSON-serializable values become application/json, std::string-assignable values become text/plain, std::monostate becomes an empty 200 OK, and so on.

struct Product { std::string id; std::string name; int price; };

app->MapGet("/products/:id",
    [](FromParams<IdParam> params,
       skr::Arc<ProductRepository> repo)
       -> std::variant<JsonResult<Product, OK>, NotFoundResult> {
        auto product = repo->Find(params.value.id);
        if (!product) return Results::NotFound();
        return JsonResult<Product, OK>(*product);
    });

OpenAPI: one entry per variant alternative¶

OpenAPI auto-derives one responses entry per status code from the variant alternatives:

• A TypedResult subclass (e.g. NotFoundResult, BadRequestResult, JsonResult<T, Status>) contributes its declared status with the right media type and default schema.
• A non-TypedResult IResult subclass (e.g. TextResult, ContentResult) contributes a default-constructed sample's status and content type. For ContentResult (whose content type is set at runtime) use WithResponseContentType(...) to pin the media type.
• A reflectable struct (or std::vector of one) contributes a $ref under 200 with application/json when no explicit response type is supplied.

User-supplied WithResponseType<T>() / WithResponseSchemaJson(...) win for status 200; the variant-derived entry under the same status is not emitted.

OpenAPI content-type honesty¶

The OpenAPI generator records the real media type of each response instead of defaulting to application/json:

• TextResult handlers emit text/plain.
• TypedResult subclasses with ContentTypeV (e.g. JsonResult<T, Status>, NotFoundResult, BadRequestResult) emit that media type under their status.
• ContentResult handlers emit no media type by default (the content type is set at runtime). Pin it with WithResponseContentType("image/png") and pair it with WithResponseSchemaJson(...) or WithResponseType<T>():

app->MapGet("/logo.png", [](const HttpRequest&) -> IResult {
    return ContentResult(loadPngBytes(), "image/png");
})
    .WithResponseSchemaJson(R"({"type":"string","format":"binary"})")
    .WithResponseContentType("image/png");

WithResponseContentType overrides the default application/json for the status-200 entry written by WithResponseSchemaJson / WithResponseType. It is ignored when no response schema is registered for status 200.

Parsing JSON bodies¶

HttpRequest::body is a raw std::string. Use the helpers in <Baldr/Http/Results/JsonBody.hpp> to parse it:

• baldr::parseJsonObject(request) returns JsonBodyResult<simdjson::dom::object> — either a parsed object or a populated error response.
• baldr::parseJson<T>(request) returns JsonBodyResult<T> and uses C++26 reflection to populate every non-static data member of T from the JSON object. Supported field types are std::string, std::string_view, the integral family (int/int64_t/uint8_t/...), float, double, and bool.

struct LoginRequest { std::string username; std::string password; };

app->MapPost("/login", [](const HttpRequest& req) -> IResult {
    auto parsed = baldr::parseJson<LoginRequest>(req);
    if (!parsed.isOk())
        return Results::Status(parsed.error().statusCode);
    // ...
});

For the request side, FromBody<T> / FromQuery<T> / FromParams<T> handler arguments derive the matching OpenAPI metadata automatically — see Request binding for the wrapper reference and Route options for the surrounding route metadata.

Next steps¶

• Stream large responses with Streaming results.
• See all built-in middleware in Middleware.
• Configure schema generation in OpenAPI extension.