// 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.type.http.v3;

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

option java_package = "io.envoyproxy.envoy.type.http.v3";
option java_outer_classname = "PathTransformationProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/type/http/v3;httpv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;

// [#protodoc-title: Path Transformations API]

// PathTransformation defines an API to apply a sequence of operations that can be used to alter
// text before it is used for matching or routing. Multiple actions can be applied in the same
// Transformation, forming a sequential pipeline. The transformations will be performed in the order
// that they appear.
//
// This API is a work in progress.

message PathTransformation {
  // A type of operation to alter text.
  message Operation {
    // Should text be normalized according to RFC 3986? This typically is used for path headers
    // before any processing of requests by HTTP filters or routing. This applies percent-encoded
    // normalization and path segment normalization. Fails on characters disallowed in URLs
    // (e.g. NULLs). See `Normalization and Comparison
    // <https://tools.ietf.org/html/rfc3986#section-6>`_ for details of normalization. Note that
    // this options does not perform `case normalization
    // <https://tools.ietf.org/html/rfc3986#section-6.2.2.1>`_
    message NormalizePathRFC3986 {
    }

    // Determines if adjacent slashes are merged into one. A common use case is for a request path
    // header. Using this option in ``:ref: PathNormalizationOptions
    // <envoy_v3_api_msg_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.PathNormalizationOptions>``
    // will allow incoming requests with path ``//dir///file`` to match against route with ``prefix``
    // match set to ``/dir``. When using for header transformations, note that slash merging is not
    // part of `HTTP spec <https://tools.ietf.org/html/rfc3986>`_ and is provided for convenience.
    message MergeSlashes {
    }

    oneof operation_specifier {
      option (validate.required) = true;

      // Enable path normalization per RFC 3986.
      NormalizePathRFC3986 normalize_path_rfc_3986 = 2;

      // Enable merging adjacent slashes.
      MergeSlashes merge_slashes = 3;
    }
  }

  // A list of operations to apply. Transformations will be performed in the order that they appear.
  repeated Operation operations = 1;
}
