Mercurial > hg > nginx-site
changeset 1616:9e8ec9c67cf3
Documented ngx_http_slice_module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 08 Dec 2015 18:53:15 +0300 |
parents | a1531068d436 |
children | 69ff752dcb55 |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_slice_module.xml xml/en/docs/index.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_slice_module.xml xml/ru/docs/index.xml |
diffstat | 6 files changed, 229 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -71,6 +71,7 @@ REFS = \ http/ngx_http_rewrite_module \ http/ngx_http_scgi_module \ http/ngx_http_secure_link_module \ + http/ngx_http_slice_module \ http/ngx_http_spdy_module \ http/ngx_http_session_log_module \ http/ngx_http_split_clients_module \
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_slice_module.xml @@ -0,0 +1,108 @@ +<?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="1"> + +<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><literal>size</literal></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 a large number of file descriptors. +</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://tools.ietf.org/html/rfc7233#section-2.1">HTTP +byte range</link> format, +for example, <literal>bytes=0-1048575</literal>. + +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="23" + rev="24" toc="no"> @@ -365,6 +365,11 @@ ngx_http_session_log_module</link> </listitem> <listitem> +<link doc="http/ngx_http_slice_module.xml"> +ngx_http_slice_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_spdy_module.xml"> ngx_http_spdy_module</link> </listitem>
--- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -62,6 +62,7 @@ REFS = \ http/ngx_http_rewrite_module \ http/ngx_http_scgi_module \ http/ngx_http_secure_link_module \ + http/ngx_http_slice_module \ http/ngx_http_spdy_module \ http/ngx_http_split_clients_module \ http/ngx_http_ssi_module \
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/http/ngx_http_slice_module.xml @@ -0,0 +1,107 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_http_slice_module" + link="/ru/docs/http/ngx_http_slice_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_http_slice_module</literal> (1.9.8) — это фильтр, +который разбивает запрос на подзапросы, +каждый из которых возвращает определённый диапазон ответа. +Фильтр обеспечивает более эффективное кэширование больших ответов. +</para> + +<para> +По умолчанию этот модуль не собирается, его сборку необходимо +разрешить с помощью конфигурационного параметра +<literal>--with-http_slice_module</literal>. +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<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> +В данном примере +ответ разбивается на кэшируемые фрагменты размером в 1 мегабайт. +</para> +</section> + + +<section id="directives" name="Директивы"> + +<directive name="slice"> +<syntax><literal>размер</literal></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт <value>размер</value> фрагмента. +Нулевое значение запрещает разбиение ответов на фрагменты. +Обратите внимание, что слишком низкое значение может привести +к излишнему потреблению памяти +и открытию большого количества открытых файловых дескрипторов. +</para> + +<para> +Для того, чтобы подзапрос вернул необходимый диапазон, +переменная <var>$slice_range</var> должна быть +<link doc="ngx_http_proxy_module.xml" id="proxy_set_header">передана</link> на +проксируемый сервер в качестве поля <literal>Range</literal> заголовка запроса. +Если включено +<link doc="ngx_http_proxy_module.xml" id="proxy_cache">кэширование</link>, +то необходимо добавить <var>$slice_range</var> в +<link doc="ngx_http_proxy_module.xml" id="proxy_cache_key">ключ +кэширования</link> +и <link doc="ngx_http_proxy_module.xml" id="proxy_cache_valid">включить</link> +кэширование ответов с кодом 206. +</para> + +</directive> + +</section> + + +<section id="variables" name="Встроенные переменные"> + +<para> +Модуль <literal>ngx_http_slice_module</literal> +поддерживает следующие встроенные переменные: +<list type="tag"> + +<tag-name id="var_slice_range"><var>$slice_range</var></tag-name> +<tag-desc> +текущий диапазон фрагмента в формате +<link url="https://tools.ietf.org/html/rfc7233#section-2.1">HTTP +byte range</link>, +например <literal>bytes=0-1048575</literal>. +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/ru/docs/index.xml +++ b/xml/ru/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="23" + rev="24" toc="no"> @@ -369,6 +369,11 @@ ngx_http_session_log_module</link> [en] </listitem> <listitem> +<link doc="http/ngx_http_slice_module.xml"> +ngx_http_slice_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_spdy_module.xml"> ngx_http_spdy_module</link> </listitem>