# zkpp

**Repository Path**: gycherish/zkpp

## Basic Information

- **Project Name**: zkpp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-30
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zkpp

A C++23 asynchronous ZooKeeper client built on [stdexec][stdexec] and [asio][asio].

zkpp exposes every ZK call as an `exec::task<T>` coroutine, multiplexes a single
TCP connection with built-in heartbeat and transparent reconnect, and runs
unchanged on Linux (io_uring or epoll) and Windows (MinGW or MSVC).

## Features

- Full ZooKeeper client protocol: session establishment & resume, CRUD,
  one-shot watches, ACL get/set, digest auth.
- Transparent reconnect: TCP drops within the negotiated session timeout
  rotate through the server list and re-arm outstanding watches; only
  unrecoverable session expiry surfaces to the caller.
- Structured concurrency: every blocking call is an `exec::task<T>`, so the
  same code composes under `stdexec::when_all` / `exec::when_any` / a
  cancellation `stop_token`.
- Single multiplexed connection; concurrent business calls share one socket
  and pipeline xids without blocking each other.
- One driver loop (`client::run()`) owns reads, dispatch, and heartbeat —
  the rest of the API is request/response coroutines that await on it.

## Requirements

- C++23 compiler (GCC 14+, Clang 18+, MSVC 17.10+).
- [xmake](https://xmake.io/) ≥ 3.0.0.
- asio, stdexec — pulled automatically via xmake / xrepo.

## Build

```sh
xmake f -m release                               # configure (use -m debug while developing)
xmake build                                      # build everything
xmake test                                       # run the catch2 test suite
xmake project -k compile_commands build          # export compile_commands.json
```

Linux defaults to io_uring; switch to epoll with:

```sh
xmake f -m release --with-iouring=n
```

Build with MinGW on Windows:

```sh
xmake f -m release -p mingw --sdk=/path/to/mingw
```

## Use as a package

Add the gitee xrepo and require zkpp from your `xmake.lua`:

```lua
add_repositories("repo https://gitee.com/gycherish/xrepo.git")
add_requires("zkpp")

target("your-app")
    set_kind("binary")
    add_files("main.cpp")
    add_packages("zkpp")
```

The package forwards its `with-iouring` config to the asio dependency,
so picking io_uring or epoll affects both consistently. If your project
also depends on asio directly, pin it to the same value:

```lua
add_requires("zkpp", {configs = {["with-iouring"] = true}})
add_requires("asio",  {configs = {["with-iouring"] = true}})
```

## Library usage

The driver pattern: spawn or `when_all` the long-running `client::run()`
alongside your business coroutine; have the business side call
`client::close()` when it is done so `run()` unwinds.

```cpp
#include <array>
#include <asio.hpp>
#include <exec/task.hpp>
#include <stdexec/execution.hpp>
#include <zkpp/client.hpp>

exec::task<void> demo(zkpp::client& c) {
    co_await c.connect();

    co_await c.create("/foo", zkpp::create_mode::persistent);

    std::array<std::uint8_t, 2> data{'h', 'i'};
    co_await c.set("/foo", data);

    auto node = co_await c.get("/foo", /*watch=*/true);
    auto ev   = co_await c.next_event();  // fires when /foo changes

    co_await c.remove("/foo");
    c.close();                            // makes c.run() return
}
```

See [`tools/zkcli.cpp`](tools/zkcli.cpp) for a complete driver: signal
handling, REPL mode, structured shutdown with `exec::when_any`, and the
event-printer pattern for watches.

## Tools

### zkcli

A small CLI built on top of the library, also useful as a worked example.

```sh
# one-shot
zkcli -s 127.0.0.1:2181 create -p /foo "hello"
zkcli set /foo -f payload.bin
zkcli get /foo
zkcli delete /foo

# interactive REPL with watch events printed asynchronously
zkcli -s 127.0.0.1:2181
zkcli> get /foo -w
zkcli> ...
```

`zkcli --help` and `zkcli <command> --help` document the full surface.

## Tests

Unit tests run unconditionally. Integration tests require a running
ZooKeeper instance; point them at it with `ZKPP_TEST_SERVERS`.

```sh
ZKPP_TEST_SERVERS=127.0.0.1:2181 xmake test
```

Without the env var, the integration tests are skipped (not failed) and
only the pure unit tests run.

## License

[MIT](LICENSE)