From 5aa0208c3bf0ba35833dc4ac16c73839b032e70a Mon Sep 17 00:00:00 2001 From: Gabriel Sagula Date: Thu, 25 Jan 2018 05:04:57 -0800 Subject: [PATCH] filter: final documentation for gzip http filter (#391) In this PR: Proto definition and documentation Documentation around the filter Signed-off-by: Gabriel --- api/BUILD | 1 + api/filter/http/gzip.proto | 83 ++++++++----------- .../network/http_connection_manager.proto | 1 + docs/build.sh | 1 + .../http_filters/gzip_filter.rst | 51 ++++++++++++ .../http_filters/http_filters.rst | 1 + test/validate/BUILD | 1 + test/validate/pgv_test.cc | 1 + 8 files changed, 91 insertions(+), 49 deletions(-) create mode 100644 docs/root/configuration/http_filters/gzip_filter.rst diff --git a/api/BUILD b/api/BUILD index 05148700..5f61aa11 100644 --- a/api/BUILD +++ b/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", diff --git a/api/filter/http/gzip.proto b/api/filter/http/gzip.proto index c1f0713f..8d5a387e 100644 --- a/api/filter/http/gzip.proto +++ b/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 `. + 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}]; } diff --git a/api/filter/network/http_connection_manager.proto b/api/filter/network/http_connection_manager.proto index dddcec81..8f89bc75 100644 --- a/api/filter/network/http_connection_manager.proto +++ b/api/filter/network/http_connection_manager.proto @@ -205,6 +205,7 @@ message HttpFilter { // * :ref:`envoy.buffer ` // * :ref:`envoy.cors ` // * :ref:`envoy.fault ` + // * :ref:`envoy.gzip ` // * :ref:`envoy.http_dynamo_filter ` // * :ref:`envoy.grpc_http1_bridge ` // * :ref:`envoy.grpc_json_transcoder ` diff --git a/docs/build.sh b/docs/build.sh index 63435c4d..ba9b97bc 100755 --- a/docs/build.sh +++ b/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 diff --git a/docs/root/configuration/http_filters/gzip_filter.rst b/docs/root/configuration/http_filters/gzip_filter.rst new file mode 100644 index 00000000..aaa0dd93 --- /dev/null +++ b/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 ` + +.. 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. diff --git a/docs/root/configuration/http_filters/http_filters.rst b/docs/root/configuration/http_filters/http_filters.rst index ee5c6019..360dd064 100644 --- a/docs/root/configuration/http_filters/http_filters.rst +++ b/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 diff --git a/test/validate/BUILD b/test/validate/BUILD index 6ae1a807..501decf6 100644 --- a/test/validate/BUILD +++ b/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", diff --git a/test/validate/pgv_test.cc b/test/validate/pgv_test.cc index b6060abc..1e7cc1c1 100644 --- a/test/validate/pgv_test.cc +++ b/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"