filter: Add an incomplete pluggable HTTP caching filter (CacheFilter).

CODEOWNERS

@@ -49,6 +49,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/filters/http/dynamic_forward_proxy @mattklein123 @alyssawilk
 # omit_canary_hosts retry predicate
 /*/extensions/retry/host/omit_canary_hosts @sriduth @snowp
+# HTTP caching extension
+/*/extensions/filters/http/cache @toddmgreer @jmarantz
 # aws_iam grpc credentials
 /*/extensions/grpc_credentials/aws_iam @lavignes @mattklein123
 /*/extensions/filters/http/common/aws @lavignes @mattklein123

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",
@@ -156,6 +157,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;
+}

docs/root/configuration/http/http_filters/cache_filter.rst

@@ -0,0 +1,46 @@
+.. _config_http_filters_cache:
+
+HTTP Cache Filter
+=================
+.. attention:: Work in Progress--not ready for deployment
+
+HTTP caching can improve system throughput, latency, and network/backend load
+levels when the same content is requested multiple times. Caching is
+particularly valuable for edge proxies and browser-based traffic, which
+typically include many cacheable static resources, but it can be useful any time
+there is enough repeatedly served cacheable content.
+
+Configuration
+-------------
+* :ref:`Configuration API <envoy_api_msg_config.filter.http.cache.v2.cacheConfig>`
+* This filter should be configured with the name *envoy.filters.http.cache*.
+
+The only required configuration field is :ref:`name
+<envoy_api_field_config.filter.http.cache.v2.CacheConfig.name>`, which must
+specify a valid cache storage implementation linked into your Envoy
+binary. Specifying 'envoy.extensions.http.cache.simple' will select a proof-of-concept
+implementation included in the Envoy source. More implementations can (and will)
+be provided by implementing Envoy::Extensions::HttpFilters::Cache::HttpCache. To
+write a cache storage implementation, see :repo:`Writing Cache Filter
+Implementations <source/docs/cache_filter_plugins.md>`
+
+.. TODO(toddmgreer) Describe other fields as they get implemented.
+   The remaining configuration fields control caching behavior and limits. By
+   default, this filter will cache almost all responses that are considered
+   cacheable by `RFC7234 <https://httpwg.org/specs/rfc7234.html>`_, with handling
+   of conditional (`RFC7232 <https://httpwg.org/specs/rfc7232.html>`_), and *range*
+   (`RFC7233 <https://httpwg.org/specs/rfc7233.html>`_) requests. Those RFC define
+   which request methods and response codes are cacheable, subject to the
+   cache-related headers they also define: *cache-control*, *range*, *if-match*,
+   *if-none-match*, *if-modified-since*, *if-unmodified-since*, *if-range*, *authorization*,
+   *date*, *age*, *expires*, and *vary*. Responses with a *vary* header will only be cached
+   if the named headers are listed in :ref:`allowed_vary_headers
+   <envoy_api_field_config.filter.http.cache.v3.CacheConfig.allowed_vary_headers>`
+
+Status
+------
+* This filter *is* ready for developers to write cache storage plugins; please
+  contribute them to the Envoy repository if possible.
+* This filter *is* ready for contributions to help finish its implementation of
+  HTTP caching semantics.
+* This filter *is not* ready for actual use. Please see TODOs in the code.

docs/root/configuration/http/http_filters/http_filters.rst

@@ -8,6 +8,7 @@ HTTP filters
 
   adaptive_concurrency_filter
   buffer_filter
+  cache_filter
   cors_filter
   csrf_filter
   dynamic_forward_proxy_filter

generated_api_shadow/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",