changeset 2664:9e39e64bff84

Documented the js_body_filter directive.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 04 Mar 2021 14:34:52 +0000
parents a33d8f0f48b2
children 529114f1108a
files xml/en/docs/http/ngx_http_js_module.xml xml/ru/docs/http/ngx_http_js_module.xml
diffstat 2 files changed, 130 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_js_module.xml
+++ b/xml/en/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Module ngx_http_js_module"
         link="/en/docs/http/ngx_http_js_module.html"
         lang="en"
-        rev="23">
+        rev="24">
 
 <section id="summary">
 
@@ -118,6 +118,70 @@ export default {foo, summary, baz, hello
 
 <section id="directives" name="Directives">
 
+<directive name="js_body_filter">
+<syntax><value>function</value> | <value>module.function</value>
+[<value>buffer_type</value>=<value>string</value> | <value>buffer</value>]</syntax>
+<default/>
+<context>location</context>
+<context>limit_except</context>
+<appeared-in>0.5.2</appeared-in>
+
+<para>
+Sets an njs function as a response body filter.
+The filter function is called for each data chunk of a response body
+with the following arguments:
+
+<list type="tag">
+<tag-name><literal>data</literal></tag-name>
+<tag-desc>
+the incoming data chunk,
+may be a string or Buffer
+depending on the <literal>buffer_type</literal> value,
+by default is a string.
+</tag-desc>
+
+<tag-name><literal>flags</literal></tag-name>
+<tag-desc>
+an object with the following properties:
+<list type="tag">
+<tag-name><literal>last</literal></tag-name>
+<tag-desc>
+a boolean value, true if data is a last buffer.
+</tag-desc>
+
+</list>
+</tag-desc>
+
+</list>
+</para>
+
+<para>
+The filter function can pass its own modified version
+of the input data chunk to the next body filter by calling
+<link doc="../njs/reference.xml" id="r_sendbuffer"><literal>r.sendBuffer()</literal></link>.
+For example, to transform all the lowercase letters in the response body:
+<example>
+function filter(data, flags) {
+    r.sendBuffer(data.toLowerCase(), flags);
+}
+</example>
+To stop filtering (following data chunks will be passed to client
+without calling <literal>js_body_filter</literal>),
+<link doc="../njs/reference.xml" id="r_done"><literal>r.done()</literal></link>
+can be used.
+</para>
+
+<para>
+If the filter function changes the length of the response body, then
+it is required to clear out the <header>Content-Length</header> response header
+(if any) in
+<link id="js_header_filter"><literal>js_header_filter</literal></link>
+to enforce chunked transfer encoding.
+</para>
+
+</directive>
+
+
 <directive name="js_content">
 <syntax><value>function</value> | <value>module.function</value></syntax>
 <default/>
--- a/xml/ru/docs/http/ngx_http_js_module.xml
+++ b/xml/ru/docs/http/ngx_http_js_module.xml
@@ -9,7 +9,7 @@
 <module name="Модуль ngx_http_js_module"
         link="/ru/docs/http/ngx_http_js_module.html"
         lang="ru"
-        rev="23">
+        rev="24">
 
 <section id="summary">
 
@@ -118,6 +118,70 @@ export default {foo, summary, baz, hello
 
 <section id="directives" name="Директивы">
 
+<directive name="js_body_filter">
+<syntax><value>функция</value> | <value>модуль.функция</value>
+[<value>buffer_type</value>=<value>строка</value> | <value>буфер</value>]</syntax>
+<default/>
+<context>location</context>
+<context>limit_except</context>
+<appeared-in>0.5.2</appeared-in>
+
+<para>
+Задаёт функцию njs в качестве фильтра тела ответа.
+Функция фильтра вызывается для каждого блока данных тела ответа
+со следующими аргументами:
+
+<list type="tag">
+<tag-name><literal>data</literal></tag-name>
+<tag-desc>
+входящий блок данных
+может быть строкой или буфером
+в зависимости от значения <literal>buffer_type</literal>,
+по умолчанию является строкой.
+</tag-desc>
+
+<tag-name><literal>flags</literal></tag-name>
+<tag-desc>
+объект со следующими свойствами:
+<list type="tag">
+<tag-name><literal>last</literal></tag-name>
+<tag-desc>
+логическое значение, true, если данные являются последним буфером.
+</tag-desc>
+
+</list>
+</tag-desc>
+
+</list>
+</para>
+
+<para>
+Функция фильтра может передавать свою модифицированную версию
+входящего блока данных следующему фильтру тела ответа при помощи вызова
+<link doc="../njs/reference.xml" id="r_sendbuffer"><literal>r.sendBuffer()</literal></link>.
+Пример преобразования букв в нижний регистр в теле ответа:
+<example>
+function filter(data, flags) {
+    r.sendBuffer(data.toLowerCase(), flags);
+}
+</example>
+Для отмены фильтра (блоки данных будут передаваться клиенту
+без вызова <literal>js_body_filter</literal>),
+можно использовать
+<link doc="../njs/reference.xml" id="r_done"><literal>r.done()</literal></link>.
+</para>
+
+<para>
+Если функция фильтра изменяет длину тела ответа, то
+необходимо очистить заголовок ответа <header>Content-Length</header>
+(если присутствует) в
+<link id="js_header_filter"><literal>js_header_filter</literal></link>,
+чтобы применить поблочное кодирование.
+</para>
+
+</directive>
+
+
 <directive name="js_content">
 <syntax><value>функция</value> | <value>модуль.функция</value></syntax>
 <default/>