Ppconsul

Version 0.2

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 macOS platforms supported.
• Cover all the code with automated tests.

Note that this project is under development and doesn't promise a stable interface.

Library tests are currently running against Consul v1.11.1. Library is known to work with Consul starting from version 0.4 (earlier versions might work as well but has never been tested) although some tests fail for older versions because of backward incompatible changes in Consul.

The library is written in C++11 and requires a quite modern compiler. Currently it's compiled with:

• macOS: Clang 11 (Xcode 11.3.1)
• Ubuntu Linux: GCC 7.4 with stdlibc++
• Windows: n/a

Oldest versions of compilers that should work (all with using C++11 standard)

• Clang 5
• GCC 4.8
• Visual Studio 2013

I try to support all modern compilers and platforms but I don't have resources to do extensive testing so from time to time something got broken on some platforms (mostly old GCC or Windows issues). Please create an issue if you discover a compilation error on your platform.

The library depends on:

• git (optional) to deduce correct .so version
• Boost 1.55 or later. Ppconsul needs only headers with one exception: using of GCC 4.8 requires Boost.Regex library because regular expressions are broken in GCC 4.8.
• libCURL to do HTTP/HTTPS.

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

• json11 library to deal with JSON.
• libb64 library for base64 decoding.

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

Warm Up Examples

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

#include "ppconsul/agent.h"

using ppconsul::Consul;
using namespace ppconsul::agent;

// Create a consul client that uses default local endpoint `http://127.0.0.1:8500` and default data center
Consul consul;
// We need the 'agent' endpoint for a service registration
Agent agent(consul);

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

...

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

...

