<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_slice_module"
        link="/en/docs/http/ngx_http_slice_module.html"
        lang="en"
        rev="3">

<section id="summary">

<para>
The <literal>ngx_http_slice_module</literal> module (1.9.8) is a filter
that splits a request into subrequests,
each returning a certain range of response.
The filter provides more effective caching of big responses.
</para>

<para>
This module is not built by default, it should be enabled with the
<literal>--with-http_slice_module</literal>
configuration parameter.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
location / {
    <emphasis>slice</emphasis>             1m;
    proxy_cache       cache;
    proxy_cache_key   $uri$is_args$args<emphasis>$slice_range</emphasis>;
    proxy_set_header  Range <emphasis>$slice_range</emphasis>;
    proxy_cache_valid 200 206 1h;
    proxy_pass        http://localhost:8000;
}
</example>
In this example,
the response is split into 1-megabyte cacheable slices.
</para>

</section>


<section id="directives" name="Directives">


<directive name="slice">
<syntax><value>size</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the <value>size</value> of the slice.
The zero value disables splitting responses into slices.
Note that a too low value may result in excessive memory usage
and opening a large number of files.
</para>

<para>
In order for a subrequest to return the required range,
the <var>$slice_range</var> variable should be
<link doc="ngx_http_proxy_module.xml" id="proxy_set_header">passed</link> to
the proxied server as the <literal>Range</literal> request header field.
If
<link doc="ngx_http_proxy_module.xml" id="proxy_cache">caching</link>
is enabled, <var>$slice_range</var> should be added to the
<link doc="ngx_http_proxy_module.xml" id="proxy_cache_key">cache key</link>
and caching of responses with 206 status code should be
<link doc="ngx_http_proxy_module.xml" id="proxy_cache_valid">enabled</link>.
</para>

</directive>

</section>


<section id="variables" name="Embedded Variables">

<para>
The <literal>ngx_http_slice_module</literal> module
supports the following embedded variables:
<list type="tag">

<tag-name id="var_slice_range"><var>$slice_range</var></tag-name>
<tag-desc>
the current slice range in
<link url="https://datatracker.ietf.org/doc/html/rfc7233#section-2.1">HTTP
byte range</link> format,
for example, <literal>bytes=0-1048575</literal>.

</tag-desc>

</list>
</para>

</section>

</module>