docs: clarify http cache filter architecture and document filesystem storage backend configuration (#40842)

Commit Message:
docs: clarify http cache filter architecture; document filesystem
storage backend config

Additional Description:
- Clarify the architecture and extension points (HTTP Cache filter vs.
storage
  backends) and how a storage backend is selected
- Add a filesystem storage backend configuration example
- Add links to related API/docs in the "See also" section

Partially addresses #16246.

Risk Level:
None (docs-only)

Testing:
- CI passed for this PR
- Verified in the preview artifact:
* the "Architecture and extension points" section appears in the page
(anchor link visible)
  * both example blocks appear under "Example configuration"
* the File System backend YAML snippet renders via `literalinclude`
(slice) with line numbers matching the source
  * the download link for `http-cache-configuration-fs.yaml` works
  * the "See also" links resolve

Docs Changes:
- docs/root/configuration/http/http_filters/cache_filter.rst
-
docs/root/configuration/http/http_filters/_include/http-cache-configuration-fs.yaml
(new)
- docs/BUILD (added FS include path to `configs` exclude list)

---------

Signed-off-by: Renin John <[email protected]>

Author: reninjohn

docs/BUILD

@@ -22,6 +22,7 @@ filegroup(
             "root/operations/_include/traffic_tapping_*.yaml",
             "root/configuration/http/http_filters/_include/checksum_filter.yaml",
             "root/configuration/http/http_filters/_include/dns-cache-circuit-breaker.yaml",
+            "root/configuration/http/http_filters/_include/http-cache-configuration-fs.yaml",
             "root/configuration/other_features/_include/dlb.yaml",
             "root/configuration/other_features/_include/hyperscan_matcher.yaml",
             "root/configuration/other_features/_include/hyperscan_matcher_multiple.yaml",

docs/root/configuration/http/http_filters/_include/http-cache-configuration-fs.yaml

@@ -0,0 +1,68 @@
+static_resources:
+  listeners:
+  - address:
+      socket_address:
+        address: 0.0.0.0
+        port_value: 8000
+    filter_chains:
+    - filters:
+      - name: envoy.filters.network.http_connection_manager
+        typed_config:
+          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+          codec_type: AUTO
+          stat_prefix: ingress_http
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: backend
+              domains:
+              - "*"
+              routes:
+              - match:
+                  prefix: "/service/1"
+                route:
+                  cluster: service1
+              - match:
+                  prefix: "/service/2"
+                route:
+                  cluster: service2
+          http_filters:
+          - name: envoy.filters.http.cache
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.cache.v3.CacheConfig
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.http.cache.file_system_http_cache.v3.FileSystemHttpCacheConfig
+                manager_config:
+                  thread_pool:
+                    thread_count: 2
+                cache_path: /var/cache/envoy
+                max_cache_size_bytes: 1073741824
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+  - name: service1
+    type: STRICT_DNS
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service1
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: service1
+                port_value: 8000
+  - name: service2
+    type: STRICT_DNS
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service2
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: service2
+                port_value: 8000

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

@@ -36,7 +36,15 @@ For HTTP Responses:
 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>`.
+Built-in cache storage backends include :ref:`SimpleHttpCacheConfig <envoy_v3_api_msg_extensions.http.cache.simple_http_cache.v3.SimpleHttpCacheConfig>` (in-memory) and :ref:`FileSystemHttpCacheConfig <envoy_v3_api_msg_extensions.http.cache.file_system_http_cache.v3.FileSystemHttpCacheConfig>` (persistent; LRU).
+
+Architecture and extension points
+---------------------------------
+
+Envoy’s HTTP caching is split into:
+
+* **HTTP Cache filter** (extension name ``envoy.filters.http.cache``, category ``envoy.filters.http``) — configured via ``CacheConfig`` to apply HTTP caching semantics.
+* **Cache storage backends** (extension category ``envoy.http.cache``) — the filter delegates object storage/retrieval to a backend, selected via a nested ``typed_config`` in ``CacheConfig``.
 
 Example configuration
 ---------------------
@@ -50,7 +58,26 @@ Example filter configuration with a ``SimpleHttpCache`` cache implementation:
    :lineno-start: 29
    :caption: :download:`http-cache-configuration.yaml <_include/http-cache-configuration.yaml>`
 
+Example filter configuration with a ``FileSystemHttpCache`` cache implementation:
+
+.. literalinclude:: _include/http-cache-configuration-fs.yaml
+   :language: yaml
+   :start-at: http_filters:
+   :end-before: envoy.filters.http.router
+   :linenos:
+   :lineno-match:
+   :caption: :download:`http-cache-configuration-fs.yaml <_include/http-cache-configuration-fs.yaml>`
+
 .. seealso::
 
    :ref:`Envoy Cache Sandbox <install_sandboxes_cache_filter>`
       Learn more about the Envoy Cache filter in the step by step sandbox.
+
+   :ref:`HTTP Cache filter (proto file) <envoy_v3_api_file_envoy/extensions/filters/http/cache/v3/cache.proto>`
+      ``CacheConfig`` API reference.
+
+   :ref:`In-memory storage backend <envoy_v3_api_file_envoy/extensions/http/cache/simple_http_cache/v3/config.proto>`
+      ``SimpleHttpCacheConfig`` API reference.
+
+   :ref:`Persistent on-disk storage backend <config_http_caches_file_system_http_cache>`
+      Docs page for File System Http Cache; links to ``FileSystemHttpCacheConfig`` API reference.