dns: configuring a basic key value store to persist to disk

CODEOWNERS

@@ -200,7 +200,8 @@ extensions/filters/http/oauth2 @rgs1 @derekargueta @snowp
 /*/extensions/matching/input_matchers/ip @aguinet @snowp
 # Kafka
 /*/extensions/filters/network/kafka @mattklein123 @adamkotwasinski
-
+# Key Value store
+/*extensions/cache/key_value_store/ @alyssawilk @ryantheoptimist
 # Contrib
 /contrib/exe/ @mattklein123 @lizan
 /contrib/squash/ @yuval-k @alyssawilk

api/BUILD

@@ -90,6 +90,7 @@ proto_library(
         "//envoy/extensions/access_loggers/open_telemetry/v3alpha:pkg",
         "//envoy/extensions/access_loggers/stream/v3:pkg",
         "//envoy/extensions/access_loggers/wasm/v3:pkg",
+        "//envoy/extensions/cache/key_value_cache/v3:pkg",
         "//envoy/extensions/cache/simple_http_cache/v3alpha:pkg",
         "//envoy/extensions/clusters/aggregate/v3:pkg",
         "//envoy/extensions/clusters/dynamic_forward_proxy/v3:pkg",

api/envoy/extensions/cache/key_value_cache/v3/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_format/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

api/envoy/extensions/cache/key_value_cache/v3/config.proto

@@ -0,0 +1,38 @@
+syntax = "proto3";
+
+package envoy.extensions.cache.key_value_cache.v3;
+
+import "google/protobuf/any.proto";
+import "google/protobuf/duration.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.cache.key_value_cache.v3";
+option java_outer_classname = "ConfigProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Key Value Cache storage plugin]
+
+// This shared configuration for Envoy key value stores.
+message KeyValueCacheConfig {
+  // Extensible config for key values caches.
+  // The expectation is that these are flushed to disk but for mobile, that may
+  // be via indirect APIs so may need more than just a simple file name.
+  string name = 1 [(validate.rules).string = {min_len: 1}];
+
+  google.protobuf.Any typed_config = 2;
+
+  // The interval at which the key value store should be flushed to long term
+  // storage.
+  google.protobuf.Duration flush_interval = 3;
+}
+
+// [#extension: envoy.cache.key_value_cache.file_based_cache]
+// This is configuration to flush a key value store out to disk.
+message FileBasedKeyValueCacheConfig {
+  // The filename to read the keys and values from, and write the keys and
+  // values to.
+  string filename = 1 [(validate.rules).string = {min_len: 1}];
+}

api/envoy/extensions/common/dynamic_forward_proxy/v3/BUILD

@@ -9,6 +9,7 @@ api_proto_package(
         "//envoy/annotations:pkg",
         "//envoy/config/cluster/v3:pkg",
         "//envoy/config/core/v3:pkg",
+        "//envoy/extensions/cache/key_value_cache/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
     ],
 )

api/envoy/extensions/common/dynamic_forward_proxy/v3/dns_cache.proto

@@ -6,6 +6,7 @@ import "envoy/config/cluster/v3/cluster.proto";
 import "envoy/config/core/v3/address.proto";
 import "envoy/config/core/v3/extension.proto";
 import "envoy/config/core/v3/resolver.proto";
+import "envoy/extensions/cache/key_value_cache/v3/config.proto";
 
 import "google/protobuf/duration.proto";
 import "google/protobuf/wrappers.proto";
@@ -31,7 +32,7 @@ message DnsCacheCircuitBreakers {
 
 // Configuration for the dynamic forward proxy DNS cache. See the :ref:`architecture overview
 // <arch_overview_http_dynamic_forward_proxy>` for more information.
-// [#next-free-field: 13]
+// [#next-free-field: 14]
 message DnsCacheConfig {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.common.dynamic_forward_proxy.v2alpha.DnsCacheConfig";
@@ -138,4 +139,8 @@ message DnsCacheConfig {
   // Setting this timeout will ensure that queries succeed or fail within the specified time frame
   // and are then retried using the standard refresh rates. Defaults to 5s if not set.
   google.protobuf.Duration dns_query_timeout = 11 [(validate.rules).duration = {gt {}}];
+
+  // [#not-implemented-hide:]
+  // Configuration to flush the DNS cache to long term storage.
+  cache.key_value_cache.v3.KeyValueCacheConfig persistent_cache_config = 13;
 }

api/versioning/BUILD

@@ -42,6 +42,7 @@ proto_library(
         "//envoy/extensions/access_loggers/open_telemetry/v3alpha:pkg",
         "//envoy/extensions/access_loggers/stream/v3:pkg",
         "//envoy/extensions/access_loggers/wasm/v3:pkg",
+        "//envoy/extensions/cache/key_value_cache/v3:pkg",
         "//envoy/extensions/cache/simple_http_cache/v3alpha:pkg",
         "//envoy/extensions/clusters/aggregate/v3:pkg",
         "//envoy/extensions/clusters/dynamic_forward_proxy/v3:pkg",

docs/root/api-v3/config/cache/key_value_cache.rst

@@ -0,0 +1,10 @@
+Key Value Cache
+===============
+
+.. _extension_category_envoy.key_value_cache:
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../../extensions/cache/*/v3/**

docs/root/api-v3/config/config.rst

@@ -31,3 +31,4 @@ Extensions
   stat_sinks/stat_sinks
   quic/quic_extensions
   formatter/formatter
+  cache/key_value_cache

envoy/common/BUILD

@@ -75,6 +75,7 @@ envoy_cc_library(
     name = "key_value_store_interface",
     hdrs = ["key_value_store.h"],
     deps = [
+        "//envoy/protobuf:message_validator_interface",
     ],
 )
 

envoy/common/key_value_store.h

@@ -1,6 +1,10 @@
 #pragma once
 
 #include "envoy/common/pure.h"
+#include "envoy/config/typed_config.h"
+#include "envoy/event/dispatcher.h"
+#include "envoy/filesystem/filesystem.h"
+#include "envoy/protobuf/message_validator.h"
 
 #include "absl/strings/string_view.h"
 #include "absl/types/optional.h"
@@ -37,6 +41,45 @@ class KeyValueStore {
    * Flushes the store to long term storage.
    */
   virtual void flush() PURE;
