Mercurial > hg > nginx-site
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/>