Mercurial > hg > nginx-site

changeset 1616:9e8ec9c67cf3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>