docs: fix typos and formatting issues (#28757)

Signed-off-by: Peter Jausovec <[email protected]>

Author: peterj

docs/root/configuration/http/http_filters/_include/aws_credentials.rst

@@ -5,12 +5,12 @@ The filter uses a few different credentials providers to obtain an AWS access ke
 It moves through the credentials providers in the order described below, stopping when one of them returns an access key ID and a
 secret access key (the session token is optional).
 
-1. Environment variables. The environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN are used.
+1. Environment variables. The environment variables ``AWS_ACCESS_KEY_ID``, ``AWS_SECRET_ACCESS_KEY``, and ``AWS_SESSION_TOKEN`` are used.
 
-2. The AWS credentials file. The environment variables AWS_SHARED_CREDENTIALS_FILE and AWS_PROFILE are respected if they are set, else
-   the file '~/.aws/credentials' and profile 'default' are used. The fields 'aws_access_key_id', 'aws_secret_access_key', and
-   'aws_session_token' defined for the profile in the credentials file are used. These credentials are cached for 1 hour.
+2. The AWS credentials file. The environment variables ``AWS_SHARED_CREDENTIALS_FILE`` and ``AWS_PROFILE`` are respected if they are set, else
+   the file ``~/.aws/credentials`` and profile ``default`` are used. The fields ``aws_access_key_id``, ``aws_secret_access_key``, and
+   ``aws_session_token`` defined for the profile in the credentials file are used. These credentials are cached for 1 hour.
 
-3. Either EC2 instance metadata or ECS task metadata. For EC2 instance metadata, the fields 'AccessKeyId', 'SecretAccessKey', and
-   'Token' are used, and credentials are cached for 1 hour. For ECS task metadata, the fields AccessKeyId', 'SecretAccessKey', and
-   'Token' are used, and credentials are cached for 1 hour or until they expire (according to the field 'Expiration').
+3. Either EC2 instance metadata or ECS task metadata. For EC2 instance metadata, the fields ``AccessKeyId``, ``SecretAccessKey``, and
+   ``Token`` are used, and credentials are cached for 1 hour. For ECS task metadata, the fields ``AccessKeyId``, ``SecretAccessKey``, and
+   ``Token`` are used, and credentials are cached for 1 hour or until they expire (according to the field ``Expiration``).

docs/root/configuration/http/http_filters/aws_lambda_filter.rst

@@ -39,8 +39,8 @@ is set to ``false``, then the HTTP request is transformed to a JSON payload with
 - ``headers`` are the HTTP request headers. If multiple headers share the same name, their values are
   coalesced into a single comma-separated value.
 - ``query_string_parameters`` are the HTTP request query string parameters. If multiple parameters share the same name,
-  the last one wins. That is, parameters are _not_ coalesced into a single value if they share the same key name.
-- ``body`` the body of the HTTP request is base64-encoded by the filter if the ``content-type`` header exists and is _not_ one of the following:
+  the last one wins. That is, parameters are **not** coalesced into a single value if they share the same key name.
+- ``body`` the body of the HTTP request is base64-encoded by the filter if the ``content-type`` header exists and is **not** one of the following:
 
     -  text/*
     -  application/json
@@ -66,7 +66,7 @@ On the other end, the response of the Lambda function must conform to the follow
   OK``.
 - The ``headers`` are used as the HTTP response headers.
 - The ``cookies`` are used as ``Set-Cookie`` response headers. Unlike the request headers, cookies are _not_ part of the
-  response headers because the ``Set-Cookie`` header cannot contain more than one value per the `RFC`_. Therefore, Each
+  response headers because the ``Set-Cookie`` header cannot contain more than one value per the `RFC`_. Therefore, each
   key/value pair in this JSON array will translate to a single ``Set-Cookie`` header.
 - The ``body`` is base64-decoded if it is marked as base64-encoded and sent as the body of the HTTP response.
 
@@ -200,4 +200,4 @@ comes from the owning HTTP connection manager.
   :widths: 1, 1, 2
 
   server_error, Counter, Total requests that returned invalid JSON response (see :ref:`payload_passthrough <envoy_v3_api_msg_extensions.filters.http.aws_lambda.v3.Config>`)
-  upstream_rq_payload_size, Histogram, Size in bytes of the request after JSON-tranformation (if any).
+  upstream_rq_payload_size, Histogram, Size in bytes of the request after JSON-transformation (if any).

docs/root/configuration/http/http_filters/aws_request_signing_filter.rst

@@ -23,7 +23,7 @@ policies to determine if this option is appropriate.
 
 When :ref:`use_unsigned_payload <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.use_unsigned_payload>`
 is false (the default), requests which exceed the configured buffer limit will receive a 413 response. See the
-ref:`flow control docs <faq_flow_control>` for details.
+:ref:`flow control docs <faq_flow_control>` for details.
 
 The :ref:`match_excluded_headers <envoy_v3_api_field_extensions.filters.http.aws_request_signing.v3.AwsRequestSigning.match_excluded_headers>`
 option allows excluding certain request headers from being signed. This usually applies to headers that are likely to mutate or

docs/root/configuration/http/http_filters/cache_filter.rst

@@ -17,14 +17,14 @@ For HTTP Requests:
 
 For HTTP Responses:
 
-* HTTP Cache only caches responses with enough data to calculate freshness lifetime as per `RFC7234#calculating.freshness.lifetime <https://httpwg.org/specs/rfc7234.html#calculating.freshness.lifetime>`_.
+* HTTP Cache only caches responses with enough data to calculate freshness lifetime as per `RFC7234 <https://httpwg.org/specs/rfc7234.html#calculating.freshness.lifetime>`_.
 * HTTP Cache respects ``Cache-Control`` directive from the upstream host. For example, if HTTP response returns status code 200 with ``Cache-Control: max-age=60`` and no ``vary`` header, it will be cached.
 * HTTP Cache only caches responses with status codes: 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 451, 501.
 
 HTTP Cache delegates the actual storage of HTTP responses to implementations of the ``HttpCache`` interface. These implementations can
 cover all points on the spectrum of persistence, performance, and distribution, from local RAM caches to globally distributed
 persistent caches. They can be fully custom caches, or wrappers/adapters around local or remote open-source or proprietary caches.
-Currently the only available cache storage implementation is :ref:`SimpleHTTPCache <envoy_v3_api_msg_extensions.http.cache.simple_http_cache.v3.SimpleHttpCacheConfig>`
+Currently the only available cache storage implementation is :ref:`SimpleHTTPCache <envoy_v3_api_msg_extensions.http.cache.simple_http_cache.v3.SimpleHttpCacheConfig>`.
 
 Example configuration
 ---------------------

docs/root/configuration/http/http_filters/composite_filter.rst

@@ -39,7 +39,7 @@ instantiated.
 Statistics
 ----------
 
-The composite filter outputs statistics in the <stat_prefix>.composite.* namespace.
+The composite filter outputs statistics in the ``<stat_prefix>.composite.*`` namespace.
 
 .. csv-table::
   :header: Name, Type, Description

docs/root/configuration/http/http_filters/compressor_filter.rst

@@ -55,60 +55,75 @@ An example configuration of the filter may look like the following:
 
 By *default* request compression is disabled, but when enabled it will be *skipped* if:
 
-- A request does not contain a *content-type* value that matches one of the selected
-  mime-types, which default to *application/javascript*, *application/json*,
-  *application/xhtml+xml*, *image/svg+xml*, *text/css*, *text/html*, *text/plain*,
-  *text/xml*.
-- *content-length* header is not present in the request.
-- A request contains a *content-encoding* header.
-- A request contains a *transfer-encoding* header whose value includes a known
+- A request does **not** contain a ``content-type`` value that matches one of the selected
+  mime-types, which default to the following:
+
+  - ``application/javascript``
+  - ``application/json``
+  - ``application/xhtml+xml``
+  - ``image/svg+xml``
+  - ``text/css``
+  - ``text/html``
+  - ``text/plain``
+  - ``text/xml``
+
+- A request does **not** contain a ``content-length`` header.
+- A request contains a ``content-encoding`` header.
+- A request contains a ``transfer-encoding`` header whose value includes a known
   compression name.
 
 By *default* response compression is enabled, but it will be *skipped* when:
 
-- A request does NOT contain *accept-encoding* header.
-- A request includes *accept-encoding* header, but it does not contain "gzip" or "\*".
-- A request includes *accept-encoding* with "gzip" or "\*" with the weight "q=0". Note
-  that the "gzip" will have a higher weight then "\*". For example, if *accept-encoding*
-  is "gzip;q=0,\*;q=1", the filter will not compress. But if the header is set to
-  "\*;q=0,gzip;q=1", the filter will compress.
-- A request whose *accept-encoding* header includes any encoding type with a higher
-  weight than "gzip"'s given the corresponding compression filter is present in the chain.
-- A response contains a *content-encoding* header.
-- A response contains a *cache-control* header whose value includes "no-transform".
-- A response contains a *transfer-encoding* header whose value includes a known
+- A request does **not** contain ``accept-encoding`` header.
+- A request contains an ``accept-encoding`` header, but it does not contain ``gzip`` or ``\*``.
+- A request contains an ``accept-encoding`` header with ``gzip`` or ``\*```` with the weight ``q=0``. Note
+  that the ``gzip`` will have a higher weight than ``\*``. For example, if ``accept-encoding``
+  is ``gzip;q=0,\*;q=1``, the filter will not compress. But if the header is set to
+  ``\*;q=0,gzip;q=1``, the filter will compress.
+- A request whose ``accept-encoding`` header includes any encoding type with a higher
+  weight than ``gzip``'s given the corresponding compression filter is present in the chain.
+- A response contains a ``content-encoding`` header.
+- A response contains a ``cache-control```` header whose value includes ``no-transform``.
+- A response contains a ``transfer-encoding```` header whose value includes a known
   compression name.
-- A response does not contain a *content-type* value that matches one of the selected
-  mime-types, which default to *application/javascript*, *application/json*,
-  *application/xhtml+xml*, *image/svg+xml*, *text/css*, *text/html*, *text/plain*,
-  *text/xml*.
-- Neither *content-length* nor *transfer-encoding* headers are present in
-  the response.
-- Response size is smaller than 30 bytes (only applicable when *transfer-encoding*
+- A response does **not** contain a ``content-type`` value that matches one of the selected
+  mime-types, which default to:
+
+  - ``application/javascript``
+  - ``application/json``
+  - ``application/xhtml+xml``
+  - ``image/svg+xml``
+  - ``text/css``
+  - ``text/html``
+  - ``text/plain``
+  - ``text/xml``
+
+- A response does **not** contain a ``content-length`` or ``transfer-encoding`` headers.
+- Response size is smaller than 30 bytes (only applicable when ``transfer-encoding``
   is not chunked).
 
 Please note that in case the filter is configured to use a compression library extension
-other than gzip it looks for content encoding in the *accept-encoding* header provided by
+other than gzip it looks for content encoding in the ``accept-encoding`` header provided by
 the extension.
 
 When response compression is *applied*:
 
-- The *content-length* is removed from response headers.
-- Response headers contain "*transfer-encoding: chunked*", and
-  "*content-encoding*" with the compression scheme used (e.g., ``gzip``).
-- The "*vary: accept-encoding*" header is inserted on every response.
+- The ``content-length`` is removed from response headers.
+- Response headers contain ``transfer-encoding: chunked``, and
+  ``content-encoding`` with the compression scheme used (e.g., ``gzip``).
+- The ``vary: accept-encoding`` header is inserted on every response.
 
-Also the "*vary: accept-encoding*" header may be inserted even if compression is *not*
-applied due to incompatible "*accept-encoding*" header in a request. This happens
-when the requested resource still can be compressed given compatible "*accept-encoding*".
+Also the ``vary: accept-encoding`` header may be inserted even if compression is **not**
+applied due to incompatible ``accept-encoding`` header in a request. This happens
+when the requested resource can still be compressed given compatible ``accept-encoding``.
 Otherwise, if an uncompressed response is cached by a caching proxy in front of Envoy,
-the proxy won't know to fetch a new incoming request with compatible "*accept-encoding*"
+the proxy won't know to fetch a new incoming request with compatible ``accept-encoding``
 from upstream.
 
 When request compression is *applied*:
 
-- *content-length* is removed from request headers.
-- *content-encoding* with the compression scheme used (e.g., ``gzip``) is added to
+- ``content-length`` is removed from request headers.
+- ``content-encoding`` with the compression scheme used (e.g., ``gzip``) is added to
   request headers.
 
 Per-Route Configuration
@@ -215,12 +230,12 @@ specific to responses only:
   :widths: 1, 1, 2
 
   no_accept_header, Counter, Number of requests with no accept header sent.
-  header_identity, Counter, Number of requests sent with "identity" set as the *accept-encoding*.
-  header_compressor_used, Counter, Number of requests sent with filter's configured encoding set as the *accept-encoding*.
+  header_identity, Counter, Number of requests sent with "identity" set as the ``accept-encoding``.
+  header_compressor_used, Counter, Number of requests sent with filter's configured encoding set as the ``accept-encoding``.
   header_compressor_overshadowed, Counter, Number of requests skipped by this filter instance because they were handled by another filter in the same filter chain.
-  header_wildcard, Counter, Number of requests sent with "\*" set as the *accept-encoding*.
-  header_not_valid, Counter, Number of requests sent with a not valid *accept-encoding* header (aka "q=0" or an unsupported encoding type).
-  not_compressed_etag, Counter, Number of requests that were not compressed due to the etag header. *disable_on_etag_header* must be turned on for this to happen.
+  header_wildcard, Counter, Number of requests sent with ``\*`` set as the ``accept-encoding``.
+  header_not_valid, Counter, Number of requests sent with a not valid ``accept-encoding`` header (aka ``q=0`` or an unsupported encoding type).
+  not_compressed_etag, Counter, Number of requests that were not compressed due to the etag header. ``disable_on_etag_header`` must be turned on for this to happen.
 
 .. attention:
 

docs/root/configuration/http/http_filters/connect_grpc_bridge_filter.rst

@@ -8,7 +8,7 @@ Connect-gRPC Bridge
 * :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.connect_grpc_bridge.v3.FilterConfig>`
 
 This filter enables a Buf Connect client to connect to a compliant gRPC server.
-More information on the Buf Connect protocol can be found here https://connect.build/docs/protocol.
+More information on the Buf Connect protocol can be found `here <https://connect.build/docs/protocol>`_.
 
 HTTP GET support
 ----------------

docs/root/configuration/http/http_filters/cors_filter.rst

@@ -45,7 +45,7 @@ will not enforce any policies.
 Statistics
 ----------
 
-The CORS filter outputs statistics in the <stat_prefix>.cors.* namespace.
+The CORS filter outputs statistics in the ``<stat_prefix>.cors.*`` namespace.
 
 .. note::
   Requests that do not have an Origin header will be omitted from statistics.

docs/root/configuration/http/http_filters/csrf_filter.rst

@@ -20,7 +20,8 @@ There are many ways to mitigate CSRF, some of which have been outlined in the
 This filter employs a stateless mitigation pattern known as origin verification.
 
 This pattern relies on two pieces of information used in determining if
-a request originated from the same host.
+a request originated from the same host:
+
 * The origin that caused the user agent to issue the request (source origin).
 * The origin that the request is going to (target origin).
 
@@ -39,7 +40,7 @@ requests, the filter only acts on HTTP requests that have a state-changing metho
 
 For more information on CSRF please refer to the pages below.
 
-* https://www.owasp.org/index.php/Cross-Site_Request_Forgery_%28CSRF%29
+* https://owasp.org/www-community/attacks/csrf
 * https://seclab.stanford.edu/websec/csrf/csrf.pdf
 * This filter should be configured with the type URL ``type.googleapis.com/envoy.extensions.filters.http.csrf.v3.CsrfPolicy``.
 * :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.csrf.v3.CsrfPolicy>`
@@ -52,7 +53,7 @@ Configuration
 The CSRF filter supports the ability to extend the source origins it will consider
 valid. The reason it is able to do this while still mitigating cross-site request
 forgery attempts is because the target origin has already been reached by the time
-front-envoy is applying the filter. This means that while endpoints may support
+front Envoy is applying the filter. This means that while endpoints may support
 cross-origin requests they are still protected from malicious third-parties who
 have not been allowlisted.
 
@@ -92,7 +93,7 @@ to determine if it's valid but will not enforce any policies.
 Statistics
 ----------
 
-The CSRF filter outputs statistics in the <stat_prefix>.csrf.* namespace.
+The CSRF filter outputs statistics in the ``<stat_prefix>.csrf.`` namespace.
 
 .. csv-table::
   :header: Name, Type, Description

docs/root/configuration/http/http_filters/decompressor_filter.rst

@@ -37,27 +37,27 @@ An example configuration of the filter may look like the following:
 
 By *default* decompression will be *skipped* when:
 
-- A request/response does NOT contain *content-encoding* header.
-- A request/response includes *content-encoding* header, but it does not contain the configured
-  decompressor's content-encoding.
-- A request/response contains a *cache-control* header whose value includes "no-transform",
+- A request/response does **not** contain ``content-encoding`` header.
+- A request/response contains a ``content-encoding`` header, but it does not contain the configured
+  decompressor's ``content-encoding``.
+- A request/response contains a ``cache-control`` header whose value includes ``no-transform``,
   unless :ref:`ignore_no_transform_header <envoy_v3_api_field_extensions.filters.http.decompressor.v3.Decompressor.CommonDirectionConfig.ignore_no_transform_header>`
-  is set to *true*.
+  is set to ``true``.
 
-When decompression is *applied*:
+Decompression is *applied* when:
 
-- The *content-length* is removed from headers.
+- The ``content-length`` is removed from headers.
 
   .. note::
 
-    If an updated *content-length* header is desired, the buffer filter can be installed as part
+    If an updated ``content-length`` header is desired, the :ref: `buffer filter <_config_http_filters_buffer>` can be installed as part
     of the filter chain to buffer decompressed frames, and ultimately update the header. Due to
     :ref:`filter ordering <arch_overview_http_filters_ordering>` a buffer filter needs to be
     installed after the decompressor for requests and prior to the decompressor for responses.
 
-- The *content-encoding* header is modified to remove the decompression that was applied.
+- The ``content-encoding`` header is modified to remove the decompression that was applied.
 
-- *x-envoy-decompressor-<decompressor_name>-<compressed/uncompressed>-bytes* trailers are added to
+- ``x-envoy-decompressor-<decompressor_name>-<compressed/uncompressed>-bytes`` trailers are added to
   the request/response to relay information about decompression.
 
 Using different decompressors for requests and responses
@@ -106,7 +106,7 @@ Statistics
 ----------
 
 Every configured Deompressor filter has statistics rooted at
-<stat_prefix>.decompressor.<decompressor_library.name>.<decompressor_library_stat_prefix>.<request/response>*
+``<stat_prefix>.decompressor.<decompressor_library.name>.<decompressor_library_stat_prefix>.<request/response>*``
 with the following:
 
 .. csv-table::
@@ -119,4 +119,4 @@ with the following:
   total_compressed_bytes, Counter, The total compressed bytes of all the request/responses that were marked for decompression.
 
 Additional stats for the decompressor library are rooted at
-<stat_prefix>.decompressor.<decompressor_library.name>.<decompressor_library_stat_prefix>.decompressor_library.
+``<stat_prefix>.decompressor.<decompressor_library.name>.<decompressor_library_stat_prefix>.decompressor_library``.