SiddiqSoft.CosmosClient 0.7.8

Install-Package SiddiqSoft.CosmosClient -Version 0.7.8
dotnet add package SiddiqSoft.CosmosClient --version 0.7.8
<PackageReference Include="SiddiqSoft.CosmosClient" Version="0.7.8" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SiddiqSoft.CosmosClient --version 0.7.8
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: SiddiqSoft.CosmosClient, 0.7.8"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install SiddiqSoft.CosmosClient as a Cake Addin
#addin nuget:?package=SiddiqSoft.CosmosClient&version=0.7.8

// Install SiddiqSoft.CosmosClient as a Cake Tool
#tool nuget:?package=SiddiqSoft.CosmosClient&version=0.7.8
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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

CodeQL Build Status

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

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

<p align="right"> © 2021 Siddiq Software LLC. All rights reserved. </p>

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.7.8 277 11/20/2021
0.7.7 154 10/11/2021
0.7.6 77 10/8/2021
0.7.5 133 10/7/2021
0.7.4 109 10/5/2021
0.7.3 101 10/5/2021
0.7.2 89 9/28/2021
0.7.2-pullrequest0008-0005 72 9/28/2021
0.7.1 75 9/26/2021
0.6.1-pullrequest0007-0006 54 9/23/2021
0.6.1-pullrequest0007-0005 91 9/23/2021
0.6.0 88 9/11/2021
0.6.0-pullrequest0006-0088 63 9/11/2021
0.6.0-alpha0087 62 9/11/2021
0.5.7 75 9/11/2021
0.5.6 69 9/6/2021
0.5.3 64 9/3/2021
0.5.2 66 9/3/2021
0.5.1 69 9/3/2021
0.5.0 76 9/2/2021
0.4.2 81 9/1/2021