Version 0.1

A C++ client library for Consul. Consul is a distributed tool for discovering and configuring services in your infrastructure.

The goal of PPConsul is to:

• Fully cover version 1 of Consul HTTP API. Please check the current implementation status.
• Provide simple, modular and effective API based on C++11.
• Support different platforms. At the moment, Linux, Windows and OSX platforms supported.
• Cover all the code with automated tests.
• Have documentation.

Note that this project is just started so it is under active developing, doesn't have a stable interface and was not tested enough. So if you are looking for something stable and ready to be used in production then it's better to come back later or help me growing this project to the quality level you need.

Library tests are running against Consul v0.6.3. Library known to work with versions 0.4 and 0.5 as well although some tests may fail because of differences in Consul behavior.

The library is written in C++11 and requires a quite modern compiler. Currently it has been tested with:

• Windows: Visual Studio 2013 Update 3
• OS X: Clang 7 (Xcode 7), Clang 6 (Xcode 6.1), Clang 5 (Xcode 5.1) all with libc++.
• Linux: GCC 5.3, GCC 4.9, GCC 4.8.2

Please check PPConsul build status.

The newer versions of specified compilers should work fine but was not tested. Earlier versions of GCC and Clang may work. Visual Studio before 2013 definitely gives up.

The library depends on:

• Boost 1.55 or later see note. PPConsul needs only headers with one exception: using of GCC 4.8 requires Boost.Regex library because regex is supported only in GCC 4.9.
• libCURL or C++ Network Library (aka cpp-netlib) to deal with HTTP. Note that the latter depends on compiled Boost libraries.

The library includes code of the following 3rd party libraries (look at ext directory):

• Slightly tweaked version of json11 library to deal with JSON.
• libb64 library for base64 decoding.

For unit tests, the library uses Catch framework. Many thanks to Phil Nash for this great product.

Boost versions prior to 1.55 can not be used because of Boost issue #8759.

Register, deregister and report the state of your service in Consul:

#include "ppconsul/agent.h"

using namespace ppconsul;

// Create a consul client with using of a default address ("127.0.0.1:8500") and default DC
Consul consul;
// We need the 'agent' endpoint for a service registration
agent::Agent agent(consul);

// Register a service with associated HTTP check:
agent.registerService(
    agent::keywords::name = "my-service",
    agent::keywords::port = 9876,
    agent::keywords::tags = {"tcp", "super_server"},
    agent::keywords::check = agent::HttpCheck{"http://localhost:80/", std::chrono::seconds(2)}
);

...

// Unregister service
agent.deregisterService("my-service");

...

// Register a service with TTL
agent.registerService(
    agent::keywords::name = "my-service",
    agent::keywords::port = 9876,
    agent::keywords::id = "my-service-1",
    agent::keywords::check = agent::TtlCheck{std::chrono::seconds(5)}
);

// Report service is OK
agent.servicePass("my-service-1");

// Report service is failed
agent.serviceFail("my-service-1", "Disk is full");

Use Key-Value storage:

#include "ppconsul/kv.h"

using namespace ppconsul;

// Create a consul client with using of a default address ("127.0.0.1:8500") and default DC
Consul consul;

// We need the 'kv' endpoint
kv::Storage storage(consul);

// Read the value of a key from the storage
std::string something = storage.get("settings.something", "default-value");

// Read the value of a key from the storage with consistency mode specified
something = storage.get("settings.something", "default-value", keywords::consistency = Consistency::Consistent);

// Erase a key from the storage
storage.erase("settings.something-else");

// Set the value of a key
storage.put("settings.something", "new-value");

Blocking query to Key-Value storage:

// Get key-value item
kv::KeyValue item = storage.item("status.last-event-id");

// Wait for the item change for no more than 1 minute:
item = storage.item("status.last-event-id", keywords::block_for = {std::chrono::minutes(1), item.modifyIndex});

// If key exists, print it:
if (item)
    std::cout << item.key << "=" << item.value << "\n";

TBD

• Get C++11 compatible compiler. See above for the list of supported compilers.
• Install CMake 2.8.12 or above (earlier version may work as well unless you use Visual Studio compiler).
• Install Boost 1.55 or later. You need compiled Boost libraries if you going to use cpp-netlib or GCC < 4.9, otherwise you need Boost headers only.
• Install either libCURL (any version is OK) or cpp-netlib 0.11 or above.
• Install Consul 0.4.0 or above. It's only needed to run tests.

Prepare project:

mkdir workspace
cd workspace
cmake ..

• To use cpp-netlib instead of libCURL use -DUSE_CPPNETLIB=1 when invoking CMake.
• To change where the build looks for Boost, pass -DBOOST_ROOT=<path_to_boost> parameter to CMake or set BOOST_ROOT environment variable.
• To change where the build looks for libCURL, pass -DCURL_ROOT=<path_to_curl> parameter to CMake or set CURL_ROOT environment variable.
• To change the default install location pass -DCMAKE_INSTALL_PREFIX=<prefix> parameter to CMake.

Note about -G option of CMake to choose you favourite IDE to generate project files for.

Build on Linux/OSX:
make

Build on Windows:
Either open solution file workspace\ppconsul.sln or build from the command line:
cmake --build . --config Release.

TBD

Use issue tracker.

First of all, welcome on board! Please fork this repo, commit changes and create a pull request.

The library released under Boost Software License v1.0.