Snapshot endpoint (#7767)

Co-authored-by: Amaury Chamayou <amchamay@microsoft.com>

Author: cjen1-msft

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Added `POST /node/snapshot:create`, gated by the `SnapshotCreate` RPC interface operator feature, to create a snapshot via an operator endpoint rather than a governance action.
 - Added `make_cose_verifier_from_pem_cert()` and `make_cose_verifier_from_der_cert()` that accept certificates in a known format. The existing `make_cose_verifier_cert()` is renamed to `make_cose_verifier_any_cert()` (#7768).
 
 ### Changed

doc/audit/builtin_maps.rst

@@ -560,6 +560,17 @@ Status information recorded when a primary produces a snapshot.
    :project: CCF
    :members:
 
+``snapshot_create``
+~~~~~~~~~~~~~~~~~~~
+
+Durability marker written when a snapshot is explicitly requested via the operator endpoint.
+This ensures the request is recorded as a real transaction even when it would otherwise
+carry only a transaction flag.
+
+**Key** Sentinel value 0, represented as a little-endian 64-bit unsigned integer.
+
+**Value** Sentinel value 0, represented as a little-endian 64-bit unsigned integer.
+
 ``encrypted_submitted_shares``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/host_config_schema/cchost_config.json

@@ -138,7 +138,7 @@
               "enabled_operator_features": {
                 "type": "array",
                 "items": {
-                  "enum": ["SnapshotRead", "LedgerChunkRead"],
+                  "enum": ["SnapshotRead", "LedgerChunkRead", "SnapshotCreate"],
                   "type": "string"
                 },
                 "description": "An array of features which should be enabled on this interface, providing access to endpoints with specific security or performance constraints."

doc/operations/configuration.rst

@@ -30,6 +30,7 @@ Currently supported features are:
 
 1. 'SnapshotRead': gates access to endpoints used to fetch snapshots directly from nodes (:http:GET:`/node/snapshot`, :http:HEAD:`/node/snapshot`, :http:GET:`/node/snapshot/{snapshot_name}` and :http:HEAD:`/node/snapshot/{snapshot_name}`).
 2. 'LedgerChunkRead': gates access to endpoints used to retrieve ledger chunks (:http:GET:`/node/ledger_chunk`, :http:HEAD:`/node/ledger_chunk`, :http:GET:`/node/ledger_chunk/{chunk_name}` and :http:HEAD:`/node/ledger_chunk/{chunk_name}`).
+3. 'SnapshotCreate': gates access to the operator endpoint used to create a snapshot on the next signature transaction (:http:POST:`/node/snapshot:create`).
 
 Since these operations may require disk IO and produce large responses, these features should not be enabled on interfaces with public access, and instead restricted to interfaces with local connectivity for node-to-node and operator access.
 
@@ -38,4 +39,4 @@ Since these operations may require disk IO and produce large responses, these fe
 
     - Size strings are expressed as the value suffixed with the size in bytes (``B``, ``KB``, ``MB``, ``GB``, ``TB``, as factors of 1024), e.g. ``"20MB"``, ``"100KB"`` or ``"2048"`` (bytes).
 
-    - Time strings are expressed as the value suffixed with the duration (``us``, ``ms``, ``s``, ``min``, ``h``), e.g. ``"1000ms"``, ``"10s"`` or ``"30min"``.
+    - Time strings are expressed as the value suffixed with the duration (``us``, ``ms``, ``s``, ``min``, ``h``), e.g. ``"1000ms"``, ``"10s"`` or ``"30min"``.

doc/operations/ledger_snapshot.rst

@@ -166,7 +166,7 @@ To avoid this, it is possible for a new node to be added (or a service to be rec
 Snapshot Generation
 ~~~~~~~~~~~~~~~~~~~
 
-Snapshots are generated at regular intervals by the current primary node and stored under the directory specified via the ``snapshots.directory`` configuration entry (defaults to ``snapshots/``). The transaction interval at which snapshots are generated is specified via the ``snapshots.tx_count`` configuration entry (defaults to a new snapshot generated every ``10,000`` committed transactions). Snapshots can also be generated by the ``trigger_snapshot`` governance action, i.e. by submitting a proposal. A snapshot will then be generated at the next signature transaction.
+Snapshots are generated at regular intervals by the current primary node and stored under the directory specified via the ``snapshots.directory`` configuration entry (defaults to ``snapshots/``). The transaction interval at which snapshots are generated is specified via the ``snapshots.tx_count`` configuration entry (defaults to a new snapshot generated every ``10,000`` committed transactions). Snapshots can also be explicitly requested, we recommend doing so via :http:POST:`/node/snapshot:create` on an interface with the ``SnapshotCreate`` operator feature enabled. Some constitutions may instead use ``trigger_snapshot`` however the endpoint avoids the complex and costly governance flow. In both cases, the snapshot is generated at the next signature transaction.
 
 Time-based snapshotting can also be enabled with ``snapshots.time_interval``. When this is set, a snapshot is eligible once more than ``snapshots.min_tx_count`` transactions have elapsed since the last snapshot. These transactions include CCF internal signature and snapshot bookkeeping transactions as well as application writes.
 

doc/schemas/node_openapi.json

@@ -603,7 +603,8 @@
       "OperatorFeature": {
         "enum": [
           "SnapshotRead",
-          "LedgerChunkRead"
+          "LedgerChunkRead",
+          "SnapshotCreate"
         ],
         "type": "string"
       },
@@ -929,7 +930,7 @@
   "info": {
     "description": "This API provides public, uncredentialed access to service and node state.",
     "title": "CCF Public Node API",
-    "version": "5.0.4"
+    "version": "5.0.5"
   },
   "openapi": "3.0.0",
   "paths": {
@@ -1841,6 +1842,22 @@
         }
       ]
     },
+    "/node/snapshot:create": {
+      "post": {
+        "operationId": "PostNodeSnapshotCreate",
+        "responses": {
+          "204": {
+            "description": "Default response description"
+          },
+          "default": {
+            "$ref": "#/components/responses/default"
+          }
+        },
+        "x-ccf-forwarding": {
+          "$ref": "#/components/x-ccf-forwarding/never"
+        }
+      }
+    },
     "/node/state": {
       "get": {
         "operationId": "GetNodeState",

include/ccf/kv/unit.h

@@ -9,9 +9,9 @@ namespace ccf::kv::serialisers
   // Unit serialisations are used as a utility type to convert ccf::kv::Maps to
   // ccf::kv::Maps and ccf::kv::Sets. Specifically, these are implemented as
   // wrappers so that ccf::kv::Value<T> is essentially ccf::kv::Map<Unit, T>,
-  // and ccf::kv::Set<T> is ccf::kv::Map<T, Unit>. This is used as a template
-  // parameter allowing the caller to specify what value is inserted into the
-  // ledger.
+  // ccf::kv::Set<T> is ccf::kv::Map<T, Unit>, and ccf::kv::UnitValue is
+  // ccf::kv::Map<Unit, Unit>. This is used as a template parameter allowing
+  // the caller to specify what value is inserted into the ledger.
 
   // This is the default UnitCreator, returning 8 null bytes for compatibility
   // with old ledgers (where Values were previously Maps with a single entry

include/ccf/kv/unit_value.h

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the Apache 2.0 License.
+#pragma once
+
+#include "ccf/kv/get_name.h"
+#include "ccf/kv/hooks.h"
+#include "ccf/kv/unit_value_handle.h"
+#include "ccf/kv/untyped.h"
+
+namespace ccf::kv
+{
+  /** Defines the schema of a touched-only type accessed by a @c ccf::Tx. This
+   * value is a container for an optional single marker indicating whether it
+   * has been touched.
+   *
+   * This is implemented as a @c ccf::kv::Map from Unit to Unit, and the
+   * serialisation of the fixed key and value are overridable with the Unit
+   * template parameter.
+   */
+  template <typename Unit = ccf::kv::serialisers::ZeroBlitUnitCreator>
+  class UnitValue : public GetName
+  {
+  public:
+    using ReadOnlyHandle = ccf::kv::ReadableUnitValueHandle<Unit>;
+    using WriteOnlyHandle = ccf::kv::WriteableUnitValueHandle<Unit>;
+    using Handle = ccf::kv::UnitValueHandle<Unit>;
+
+    using Write = std::optional<ccf::kv::serialisers::SerialisedEntry>;
+    using MapHook = ccf::kv::MapHook<Write>;
+    using CommitHook = ccf::kv::CommitHook<Write>;
+
+    using GetName::GetName;
+
+    static ccf::kv::serialisers::SerialisedEntry create_unit()
+    {
+      return Unit::get();
+    }
+
+  private:
+    static Write deserialise_write(const ccf::kv::untyped::Write& w)
+    {
+      const auto it = w.find(Unit::get());
+      if (it == w.end() || !it->second.has_value())
+      {
+        return std::nullopt;
+      }
+
+      return Unit::get();
+    }
+
+  public:
+    static ccf::kv::untyped::CommitHook wrap_commit_hook(const CommitHook& hook)
+    {
+      return [hook](Version v, const ccf::kv::untyped::Write& w) {
+        hook(v, deserialise_write(w));
+      };
+    }
+
+    static ccf::kv::untyped::MapHook wrap_map_hook(const MapHook& hook)
+    {
+      return [hook](Version v, const ccf::kv::untyped::Write& w) {
+        return hook(v, deserialise_write(w));
+      };
+    }
+  };
+}

include/ccf/kv/unit_value_handle.h

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the Apache 2.0 License.
+#pragma once
+
+#include "ccf/kv/unit.h"
+#include "ccf/kv/untyped_map_handle.h"
+
+namespace ccf::kv
+{
+  /** Grants read access to a @c ccf::kv::UnitValue, as part of a @c
+   * ccf::kv::Tx.
+   */
+  template <typename Unit>
+  class ReadableUnitValueHandle
+  {
+  protected:
+    ccf::kv::untyped::MapHandle& read_handle;
+
+  public:
+    ReadableUnitValueHandle(ccf::kv::untyped::MapHandle& uh) : read_handle(uh)
+    {}
+
+    /** Test if the value has been touched.
+     *
+     * @return Boolean true iff the value is defined
+     */
+    bool has()
+    {
+      return read_handle.has(Unit::get());
+    }
+
+    /** Get version when this value was last written to, by a previous
+     * transaction.
+     *
+     * @see ccf::kv::ReadableMapHandle::get_version_of_previous_write
+     *
+     * @return Optional containing version of applied transaction which last
+     * wrote to this value, or nullopt if such a version does not exist
+     */
+    std::optional<Version> get_version_of_previous_write()
+    {
+      return read_handle.get_version_of_previous_write(Unit::get());
+    }
+  };
+
+  /** Grants write access to a @c ccf::kv::UnitValue, as part of a @c
+   * ccf::kv::Tx.
+   */
+  template <typename Unit>
+  class WriteableUnitValueHandle
+  {
+  protected:
+    ccf::kv::untyped::MapHandle& write_handle;
+
+  public:
+    WriteableUnitValueHandle(ccf::kv::untyped::MapHandle& uh) : write_handle(uh)
+    {}
+
+    /** Touch this value.
+     *
+     * If this value was previously defined, it will be overwritten. Even if the
+     * previous value was identical, this produces a serialised write in the
+     * ledger.
+     */
+    void touch()
+    {
+      write_handle.put(Unit::get(), Unit::get());
+    }
+
+    /** Delete this value, restoring its original undefined state.
+     */
+    void clear()
+    {
+      write_handle.clear();
+    }
+  };
+
+  /** Grants read and write access to a @c ccf::kv::UnitValue, as part of a @c
+   * ccf::kv::Tx.
+   *
+   * @see ccf::kv::ReadableUnitValueHandle
+   * @see ccf::kv::WriteableUnitValueHandle
+   */
+  template <typename Unit>
+  class UnitValueHandle : public AbstractHandle,
+                          public ReadableUnitValueHandle<Unit>,
+                          public WriteableUnitValueHandle<Unit>
+  {
+  protected:
+    ccf::kv::untyped::MapHandle untyped_handle;
+
+    using ReadableBase = ReadableUnitValueHandle<Unit>;
+    using WriteableBase = WriteableUnitValueHandle<Unit>;
+
+  public:
+    UnitValueHandle(
+      ccf::kv::untyped::ChangeSet& changes, const std::string& map_name) :
+      ReadableBase(untyped_handle),
+      WriteableBase(untyped_handle),
+      untyped_handle(changes, map_name)
+    {}
+  };
+}

include/ccf/kv/version.h

@@ -2,6 +2,8 @@
 // Licensed under the Apache 2.0 License.
 #pragma once
 
+#include <cstdint>
+
 namespace ccf::kv
 {
   // Version indexes modifications to the local kv store.