// Register a service with TTL
agent.registerService(
    kw::name = "my-service",
    kw::port = 9876,
    kw::id = "my-service-1",
    kw::check = 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");

Determine raft leader (or lack thereof) and raft peers:

#include "ppconsul/status.h"

using ppconsul::Consul;
using namespace ppconsul::status;

// Create a consul client that uses default local endpoint `http://127.0.0.1:8500` and default data center
Consul consul;

// We need the status endpoint
Status status(consul);

// Determine whether a leader has been elected
bool isLeaderElected = status.isLeaderElected();

// Determine the actual raft leader
auto leader = status.leader();

// Determine the raft peers
auto peers = status.peers();

Use Key-Value storage:

#include "ppconsul/kv.h"

using ppconsul::Consul;
using ppconsul::Consistency;
using namespace ppconsul::kv;

Consul consul;

// We need the 'kv' endpoint
Kv kv(consul);

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

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

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

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

Blocking query to Key-Value storage:

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

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

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

Abort all [blocking] queries:

Consul consul(kw::enable_stop = true); // Must be enabled at construction time
Kv kv(consul);

// Issue blocking queries, similarly to example above, on background threads etc.

// Stop all pending requests, e.g. at shutdown. No further requests can be done after this call.
consul.stop();

Call to Consul::stop() is irreversible: once it's done the Consul object is switched to the stopped state forever. This whole feature purpose is to gracefully abort ongoing blocking queries on application/component shutdown.

Configure connect and request timeouts

By default, connect timeout is set to 5 seconds and request timeout is not set (so it is unlimited). If needed you can override default values as following:

#include "ppconsul/consul.h"

using namespace ppconsul;

Consul consul("https://localhost:8080",
              kw::connect_timeout = std::chrono::milliseconds{15000}
              kw::request_timeout = std::chrono::milliseconds{5000});

// Use consul ...

If you're using blocking queries then make sure that request timeout is longer than block interval, otherwise request will fail with timeout error.

Connect to Consul via HTTPS (TLS/SSL, whatever you call it):

#include "ppconsul/consul.h"

using namespace ppconsul;

Consul consul("https://localhost:8080",
              kw::tls::cert="path/to/cert",
              kw::tls::key="path/to/private/key",
              kw::tls::ca_info="path/to/ca/cert");

// Use consul ...

Multi-Threaded Usage of Ppconsul

Each Consul object has a pool of HTTP(S) clients to perform network requests. It is safe to call any endpoint (e.g. Kv, Agent etc) object or Consul object from multiple threads in the same time.

Call to Consul::stop() method stops all ongoing requests on that particular Consul object.

Multi-Threaded Usage of Ppconsul and libCURL initialization

libCURL requires that global initialization function curl_global_init is called before any oither libCURL function is called and before any additional thread is started. Ppconsul calls curl_global_init for you at the moment when makeDefaultHttpClientFactory() is called for the first time which is usually done when first Consul object is created. If this is too late then you need to call to curl_global_init and curl_global_cleanup at the right moment yourself, similar to this example:

int main(int argc, char *argv[])
{
    curl_global_init(CURL_GLOBAL_DEFAULT | CURL_GLOBAL_SSL);

    // Existing code that uses Ppconsul and starts extra threads...

    curl_global_cleanup();

    return 0;
}

CURL_GLOBAL_SSL flag is only needed if your're using HTTPS (TLS/SSL).

If your application needs to exclusively control libCURL initialization then you m ay want to skip libCURL initialization in Ppconsul's default HttpClientFactory. To do this, create default HttpClientFactory explicitly via makeDefaultHttpClientFactory(false) and pass it to Consul:

Consul consul(makeDefaultHttpClientFactory(false), ...);

Custom http::HttpClient

If needed, user can implement http::HttpClient interface and pass custom HttpClientFactory to Consul's constructor.

Documentation

TBD

How To Build

You need C++11 compatible compiler (see above for the list of supported compilers) and CMake 3.1 or above.

TLDR

# Install dependencies
conan install .

# Make workspace directory
mkdir workspace
cd workspace

# Configure:
cmake ..

#Build
cmake --build . --config Release

# Install
cmake --build . --config Release --target install

Get dependencies

If you use Conan then simply run conan install . to install dependencies.

Otherwise:

• Install git (any version should be fine)
• Install Boost 1.55 or later. You need compiled Boost.Regex library if you use GCC 4.8, otherwise you need headers only.
• Install libCURL (any version should be fine).

Build

Configure project:

mkdir workspace
cd workspace
cmake ..

You may want to set the following CMake variables on the command line:

To change where CMake looks for Boost, pass -DBOOST_ROOT=<path_to_boost> parameter to CMake or set BOOST_ROOT environment variable.

To change where CMake looks for libCURL, pass -DCURL_ROOT=<path_to_curl> parameter to CMake or set CURL_ROOT environment variable.

To change default install location, pass -DCMAKE_INSTALL_PREFIX=<prefix> parameter.

To build Ppconsul as static library, pass -DBUILD_STATIC_LIB=ON parameter. Note that in this case you have to link with json11 static library as well (json11 library is build as part of Ppconsul build.)

Note that on Windows Ppconsul can only be built as static library (that's default mode on Windows), see issue Allow to build Ppconsul as dynamic library on Windows.

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

Build:

cmake --build . --config Release

If Makefile generator was used then you can also do:

make

How to Install

Build it first as described above then run

cmake --build . --config Release --target install

If Makefile generator was used then you can also do:

make install

How To Run Tests

Install Consul 0.4 or newer. I recommend 0.7 or newer since it's easier to run it in development mode.

Run Consul

For Consul 0.9 and above:

consul agent -dev -datacenter=ppconsul_test -enable-script-checks=true

For Consul 0.7 and 0.8:

consul agent -dev -datacenter=ppconsul_test

For earlier version of Consul follow its documentation on how to run it with ppconsul_test datacenter.

Run Tests

ctest -C Release

If Makefile generator was used then you can also do:

make test

There are the following environment variable to configure tests:

Name	Default Value	Description
PPCONSUL_TEST_ADDR	"127.0.0.1:8500"	The Consul network address
PPCONSUL_TEST_DC	"ppconsul_test"	The Consul datacenter
PPCONSUL_TEST_LEADER_ADDR	"127.0.0.1:8300"	The Consul raft leader address

Never set PPCONSUL_TEST_DC into a datacenter that you can't throw away because Ppconsul tests will screw it up in many different ways.

Known Problems

Sometimes catalog tests failed on assertion REQUIRE(index1 == resp1.headers().index());. In this case, just rerun the tests. The reason for the failure is Consul's internal idempotent write which cause a spurious wakeup of waiting blocking query. Check the critical note under the blocking queries documentation at https://www.consul.io/docs/agent/http.html.

How to Use Ppconsul in Your Project

Build and install it first as described above.

When installed, the library can be simply used in any CMake-based project as following:

find_package(ppconsul)
add_executable(<your_app> ...)
target_link_libraries(<your_app> ppconsul)

As an alternative you can clone ppconsul into your project as submodule:

git submodule add https://github.com/oliora/ppconsul.git

And then include it into your CMake-based project as subdirectory:

set(BUILD_TESTS OFF)
set(BUILD_STATIC_LIB ON)
add_subdirectory(ppconsul)
...
target_link_libraries(<your_app> ppconsul)

Found a bug? Got a feature request? Need help with Ppconsul?

Use issue tracker or/and drop an email to oliora.

Contribute

First of all, welcome on board!

To contribute, please fork this repo, make your changes and create a pull request.

License

The library released under Boost Software License v1.0.