cloudevents-cpp v0.1.0

CloudEvents v1.0.2 for C++20: the core event model, the JSON event format, the HTTP protocol binding, and a typed layer over both.

Header-only, no exceptions, no network I/O. The SDK names no HTTP type and picks no JSON library for you — ce::json::json_codec is a concept, and an nlohmann codec ships beside it.

This tag freezes the ce::v1 API. A breaking change after it introduces a new version namespace (SWR-BUILD-0006).

#include <cloudevents/binding/http.hpp>
#include <cloudevents/codec/nlohmann.hpp>

using codec = ce::codec::nlohmann_codec;

ce::event order{
    .id = "A234-1234-1234",
    .source = ce::uri_ref{"https://example.test/orders"},
    .type = "com.example.order.placed",
};
order.datacontenttype = "application/json";
order.data = ce::json_text{.raw = R"({"total":42})"};

auto request = ce::http::to_message<codec>(order, ce::content_mode::binary_mode);

Measured on this commit, not asserted

Line coverage	95.9% (1021 of 1065)
Fuzzing	5 targets, 10 minutes each, 338.3M executions, clean
Sanitizers	full suite under ASan and UBSan, clean
Interoperability	the Go and Java SDKs accept every document this SDK produces, and their goldens decode here
Conformance	all 19 examples from the CloudEvents core, JSON format and HTTP binding documents, stored verbatim
Requirements	122, every one with test evidence that resolves

Per-target fuzz executions: timestamp 186.4M, base64 123.9M, json_decode 6.3M, http_message 14.2M, typed 7.4M.

Toolchains exercised

GCC 13 and 16, Clang 16 with libstdc++ 13, Clang 17 with libc++ 17, AppleClang, MSVC 19. C++20 and C++23, with and without std::expected, with and without exceptions, with and without the default codec, plus C++26 static reflection.

What is in it

• Three content modes — binary, structured and batched, both directions, over a transport-neutral ce::message.
• Typed extensions — the five documented CloudEvents extensions as structs. event.get<ce::ext::tracing>() restores the declared field type even when the wire form threw it away, which HTTP binary mode always does.
• Typed payloads — describe your own struct once: set_data<order>(event, value), data_as<order>(event), event_of<order, codec>.
• Your JSON library — a codec is a struct of statics over your DOM; examples/custom_codec.cpp is a complete one.
• Four targets with a strictly downward dependency graph. ce::core depends on CTRE alone, checked by a test built against the installed package.

Installing

cmake -S . -B build && cmake --build build --target install

find_package(cloudevents REQUIRED)                            # core, format, binding
find_package(cloudevents REQUIRED COMPONENTS codec_nlohmann)  # and the codec

Known limitations

Each recorded in docs/DECISIONS.md with the measurement behind it.

• D-CI-1 — libc++ 17 and 18 implement std::format without defining __cpp_lib_format, so the SDK carves them out by version. Clang 16 cannot compile libstdc++ 13 or 14 in C++23 mode at all.
• D-MODULE-1 — cloudevents.cppm is usable, but an importing translation unit may not also include a standard header its global module fragment absorbed. It stays out of the default build.
• D-INTEROP-1 — given the same non-JSON payload, the Java SDK writes data_base64 where Go and this SDK write a JSON string. Both are legal. Compare bytes, not representation.
• D-ADOPT-1 — nlohmann is looked up softly, so find_package(cloudevents) works without it. Ask for the codec_nlohmann component when you need the codec.

Licence

Apache-2.0, matching the other CloudEvents SDKs.