Mercurial > hg > nginx-site
changeset 2878:fd8ec06ceafa
Improved descriptions of js_access, js_filter, js_preread.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Mon, 08 Aug 2022 16:29:42 +0100 |
parents | 0280b6c71d38 |
children | 12dd77007e22 |
files | xml/en/docs/stream/ngx_stream_js_module.xml xml/ru/docs/stream/ngx_stream_js_module.xml |
diffstat | 2 files changed, 267 insertions(+), 6 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/stream/ngx_stream_js_module.xml +++ b/xml/en/docs/stream/ngx_stream_js_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_stream_js_module" link="/en/docs/stream/ngx_stream_js_module.html" lang="en" - rev="31"> + rev="32"> <section id="summary"> @@ -142,6 +142,50 @@ Since <link doc="../njs/changes.xml" id= a module function can be referenced. </para> +<para> +The function is called once at the moment when the stream session reaches +the <link doc="stream_processing.xml" id="access_phase">access</link> phase +for the first time. +The function is called with the following arguments: + +<list type="tag"> +<tag-name><literal>s</literal></tag-name> +<tag-desc> +the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object +</tag-desc> + +</list> +</para> + +<para> +At this phase, it is possible to perform initialization +or register a callback with +the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +method +for each incoming data chunk until one of the following methods are called: +<link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>, +<link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>, +<link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link>. +As soon as one of these methods is called, the stream session processing +switches to the <link doc="stream_processing.xml">next phase</link> +and all current +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +callbacks are dropped. +</para> + +<para> +<note> +As the <literal>js_access</literal> handler +returns its result immediately, it supports +only synchronous callbacks. +Thus, asynchronous callbacks such as +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> +or +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link> +are not supported. +</note> +</para> + </directive> @@ -291,6 +335,42 @@ with <link doc="../njs/reference.xml" id Sets a data filter. Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, a module function can be referenced. +The filter function is called once at the moment when the stream session reaches +the <link doc="stream_processing.xml" id="content_phase">content</link> phase. +</para> + +<para> +The filter function is called with the following arguments: +<list type="tag"> +<tag-name><literal>s</literal></tag-name> +<tag-desc> +the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object +</tag-desc> + +</list> +</para> + +<para> +At this phase, it is possible to perform initialization +or register a callback with +the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +method for each incoming data chunk. +The +<link doc="../njs/reference.xml" id="s_off"><literal>s.off()</literal></link> +method may be used to unregister a callback and stop filtering. +</para> + +<para> +<note> +As the <literal>js_filter</literal> handler +returns its result immediately, it supports +only synchronous operations. +Thus, asynchronous operations such as +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> +or +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link> +are not supported. +</note> </para> </directive> @@ -386,6 +466,58 @@ Since <link doc="../njs/changes.xml" id= a module function can be referenced. </para> +<para> +The function is called once +at the moment when the stream session reaches the +<link doc="stream_processing.xml" id="preread_phase">preread</link> phase +for the first time. +The function is called with the following arguments: + +<list type="tag"> +<tag-name><literal>s</literal></tag-name> +<tag-desc> +the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object +</tag-desc> + +</list> +</para> + +<para> +At this phase, it is possible to perform initialization +or register a callback with +the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +method +for each incoming data chunk until one of the following methods are called: +<link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>, +<link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>, +<link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link>. +When one of these methods is called, +the stream session switches to the +<link doc="stream_processing.xml">next phase</link> +and all current +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +callbacks are dropped. +</para> + +<para> +<note> +As the <literal>js_preread</literal> handler +returns its result immediately, it supports +only synchronous callbacks. +Thus, asynchronous callbacks such as +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> +or +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link> +are not supported. +Nevertheless, asynchronous operations are supported in +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +callbacks in the +<link doc="stream_processing.xml" id="preread_phase">preread</link> phase. +See +<link url="https://github.com/nginx/njs-examples#authorizing-connections-using-ngx-fetch-as-auth-request-stream-auth-request">this example</link> for more information. +</note> +</para> + </directive>
--- a/xml/ru/docs/stream/ngx_stream_js_module.xml +++ b/xml/ru/docs/stream/ngx_stream_js_module.xml @@ -9,7 +9,7 @@ <module name="Модуль ngx_stream_js_module" link="/ru/docs/stream/ngx_stream_js_module.html" lang="ru" - rev="31"> + rev="32"> <section id="summary"> @@ -142,6 +142,49 @@ export default {bar, preread, req_line, можно ссылаться на функцию модуля. </para> +<para> +Функция вызывается однократно при первом достижении сессией +<link doc="stream_processing.xml" id="access_phase">access</link>-фазы. +Функция вызывается со следующими аргументами: + +<list type="tag"> +<tag-name><literal>s</literal></tag-name> +<tag-desc> +объект <link doc="../njs/reference.xml" id="stream">stream-сессии</link> +</tag-desc> + +</list> +</para> + +<para> +В этой фазе может происходить инициализация, +также при помощи метода +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +может регистрироваться вызов +для каждого входящего блока данных пока не будет вызван один из методов: +<link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link> +<link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>, +<link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>. +При вызове любого из этих методов обработка сессии +переходит на <link doc="stream_processing.xml">следующую фазу</link> +и все текущие вызовы +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +сбрасываются. +</para> + +<para> +<note> +Так как обработчик <literal>js_access</literal> +должен сразу возвращать результат, +то поддерживаются только синхронные операции. +Таким образом, асинхронные операции, например +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> +или +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>, +не поддерживаются. +</note> +</para> + </directive> @@ -292,6 +335,43 @@ HTTPS-сертификата Задаёт фильтр данных. Начиная с <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link> можно ссылаться на функцию модуля. +Функция фильтра вызывается однократно при первом достижении сессией +<link doc="stream_processing.xml" id="content_phase">content</link>-фазы. +</para> + +<para> +Функция фильтра вызывается со следующими аргументами: +<list type="tag"> +<tag-name><literal>s</literal></tag-name> +<tag-desc> +объект <link doc="../njs/reference.xml" id="stream">stream-сессии</link> +</tag-desc> + +</list> +</para> + +<para> +В этой фазе может происходить инициализация, +также при помощи метода +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +может регистрироваться вызов +для каждого входящего блока данных. +Для отмены регистрации вызова и отмены фильтра +можно использовать метод +<link doc="../njs/reference.xml" id="s_off"><literal>s.off()</literal></link>. +</para> + +<para> +<note> +Так как обработчик <literal>js_filter</literal> +должен сразу возвращать результат, +то поддерживаются только синхронные операции. +Таким образом, асинхронные операции, например +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> +или +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>, +не поддерживаются. +</note> </para> </directive> @@ -374,6 +454,55 @@ function address(s) { можно ссылаться на функцию модуля. </para> +<para> +Функция вызывается однократно при первом достижении сессией +<link doc="stream_processing.xml" id="preread_phase">preread</link>-фазы. +Функция вызывается со следующими аргументами: + +<list type="tag"> +<tag-name><literal>s</literal></tag-name> +<tag-desc> +объект <link doc="../njs/reference.xml" id="stream">stream-сессии</link> +</tag-desc> + +</list> +</para> + +<para> +В этой фазе может происходить инициализация, +также при помощи метода +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +может регистрироваться вызов +для каждого входящего блока данных пока не будет вызван один из методов: +<link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link> +<link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>, +<link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>. +При вызове любого из этих методов обработка сессии +переходит на <link doc="stream_processing.xml">следующую фазу</link> +и все текущие вызовы +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +сбрасываются. +</para> + +<para> +<note> +Так как обработчик <literal>js_preread</literal> +должен сразу возвращать результат, +то поддерживаются только синхронные операции. +Таким образом, асинхронные операции, например +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> +или +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>, +не поддерживаются. +Тем не менее асинхронные операции поддерживаются в вызовах +<link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link> +в +<link doc="stream_processing.xml" id="preread_phase">preread</link>-фазе. +Подробнее см. +<link url="https://github.com/nginx/njs-examples#authorizing-connections-using-ngx-fetch-as-auth-request-stream-auth-request">пример</link>. +</note> +</para> + </directive> @@ -424,11 +553,11 @@ function address(s) { <note> Так как обработчик <literal>js_set</literal> должен сразу возвращать результат, -то поддерживаются только синхронные вызовы. -Таким образом, асинхронные вызовы, например -<link doc="../njs/reference.xml" id="ngx_fetch">ngx.fetch()</link> +то поддерживаются только синхронные операции. +Таким образом, асинхронные операции, например +<link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link> или -<link doc="../njs/reference.xml" id="settimeout">setTimeout()</link>, +<link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>, не поддерживаются. </note> </para>