Add HttpCache version 2

CODEOWNERS

@@ -102,6 +102,8 @@ extensions/filters/common/original_src @klarose @mattklein123
 # HTTP caching extension
 /*/extensions/filters/http/cache @toddmgreer @ravenblackx @penguingao @mpwarres @capoferro
 /*/extensions/http/cache/simple_http_cache @toddmgreer @ravenblackx @penguingao @mpwarres @capoferro
+/*/extensions/filters/http/cache_v2 @toddmgreer @ravenblackx @penguingao @mpwarres @capoferro
+/*/extensions/http/cache_v2/simple_http_cache @toddmgreer @ravenblackx @penguingao @mpwarres @capoferro
 # AWS common signing components
 /*/extensions/common/aws @mattklein123 @nbaws @niax
 # adaptive concurrency limit extension.
@@ -245,6 +247,7 @@ extensions/upstreams/tcp @ggreenway @mattklein123
 /*/extensions/common/async_files @mattklein123 @ravenblackx
 /*/extensions/filters/http/file_system_buffer @mattklein123 @ravenblackx
 /*/extensions/http/cache/file_system_http_cache @ggreenway @ravenblackx
+/*/extensions/http/cache_v2/file_system_http_cache @ggreenway @ravenblackx
 # Google Cloud Platform Authentication Filter
 /*/extensions/filters/http/gcp_authn @tyxia @yanavlasov
 # DNS resolution

api/BUILD

@@ -173,6 +173,7 @@ proto_library(
         "//envoy/extensions/filters/http/basic_auth/v3:pkg",
         "//envoy/extensions/filters/http/buffer/v3:pkg",
         "//envoy/extensions/filters/http/cache/v3:pkg",
+        "//envoy/extensions/filters/http/cache_v2/v3:pkg",
         "//envoy/extensions/filters/http/cdn_loop/v3:pkg",
         "//envoy/extensions/filters/http/composite/v3:pkg",
         "//envoy/extensions/filters/http/compressor/v3:pkg",
@@ -273,6 +274,8 @@ proto_library(
         "//envoy/extensions/health_checkers/thrift/v3:pkg",
         "//envoy/extensions/http/cache/file_system_http_cache/v3:pkg",
         "//envoy/extensions/http/cache/simple_http_cache/v3:pkg",
+        "//envoy/extensions/http/cache_v2/file_system_http_cache/v3:pkg",
+        "//envoy/extensions/http/cache_v2/simple_http_cache/v3:pkg",
         "//envoy/extensions/http/custom_response/local_response_policy/v3:pkg",
         "//envoy/extensions/http/custom_response/redirect_policy/v3:pkg",
         "//envoy/extensions/http/early_header_mutation/header_mutation/v3:pkg",

api/envoy/extensions/filters/http/cache_v2/v3/BUILD

@@ -0,0 +1,14 @@
+# 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 = [
+        "//envoy/config/route/v3:pkg",
+        "//envoy/type/matcher/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+        "@com_github_cncf_xds//xds/annotations/v3:pkg",
+    ],
+)

api/envoy/extensions/filters/http/cache_v2/v3/cache.proto

