[WIP] examples: Add cache-mirror sandbox

docs/root/start/sandboxes/cache-mirror.rst

@@ -0,0 +1,64 @@
+.. _install_sandboxes_cache_mirror:
+
+Caching mirror
+==============
+
+.. sidebar:: Requirements
+
+   .. include:: _include/docker-env-setup-link.rst
+
+   :ref:`curl <start_sandboxes_setup_curl>`
+        Used to make ``HTTP`` requests.
+
+This is a simple example to demonstrate caching resources from an upstream, validating their contents against known checksums using the ``ChecksumFilter``.
+
+This can be useful, for example, to cache build assets for improved speed or reliability.
+
+The example uses a backend that serves 2 endpoints ``/foo`` and ``/bar``, that are expected to return ``FOO`` and ``BAR`` respectively.
+
+In the latter case it does not and therefore fails validation and is not cached or proxied.
+
+The cache mirror inserts a cache-forever header in any validated resources to ensure they are cached without expiry. (TODO)
+
+Step 1: Start all of our containers
+***********************************
+
+Change to the ``examples/cache-mirror`` directory.
+
+.. code-block:: console
+
+    $ pwd
+    envoy/examples/cache-mirror
+    $ docker compose pull
+    $ docker compose up --build -d
+    $ docker compose ps
+
+    NAME                         IMAGE                      COMMAND                 SERVICE       CREATED        STATUS        PORTS
+    ------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+    cache-mirror-backend-1       cache-mirror-backend       "/docker-entrypoint.…"  backend       6 seconds ago  Up 5 seconds  10000/tcp
+    cache-mirror-mirror-proxy-1  cache-mirror-mirror-proxy  "/docker-entrypoint.…"  mirror-proxy  6 seconds ago  Up 5 seconds  0.0.0.0:10000->10000/tcp, :::10000->10000/tcp
+
+
+Step 2: Fetch the cached asset
+******************************
+
+Step 3: Check the stats
+***********************
+
+Step 4: Fetch the cached asset again
+************************************
+
+Step 5: Confirm the asset was served from cache
+***********************************************
+
+Step 6: Fetch cached asset with invalid checksum
+************************************************
+
+Step 7: Confirm the asset was not cached
+****************************************
+
+
+.. seealso::
+
+   :ref:`Envoy Cache filter configuration <config_http_filters_cache>`
+      Learn more about configuring the Envoy Cache filter.

docs/root/start/sandboxes/index.rst

@@ -47,6 +47,7 @@ The following sandboxes are available:
 
     brotli
     cache
+    cache-mirror
     cors
     csrf
     double-proxy

examples/BUILD

