consul/proto-public/pbmesh/v2beta1/http_route.proto

// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: MPL-2.0

syntax = "proto3";

package hashicorp.consul.mesh.v2beta1;

import "pbmesh/v2beta1/common.proto";
import "pbmesh/v2beta1/http_route_retries.proto";
import "pbmesh/v2beta1/http_route_timeouts.proto";
import "pbresource/annotations.proto";

// NOTE: this should align to the GAMMA/gateway-api version, or at least be
// easily translatable.
//
// https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute
//
// This is a Resource type.
message HTTPRoute {
  option (hashicorp.consul.resource.spec) = {scope: SCOPE_NAMESPACE};

  // ParentRefs references the resources (usually Services) that a Route wants
  // to be attached to.
  //
  // It is invalid to reference an identical parent more than once. It is valid
  // to reference multiple distinct sections within the same parent resource.
  repeated ParentReference parent_refs = 1;

  // Hostnames are the hostnames for which this HTTPRoute should respond to requests.
  //
  // This is only valid for north/south.
  repeated string hostnames = 2;

  // Rules are a list of HTTP-based routing rules that this route should
  // use for constructing a routing table.
  repeated HTTPRouteRule rules = 3;
}

// HTTPRouteRule specifies the routing rules used to determine what upstream
// service an HTTP request is routed to.
message HTTPRouteRule {
  repeated HTTPRouteMatch matches = 1;
  repeated HTTPRouteFilter filters = 2;

  // BackendRefs defines the backend(s) where matching requests should be sent.
  //
  // Failure behavior here depends on how many BackendRefs are specified and
  // how many are invalid.
  //
  // If all entries in BackendRefs are invalid, and there are also no filters
  // specified in this route rule, all traffic which matches this rule MUST
  // receive a 500 status code.
  //
  // See the HTTPBackendRef definition for the rules about what makes a single
  // HTTPBackendRef invalid.
  //
  // When a HTTPBackendRef is invalid, 500 status codes MUST be returned for
  // requests that would have otherwise been routed to an invalid backend. If
  // multiple backends are specified, and some are invalid, the proportion of
  // requests that would otherwise have been routed to an invalid backend MUST
  // receive a 500 status code.
  //
  // For example, if two backends are specified with equal weights, and one is
  // invalid, 50 percent of traffic must receive a 500. Implementations may
  // choose how that 50 percent is determined.
  repeated HTTPBackendRef backend_refs = 3;

  HTTPRouteTimeouts timeouts = 4;
  HTTPRouteRetries retries = 5;
}

message HTTPRouteMatch {
  // Path specifies a HTTP request path matcher. If this field is not
  // specified, a default prefix match on the “/” path is provided.
  HTTPPathMatch path = 1;

  // Headers specifies HTTP request header matchers. Multiple match values are
  // ANDed together, meaning, a request must match all the specified headers to
  // select the route.
  repeated HTTPHeaderMatch headers = 2;

  // QueryParams specifies HTTP query parameter matchers. Multiple match values
  // are ANDed together, meaning, a request must match all the specified query
  // parameters to select the route.
  repeated HTTPQueryParamMatch query_params = 3;

  // Method specifies HTTP method matcher. When specified, this route will be
  // matched only if the request has the specified method.
  string method = 4;
}

message HTTPPathMatch {
  // Type specifies how to match against the path Value.
  PathMatchType type = 1;
  // Value of the HTTP path to match against.
  string value = 2;
}

// PathMatchType specifies the semantics of how HTTP paths should be compared.
// Valid PathMatchType values, along with their support levels, are:
//
// PathPrefix and Exact paths must be syntactically valid:
//
// - Must begin with the / character
// - Must not contain consecutive / characters (e.g. /foo///, //).
// - Note that values may be added to this enum, implementations must ensure that unknown values will not cause a crash.
//
// Unknown values here must result in the implementation setting the Accepted
// Condition for the Route to status: False, with a Reason of UnsupportedValue.
//
// +kubebuilder:validation:Enum=PATH_MATCH_TYPE_UNSPECIFIED;PATH_MATCH_TYPE_EXACT;PATH_MATCH_TYPE_PREFIX;PATH_MATCH_TYPE_REGEX
// +kubebuilder:validation:Type=string
enum PathMatchType {
  PATH_MATCH_TYPE_UNSPECIFIED = 0;
  PATH_MATCH_TYPE_EXACT = 1;
  PATH_MATCH_TYPE_PREFIX = 2;
  PATH_MATCH_TYPE_REGEX = 3;
}

message HTTPHeaderMatch {
  // Type specifies how to match against the value of the header.
  HeaderMatchType type = 1;

  // Name is the name of the HTTP Header to be matched. Name matching MUST be
  // case insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2).
  //
  // If multiple entries specify equivalent header names, only the first entry
  // with an equivalent name MUST be considered for a match. Subsequent entries
  // with an equivalent header name MUST be ignored. Due to the
  // case-insensitivity of header names, “foo” and “Foo” are considered
  // equivalent.
  //
  // When a header is repeated in an HTTP request, it is
  // implementation-specific behavior as to how this is represented. Generally,
  // proxies should follow the guidance from the RFC:
  // https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2.2 regarding
  // processing a repeated header, with special handling for “Set-Cookie”.
  string name = 2;

  // Value is the value of HTTP Header to be matched.
  string value = 3;

  // NOTE: not in gamma; service-router compat
  bool invert = 4;
}