@@ -0,0 +1,108 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.cache_v2.v3;
+
+import "envoy/config/route/v3/route_components.proto";
+import "envoy/type/matcher/v3/string.proto";
+
+import "google/protobuf/any.proto";
+import "google/protobuf/wrappers.proto";
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.cache_v2.v3";
+option java_outer_classname = "CacheProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/cache_v2/v3;cache_v2v3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: HTTP Cache Filter V2]
+
+// [#extension: envoy.filters.http.cache_v2]
+// [#next-free-field: 8]
+message CacheV2Config {
+  // [#not-implemented-hide:]
+  // Modifies cache key creation by restricting which parts of the URL are included.
+  message KeyCreatorParams {
+    // If true, exclude the URL scheme from the cache key. Set to true if your origins always
+    // produce the same response for http and https requests.
+    bool exclude_scheme = 1;
+
+    // If true, exclude the host from the cache key. Set to true if your origins' responses don't
+    // ever depend on host.
+    bool exclude_host = 2;
+
+    // If ``query_parameters_included`` is nonempty, only query parameters matched
+    // by one or more of its matchers are included in the cache key. Any other
+    // query params will not affect cache lookup.
+    repeated config.route.v3.QueryParameterMatcher query_parameters_included = 3;
+
+    // If ``query_parameters_excluded`` is nonempty, query parameters matched by one
+    // or more of its matchers are excluded from the cache key (even if also
+    // matched by ``query_parameters_included``), and will not affect cache lookup.
+    repeated config.route.v3.QueryParameterMatcher query_parameters_excluded = 4;
+  }
+
+  // Config specific to the cache storage implementation. Required unless ``disabled``
+  // is true.
+  // [#extension-category: envoy.http.cache_v2]
+  google.protobuf.Any typed_config = 1;
+
+  // When true, the cache filter is a no-op filter.
+  //
+  // Possible use-cases for this include:
+  // - Turning a filter on and off with :ref:`ECDS <envoy_v3_api_file_envoy/service/extension/v3/config_discovery.proto>`.
+  // [#comment: once route-specific overrides are implemented, they are the more likely use-case.]
+  google.protobuf.BoolValue disabled = 5;
+
+  // [#not-implemented-hide:]
+  // List of matching rules that defines allowed ``Vary`` headers.
+  //
+  // The ``vary`` response header holds a list of header names that affect the
+  // contents of a response, as described by
+  // https://httpwg.org/specs/rfc7234.html#caching.negotiated.responses.
+  //
+  // During insertion, ``allowed_vary_headers`` acts as a allowlist: if a
+  // response's ``vary`` header mentions any header names that aren't matched by any rules in
+  // ``allowed_vary_headers``, that response will not be cached.
+  //
+  // During lookup, ``allowed_vary_headers`` controls what request headers will be
+  // sent to the cache storage implementation.
+  repeated type.matcher.v3.StringMatcher allowed_vary_headers = 2;
+
+  // [#not-implemented-hide:]
+  // <TODO(toddmgreer) implement key customization>
+  //
+  // Modifies cache key creation by restricting which parts of the URL are included.
+  KeyCreatorParams key_creator_params = 3;
+
+  // [#not-implemented-hide:]
+  // <TODO(toddmgreer) implement size limit>
+  //
+  // Max body size the cache filter will insert into a cache. 0 means unlimited (though the cache
+  // storage implementation may have its own limit beyond which it will reject insertions).
+  uint32 max_body_bytes = 4;
+
+  // By default, a ``cache-control: no-cache`` or ``pragma: no-cache`` header in the request
+  // causes the cache to validate with its upstream even if the lookup is a hit. Setting this
+  // to true will ignore these headers.
+  bool ignore_request_cache_control_header = 6;
+
+  // If this is set, requests sent upstream to populate the cache will go to the
+  // specified cluster rather than the cluster selected by the vhost and route.
+  //
+  // If you have actions to be taken by the router filter - either
+  // ``upstream_http_filters`` or one of the ``RouteConfiguration`` actions such as
+  // ``response_headers_to_add`` - then the cache's side-channel going directly to the
+  // routed cluster will bypass these actions. You can set ``override_upstream_cluster``
+  // to an internal listener which duplicates the relevant ``RouteConfiguration``, to
+  // replicate the desired behavior on the side-channel upstream request issued by the
+  // cache.
+  //
+  // This is a workaround for implementation constraints which it is hoped will at some
+  // point become unnecessary, then unsupported and this field will be removed.
+  string override_upstream_cluster = 7;
+}

api/envoy/extensions/http/cache_v2/file_system_http_cache/v3/BUILD

@@ -0,0 +1,13 @@
+# 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 = [
+        "//envoy/extensions/common/async_files/v3:pkg",
+        "@com_github_cncf_xds//udpa/annotations:pkg",
+        "@com_github_cncf_xds//xds/annotations/v3:pkg",
+    ],
+)

api/envoy/extensions/http/cache_v2/file_system_http_cache/v3/file_system_http_cache.proto

