filter: final documentation for gzip http filter (#391)

In this PR:

Proto definition and documentation
Documentation around the filter

Signed-off-by: Gabriel <gsagula@gmail.com>

api/BUILD

@@ -353,6 +353,7 @@ proto_library(
         "//api/filter/http:buffer",
         "//api/filter/http:ext_authz",
         "//api/filter/http:fault",
+        "//api/filter/http:gzip",
         "//api/filter/http:health_check",
         "//api/filter/http:lua",
         "//api/filter/http:rate_limit",

api/filter/http/gzip.proto

@@ -1,27 +1,20 @@
 syntax = "proto3";
 
-// [#proto-status: experimental]
-
 package envoy.api.v2.filter.http;
 
 import "google/protobuf/wrappers.proto";
 
 import "validate/validate.proto";
 
-// Gzip is an HTTP filter which enables Envoy to compress dispatched data from an upstream
-// service upon client request. This is useful in situations where large payloads need to
-// be transmitted without compromising the response time. Note that when compression is applied,
-// this filter will set "content-encoding" and "transfer-encoding" headers to gzip and chunked,
-// respectively.
-// TODO(gsagula): elaborate the last part in the final documentation.
+// [#protodoc-title: Gzip]
+// Gzip :ref:`configuration overview <config_http_filters_gzip>`.
+
 message Gzip {
-  // Value from 1 to 9 that controls the amount of internal memory
-  // used by zlib. Higher values use more memory, but are faster and produce better compression
-  // results. Default value is 8.
+  // Value from 1 to 9 that controls the amount of internal memory used by zlib. Higher values
+  // use more memory, but are faster and produce better compression results. Default value is 5.
   google.protobuf.UInt32Value memory_level = 1 [(validate.rules).uint32 = {gte: 1, lte: 9}];
 
-  // Minimum response length, in bytes, which will trigger
-  // compression. Default value is 30.
+  // Minimum response length, in bytes, which will trigger compression. Default value is 30.
   google.protobuf.UInt32Value content_length = 2 [(validate.rules).uint32.gte = 30];
 
   message CompressionLevel {
@@ -32,11 +25,11 @@ message Gzip {
     }
   }
 
-  // Allows selecting Zlib's compression level. This setting will affect
-  // speed and amount of compression applied to the content. "BEST" option provides higher
-  // compression at cost of higher latency, "SPEED" provides lower compression with minimum impact
-  // on response time. "DEFAULT" provides an optimal result between speed and compression. This
-  // field will be set to "DEFAULT" if not specified.
+  // A value used for selecting zlib's compression level. This setting will affect speed and amount
+  // of compression applied to the content. "BEST" provides higher compression at the cost of higher
+  // latency, "SPEED" provides lower compression with minimum impact on response time. "DEFAULT"
+  // provides an optimal result between speed and compression. This field will be set to "DEFAULT"
+  // if not specified.
   CompressionLevel.Enum compression_level = 3 [(validate.rules).enum.defined_only = true];
 
   enum CompressionStrategy {
@@ -46,41 +39,33 @@ message Gzip {
     RLE = 3;
   }
 
-  // Allows selecting zlib's compression strategy. Strategy is directly
-  // related to the characteristics of the content which is being compressed. Most of the time
-  // "DEFAULT" will be the best choice, however there are situations which changing the strategy
-  // might produce better results. For example, Run-length encoding (RLE) is normally used when the
-  // content is known for having sequences which same data occurs many consecutive times. For more
-  // information about each strategy, please refer to Zlib manual. This field will be set to
-  // "DEFAULT" if not specified.
+  // A value used for selecting zlib's compression strategy which is directly related to the
+  // characteristics of the content. Most of the time "DEFAULT" will be the best choice, though
+  // there are situations which changing this parameter might produce better results. For example,
+  // run-length encoding (RLE) is typically used when the content is known for having sequences
+  // which same data occurs many consecutive times. For more information about each strategy, please
+  // refer to zlib manual.
   CompressionStrategy compression_strategy = 4 [(validate.rules).enum.defined_only = true];
 
-  // Array of strings that allows specifying which "cache-control" header
-  // values yield compression. Normally, if "cache-control" is present in the response headers,
-  // compression should only occur if directives indicate that the content should not be cached;
-  // e.g. no-cache or no-store.
-  repeated string cache_control = 5
-      [(validate.rules).repeated = {min_items: 0, max_items: 10, unique: true}];
-
-  // Array of strings that allows specifying which mime-types yield compression; e.g.
-  // application/json, text/html, etc. When this field is not specified, compression will be applied
-  // to any "content-type".
-  repeated string content_type = 6 [(validate.rules).repeated = {min_items: 0, max_items: 30}];
+  // Set of strings that allows specifying which mime-types yield compression; e.g.,
+  // application/json, text/html, etc. When this field is not defined, compression will be applied
+  // to the following mime-types: "application/javascript", "application/json",
+  // "application/xhtml+xml", "image/svg+xml", "text/css", "text/html", "text/plain", "text/xml".
+  repeated string content_type = 6 [(validate.rules).repeated = {max_items: 50}];
 
-  // Allows disabling compression if response contains "etag" (entity tag)
-  // header. Default is false.
-  google.protobuf.BoolValue disable_on_etag = 7;
+  // If true, disables compression when the response contains Etag header. When it is false, the
+  // filter will preserve weak Etags and remove the ones that require strong validation. Note that
+  // if any of these options fit the specific scenario, an alternative solution is to disabled Etag
+  // at the origin and use *last-modified* header instead.
+  bool disable_on_etag_header = 7;
 
-  // Allows disabling compression if response contains "last-modified"
-  // header. Default is false.
-  google.protobuf.BoolValue disable_on_last_modified = 8;
+  // If true, disables compression when response contains *last-modified*
+  // header.
+  bool disable_on_last_modified_header = 8;
 
-  // Value from 9 to 15 that represents the base two logarithm of the compressor's window size.
-  // Larger values result in better compression at the expense of memory usage; e.g. 12 will produce
-  // a 4096 bytes window. Default is 15. For more details about this parameter, please refer to Zlib
-  // manual > deflateInit2.
-  // Note that due to a known bug in the underlying zlib library, window bits
-  // with value 8 does not work as expected, therefore 9 is the smallest window size supported by
-  // this filter at the moment. This issue might be solved in future releases of the library.
+  // Value from 9 to 15 that represents the base two logarithmic of the compressor's window size.
+  // Larger window results in better compression at the expense of memory usage. The default is 12
+  // which will produce a 4096 bytes window. For more details about this parameter, please refer to
+  // zlib manual > deflateInit2.
   google.protobuf.UInt32Value window_bits = 9 [(validate.rules).uint32 = {gte: 9, lte: 15}];
 }

api/filter/network/http_connection_manager.proto

@@ -205,6 +205,7 @@ message HttpFilter {
   // * :ref:`envoy.buffer <config_http_filters_buffer>`
   // * :ref:`envoy.cors <config_http_filters_cors>`
   // * :ref:`envoy.fault <config_http_filters_fault_injection>`
+  // * :ref:`envoy.gzip <config_http_filters_gzip>`
   // * :ref:`envoy.http_dynamo_filter <config_http_filters_dynamo>`
   // * :ref:`envoy.grpc_http1_bridge <config_http_filters_grpc_bridge>`
   // * :ref:`envoy.grpc_json_transcoder <config_http_filters_grpc_json_transcoder>`

docs/build.sh

@@ -46,6 +46,7 @@ PROTO_RST="
   /api/filter/fault/api/filter/fault.proto.rst
   /api/filter/http/buffer/api/filter/http/buffer.proto.rst
   /api/filter/http/fault/api/filter/http/fault.proto.rst
+  /api/filter/http/gzip/api/filter/http/gzip.proto.rst
   /api/filter/http/health_check/api/filter/http/health_check.proto.rst
   /api/filter/http/lua/api/filter/http/lua.proto.rst
   /api/filter/http/rate_limit/api/filter/http/rate_limit.proto.rst

docs/root/configuration/http_filters/gzip_filter.rst

@@ -0,0 +1,51 @@
+.. _config_http_filters_gzip:
+
+Gzip
+====
+Gzip is an HTTP filter which enables Envoy to compress dispatched data
+from an upstream service upon client request. Compression is useful in
+situations where large payloads need to be transmitted without
+compromising the response time.
+
+Configuration
+-------------
+* :ref:`v2 API reference <envoy_api_msg_filter.http.Gzip>`
+
+.. attention::
+
+  The *window bits* is a number that tells the compressor how far ahead in the
+  text the algorithm should be looking for repeated sequence of characters.
+  Due to a known bug in the underlying zlib library, *window bits* with value
+  eight does not work as expected. Therefore any number below that will be
+  automatically set to 9. This issue might be solved in future releases of
+  the library.
+
+How it works
+------------
+When gzip filter is enabled, request and response headers are inspected to
+determine whether or not the content should be compressed. The content is
+compressed and then sent to the client with the appropriate headers if either
+response and request allow.
+
+By *default* compression will be *skipped* when:
+
+- A request does NOT contain *accept-encoding* header.
+- A request includes *accept-encoding* header, but it does not contain "gzip".
+- 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 "gzip".
+- 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*
+  is not chuncked).
+
+When compression is *applied*:
+
+- The *content-length* is removed from response headers.
+- Response headers contain "*transfer-encoding: chunked*" and
+  "*content-encoding: gzip*".
+- The "*vary: accept-encoding*" header is inserted on every response.

docs/root/configuration/http_filters/http_filters.rst

@@ -9,6 +9,7 @@ HTTP filters
   buffer_filter
   cors_filter
   fault_filter
+  gzip_filter
   dynamodb_filter
   grpc_http1_bridge_filter
   grpc_json_transcoder_filter

test/validate/BUILD

@@ -15,6 +15,7 @@ api_cc_test(
         "//api/filter/accesslog",
         "//api/filter/http:buffer",
         "//api/filter/http:fault",
+        "//api/filter/http:gzip",
         "//api/filter/http:health_check",
         "//api/filter/http:lua",
         "//api/filter/http:router",

test/validate/pgv_test.cc

@@ -15,6 +15,7 @@
 #include "api/filter/http/fault.pb.validate.h"
 #include "api/filter/http/health_check.pb.validate.h"
 #include "api/filter/http/lua.pb.validate.h"
+#include "api/filter/http/gzip.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"