// Copyright 2022 gRPC 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.

// Local copy of Envoy xDS proto file, used for testing only.

syntax = "proto3";

package envoy.extensions.http.stateful_session.cookie.v3;

import "src/proto/grpc/testing/xds/v3/cookie.proto";

// [#protodoc-title: Cookie based stateful session extension]

// This extension allows the session state to be tracked via cookies.
//
// This extension first encodes the address of the upstream host selected by the load balancer
// into a ``set-cookie`` response header with the :ref:`cookie configuration
// <envoy_v3_api_field_extensions.http.stateful_session.cookie.v3.CookieBasedSessionState.cookie>`.
// when new requests are incoming, this extension will try to parse the specific upstream host
// address by the cookie name. If the address parsed from the cookie corresponds to a valid
// upstream host, this upstream host will be selected first. See :ref:`stateful session filter
// <envoy_v3_api_msg_extensions.filters.http.stateful_session.v3.StatefulSession>`.
//
// For example, if the cookie name is set to ``sticky-host``, envoy will prefer ``1.2.3.4:80``
// as the upstream host when the request contains the following header:
//
// .. code-block:: none
//
//     cookie: sticky-host="MS4yLjMuNDo4MA=="
//
// When processing the upstream response, if ``1.2.3.4:80`` is indeed the final choice the extension
// does nothing. If ``1.2.3.4:80`` is not the final choice, the new selected host will be used to
// update the cookie (via the ``set-cookie`` response header).
//
// [#extension: envoy.http.stateful_session.cookie]
message CookieBasedSessionState {
  // The cookie configuration used to track session state.
  type.http.v3.Cookie cookie = 1;
}