@@ -0,0 +1,131 @@
+syntax = "proto3";
+
+package envoy.extensions.http.cache_v2.file_system_http_cache.v3;
+
+import "envoy/extensions/common/async_files/v3/async_file_manager.proto";
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/wrappers.proto";
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.http.cache_v2.file_system_http_cache.v3";
+option java_outer_classname = "FileSystemHttpCacheProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/cache_v2/file_system_http_cache/v3;file_system_http_cachev3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: FileSystemHttpCacheV2Config]
+// [#extension: envoy.extensions.http.cache_v2.file_system_http_cache]
+
+// Configuration for a cache implementation that caches in the local file system.
+//
+// By default this cache uses a least-recently-used eviction strategy.
+//
+// For implementation details, see `DESIGN.md <https://github.com/envoyproxy/envoy/blob/main/source/extensions/http/cache/file_system_http_cache/DESIGN.md>`_.
+// [#next-free-field: 11]
+message FileSystemHttpCacheV2Config {
+  // Configuration of a manager for how the file system is used asynchronously.
+  common.async_files.v3.AsyncFileManagerConfig manager_config = 1
+      [(validate.rules).message = {required: true}];
+
+  // Path at which the cache files will be stored.
+  //
+  // This also doubles as the unique identifier for a cache, so a cache can be shared
+  // between different routes, or separate paths can be used to specify separate caches.
+  //
+  // If the same ``cache_path`` is used in more than one ``CacheV2Config``, the rest of the
+  // ``FileSystemHttpCacheV2Config`` must also match, and will refer to the same cache
+  // instance.
+  string cache_path = 2 [(validate.rules).string = {min_len: 1}];
+
+  // The maximum size of the cache in bytes - when reached, cache eviction is triggered.
+  //
+  // This is measured as the sum of file sizes, such that it includes headers, trailers,
+  // and metadata, but does not include e.g. file system overhead and block size padding.
+  //
+  // If unset there is no limit except file system failure.
+  google.protobuf.UInt64Value max_cache_size_bytes = 3;
+
+  // The maximum size of a cache entry in bytes - larger responses will not be cached.
+  //
+  // This is measured as the file size for the cache entry, such that it includes
+  // headers, trailers, and metadata.
+  //
+  // If unset there is no limit.
+  //
+  // [#not-implemented-hide:]
+  google.protobuf.UInt64Value max_individual_cache_entry_size_bytes = 4;
+
+  // The maximum number of cache entries - when reached, cache eviction is triggered.
+  //
+  // If unset there is no limit.
+  google.protobuf.UInt64Value max_cache_entry_count = 5;
+
+  // A number of folders into which to subdivide the cache.
+  //
+  // Setting this can help with performance in file systems where a large number of inodes
+  // in a single branch degrades performance. The optimal value in that case would be
+  // ``sqrt(expected_cache_entry_count)``.
+  //
+  // On file systems that perform well with many inodes, the default value of 1 should be used.
+  //
+  // [#not-implemented-hide:]
+  uint32 cache_subdivisions = 6;
+
+  // The amount of the maximum cache size or count to evict when cache eviction is
+  // triggered. For example, if ``max_cache_size_bytes`` is 10000000 and ``evict_fraction``
+  // is 0.2, then when the cache exceeds 10MB, entries will be evicted until the cache size is
+  // less than or equal to 8MB.
+  //
+  // The default value of 0 means when the cache exceeds 10MB, entries will be evicted only
+  // until the cache is less than or equal to 10MB.
+  //
+  // Evicting a larger fraction will mean the eviction thread will run less often (sparing
+  // CPU load) at the cost of more cache misses due to the extra evicted entries.
+  //
+  // [#not-implemented-hide:]
+  float evict_fraction = 7;
+
+  // The longest amount of time to wait before running a cache eviction pass. An eviction
+  // pass may not necessarily remove any files, but it will update the cache state to match
+  // the on-disk state. This can be important if multiple instances are accessing the same
+  // cache in parallel. (e.g. if two instances each independently added non-overlapping 10MB
+  // of content to a cache with a 15MB limit, neither instance would be aware that the limit
+  // was exceeded without this synchronizing pass.)
+  //
+  // If an eviction pass has not happened within this duration, the eviction thread will
+  // be awoken and perform an eviction pass.
+  //
+  // If unset, there will be no eviction passes except those triggered by cache limits.
+  //
+  // [#not-implemented-hide:]
+  google.protobuf.Duration max_eviction_period = 8;
+
+  // The shortest amount of time between cache eviction passes. This can be used to reduce
+  // eviction churn, if your cache max size can be flexible. If a cache eviction pass already
+  // occurred more recently than this period when another would be triggered, that new
+  // pass is cancelled.
+  //
+  // This means the cache can potentially grow beyond ``max_cache_size_bytes`` by as much as
+  // can be written within the duration specified.
+  //
+  // Generally you would use *either* ``min_eviction_period`` *or* ``evict_fraction`` to
+  // reduce churn. Both together will work but since they're both aiming for the same goal,
+  // it's simpler not to.
+  //
+  // [#not-implemented-hide:]
+  google.protobuf.Duration min_eviction_period = 9;
+
+  // If true, and the cache path does not exist, attempt to create the cache path, including
+  // any missing directories leading up to it. On failure, the config is rejected.
+  //
+  // If false, and the cache path does not exist, the config is rejected.
+  //
+  // [#not-implemented-hide:]
+  bool create_cache_path = 10;
+}

