// Copyright 2025 Envoy Project Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
//     http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

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 "google/protobuf/wrappers.proto";

import "udpa/annotations/status.proto";
import "udpa/annotations/versioning.proto";

option java_package = "io.envoyproxy.envoy.extensions.filters.http.cache.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/v3;cachev3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: HTTP Cache Filter]

// [#extension: envoy.filters.http.cache]
// [#next-free-field: 7]
message CacheConfig {
  option (udpa.annotations.versioning).previous_message_type =
      "envoy.config.filter.http.cache.v2alpha.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.v2alpha.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. Required unless ``disabled``
  // is true.
  // [#extension-category: envoy.http.cache]
  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;

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