+
+  // Returns for the iterate function.
+  enum class Iterate { Continue, Break };
+
+  /**
+   * Callback when calling iterate() in a key value store.
+   * @param key is the key for a given entry
+   * @param value is the value for a given entry
+   * @return Iterate::Continue to continue iteration, or Iterate::Break to stop.
+   */
+  using ConstIterateCb = std::function<Iterate(const std::string& key, const std::string& value)>;
+
+  /**
+   * Iterate over a key value store.
+   * @param cb supplies the iteration callback.
+   */
+  virtual void iterate(ConstIterateCb cb) const PURE;
+};
+
+using KeyValueStorePtr = std::unique_ptr<KeyValueStore>;
+
+// A factory for creating key value stores.
+class KeyValueStoreFactory : public Envoy::Config::TypedFactory {
+public:
+  /**
+   * Function to create KeyValueStores from the specified config.
+   * @param cb supplies the key value store configuration
+   * @param validation_visitor the configuration validator
+   * @dispatcher the dispatcher for the thread, for flush alarms.
+   * @file_system the file system.
+   * @return a new key value store.
+   */
+  virtual KeyValueStorePtr createStore(const Protobuf::Message& config,
+                                       ProtobufMessage::ValidationVisitor& validation_visitor,
+                                       Event::Dispatcher& dispatcher,
+                                       Filesystem::Instance& file_system) PURE;
+
+  // @brief the category of the key value store for factory registration.
+  std::string category() const override { return "envoy.cache.key_value_cache"; }
 };
 
 } // namespace Envoy

generated_api_shadow/BUILD

@@ -90,6 +90,7 @@ proto_library(
         "//envoy/extensions/access_loggers/open_telemetry/v3alpha:pkg",
         "//envoy/extensions/access_loggers/stream/v3:pkg",
         "//envoy/extensions/access_loggers/wasm/v3:pkg",
+        "//envoy/extensions/cache/key_value_cache/v3:pkg",
         "//envoy/extensions/cache/simple_http_cache/v3alpha:pkg",
         "//envoy/extensions/clusters/aggregate/v3:pkg",
         "//envoy/extensions/clusters/dynamic_forward_proxy/v3:pkg",

source/common/common/key_value_store_base.cc

@@ -72,37 +72,13 @@ absl::optional<absl::string_view> KeyValueStoreBase::get(absl::string_view key)
   return it->second;
 }
 
-FileBasedKeyValueStore::FileBasedKeyValueStore(Event::Dispatcher& dispatcher,
-                                               std::chrono::seconds flush_interval,
-                                               Filesystem::Instance& file_system,
-                                               const std::string& filename)
-    : KeyValueStoreBase(dispatcher, flush_interval), file_system_(file_system),
-      filename_(filename) {
-  if (!file_system_.fileExists(filename_)) {
-    return;
-  }
-  const std::string contents = file_system_.fileReadToEnd(filename_);
-  if (!parseContents(contents, store_)) {
-    ENVOY_LOG(warn, "Failed to parse key value store file {}", filename);
-  }
-}
-
-void FileBasedKeyValueStore::flush() {
-  static constexpr Filesystem::FlagSet DefaultFlags{1 << Filesystem::File::Operation::Write |
-                                                    1 << Filesystem::File::Operation::Create};
-  Filesystem::FilePathAndType file_info{Filesystem::DestinationType::File, filename_};
-  auto file = file_system_.createFile(file_info);
-  if (!file || !file->open(DefaultFlags).return_value_) {
-    ENVOY_LOG(error, "Failed to flush cache to file {}", filename_);
-    return;
-  }
-  for (const auto& it : store_) {
-    file->write(absl::StrCat(it.first.length(), "\n"));
-    file->write(it.first);
-    file->write(absl::StrCat(it.second.length(), "\n"));
-    file->write(it.second);
+void KeyValueStoreBase::iterate(ConstIterateCb cb) const {
+  for (const auto& [key, value] : store_) {
+    Iterate ret = cb(key, value);
+    if (ret == Iterate::Break) {
+      return;
+    }
   }
-  file->close();
 }
 
 } // namespace Envoy