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>