// HeaderMatchType specifies the semantics of how HTTP header values should be
// compared. Valid HeaderMatchType values, along with their conformance levels,
// are:
//
// Note that values may be added to this enum, implementations must ensure that
// unknown values will not cause a crash.
//
// Unknown values here must result in the implementation setting the Accepted
// Condition for the Route to status: False, with a Reason of UnsupportedValue.
//
// +kubebuilder:validation:Enum=HEADER_MATCH_TYPE_UNSPECIFIED;HEADER_MATCH_TYPE_EXACT;HEADER_MATCH_TYPE_REGEX;HEADER_MATCH_TYPE_PRESENT;HEADER_MATCH_TYPE_PREFIX;HEADER_MATCH_TYPE_SUFFIX
// +kubebuilder:validation:Type=string
enum HeaderMatchType {
  HEADER_MATCH_TYPE_UNSPECIFIED = 0;
  HEADER_MATCH_TYPE_EXACT = 1;
  HEADER_MATCH_TYPE_REGEX = 2;
  // consul only after this point (service-router compat)
  HEADER_MATCH_TYPE_PRESENT = 3;
  HEADER_MATCH_TYPE_PREFIX = 4;
  HEADER_MATCH_TYPE_SUFFIX = 5;
}

message HTTPQueryParamMatch {
  // Type specifies how to match against the value of the query parameter.
  QueryParamMatchType type = 1;

  // Name is the name of the HTTP query param to be matched. This must be an
  // exact string match. (See
  // https://tools.ietf.org/html/rfc7230#section-2.7.3).
  //
  // If multiple entries specify equivalent query param names, only the first
  // entry with an equivalent name MUST be considered for a match. Subsequent
  // entries with an equivalent query param name MUST be ignored.
  //
  // If a query param is repeated in an HTTP request, the behavior is purposely
  // left undefined, since different data planes have different capabilities.
  // However, it is recommended that implementations should match against the
  // first value of the param if the data plane supports it, as this behavior
  // is expected in other load balancing contexts outside of the Gateway API.
  //
  // Users SHOULD NOT route traffic based on repeated query params to guard
  // themselves against potential differences in the implementations.
  string name = 2;

  // Value is the value of HTTP query param to be matched.
  string value = 3;
}

// +kubebuilder:validation:Enum=QUERY_PARAM_MATCH_TYPE_UNSPECIFIED;QUERY_PARAM_MATCH_TYPE_EXACT;QUERY_PARAM_MATCH_TYPE_REGEX;QUERY_PARAM_MATCH_TYPE_PRESENT
// +kubebuilder:validation:Type=string
enum QueryParamMatchType {
  QUERY_PARAM_MATCH_TYPE_UNSPECIFIED = 0;
  QUERY_PARAM_MATCH_TYPE_EXACT = 1;
  QUERY_PARAM_MATCH_TYPE_REGEX = 2;
  // consul only after this point (service-router compat)
  QUERY_PARAM_MATCH_TYPE_PRESENT = 3;
}

message HTTPRouteFilter {
  // RequestHeaderModifier defines a schema for a filter that modifies request
  // headers.
  HTTPHeaderFilter request_header_modifier = 1;

  // ResponseHeaderModifier defines a schema for a filter that modifies
  // response headers.
  HTTPHeaderFilter response_header_modifier = 2;

  // URLRewrite defines a schema for a filter that modifies a request during
  // forwarding.
  HTTPURLRewriteFilter url_rewrite = 5;
}

message HTTPHeaderFilter {
  // Set overwrites the request with the given header (name, value) before the
  // action.
  repeated HTTPHeader set = 1;

  // Add adds the given header(s) (name, value) to the request before the
  // action. It appends to any existing values associated with the header name.
  repeated HTTPHeader add = 2;

  // Remove the given header(s) from the HTTP request before the action. The
  // value of Remove is a list of HTTP header names. Note that the header names
  // are case-insensitive (see
  // https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
  repeated string remove = 3;
}

message HTTPHeader {
  string name = 1;
  string value = 2;
}

message HTTPURLRewriteFilter {
  string path_prefix = 1;
}

message HTTPBackendRef {
  BackendReference backend_ref = 1;

  // Weight specifies the proportion of requests forwarded to the referenced
  // backend. This is computed as weight/(sum of all weights in this
  // BackendRefs list). For non-zero values, there may be some epsilon from the
  // exact proportion defined here depending on the precision an implementation
  // supports. Weight is not a percentage and the sum of weights does not need
  // to equal 100.
  //
  // If only one backend is specified and it has a weight greater than 0, 100%
  // of the traffic is forwarded to that backend. If weight is set to 0, no
  // traffic should be forwarded for this entry. If unspecified, weight defaults
  // to 1.
  uint32 weight = 2;

  // Filters defined at this level should be executed if and only if the
  // request is being forwarded to the backend defined here.
  repeated HTTPRouteFilter filters = 3;
}