Skip to content

L
libvfp-brotli
Commit c37a1594 authored by Geoff Simmons's avatar Geoff Simmons
Browse files
Options

Doc fixes and polish.

parent 5682ccfc
Hide whitespace changes
Inline Side-by-side
Showing with 40 additions and 42 deletions
README.rst
View file @ c37a1594
......@@ -61,9 +61,9 @@ SYNOPSIS
DESCRIPTION
===========
Varnish Fetch Processor (VFP) to support the brotli compresion
algorithm for responses fetched from backends. This VFP integrates
Varnish with the `Google brotli library`_.
VFP brotli is a Varnish Fetch Processor to support the brotli
compression algorithm for responses fetched from backends. The VFP
integrates Varnish with the `Google brotli library`_.
The Brotli Compressed Data Format is specified in `RFC 7932`_. Details
of the compression algorithm are beyond the scope of this manual; see
......@@ -71,15 +71,15 @@ the RFC and library documentation for more information.
A VFP is technically similar to a Varnish Module (VMOD). In
particular, it must be installed against Varnish in the same way a
VMOD is installed, and like a VMOD, a VCL source must instruct Varnish
to load the VFP using the ``import`` statement. But unlike a VMOD, a
VFP's primary purpose is not to extend the VCL language; instead, a
VFP creates filters for backend fetches that can be named as strings
in the space-separated list assigned to the VCL variable
VMOD is installed; and as with a VMOD, a VCL source must instruct
Varnish to load the VFP using the ``import`` statement. But unlike a
VMOD, a VFP's primary purpose is not to extend the VCL language;
instead, a VFP creates filters for backend fetches that can be named
as strings in the space-separated list assigned to the VCL variable
``beresp.filters`` (see ``vcl(7)``).
VFP brotli always creates two filters named ``"br"`` and ``"unbr"``,
for compression and decompression, respectively, with default
for compression and decompression respectively, with default
parameters for the compression algorithm::
import brotli;
......@@ -114,11 +114,10 @@ the incoming backend response body. The resulting response body is
passed to the client, and if the response is cached, then the body is
stored in the cache as it results from the filtering.
To use non-default values for the compression algorithm, create an
To use non-default settings for the compression algorithm, create an
``encoder`` or ``decoder`` object as specified below. The string
passed in the ``name`` parameter of the object constructor can be used
in a ``beresp.filters`` list, as with ``"br"`` and
``"unbr"``::
in a ``beresp.filters`` list, as with ``"br"`` and ``"unbr"``::
import brotli;
......@@ -181,12 +180,12 @@ support:
response header is removed.
* Any ``Content-Length`` response header fetched from the backend is
removed -- Varnish may set a new ``Content-Length`` header in a
removed -- Varnish may add a new ``Content-Length`` header in a
client response, set to the changed size of the response body. When
streaming is enabled, Varnish sends the client response for a fetch
with chunked encoding (and hence with no ``Content-Length`` header).
* If the backend response has an ``ETag`` header, then the ``Etag``
* If the backend response has an ``ETag`` header, then the ``ETag``
value is "weakened" (prefixed with ``W/``), for weak validation
according to `RFC 7232`_ section 2.1. This is because the response
after de-/compression is not byte-identical with the fetched
......@@ -240,7 +239,7 @@ The parameters are:
* ``quality`` (default 11): sets a compression level, where 0
represents the fastest execution, and 11 represents the highest
compression rate (smallest compressed result). ``quality`` MUST be
>= 0 and <= 11.
in the range 0 to 11, inclusive.
* ``large_win`` (default ``false``): if ``true``, use Large Window
Brotli, which may yield better results for response bodies larger
......@@ -248,10 +247,10 @@ The parameters are:
algorithm; under certain circumstances, it may be necessary to use
the Large Window setting for both compression and decompression.
* ``lgwin`` (default 22): set the window size for the LZ77 algorithm.
The window size is (2 ^ ``lgwin`` - 16), and larger window sizes may
result in better compression rates. ``lgwin`` MUST be >= 10 and <=
24.
* ``lgwin`` (default 22): set the size of the LZ77 sliding window used
by the brotli algorithm. The window size is (2 ^ ``lgwin`` - 16),
and larger window sizes may result in better compression rates.
``lgwin`` MUST be in the range 10 to 24, inclusive.
* ``mode`` (default ``GENERIC``): provide a hint about the expected
contents of the response body; the compression may benefit from
......@@ -275,7 +274,7 @@ Example::
sub vcl_init {
# Create a compression filter with a 1MiB buffer, optimized
# for WOFF.
new br_woff = brotli.encoder("br_woff", buffer=1m, mode=WOFF);
new br_woff = brotli.encoder("br_woff", buffer=1m, mode=FONT);
}
sub vcl_backend_response {
......@@ -330,7 +329,7 @@ As with the ``encoder`` object, the default values for the parameters
correspond to the defaults used in the standard ``"unbr"``
decompression filter.
Also as with ``"encoder``, the ``name`` MAY NOT be ``"br"`` or
Also as with ``encoder``, the ``name`` MAY NOT be ``"br"`` or
``"unbr"``, or the same as any of Varnish's standard filters. It
SHOULD NOT be the same as a name used by another third-party VFP.
......
src/vfp_brotli.vcc
View file @ c37a1594
......@@ -63,9 +63,9 @@ SYNOPSIS
DESCRIPTION
===========
Varnish Fetch Processor (VFP) to support the brotli compresion
algorithm for responses fetched from backends. This VFP integrates
Varnish with the `Google brotli library`_.
VFP brotli is a Varnish Fetch Processor to support the brotli
compression algorithm for responses fetched from backends. The VFP
integrates Varnish with the `Google brotli library`_.
The Brotli Compressed Data Format is specified in `RFC 7932`_. Details
of the compression algorithm are beyond the scope of this manual; see
......@@ -73,15 +73,15 @@ the RFC and library documentation for more information.
A VFP is technically similar to a Varnish Module (VMOD). In
particular, it must be installed against Varnish in the same way a
VMOD is installed, and like a VMOD, a VCL source must instruct Varnish
to load the VFP using the ``import`` statement. But unlike a VMOD, a
VFP's primary purpose is not to extend the VCL language; instead, a
VFP creates filters for backend fetches that can be named as strings
in the space-separated list assigned to the VCL variable
VMOD is installed; and as with a VMOD, a VCL source must instruct
Varnish to load the VFP using the ``import`` statement. But unlike a
VMOD, a VFP's primary purpose is not to extend the VCL language;
instead, a VFP creates filters for backend fetches that can be named
as strings in the space-separated list assigned to the VCL variable
``beresp.filters`` (see ``vcl(7)``).
VFP brotli always creates two filters named ``"br"`` and ``"unbr"``,
for compression and decompression, respectively, with default
for compression and decompression respectively, with default
parameters for the compression algorithm::
import brotli;
......@@ -116,11 +116,10 @@ the incoming backend response body. The resulting response body is
passed to the client, and if the response is cached, then the body is
stored in the cache as it results from the filtering.
To use non-default values for the compression algorithm, create an
To use non-default settings for the compression algorithm, create an
``encoder`` or ``decoder`` object as specified below. The string
passed in the ``name`` parameter of the object constructor can be used
in a ``beresp.filters`` list, as with ``"br"`` and
``"unbr"``::
in a ``beresp.filters`` list, as with ``"br"`` and ``"unbr"``::
import brotli;
......@@ -183,12 +182,12 @@ support:
response header is removed.
* Any ``Content-Length`` response header fetched from the backend is
removed -- Varnish may set a new ``Content-Length`` header in a
removed -- Varnish may add a new ``Content-Length`` header in a
client response, set to the changed size of the response body. When
streaming is enabled, Varnish sends the client response for a fetch
with chunked encoding (and hence with no ``Content-Length`` header).
* If the backend response has an ``ETag`` header, then the ``Etag``
* If the backend response has an ``ETag`` header, then the ``ETag``
value is "weakened" (prefixed with ``W/``), for weak validation
according to `RFC 7232`_ section 2.1. This is because the response
after de-/compression is not byte-identical with the fetched
......@@ -230,7 +229,7 @@ The parameters are:
* ``quality`` (default 11): sets a compression level, where 0
represents the fastest execution, and 11 represents the highest
compression rate (smallest compressed result). ``quality`` MUST be
>= 0 and <= 11.
in the range 0 to 11, inclusive.
* ``large_win`` (default ``false``): if ``true``, use Large Window
Brotli, which may yield better results for response bodies larger
......@@ -238,10 +237,10 @@ The parameters are:
algorithm; under certain circumstances, it may be necessary to use
the Large Window setting for both compression and decompression.
* ``lgwin`` (default 22): set the window size for the LZ77 algorithm.
The window size is (2 ^ ``lgwin`` - 16), and larger window sizes may
result in better compression rates. ``lgwin`` MUST be >= 10 and <=
24.
* ``lgwin`` (default 22): set the size of the LZ77 sliding window used
by the brotli algorithm. The window size is (2 ^ ``lgwin`` - 16),
and larger window sizes may result in better compression rates.
``lgwin`` MUST be in the range 10 to 24, inclusive.
* ``mode`` (default ``GENERIC``): provide a hint about the expected
contents of the response body; the compression may benefit from
......@@ -265,7 +264,7 @@ Example::
sub vcl_init {
# Create a compression filter with a 1MiB buffer, optimized
# for WOFF.
new br_woff = brotli.encoder("br_woff", buffer=1m, mode=WOFF);
new br_woff = brotli.encoder("br_woff", buffer=1m, mode=FONT);
}
sub vcl_backend_response {
......@@ -306,7 +305,7 @@ As with the ``encoder`` object, the default values for the parameters
correspond to the defaults used in the standard ``"unbr"``
decompression filter.
Also as with ``"encoder``, the ``name`` MAY NOT be ``"br"`` or
Also as with ``encoder``, the ``name`` MAY NOT be ``"br"`` or
``"unbr"``, or the same as any of Varnish's standard filters. It
SHOULD NOT be the same as a name used by another third-party VFP.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment