SiddiqSoft.CosmosClient 0.7.1

There is a newer version of this package available.
See the version list below for details.
dotnet add package SiddiqSoft.CosmosClient --version 0.7.1
NuGet\Install-Package SiddiqSoft.CosmosClient -Version 0.7.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="SiddiqSoft.CosmosClient" Version="0.7.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SiddiqSoft.CosmosClient --version 0.7.1
#r "nuget: SiddiqSoft.CosmosClient, 0.7.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. 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.1

// Install SiddiqSoft.CosmosClient as a Cake Tool
#tool nuget:?package=SiddiqSoft.CosmosClient&version=0.7.1

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

CodeQL Build Status alternate text is missing from this package README image alternate text is missing from this package README image alternate text is missing from this package README image alternate text is missing from this package README image

alternate text is missing from this package README image

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>

Product Compatible and additional computed target framework versions.
native native is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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.14 1,121 12/23/2021
0.7.13 1,062 12/21/2021
0.7.12 1,144 12/20/2021
0.7.11 1,227 12/20/2021
0.7.10 1,235 12/18/2021
0.7.9 1,104 12/15/2021
0.7.8 1,479 11/20/2021
0.7.7 1,341 10/11/2021
0.7.6 989 10/8/2021
0.7.5 1,212 10/7/2021
0.7.4 1,281 10/5/2021
0.7.3 1,240 10/5/2021
0.7.2 1,259 9/28/2021
0.7.2-pullrequest0008-0005 1,205 9/28/2021
0.7.1 1,284 9/26/2021
0.6.1-pullrequest0007-0006 1,181 9/23/2021
0.6.1-pullrequest0007-0005 1,144 9/23/2021
0.6.0 1,343 9/11/2021
0.6.0-pullrequest0006-0088 1,104 9/11/2021
0.6.0-alpha0087 1,271 9/11/2021
0.5.7 1,246 9/11/2021
0.5.6 1,291 9/6/2021
0.5.3 1,224 9/3/2021
0.5.2 1,278 9/3/2021
0.5.1 1,309 9/3/2021
0.5.0 1,250 9/2/2021
0.4.2 1,484 9/1/2021