Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_slice_module.xml @ 3039:e6b785b7e308

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Minor fixes in njs documentation.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 06 Feb 2024 08:52:52 +0000
parents 4add6ae1296f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1616
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
2
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
3 <!--
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
5 -->
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
6
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
8
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_http_slice_module"
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
10 link="/en/docs/http/ngx_http_slice_module.html"
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
11 lang="en"
1886
6299f9cabfe4 Changed <literal> to <value> in the slice directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1802
diff changeset
12 rev="3">
1616
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
13
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
14 <section id="summary">
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
15
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
16 <para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
17 The <literal>ngx_http_slice_module</literal> module (1.9.8) is a filter
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
18 that splits a request into subrequests,
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
19 each returning a certain range of response.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
20 The filter provides more effective caching of big responses.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
21 </para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
22
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
23 <para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
24 This module is not built by default, it should be enabled with the
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
25 <literal>--with-http_slice_module</literal>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
26 configuration parameter.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
27 </para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
28
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
29 </section>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
30
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
31
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
32 <section id="example" name="Example Configuration">
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
33
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
34 <para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
35 <example>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
36 location / {
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
37 <emphasis>slice</emphasis> 1m;
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
38 proxy_cache cache;
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
39 proxy_cache_key $uri$is_args$args<emphasis>$slice_range</emphasis>;
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
40 proxy_set_header Range <emphasis>$slice_range</emphasis>;
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
41 proxy_cache_valid 200 206 1h;
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
42 proxy_pass http://localhost:8000;
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
43 }
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
44 </example>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
45 In this example,
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
46 the response is split into 1-megabyte cacheable slices.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
47 </para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
48
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
49 </section>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
50
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
51
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
52 <section id="directives" name="Directives">
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
53
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
54
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
55 <directive name="slice">
1886
6299f9cabfe4 Changed <literal> to <value> in the slice directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1802
diff changeset
56 <syntax><value>size</value></syntax>
1616
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
57 <default>0</default>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
58 <context>http</context>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
59 <context>server</context>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
60 <context>location</context>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
61
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
62 <para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
63 Sets the <value>size</value> of the slice.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
64 The zero value disables splitting responses into slices.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
65 Note that a too low value may result in excessive memory usage
1802
51e1c73cc027 Rephrased file descriptors in the "slice" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1616
diff changeset
66 and opening a large number of files.
1616
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
67 </para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
68
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
69 <para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
70 In order for a subrequest to return the required range,
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
71 the <var>$slice_range</var> variable should be
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
72 <link doc="ngx_http_proxy_module.xml" id="proxy_set_header">passed</link> to
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
73 the proxied server as the <literal>Range</literal> request header field.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
74 If
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
75 <link doc="ngx_http_proxy_module.xml" id="proxy_cache">caching</link>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
76 is enabled, <var>$slice_range</var> should be added to the
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
77 <link doc="ngx_http_proxy_module.xml" id="proxy_cache_key">cache key</link>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
78 and caching of responses with 206 status code should be
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
79 <link doc="ngx_http_proxy_module.xml" id="proxy_cache_valid">enabled</link>.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
80 </para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
81
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
82 </directive>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
83
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
84 </section>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
85
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
86
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
87 <section id="variables" name="Embedded Variables">
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
88
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
89 <para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
90 The <literal>ngx_http_slice_module</literal> module
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
91 supports the following embedded variables:
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
92 <list type="tag">
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
93
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
94 <tag-name id="var_slice_range"><var>$slice_range</var></tag-name>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
95 <tag-desc>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
96 the current slice range in
2831
4add6ae1296f Updated links to datatracker.ietf.org.
Sergey Kandaurov <pluknet@nginx.com>
parents: 1886
diff changeset
97 <link url="https://datatracker.ietf.org/doc/html/rfc7233#section-2.1">HTTP
1616
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
98 byte range</link> format,
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
99 for example, <literal>bytes=0-1048575</literal>.
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
100
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
101 </tag-desc>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
102
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
103 </list>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
104 </para>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
105
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
106 </section>
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
107
9e8ec9c67cf3 Documented ngx_http_slice_module.
Yaroslav Zhuravlev <yar@nginx.com>
parents:
diff changeset
108 </module>