filter: pb definition for squash filter (#353)

Signed-off-by: Yuval Kohavi <yuval.kohavi@gmail.com>

api/BUILD

@@ -171,6 +171,7 @@ proto_library(
         "//api/filter/http:lua",
         "//api/filter/http:rate_limit",
         "//api/filter/http:router",
+        "//api/filter/http:squash",
         "//api/filter/http:transcoder",
         "//api/filter/network:client_ssl_auth",
         "//api/filter/network:http_connection_manager",

api/filter/http/BUILD

@@ -52,3 +52,8 @@ api_proto_library(
     name = "gzip",
     srcs = ["gzip.proto"],
 )
+
+api_proto_library(
+    name = "squash",
+    srcs = ["squash.proto"],
+)

api/filter/http/squash.proto

@@ -0,0 +1,48 @@
+syntax = "proto3";
+
+package envoy.api.v2.filter.http;
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/struct.proto";
+import "validate/validate.proto";
+
+// [#protodoc-title: Squash]
+// Squash :ref:`configuration overview <config_http_filters_squash>`.
+
+// [#proto-status: experimental]
+message Squash {
+  // The name of the cluster that hosts the Squash server.
+  string cluster = 1 [(validate.rules).string.min_bytes = 1];
+
+  // When the filter requests the Squash server to create a DebugAttachment, it will use this
+  // structure as template for the body of the request. It can contain reference to environment
+  // variables in the form of '{{ ENV_VAR_NAME }}'. These can be used to provide the Squash server
+  // with more information to find the process to attach the debugger to. For example, in a
+  // Istio/k8s environment, this will contain information on the pod:
+  //
+  // .. code-block:: json
+  //
+  //  {
+  //    "spec": {
+  //      "attachment": {
+  //        "pod": "{{ POD_NAME }}",
+  //        "namespace": "{{ POD_NAMESPACE }}"
+  //      },
+  //      "match_request": true
+  //    }
+  //  }
+  //
+  // (where POD_NAME, POD_NAMESPACE are configured in the pod via the Downward API)
+  google.protobuf.Struct attachment_template = 2;
+
+  // The timeout for individual requests sent to the Squash cluster. Defaults to 1 second.
+  google.protobuf.Duration request_timeout = 3;
+
+  // The total timeout Squash will delay a request and wait for it to be attached. Defaults to 60
+  // seconds.
+  google.protobuf.Duration attachment_timeout = 4;
+
+  // Amount of time to poll for the status of the attachment object in the Squash server
+  // (to check if has been attached). Defaults to 1 second.
+  google.protobuf.Duration attachment_poll_period = 5;
+}

api/filter/network/http_connection_manager.proto

@@ -208,6 +208,7 @@ message HttpFilter {
   // * :ref:`envoy.lua <config_http_filters_lua>`
   // * :ref:`envoy.rate_limit <config_http_filters_rate_limit>`
   // * :ref:`envoy.router <config_http_filters_router>`
+  // * :ref:`envoy.squash <config_http_filters_squash>`
   string name = 1 [(validate.rules).string.min_bytes = 1];
 
   // Filter specific configuration which depends on the filter being

docs/build.sh

@@ -47,6 +47,7 @@ PROTO_RST="
   /api/filter/http/lua/api/filter/http/lua.proto.rst
   /api/filter/http/rate_limit/api/filter/http/rate_limit.proto.rst
   /api/filter/http/router/api/filter/http/router.proto.rst
+  /api/filter/http/squash/api/filter/http/squash.proto.rst
   /api/filter/http/transcoder/api/filter/http/transcoder.proto.rst
   /api/filter/network/client_ssl_auth/api/filter/network/client_ssl_auth.proto.rst
   /api/filter/network/http_connection_manager/api/filter/network/http_connection_manager.proto.rst

docs/root/api-v1/http_filters/squash_filter.rst

@@ -0,0 +1,56 @@
+.. _config_http_filters_squash_v1:
+
+Squash
+======
+
+Squash :ref:`configuration overview <config_http_filters_squash>`.
+
+.. code-block:: json
+
+  {
+    "name": "squash",
+    "config": {
+      "cluster": "...",
+      "attachment_template": "{...}",
+      "attachment_timeout_ms": "...",
+      "attachment_poll_period_ms": "...",
+      "request_timeout_ms": "..."
+    }
+  }
+
+cluster
+  *(required, object)* The name of the cluster that hosts the Squash server.
+
+attachment_template
+  *(required, object)* When the filter requests the Squash server to create a DebugAttachment, it
+  will use this structure as template for the body of the request. It can contain reference to 
+  environment variables in the form of '{{ ENV_VAR_NAME }}'. These can be used to provide the Squash
+  server with more information to find the process to attach the debugger to. For example, in a
+  Istio/k8s environment, this will contain information on the pod:
+
+  .. code-block:: json
+  
+   {
+     "spec": {
+       "attachment": {
+         "pod": "{{ POD_NAME }}",
+         "namespace": "{{ POD_NAMESPACE }}"
+       },
+       "match_request": true
+     }
+   }
+  
+  (where POD_NAME, POD_NAMESPACE are configured in the pod via the Downward API)
+
+request_timeout_ms
+  *(required, integer)* The timeout for individual requests sent to the Squash cluster. Defaults to 
+  1 second.
+
+attachment_timeout_ms
+  *(required, integer)* The total timeout Squash will delay a request and wait for it to be 
+  attached. Defaults to 60 seconds.
+
+attachment_poll_period_ms
+  *(required, integer)* Amount of time to poll for the status of the attachment object in the Squash 
+  server (to check if has been attached). Defaults to 1 second.
+

docs/root/configuration/http_filters/http_filters.rst

@@ -17,3 +17,4 @@ HTTP filters
   rate_limit_filter
   router_filter
   lua_filter
+  squash_filter

docs/root/configuration/http_filters/squash_filter.rst

@@ -0,0 +1,40 @@
+.. _config_http_filters_squash:
+
+Squash
+======
+
+Squash is an HTTP filter which enables Envoy to integrate with Squash microservices debugger.
+Code: https://github.com/solo-io/squash, API Docs:  https://squash.solo.io/
+
+Overview
+--------
+
+The main use case for this filter is in a service mesh, where Envoy is deployed as a sidecar.
+Once a request marked for debugging enters the mesh, the Squash Envoy filter reports its 'location'
+in the cluster to the Squash server - as there is a 1-1 mapping between Envoy sidecars and
+application containers, the Squash server can find and attach a debugger to the application container.
+The Squash filter also holds the request until a debugger is attached (or a timeout occurs). This
+enables developers (via Squash) to attach a native debugger to the container that will handle the 
+request, before the request arrive to the application code, without any changes to the cluster.
+
+Configuration
+-------------
+
+* :ref:`v1 API reference <config_http_filters_squash_v1>`
+* :ref:`v2 API reference <envoy_api_msg_filter.http.Squash>`
+
+How it works
+------------
+
+When the Squash filter encounters a request containing the header 'x-squash-debug' it will:
+
+1. Delay the incoming request.
+2. Contact the Squash server and request the creation of a DebugAttachment
+
+   - On the Squash server side, Squash will attempt to attach a debugger to the application Envoy
+     proxies to. On success, it changes the state of the DebugAttachment
+     to attached.
+
+3. Wait until the Squash server updates the DebugAttachment object's state to attached (or
+   error state)
+4. Resume the incoming request

test/validate/BUILD

@@ -18,6 +18,7 @@ api_cc_test(
         "//api/filter/http:health_check",
         "//api/filter/http:lua",
         "//api/filter/http:router",
+        "//api/filter/http:squash",
         "//api/filter/http:transcoder",
         "//api/filter/network:http_connection_manager",
         "//api/filter/network:mongo_proxy",

test/validate/pgv_test.cc

@@ -16,6 +16,7 @@
 #include "api/filter/http/health_check.pb.validate.h"
 #include "api/filter/http/lua.pb.validate.h"
 #include "api/filter/http/router.pb.validate.h"
+#include "api/filter/http/squash.pb.validate.h"
 #include "api/filter/http/transcoder.pb.validate.h"
 #include "api/filter/network/http_connection_manager.pb.validate.h"
 #include "api/filter/network/mongo_proxy.pb.validate.h"