api/envoy/extensions/http/cache_v2/simple_http_cache/v3/BUILD

@@ -0,0 +1,12 @@
+# 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_xds//udpa/annotations:pkg",
+        "@com_github_cncf_xds//xds/annotations/v3:pkg",
+    ],
+)

api/envoy/extensions/http/cache_v2/simple_http_cache/v3/config.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package envoy.extensions.http.cache_v2.simple_http_cache.v3;
+
+import "xds/annotations/v3/status.proto";
+
+import "udpa/annotations/status.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.http.cache_v2.simple_http_cache.v3";
+option java_outer_classname = "ConfigProto";
+option java_multiple_files = true;
+option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/cache_v2/simple_http_cache/v3;simple_http_cachev3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+option (xds.annotations.v3.file_status).work_in_progress = true;
+
+// [#protodoc-title: SimpleHttpCache CacheFilter storage plugin]
+
+// [#extension: envoy.extensions.http.cache_v2.simple]
+message SimpleHttpCacheV2Config {
+}

api/versioning/BUILD

@@ -111,6 +111,7 @@ proto_library(
         "//envoy/extensions/filters/http/basic_auth/v3:pkg",
         "//envoy/extensions/filters/http/buffer/v3:pkg",
         "//envoy/extensions/filters/http/cache/v3:pkg",
+        "//envoy/extensions/filters/http/cache_v2/v3:pkg",
         "//envoy/extensions/filters/http/cdn_loop/v3:pkg",
         "//envoy/extensions/filters/http/composite/v3:pkg",
         "//envoy/extensions/filters/http/compressor/v3:pkg",
@@ -211,6 +212,8 @@ proto_library(
         "//envoy/extensions/health_checkers/thrift/v3:pkg",
         "//envoy/extensions/http/cache/file_system_http_cache/v3:pkg",
         "//envoy/extensions/http/cache/simple_http_cache/v3:pkg",
+        "//envoy/extensions/http/cache_v2/file_system_http_cache/v3:pkg",
+        "//envoy/extensions/http/cache_v2/simple_http_cache/v3:pkg",
         "//envoy/extensions/http/custom_response/local_response_policy/v3:pkg",
         "//envoy/extensions/http/custom_response/redirect_policy/v3:pkg",
         "//envoy/extensions/http/early_header_mutation/header_mutation/v3:pkg",

bazel/repositories.bzl

@@ -7,6 +7,7 @@ PPC_SKIP_TARGETS = ["envoy.string_matcher.lua", "envoy.filters.http.lua", "envoy
 
 WINDOWS_SKIP_TARGETS = [
     "envoy.extensions.http.cache.file_system_http_cache",
+    "envoy.extensions.http.cache_v2.file_system_http_cache",
     "envoy.filters.http.file_system_buffer",
     "envoy.filters.http.language",
     "envoy.filters.http.sxg",

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

@@ -22,6 +22,7 @@ Extensions
   health_check_event_sinks/health_check_event_sinks
   health_checker/health_checker
   http/early_header_mutation
+  http/cache_v2
   http/custom_response
   http/ext_proc
   http/header_formatters

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

@@ -0,0 +1,8 @@
+HttpCacheV2 cache implementations
+=================================
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../../extensions/http/cache_v2/*/v3/*

docs/root/configuration/http/caches_v2/caches.rst

@@ -0,0 +1,9 @@
+.. _config_http_caches_v2:
+
+HTTP caches
+===========
+
+.. toctree::
+  :maxdepth: 2
+
+  file_system