EventStore C++ Client Header-Only Library

Introduction

A Boost.Asio and Boost.Beast based C++ client library for EventStore.

Prerequisites

• a C++ 17 compiler
• cmake >= 3.14 (or build by hand)
• protoc (protobuf compiler) if you want to regenerate the message implementation

Dependencies

• protobuf
• Boost.Asio
• Boost.System (header-only)
• Boost.Beast
• Boost.Uuid
• Boost.ContainerHash
• spdlog
• JSON for Modern C++
• Catch2 (for tests only)

Help installing dependencies

You can use vcpkg for dependency management.

# for windows
./vcpkg install protobuf:x64-windows-static boost-asio:x64-windows-static \ 
                spdlog:x64-windows-static boost-uuid:x64-windows-static \ 
				boost-container-hash:x64-windows-static boost-beast:x64-windows-static \
				nlohmann-json:x64-windows-static catch2:x64-windows-static

# for linux
./vcpkg install protobuf boost-asio spdlog boost-uuid boost-container-hash boost-beast nlohmann-json catch2

Building

There are currently no imported targets and no custom FindEventStoreClientApiCpp.cmake module. For an example on how to build the project, see how our CMakeLists script builds the examples in the examples subdirectory.

To generate the build system with cmake, run:

mkdir build
cd build
# for windows (you can use any other generator of your choice)
cmake .. -G "Visual Studio 15 2017 Win64" -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake -DCMAKE_CXX_STANDARD=17 -DVCPKG_TARGET_TRIPLET=x64-windows-static

# for linux
cmake .. -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake -DCMAKE_CXX_STANDARD=17 -DCMAKE_BUILD_TYPE=Release # or Debug, RelWithDebInfo, MinSizeRel

To build an example (or your executable), like the append-to-stream example, run (from ./build):

# windows, see CMakeLists.txt file for build targets such as `append-to-stream`, `read-stream-event`, `delete-stream-event` and more to come
cmake --build . --target append-to-stream --config Release # or Debug, RelWithDebInfo, MinSizeRel

# linux
cmake --build . --target append-to-stream

All the examples have a provided CMake target named like the example's cpp source file, with dashes '-' replacing the source file name's underscores '_'. For example, there is a "persistent_subscriptions.cpp" example source file in the examples subdirectory, and its corresponding CMake target is "persistent-subscriptions".

Running the examples

For usage information, execute the examples without arguments. For example, after building the append-to-stream examples, run:

# windows
./append-to-stream.exe

[2019-08-27 18:05:30.964] [stdout] [error] expected 5 arguments, got 0
[2019-08-27 18:05:30.964] [stdout] [error] usage: <executable> <ip endpoint> <port> <username> <password> [trace | debug | info | warn | error | critical | off]
[2019-08-27 18:33:20.657] [stdout] [error] example: ./append-to-stream 127.0.0.1 1113 admin changeit info
[2019-08-27 18:05:30.964] [stdout] [error] tool will write the following data to event store
[2019-08-27 18:05:30.964] [stdout] [error] stream=test-stream
        event-type=Test.Type
        is-json=true
        data={ "test": "data"}
        metadata=test metadata

# linux
$ ./append-to-stream
$ [2019-08-27 18:05:30.964] [stdout] [error] expected 5 arguments, got 0
$ [2019-08-27 18:05:30.964] [stdout] [error] usage: <executable> <ip endpoint> <port> <username> <password> [trace | debug | info | warn | error | critical | off]
$ [2019-08-27 18:33:20.657] [stdout] [error] example: ./append-to-stream 127.0.0.1 1113 admin changeit info
$ [2019-08-27 18:05:30.964] [stdout] [error] tool will write the following data to event store
$ [2019-08-27 18:05:30.964] [stdout] [error] stream=test-stream
$         event-type=Test.Type
$         is-json=true
$         data={ "test": "data"}
$         metadata=test metadata

where:

• endpoint is the ipv4 address of the EventStore server
• port is the EventStore server's TCP listening port
• username and password should be valid credentials (use "admin" "changeit", EventStore creates that user by default)
• verbosity level should be specified

Features

• operations on streams ✔️
• operations on stream metadata (without serialization) ✔️
• volatile subscriptions ✔️
• catchup subscriptions ✔️
• persistent subscriptions ✔️
• transactions ✔️
• connection configuration (retries, node preference, ssl, queue size, etc) (IN PROGRESS)
• user management (IN PROGRESS)
• cluster node discovery ✔️
• projections

Others

• unit tests
• benchmarks
• documentation
• more examples

Useful links

• boost.asio
• EventStore documentation
• EventStore .NET Client Api (see ClientAPI and ClusterNode projects for debugging/development)
• protobuf for C++
• cppreference
• stackoverflow