filter: Add HttpCache interface and helpers

api/BUILD

@@ -29,6 +29,7 @@ proto_library(
         "//envoy/config/filter/fault/v2:pkg",
         "//envoy/config/filter/http/adaptive_concurrency/v2alpha:pkg",
         "//envoy/config/filter/http/buffer/v2:pkg",
+        "//envoy/config/filter/http/cache/v2:pkg",
         "//envoy/config/filter/http/cors/v2:pkg",
         "//envoy/config/filter/http/csrf/v2:pkg",
         "//envoy/config/filter/http/dynamic_forward_proxy/v2alpha:pkg",
@@ -157,6 +158,7 @@ proto_library(
         "//envoy/extensions/filters/common/fault/v3:pkg",
         "//envoy/extensions/filters/http/adaptive_concurrency/v3:pkg",
         "//envoy/extensions/filters/http/buffer/v3:pkg",
+        "//envoy/extensions/filters/http/cache/v3:pkg",
         "//envoy/extensions/filters/http/cors/v3:pkg",
         "//envoy/extensions/filters/http/csrf/v3:pkg",
         "//envoy/extensions/filters/http/dynamic_forward_proxy/v3:pkg",

api/docs/BUILD

@@ -35,6 +35,7 @@ proto_library(
         "//envoy/config/filter/fault/v2:pkg",
         "//envoy/config/filter/http/adaptive_concurrency/v2alpha:pkg",
         "//envoy/config/filter/http/buffer/v2:pkg",
+        "//envoy/config/filter/http/cache/v2:pkg",
         "//envoy/config/filter/http/cors/v2:pkg",
         "//envoy/config/filter/http/csrf/v2:pkg",
         "//envoy/config/filter/http/dynamic_forward_proxy/v2alpha:pkg",

api/envoy/config/filter/http/cache/v2/BUILD

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

api/envoy/config/filter/http/cache/v2/cache.proto

@@ -0,0 +1,82 @@
+syntax = "proto3";
+
+package envoy.config.filter.http.cache.v2;
+
+import "envoy/api/v2/route/route_components.proto";
+import "envoy/type/matcher/string.proto";
+
+import "google/protobuf/any.proto";
+
+import "udpa/annotations/migrate.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.filter.http.cache.v2";
+option java_outer_classname = "CacheProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_migrate).move_to_package = "envoy.extensions.filters.http.cache.v3";
+
+// [#protodoc-title: HTTP Cache Filter]
+// HTTP Cache Filter :ref:`overview <config_http_filters_cache>`.
+// [#extension: envoy.filters.http.cache]
+
+// [#next-free-field: 6]
+message CacheConfig {
+  // [#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 api.v2.route.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 api.v2.route.QueryParameterMatcher query_parameters_excluded = 4;
+  }
+
+  // Config specific to the cache storage implementation.
+  google.protobuf.Any typed_config = 1;
+
+  // Name of cache implementation to use, as specified in the intended HttpCacheFactory
+  // implementation. Cache names should use reverse DNS format, though this is not enforced.
+  string name = 2;
+
+  // [#not-implemented-hide:]
+  // <TODO(toddmgreer) implement *vary* headers>
+  //
+  // List of 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 whitelist: if a
+  // response's *vary* header mentions any header names that aren't 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.StringMatcher allowed_vary_headers = 3;
+
+  // [#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 = 4;
+
+  // [#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 = 5;
+}

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

@@ -0,0 +1,14 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/filter/http/cache/v2:pkg",
+        "//envoy/config/route/v3:pkg",
+        "//envoy/type/matcher/v3:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

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

@@ -0,0 +1,88 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.cache.v3;
+
+import "envoy/config/route/v3/route_components.proto";
+import "envoy/type/matcher/v3/string.proto";
+
+import "google/protobuf/any.proto";
+
+import "udpa/annotations/versioning.proto";
+
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.cache.v3";
+option java_outer_classname = "CacheProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: HTTP Cache Filter]
+// HTTP Cache Filter :ref:`overview <config_http_filters_cache>`.
+// [#extension: envoy.filters.http.cache]
+
+// [#next-free-field: 6]
+message CacheConfig {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.http.cache.v2.CacheConfig";
+
+  // [#not-implemented-hide:]
+  // Modifies cache key creation by restricting which parts of the URL are included.
+  message KeyCreatorParams {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.config.filter.http.cache.v2.CacheConfig.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.
+  google.protobuf.Any typed_config = 1;
+
+  // Name of cache implementation to use, as specified in the intended HttpCacheFactory
+  // implementation. Cache names should use reverse DNS format, though this is not enforced.
+  string name = 2;
+
+  // [#not-implemented-hide:]
+  // <TODO(toddmgreer) implement *vary* headers>
+  //
+  // List of 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 whitelist: if a
+  // response's *vary* header mentions any header names that aren't 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 = 3;
+
+  // [#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 = 4;
+
+  // [#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 = 5;
+}