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;
}
