compressor: expose generic compressor filter to users

CODEOWNERS

@@ -20,6 +20,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/filters/network/thrift_proxy @zuercher @brian-pane
 # compressor used by http compression filters
 /*/extensions/filters/http/common/compressor @gsagula @rojkov @dio
+/*/extensions/filters/http/compressor @rojkov @dio
+/*/extensions/filters/http/compressor/gzip @gsagula @rojkov @dio
 # jwt_authn http filter extension
 /*/extensions/filters/http/jwt_authn @qiwzhang @lizan
 # grpc_http1_reverse_bridge http filter extension

api/BUILD

@@ -32,6 +32,7 @@ proto_library(
         "//envoy/config/filter/http/aws_request_signing/v2alpha:pkg",
         "//envoy/config/filter/http/buffer/v2:pkg",
         "//envoy/config/filter/http/cache/v2alpha:pkg",
+        "//envoy/config/filter/http/compressor/gzip/v2:pkg",
         "//envoy/config/filter/http/compressor/v2:pkg",
         "//envoy/config/filter/http/cors/v2:pkg",
         "//envoy/config/filter/http/csrf/v2:pkg",
@@ -165,6 +166,7 @@ proto_library(
         "//envoy/extensions/filters/http/aws_request_signing/v3:pkg",
         "//envoy/extensions/filters/http/buffer/v3:pkg",
         "//envoy/extensions/filters/http/cache/v3alpha:pkg",
+        "//envoy/extensions/filters/http/compressor/gzip/v3:pkg",
         "//envoy/extensions/filters/http/compressor/v3:pkg",
         "//envoy/extensions/filters/http/cors/v3:pkg",
         "//envoy/extensions/filters/http/csrf/v3:pkg",

api/envoy/config/filter/http/compressor/gzip/v2/BUILD

@@ -0,0 +1,9 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = ["@com_github_cncf_udpa//udpa/annotations:pkg"],
+)

api/envoy/config/filter/http/compressor/gzip/v2/gzip.proto

@@ -0,0 +1,62 @@
+syntax = "proto3";
+
+package envoy.config.filter.http.compressor.gzip.v2;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.filter.http.compressor.gzip.v2";
+option java_outer_classname = "GzipProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_migrate).move_to_package =
+    "envoy.extensions.filters.http.compressor.gzip.v3";
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Gzip]
+// [#extension: envoy.filters.http.compressor.gzip]
+
+// [#next-free-field: 10]
+message Gzip {
+  enum CompressionStrategy {
+    DEFAULT = 0;
+    FILTERED = 1;
+    HUFFMAN = 2;
+    RLE = 3;
+  }
+
+  message CompressionLevel {
+    enum Enum {
+      DEFAULT = 0;
+      BEST = 1;
+      SPEED = 2;
+    }
+  }
+
+  // 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. The default value is 5.
+  google.protobuf.UInt32Value memory_level = 1 [(validate.rules).uint32 = {lte: 9 gte: 1}];
+
+  // A value used for selecting the zlib 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}];
+
+  // A value used for selecting the zlib 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}];
+
+  // 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 = {lte: 15 gte: 9}];
+}

api/envoy/config/filter/http/compressor/v2/compressor.proto

@@ -4,10 +4,13 @@ package envoy.config.filter.http.compressor.v2;
 
 import "envoy/api/v2/core/base.proto";
 
+import "google/protobuf/any.proto";
+import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
+import "validate/validate.proto";
 
 option java_package = "io.envoyproxy.envoy.config.filter.http.compressor.v2";
 option java_outer_classname = "CompressorProto";
@@ -17,8 +20,10 @@ option (udpa.annotations.file_migrate).move_to_package =
 option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Compressor]
+// Compressor :ref:`configuration overview <config_http_filters_compressor>`.
+// [#extension: envoy.filters.http.compressor]
 
