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:
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:
Oldest versions of compilers that should work (all with using C++11 standard)
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:
The library includes code of the following 3rd party libraries (check ext directory):
For unit tests, the library uses Catch2 framework. Many thanks to Phil Nash for this great product.
#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");#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();#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");// 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";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.
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.
#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 ...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.
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), ...);http::HttpClientIf needed, user can implement http::HttpClient interface and pass custom HttpClientFactory to Consul's constructor.
TBD
You need C++11 compatible compiler (see above for the list of supported compilers) and CMake 3.1 or above.
# Install dependencies
conan install .
# Make workspace directory
mkdir workspace
cd workspace
# Configure:
cmake ..
#Build
cmake --build . --config Release
# Install
cmake --build . --config Release --target installIf you use Conan then simply run conan install . to install dependencies.
Otherwise:
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 ReleaseIf Makefile generator was used then you can also do:
makeBuild it first as described above then run
cmake --build . --config Release --target installIf Makefile generator was used then you can also do:
make installInstall Consul 0.4 or newer. I recommend 0.7 or newer since it's easier to run it in development mode.
For Consul 0.9 and above:
consul agent -dev -datacenter=ppconsul_test -enable-script-checks=trueFor Consul 0.7 and 0.8:
consul agent -dev -datacenter=ppconsul_testFor earlier version of Consul follow its documentation on how to run it with ppconsul_test datacenter.
ctest -C ReleaseIf Makefile generator was used then you can also do:
make testThere 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.
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.
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.gitAnd 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)Use issue tracker or/and drop an email to oliora.
First of all, welcome on board!
To contribute, please fork this repo, make your changes and create a pull request.
The library released under Boost Software License v1.0.