CosmosClient : Azure Cosmos REST-API Client for Modern C++

Motivation

There is a need for a light-weight Azure Cosmos client that is crafted for C++ instead of "C" wrapper.

Features

• C++20 Azure Cosmos REST API client.
  • Be instructive and functional.
  • Low-overhead--just not optimized.
  • Leverage C++ sugarcoating (structured bindings and initializer lists).
• JSON everywhere; configuration, I/O, results.
• Simple interface -- this means we limit the options you can fiddle
• Implement the Cosmos SQL REST API
  • All of the responses are JSON documents as returned from Azure Cosmos. We do not abstract/encapsulate unless there is value.
  • Implement Azure REST API best practices.
• Single header
• Use Microsoft Win32 API for IO, encryption
  • Dependency on nlohmann.json
    • The best interface
  • Dependency on azure-cpp-utils our own library.
    • We do not implement any encryption functions. We only add a thin modern C++ coating on the underlying Win32 SDK.
  • Dependency on restcl our own library.
    • Again, we wrap a modern C++ sugar coat on the Win32 WinHTTP library. Nothing overly heavy or force you to use std::wstring or invent yet-another-string!
• Simplicity and ease of use--focus on your problem set and let the libraries evolve.

Development Style

• Continuous improvement
  • During early stages, development is going to be private until a first release candidate source.
  • We break ABI often.
• Focus on end-use and ease-of-use over performance
• Build what is needed and add features subject to the above criteria

Requirements

• While the code is pretty much C++20 the IO uses WinHTTP underneath.
• The build and tests are for Visual Studio 2019 under x64 using googletest.
• We switched to googletest from VSTest for the insane reason that enabiling ASAN was not compatible with VSTest.
• As of Visual Studio v16.11.2 the tag /c++20 no longer includes format and our code is stuck at /c++latest.

API / Usage

You can start saving your documents in Cosmos with just 3 lines of code!

• Declare the instance
• Configure with json via configure
• Make call to create

The detailed API is over at Github pages.

Sample

#include "nlohmann/json.hpp"
#include "siddiqsoft/azure-cosmos-restcl.hpp"

// See the example1 test for full source code
// Code here has been trimmed for brevity.
void example1(const std::string& p, const std::string& s)
{
    // You should maintain one instance for each Cosmos service
    // It is advised to maintain a single instance per runtime (exe/dll/service)
    siddiqsoft::CosmosClient cc;

    // If you provide valid information, this will configure by probing Azure for
    // region information and sets up the read and write locations.
    // We use JSON object as the primary configuration interface.
    // The items you provide are muxed with the defaults so you can provide as much
    // or as little as the following elements.
    cc.configure({{"partitionKeyNames", {"__pk"}},
                  {"connectionStrings", {p, s}}} );

    // This is all we need to worry about when creating a document!
    // Cosmos requires the "id" field be in the document so we perform
    // no checks for id nor the primaryKey field.
    // The goal is to get you the response from Cosmos with little more
    // than convenience overhead.
    // Minimal abstractions ("there are no zero-cost abstractions").
    // Just use the JSON object!
    // Here, we ask a document to be created and our lambda be invoked
    // on success or failure.
    cc.async({.operation  = siddiqsoft::CosmosOperation::create,
              .database   = dbName,
              .collection = collectionName,
              .document   = {{"id", docId},  // We send the JSON document
                             {"ttl", 360},   // inline for this example
                             {"__pk", pkId}, // PKID is required
                             {"func", __func__},
                             {"source", "basic_tests.exe"}},
              .onResponse = [&cc](auto const& ctx, auto const& resp){
                                if( 201 == resp.statusCode ) {
                                    // Document created..
                                    ..
                                    ..
                                    ..
                                    // You can even nest (this will queue into the worker
                                    // pool another async request.. Just make sure you
                                    // capture the cc instance.
                                    // The ctx contains the current context/arguments for this callback.
                                    cc.async({.operation    = siddiqsoft::CosmosOperation::remove,
                                              .database     = ctx.database,
                                              .collection   = ctx.collection,
                                              .id           = ctx.id, // or resp.document["id"] from create op
                                              .partitionKey = ctx.partitionKey,
                                              .onResponse   = [](auto const& ctx, auto const& resp){
                                                 // on remove of document..
                                              }}); // end of the internal async op
                                }
                                else {
                                   // handle failures..
                                }
                            }}); // end of the create async op
}

Roadmap

0. Documentation
1. Async operations with auto-retry (follow the read/write locations and toggle primary/secondary)
2. Support C++20 modules
3. Co-routines
4. OpenSSL for non-Windows platforms (current implementation is Windows only)

© 2021 Siddiq Software LLC. All rights reserved.