-// [#next-free-field: 6]
+// [#next-free-field: 7]
 message Compressor {
   // Minimum response length, in bytes, which will trigger compression. The default value is 30.
   google.protobuf.UInt32Value content_length = 1;
@@ -45,4 +50,25 @@ message Compressor {
   // Runtime flag that controls whether the filter is enabled or not. If set to false, the
   // filter will operate as a pass-through filter. If not specified, defaults to enabled.
   api.v2.core.RuntimeFeatureFlag runtime_enabled = 5;
+
+  // A compressor library to use for compression. By default
+  // :ref:`envoy.filters.http.compressor.gzip<envoy_api_msg_config.filter.http.compressor.gzip.v2.Gzip>`
+  // is used.
+  //
+  // This field is ignored when used in the context of the deprecated "envoy.filters.http.gzip"
+  // filter.
+  CompressorLibrary compressor_library = 6;
+}
+
+message CompressorLibrary {
+  // The name of the compressor library to instantiate for the filter.
+  string name = 1 [(validate.rules).string = {min_bytes: 1}];
+
+  // Compressor library specific configuration. See the supported libraries for further
+  // documentation.
+  oneof config_type {
+    google.protobuf.Struct config = 2 [deprecated = true];
+
+    google.protobuf.Any typed_config = 3;
+  }
 }

api/envoy/extensions/filters/http/compressor/gzip/v3/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/filter/http/compressor/gzip/v2:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

api/envoy/extensions/filters/http/compressor/gzip/v3/gzip.proto

@@ -0,0 +1,66 @@
+syntax = "proto3";
+
+package envoy.extensions.filters.http.compressor.gzip.v3;
+
+import "google/protobuf/wrappers.proto";
+
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.extensions.filters.http.compressor.gzip.v3";
+option java_outer_classname = "GzipProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
+
+// [#protodoc-title: Gzip]
+// [#extension: envoy.filters.http.compressor.gzip]
+
+// [#next-free-field: 10]
+message Gzip {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.http.compressor.gzip.v2.Gzip";
+
+  enum CompressionStrategy {
+    DEFAULT = 0;
+    FILTERED = 1;
+    HUFFMAN = 2;
+    RLE = 3;
+  }
+
+  message CompressionLevel {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.config.filter.http.compressor.gzip.v2.Gzip.CompressionLevel";
+
+    enum Enum {
+      DEFAULT = 0;
+      BEST = 1;
+      SPEED = 2;
+    }
+  }
+
+  // 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. The default value is 5.
+  google.protobuf.UInt32Value memory_level = 1 [(validate.rules).uint32 = {lte: 9 gte: 1}];
+
+  // A value used for selecting the zlib 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}];
+
+  // A value used for selecting the zlib 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}];
+
+  // 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 = {lte: 15 gte: 9}];
+}

api/envoy/extensions/filters/http/compressor/v3/compressor.proto

@@ -4,19 +4,24 @@ package envoy.extensions.filters.http.compressor.v3;
 
 import "envoy/config/core/v3/base.proto";
 
+import "google/protobuf/any.proto";
+import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
 
 option java_package = "io.envoyproxy.envoy.extensions.filters.http.compressor.v3";
 option java_outer_classname = "CompressorProto";
 option java_multiple_files = true;
 option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE;
 
 // [#protodoc-title: Compressor]
+// Compressor :ref:`configuration overview <config_http_filters_compressor>`.
+// [#extension: envoy.filters.http.compressor]
 
-// [#next-free-field: 6]
+// [#next-free-field: 7]
 message Compressor {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.http.compressor.v2.Compressor";
@@ -46,4 +51,30 @@ message Compressor {
   // Runtime flag that controls whether the filter is enabled or not. If set to false, the
   // filter will operate as a pass-through filter. If not specified, defaults to enabled.
   config.core.v3.RuntimeFeatureFlag runtime_enabled = 5;
+
+  // A compressor library to use for compression. By default
+  // :ref:`envoy.filters.http.compressor.gzip<envoy_api_msg_extensions.filters.http.compressor.gzip.v3.Gzip>`
+  // is used.
+  //
+  // This field is ignored when used in the context of the deprecated "envoy.filters.http.gzip"
+  // filter.
+  CompressorLibrary compressor_library = 6;
+}
+
+message CompressorLibrary {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.filter.http.compressor.v2.CompressorLibrary";
+
+  reserved 2;
+
+  reserved "config";
+
+  // The name of the compressor library to instantiate for the filter.
+  string name = 1 [(validate.rules).string = {min_bytes: 1}];
+
+  // Compressor library specific configuration. See the supported libraries for further
+  // documentation.
+  oneof config_type {
+    google.protobuf.Any typed_config = 3;
+  }
 }

api/versioning/BUILD

@@ -33,6 +33,7 @@ proto_library(
         "//envoy/config/filter/http/aws_request_signing/v2alpha:pkg",
         "//envoy/config/filter/http/buffer/v2:pkg",
         "//envoy/config/filter/http/cache/v2alpha:pkg",
+        "//envoy/config/filter/http/compressor/gzip/v2:pkg",
         "//envoy/config/filter/http/compressor/v2:pkg",
         "//envoy/config/filter/http/cors/v2:pkg",
         "//envoy/config/filter/http/csrf/v2:pkg",

docs/root/api-v2/config/filter/http/http.rst

@@ -9,3 +9,4 @@ HTTP filters
   */v2/*
   */v2alpha/*
   */v2alpha1/*
+  compressor/*/v2/*

docs/root/api-v3/config/filter/http/http.rst

@@ -7,3 +7,4 @@ HTTP filters
 
   */empty/*
   ../../../extensions/filters/http/*/v3/*
+  ../../../extensions/filters/http/compressor/*/v3/*

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

@@ -0,0 +1,80 @@
+.. _config_http_filters_compressor:
+
+Compressor
+==========
+Compressor 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_config.filter.http.compressor.v2.Compressor>`
+* This filter should be configured with the name *envoy.filters.http.compressor*.
+
+How it works
+------------
+When compressor 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
+response and request allow.
+
+Currently the filter supports :ref:`gzip compression<envoy_api_msg_config.filter.http.compressor.gzip.v2.Gzip>`
+only. Other compression libraries can be supported as extensions.
+
+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" 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 "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 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
+the extension.
+
+When compression is *applied*:
+
+- The *content-length* is removed from response headers.
+- Response headers contain "*transfer-encoding: chunked*" and do not contain
+  "*content-encoding*" header.
+- The "*vary: accept-encoding*" header is inserted on every response.
+
+.. _compressor-statistics:
+
+Statistics
+----------
+
+Every configured Compressor filter has statistics rooted at <stat_prefix>.<compression_library_stat_prefix>.* with the following:
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: 1, 1, 2
+
+  compressed, Counter, Number of requests compressed.
+  not_compressed, Counter, Number of requests not compressed.
+  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 "gzip" 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).
+  total_uncompressed_bytes, Counter, The total uncompressed bytes of all the requests that were marked for compression.
+  total_compressed_bytes, Counter, The total compressed bytes of all the requests that were marked for compression.
+  content_length_too_small, Counter, Number of requests that accepted gzip encoding but did not compress because the payload was too small.
+  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.

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

@@ -10,6 +10,7 @@ HTTP filters
   aws_lambda_filter
   aws_request_signing_filter
   buffer_filter
+  compressor_filter
   cors_filter
   csrf_filter
   dynamic_forward_proxy_filter