.. _envoy_v3_api_file_envoy/extensions/http/stateful_session/envelope/v3/envelope.proto:

Envelope stateful session extension (proto)
===========================================






.. _envoy_v3_api_msg_extensions.http.stateful_session.envelope.v3.EnvelopeSessionState:

extensions.http.stateful_session.envelope.v3.EnvelopeSessionState
-----------------------------------------------------------------


:repo:`[extensions.http.stateful_session.envelope.v3.EnvelopeSessionState proto] <api/envoy/extensions/http/stateful_session/envelope/v3/envelope.proto#L29>`

The extension allows the session state is tracked via existing session context that initialized
by the upstream server. It assumes that the upstream server will generate the session context
(like session id header or cookie) in the initial response of the session and the client will use
the same session context in the subsequent requests without any modification.

When processing the response from the upstream, Envoy will check if the response contains the
session context. If the response contains the session context, no matter if it's a new session
context or an existing one, Envoy will join it and the upstream host as new session context.

When processing the request from the downstream, Envoy will check if the request contains the
session context. If the request contains the session context, Envoy will strip the
upstream host from the session context.


.. _extension_envoy.http.stateful_session.envelope:

This extension has the qualified name ``envoy.http.stateful_session.envelope``


.. note::
  This extension is functional but has not had substantial production burn time,
  use only with this caveat.

  This extension has an unknown security posture and should only be
  used in deployments where both the downstream and upstream are
  trusted.

.. tip::
  This extension extends and can be used with the following extension category:


  - :ref:`envoy.http.stateful_session <extension_category_envoy.http.stateful_session>`



  This extension must be configured with one of the following type URLs:



  - :ref:`type.googleapis.com/envoy.extensions.http.stateful_session.envelope.v3.EnvelopeSessionState <envoy_v3_api_msg_extensions.http.stateful_session.envelope.v3.EnvelopeSessionState>`




.. code-block:: json
  :force:

  {
    "header": {...}
  }

.. _envoy_v3_api_field_extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.header:


header
  (:ref:`extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.Header <envoy_v3_api_msg_extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.Header>`, *REQUIRED*) Set the header config to track the session state.


.. _envoy_v3_api_msg_extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.Header:

extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.Header
------------------------------------------------------------------------


:repo:`[extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.Header proto] <api/envoy/extensions/http/stateful_session/envelope/v3/envelope.proto#L30>`




.. code-block:: json
  :force:

  {
    "name": ...
  }

.. _envoy_v3_api_field_extensions.http.stateful_session.envelope.v3.EnvelopeSessionState.Header.name:


name
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) Iff the header specified by the ``name`` field is present in the response (assume the ``name``
  is set to ``session-header`` and original header value is ``xxxxxx``), then the upstream host
  address and value of ``name`` field specified header will be encoded in following format and
  the output will be used to update the ``name`` field specified header in the response:

  .. code-block:: none

    session-header: "MS4yLjMuNDo4MAo=;UV:eHh4eHh4Cg==" # base64(1.2.3.4:80);UV:base64(xxxxxx)

  The ``UV`` (upstream value) part is used to store the original upstream header value of
  ``name`` field specified header.

  If this mode is used then Envoy will assume that the header in the request will also be in the
  same format and will contain the ``UV`` part. This extension will parse the upstream host
  address and update the ``name`` field specified header in the request to the ``UV`` part.