From a7dd6fd6668cae7faca777dc5ca53d66d1450ab5 Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Thu, 15 Jul 2021 10:56:07 -0400 Subject: [PATCH 1/9] Add CachePolicy interface Signed-off-by: Josiah Kiehl --- source/extensions/filters/http/cache/BUILD | 10 ++++ .../filters/http/cache/cache_policy.h | 60 +++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 source/extensions/filters/http/cache/cache_policy.h diff --git a/source/extensions/filters/http/cache/BUILD b/source/extensions/filters/http/cache/BUILD index 1b04b15b7ca11..55bf8492aeca0 100644 --- a/source/extensions/filters/http/cache/BUILD +++ b/source/extensions/filters/http/cache/BUILD @@ -44,6 +44,16 @@ envoy_cc_library( ], ) +envoy_cc_library( + name = "cache_policy_lib", + hdrs = ["cache_policy.h"], + deps = [ + ":cache_headers_utils_lib", + ":http_cache_lib", + "//source/common/http:header_map_lib", + ], +) + envoy_proto_library( name = "key", srcs = ["key.proto"], diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h new file mode 100644 index 0000000000000..f1f1b20e7b389 --- /dev/null +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -0,0 +1,60 @@ +#pragma once + +#include "envoy/http/header_map.h" + +#include "source/extensions/filters/http/cache/cache_headers_utils.h" +#include "source/extensions/filters/http/cache/http_cache.h" + +namespace Envoy { +namespace Extensions { +namespace HttpFilters { +namespace Cache { + +struct CacheEntryUsability { + CacheEntryStatus status = CacheEntryStatus::Unusable; + Envoy::Seconds age = Envoy::Seconds::max(); +}; + +// CachePolicy is an extension point for deployment specific caching behavior. +class CachePolicy { +public: + virtual ~CachePolicy() = default; + + // createCacheKey calculates the lookup key for storing the entry in the cache. + virtual Key createCacheKey(const Envoy::Http::RequestHeaderMap& request_headers) PURE; + + // requestCacheable modifies the cacheability of the response during + // decoding. request_cache_control is the result of parsing the request's + // Cache-Control header, parsed by the caller. + virtual bool requestCacheable(const Envoy::Http::RequestHeaderMap& request_headers, + const RequestCacheControl& request_cache_control) PURE; + + // responseCacheable modifies the cacheability of the response during + // encoding. response_cache_control is the result of parsing the response's + // Cache-Control header, parsed by the caller. + virtual bool responseCacheable(const Envoy::Http::RequestHeaderMap& request_headers, + const Envoy::Http::ResponseHeaderMap& response_headers, + const ResponseCacheControl& response_cache_control, + const VaryHeader& vary_allow_list) PURE; + + // computeCacheEntryUsability calculates whether the cached entry may be used + // directly or must be validated with upstream. request_cache_control and + // response_cache_control are the result of parsing the request's and + // response's Cache-Control header, respectively, parsed by the caller. + virtual CacheEntryUsability + computeCacheEntryUsability(const Envoy::Http::RequestHeaderMap& request_headers, + const Envoy::Http::ResponseHeaderMap& cached_response_headers, + const RequestCacheControl& request_cache_control, + const ResponseCacheControl& cached_response_cache_control, + const uint64_t content_length, const ResponseMetadata& cached_metadata, + Envoy::SystemTime now) PURE; + + // setCallbacks allows additional callbacks to be set when the CacheFilter + // sets decoder filter callbacks. + virtual void setCallbacks(CachePolicyCallbacks& callbacks) PURE; +}; + +} // namespace Cache +} // namespace HttpFilters +} // namespace Extensions +} // namespace Envoy From 193385ca49f55f327594037df2bef76b4af48cc5 Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Thu, 15 Jul 2021 14:17:07 -0400 Subject: [PATCH 2/9] Add CachePolicyCallbacks Signed-off-by: Josiah Kiehl --- source/extensions/filters/http/cache/BUILD | 2 ++ source/extensions/filters/http/cache/cache_policy.h | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/source/extensions/filters/http/cache/BUILD b/source/extensions/filters/http/cache/BUILD index 55bf8492aeca0..ae5dddcc5fa23 100644 --- a/source/extensions/filters/http/cache/BUILD +++ b/source/extensions/filters/http/cache/BUILD @@ -50,6 +50,8 @@ envoy_cc_library( deps = [ ":cache_headers_utils_lib", ":http_cache_lib", + "//envoy/http:header_map", + "//envoy/stream_info:filter_state", "//source/common/http:header_map_lib", ], ) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index f1f1b20e7b389..e506337e2b418 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -1,6 +1,7 @@ #pragma once #include "envoy/http/header_map.h" +#include "envoy/stream_info/filter_state.h" #include "source/extensions/filters/http/cache/cache_headers_utils.h" #include "source/extensions/filters/http/cache/http_cache.h" @@ -15,6 +16,13 @@ struct CacheEntryUsability { Envoy::Seconds age = Envoy::Seconds::max(); }; +class CachePolicyCallbacks { + public: + virtual ~CachePolicyCallbacks() = default; + + virtual const Envoy::StreamInfo::FilterStateSharedPtr& filterState() PURE; +}; + // CachePolicy is an extension point for deployment specific caching behavior. class CachePolicy { public: From a60636aa8a1a0b02fca5f843f35fa782c4c4fa7e Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Thu, 15 Jul 2021 15:00:17 -0400 Subject: [PATCH 3/9] Fix BUILD Signed-off-by: Josiah Kiehl --- source/extensions/filters/http/cache/BUILD | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/extensions/filters/http/cache/BUILD b/source/extensions/filters/http/cache/BUILD index ae5dddcc5fa23..515020b134a6f 100644 --- a/source/extensions/filters/http/cache/BUILD +++ b/source/extensions/filters/http/cache/BUILD @@ -50,9 +50,8 @@ envoy_cc_library( deps = [ ":cache_headers_utils_lib", ":http_cache_lib", - "//envoy/http:header_map", - "//envoy/stream_info:filter_state", "//source/common/http:header_map_lib", + "//source/common/stream_info:filter_state_lib", ], ) From 5bf982140653172e86ed88970157c2dcfa9cd77b Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Thu, 15 Jul 2021 17:12:48 -0400 Subject: [PATCH 4/9] Fix format Signed-off-by: Josiah Kiehl --- source/extensions/filters/http/cache/cache_policy.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index e506337e2b418..3fa660ba85718 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -17,7 +17,7 @@ struct CacheEntryUsability { }; class CachePolicyCallbacks { - public: +public: virtual ~CachePolicyCallbacks() = default; virtual const Envoy::StreamInfo::FilterStateSharedPtr& filterState() PURE; From 2a82af307164a87f9ac744a502545a4dddfe388c Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Fri, 16 Jul 2021 09:34:31 -0400 Subject: [PATCH 5/9] Remove Envoy:: qualifiers Signed-off-by: Josiah Kiehl --- .../filters/http/cache/cache_policy.h | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index 3fa660ba85718..8da20c10a59f3 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -13,14 +13,14 @@ namespace Cache { struct CacheEntryUsability { CacheEntryStatus status = CacheEntryStatus::Unusable; - Envoy::Seconds age = Envoy::Seconds::max(); + Seconds age = Seconds::max(); }; class CachePolicyCallbacks { public: virtual ~CachePolicyCallbacks() = default; - virtual const Envoy::StreamInfo::FilterStateSharedPtr& filterState() PURE; + virtual const StreamInfo::FilterStateSharedPtr& filterState() PURE; }; // CachePolicy is an extension point for deployment specific caching behavior. @@ -29,19 +29,19 @@ class CachePolicy { virtual ~CachePolicy() = default; // createCacheKey calculates the lookup key for storing the entry in the cache. - virtual Key createCacheKey(const Envoy::Http::RequestHeaderMap& request_headers) PURE; + virtual Key createCacheKey(const Http::RequestHeaderMap& request_headers) PURE; // requestCacheable modifies the cacheability of the response during // decoding. request_cache_control is the result of parsing the request's // Cache-Control header, parsed by the caller. - virtual bool requestCacheable(const Envoy::Http::RequestHeaderMap& request_headers, + virtual bool requestCacheable(const Http::RequestHeaderMap& request_headers, const RequestCacheControl& request_cache_control) PURE; // responseCacheable modifies the cacheability of the response during // encoding. response_cache_control is the result of parsing the response's // Cache-Control header, parsed by the caller. - virtual bool responseCacheable(const Envoy::Http::RequestHeaderMap& request_headers, - const Envoy::Http::ResponseHeaderMap& response_headers, + virtual bool responseCacheable(const Http::RequestHeaderMap& request_headers, + const Http::ResponseHeaderMap& response_headers, const ResponseCacheControl& response_cache_control, const VaryHeader& vary_allow_list) PURE; @@ -50,12 +50,12 @@ class CachePolicy { // response_cache_control are the result of parsing the request's and // response's Cache-Control header, respectively, parsed by the caller. virtual CacheEntryUsability - computeCacheEntryUsability(const Envoy::Http::RequestHeaderMap& request_headers, - const Envoy::Http::ResponseHeaderMap& cached_response_headers, + computeCacheEntryUsability(const Http::RequestHeaderMap& request_headers, + const Http::ResponseHeaderMap& cached_response_headers, const RequestCacheControl& request_cache_control, const ResponseCacheControl& cached_response_cache_control, const uint64_t content_length, const ResponseMetadata& cached_metadata, - Envoy::SystemTime now) PURE; + SystemTime now) PURE; // setCallbacks allows additional callbacks to be set when the CacheFilter // sets decoder filter callbacks. From 7e5c6a5962b04b5919c9cf1feb59e95e741556aa Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Fri, 16 Jul 2021 11:11:31 -0400 Subject: [PATCH 6/9] Doxygen comments Signed-off-by: Josiah Kiehl --- .../filters/http/cache/cache_policy.h | 58 ++++++++++++++----- 1 file changed, 44 insertions(+), 14 deletions(-) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index 8da20c10a59f3..ebd885214daba 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -23,32 +23,58 @@ class CachePolicyCallbacks { virtual const StreamInfo::FilterStateSharedPtr& filterState() PURE; }; -// CachePolicy is an extension point for deployment specific caching behavior. +/** + * An extension point for deployment specific caching behavior. + */ class CachePolicy { public: virtual ~CachePolicy() = default; - // createCacheKey calculates the lookup key for storing the entry in the cache. + /** + * Calculates the lookup key for storing the entry in the cache. + * @param request_headers - headers from the request the CacheFilter is currently processing. + */ virtual Key createCacheKey(const Http::RequestHeaderMap& request_headers) PURE; - // requestCacheable modifies the cacheability of the response during - // decoding. request_cache_control is the result of parsing the request's - // Cache-Control header, parsed by the caller. + /** + * Modifies the cacheability of the response during decoding. + * @param request_headers - headers from the request the CacheFilter is currently processing. + * @param request_cache_control - the result of parsing the request's Cache-Control header, parsed + * by the caller. + * @return true if the response may be cached, based on the contents of the request. + */ virtual bool requestCacheable(const Http::RequestHeaderMap& request_headers, const RequestCacheControl& request_cache_control) PURE; - // responseCacheable modifies the cacheability of the response during - // encoding. response_cache_control is the result of parsing the response's - // Cache-Control header, parsed by the caller. + /** + * Modifies the cacheability of the response during encoding. + * @param request_headers - headers from the request the CacheFilter is currently processing. + * @param response_headers - headers from the upstream response the CacheFilter is currently + * processing. + * @param response_cache_control - the result of parsing the response's Cache-Control header, + * parsed by the caller. + * @param vary_allow_list - list of headers that the cache will respect when creating the Key for + * Vary-differentiated responses. + * @return true if the response may be cached. + */ virtual bool responseCacheable(const Http::RequestHeaderMap& request_headers, const Http::ResponseHeaderMap& response_headers, const ResponseCacheControl& response_cache_control, const VaryHeader& vary_allow_list) PURE; - // computeCacheEntryUsability calculates whether the cached entry may be used - // directly or must be validated with upstream. request_cache_control and - // response_cache_control are the result of parsing the request's and - // response's Cache-Control header, respectively, parsed by the caller. + /** + * Calculates whether the cached entry may be used directly or must be validated with upstream. + * @param request_headers - headers from the request the CacheFilter is currently processing. + * @param response_headers - headers from the cached response the CacheFilter has retrieved. + * @param request_cache_control - the parsed result of the request's Cache-Control header, parsed + * by the caller. + * @param cached_response_cache_control - the parsed result of the response's Cache-Control + * header, parsed by the caller. + * @param content_length - the byte length of the cached content. + * @param cached_metadata - the metadata that has been stored along side the cached entry. + * @param now - the timestamp for this request. + * @return details about whether or not the cached entry can be used. + */ virtual CacheEntryUsability computeCacheEntryUsability(const Http::RequestHeaderMap& request_headers, const Http::ResponseHeaderMap& cached_response_headers, @@ -57,8 +83,12 @@ class CachePolicy { const uint64_t content_length, const ResponseMetadata& cached_metadata, SystemTime now) PURE; - // setCallbacks allows additional callbacks to be set when the CacheFilter - // sets decoder filter callbacks. + /** + * Perform actions when StreamInfo and FilterState become available, for + * example for logging and observability, or to adapt CacheFilter behavior based on + * route-specific CacheFilter config. + * @param callbacks - Gives access to StreamInfo and FilterState + */ virtual void setCallbacks(CachePolicyCallbacks& callbacks) PURE; }; From 7e9163367482bd7dad12a23f935a82305093fb2d Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Wed, 28 Jul 2021 10:46:35 -0400 Subject: [PATCH 7/9] CachePolicy comment updates Signed-off-by: Josiah Kiehl --- .../filters/http/cache/cache_policy.h | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index ebd885214daba..01b61864aab54 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -11,8 +11,17 @@ namespace Extensions { namespace HttpFilters { namespace Cache { +/** + * Contains information about whether the cache entry is usable. + */ struct CacheEntryUsability { + /** + * Whether the cache entry is usable, additional checks are required to be usable, or unusable. + */ CacheEntryStatus status = CacheEntryStatus::Unusable; + /** + * Value to be put in the Age header for cache responses. + */ Seconds age = Seconds::max(); }; @@ -37,7 +46,7 @@ class CachePolicy { virtual Key createCacheKey(const Http::RequestHeaderMap& request_headers) PURE; /** - * Modifies the cacheability of the response during decoding. + * Determines the cacheability of the response during decoding. * @param request_headers - headers from the request the CacheFilter is currently processing. * @param request_cache_control - the result of parsing the request's Cache-Control header, parsed * by the caller. @@ -47,7 +56,7 @@ class CachePolicy { const RequestCacheControl& request_cache_control) PURE; /** - * Modifies the cacheability of the response during encoding. + * Determines the cacheability of the response during encoding. * @param request_headers - headers from the request the CacheFilter is currently processing. * @param response_headers - headers from the upstream response the CacheFilter is currently * processing. @@ -63,9 +72,9 @@ class CachePolicy { const VaryHeader& vary_allow_list) PURE; /** - * Calculates whether the cached entry may be used directly or must be validated with upstream. - * @param request_headers - headers from the request the CacheFilter is currently processing. - * @param response_headers - headers from the cached response the CacheFilter has retrieved. + * Determines whether the cached entry may be used directly or must be validated with upstream. + * @param request_headers - request headers associated with the response_headers. + * @param response_headers - headers from the cached response. * @param request_cache_control - the parsed result of the request's Cache-Control header, parsed * by the caller. * @param cached_response_cache_control - the parsed result of the response's Cache-Control @@ -84,7 +93,7 @@ class CachePolicy { SystemTime now) PURE; /** - * Perform actions when StreamInfo and FilterState become available, for + * Performs actions when StreamInfo and FilterState become available, for * example for logging and observability, or to adapt CacheFilter behavior based on * route-specific CacheFilter config. * @param callbacks - Gives access to StreamInfo and FilterState From d8acb03a595b5911a97b2d599dd884b345bffef9 Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Wed, 4 Aug 2021 13:41:55 -0400 Subject: [PATCH 8/9] Fix parameter name Signed-off-by: Josiah Kiehl --- source/extensions/filters/http/cache/cache_policy.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index 01b61864aab54..d20c81ceb34fa 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -2,7 +2,6 @@ #include "envoy/http/header_map.h" #include "envoy/stream_info/filter_state.h" - #include "source/extensions/filters/http/cache/cache_headers_utils.h" #include "source/extensions/filters/http/cache/http_cache.h" @@ -74,7 +73,7 @@ class CachePolicy { /** * Determines whether the cached entry may be used directly or must be validated with upstream. * @param request_headers - request headers associated with the response_headers. - * @param response_headers - headers from the cached response. + * @param cached_response_headers - headers from the cached response. * @param request_cache_control - the parsed result of the request's Cache-Control header, parsed * by the caller. * @param cached_response_cache_control - the parsed result of the response's Cache-Control From 891e87c69f686209f7b77c45b7804bcd344580ea Mon Sep 17 00:00:00 2001 From: Josiah Kiehl Date: Wed, 4 Aug 2021 14:18:37 -0400 Subject: [PATCH 9/9] Fix format Signed-off-by: Josiah Kiehl --- source/extensions/filters/http/cache/cache_policy.h | 1 + 1 file changed, 1 insertion(+) diff --git a/source/extensions/filters/http/cache/cache_policy.h b/source/extensions/filters/http/cache/cache_policy.h index d20c81ceb34fa..a283f20fc10b6 100644 --- a/source/extensions/filters/http/cache/cache_policy.h +++ b/source/extensions/filters/http/cache/cache_policy.h @@ -2,6 +2,7 @@ #include "envoy/http/header_map.h" #include "envoy/stream_info/filter_state.h" + #include "source/extensions/filters/http/cache/cache_headers_utils.h" #include "source/extensions/filters/http/cache/http_cache.h"