@@ -16,6 +16,7 @@ filegroup(
         exclude = [
             "cache/ci-responses.yaml",
             "cache/responses.yaml",
+            "cache-mirror/envoy.yaml",
             "dynamic-config-fs/**/*",
             "jaeger-native-tracing/*",
             "opentelemetry/otel-collector-config.yaml",
@@ -34,6 +35,7 @@ filegroup(
     name = "contrib_configs",
     srcs = glob(
         [
+            "cache-mirror/envoy.yaml",
             "golang-http/*.yaml",
             "golang-network/*.yaml",
             "mysql/*.yaml",

examples/cache-mirror/docker-compose.yml

@@ -0,0 +1,16 @@
+services:
+  mirror-proxy:
+    build:
+      context: .
+      dockerfile: ../shared/envoy/Dockerfile
+      args:
+        ENVOY_VARIANT: contrib-dev
+    ports:
+    - "${PORT_PROXY:-10000}:10000"
+
+  backend:
+    build:
+      context: .
+      dockerfile: ../shared/envoy/Dockerfile
+      args:
+        ENVOY_CONFIG: envoy-backend.yaml

examples/cache-mirror/envoy-backend.yaml

@@ -0,0 +1,36 @@
+static_resources:
+  listeners:
+  - name: listener_0
+    address:
+      socket_address:
+        protocol: TCP
+        address: 0.0.0.0
+        port_value: 10000
+    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
+          stat_prefix: ingress_http
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: local_service
+              domains: ["*"]
+              routes:
+              - match:
+                  prefix: "/foo"
+                direct_response:
+                  status: 200
+                  body:
+                    inline_string: "FOO"
+              - match:
+                  prefix: "/bar"
+                direct_response:
+                  status: 200
+                  body:
+                    inline_string: "BAZ"
+          http_filters:
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router

examples/cache-mirror/envoy.yaml

@@ -0,0 +1,63 @@
+static_resources:
+  listeners:
+  - name: listener_0
+    address:
+      socket_address:
+        protocol: TCP
+        address: 0.0.0.0
+        port_value: 10000
+    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
+          stat_prefix: ingress_http
+          access_log:
+          - name: envoy.access_loggers.stdout
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.access_loggers.stream.v3.StdoutAccessLog
+          route_config:
+            name: local_route
+            virtual_hosts:
+            - name: local_service
+              domains: ["*"]
+              routes:
+              - match:
+                  prefix: "/"
+                route:
+                  host_rewrite_literal: github.com
+                  cluster: github_com
+          http_filters:
+          - name: envoy.filters.http.checksum
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.checksum.v3alpha.ChecksumConfig
+              checksums:
+              - path_matcher:
+                  exact: /foo
+                sha256: 1706b5c18e4358041b463995efc30f8f721766fab0e018d50d85978b46df013c
+              - path_matcher:
+                  exact: /badfoo
+                sha256: e629cbae1acb296c138795f38149a3efc0eb894e041f2dc588864c8103bc5843
+          - name: envoy.filters.http.router
+            typed_config:
+              "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+  clusters:
+  - name: github_com
+    type: LOGICAL_DNS
+    # Comment out the following line to test on v6 networks
+    dns_lookup_family: V4_ONLY
+    lb_policy: ROUND_ROBIN
+    load_assignment:
+      cluster_name: service_github_com
+      endpoints:
+      - lb_endpoints:
+        - endpoint:
+            address:
+              socket_address:
+                address: github.com
+                port_value: 443
+    transport_socket:
+      name: envoy.transport_sockets.tls
+      typed_config:
+        "@type": type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.UpstreamTlsContext
+        sni: github.com

examples/cache-mirror/verify.sh

@@ -0,0 +1,9 @@
+#!/bin/bash -e
+
+export NAME=caching-mirror
+
+export PORT_PROXY="${CACHE_MIRROR_PORT_PROXY:-10330}"
+
+
+# shellcheck source=examples/verify-common.sh
+. "$(dirname "${BASH_SOURCE[0]}")/../verify-common.sh"

examples/shared/envoy/Dockerfile

@@ -3,17 +3,18 @@ ARG ENVOY_VARIANT="${ENVOY_VARIANT:-dev}"
 
 
 FROM ${ENVOY_IMAGE}:${ENVOY_VARIANT} as envoy-base
-ARG ENVOY_CONFIG=envoy.yaml
-ENV ENVOY_CONFIG="$ENVOY_CONFIG"
 ENV DEBIAN_FRONTEND=noninteractive
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
     rm -f /etc/apt/apt.conf.d/docker-clean \
     && echo 'Binary::apt::APT::Keep-Downloaded-Packages "true";' | tee /etc/apt/apt.conf.d/keep-cache \
     && apt-get -qq update -y \
     && apt-get -qq install --no-install-recommends -y curl
-COPY --chmod=777 "$ENVOY_CONFIG" /etc/envoy.yaml
 CMD ["/usr/local/bin/envoy", "-c", "/etc/envoy.yaml"]
+ARG ENVOY_CONFIG=envoy.yaml
+ENV ENVOY_CONFIG="$ENVOY_CONFIG"
+COPY --chmod=777 "$ENVOY_CONFIG" /etc/envoy.yaml
+
 
 FROM envoy-base as envoy-admin
 ARG ENVOY_ADMIN_PORT=10001