Mercurial > hg > nginx-site

changeset 3008:4470b2bff7b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the js_periodic directive.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 12 Sep 2023 21:32:42 +0100
parents 3184864bbb3f
children 2e8c1384d211
files xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/stream/ngx_stream_js_module.xml xml/ru/docs/http/ngx_http_js_module.xml xml/ru/docs/stream/ngx_stream_js_module.xml
diffstat 4 files changed, 302 insertions(+), 6 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="41">
+        rev="42">
 
 <section id="summary">
 
@@ -539,6 +539,80 @@ since <link doc="../njs/changes.xml" id=
 </directive>
 
 
+<directive name="js_periodic">
+<syntax><value>function</value> |
+        <value>module.function</value>
+        [<literal>interval</literal>=<value>time</value>]
+        [<literal>jitter</literal>=<value>number</value>]
+        [<literal>worker_affinity</literal>=<value>mask</value>]</syntax>
+<default/>
+<context>location</context>
+<context>if in location</context>
+<context>limit_except</context>
+<appeared-in>0.8.1</appeared-in>
+
+<para>
+Specifies a content handler to run at regular interval.
+The handler receives a session object as its first argument,
+it also has access to global objects such as
+<link doc="../njs/reference.xml" id="ngx">ngx</link>.
+</para>
+
+<para>
+The optional <literal>interval</literal> parameter
+sets the interval between two consecutive runs,
+by default, 5 seconds.
+</para>
+
+<para>
+The optional <literal>jitter</literal> parameter sets the time within which
+the location content handler will be randomly delayed,
+by default, there is no delay.
+</para>
+
+<para>
+By default, the <literal>js_handler</literal> is executed on worker process 0.
+The optional <literal>worker_affinity</literal> parameter
+allows specifying particular worker processes
+where the location content handler should be executed.
+Each worker process set is represented by a bitmask of allowed worker processes.
+The <literal>all</literal> mask allows the handler to be executed
+in all worker processes.
+</para>
+
+<para>
+Example:
+<example>
+example.conf:
+
+location @periodics {
+    # to be run at 1 minute intervals in worker process 0
+    js_periodic main.handler interval=60s;
+
+    # to be run at 1 minute intervals in all worker processes
+    js_periodic main.handler interval=60s worker_affinity=all;
+
+    # to be run at 1 minute intervals in worker processes 1 and 3
+    js_periodic main.handler interval=60s worker_affinity=0101;
+
+    resolver 10.0.0.1;
+    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
+}
+
+example.js:
+
+async function handler(s) {
+    let reply = async ngx.fetch('https://nginx.org/en/docs/njs/');
+    let body = async reply.text();
+
+    ngx.log(ngx.INFO, body);
+}
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_preload_object">
 <syntax><value>name.json</value> |
 <value>name</value> from <value>file.json</value></syntax>
@@ -659,7 +733,7 @@ key-value pair when the zone storage is 
 </para>
 
 <para>
-Examples:
+Example:
 <example>
 example.conf:
     # Creates a 1Mb dictionary with string values,
--- 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="39">
+        rev="41">
 
 <section id="summary">
 
@@ -458,6 +458,78 @@ since <link doc="../njs/changes.xml" id=
 </directive>
 
 
+<directive name="js_periodic">
+<syntax><value>function</value> |
+        <value>module.function</value>
+        [<literal>interval</literal>=<value>time</value>]
+        [<literal>jitter</literal>=<value>number</value>]
+        [<literal>worker_affinity</literal>=<value>mask</value>]</syntax>
+<default/>
+<context>server</context>
+<appeared-in>0.8.1</appeared-in>
+
+<para>
+Specifies a content handler to run at regular interval.
+The handler receives a session object as its first argument,
+it also has access to global objects such as
+<link doc="../njs/reference.xml" id="ngx">ngx</link>.
+</para>
+
+<para>
+The optional <literal>interval</literal> parameter
+sets the interval between two consecutive runs,
+by default, 5 seconds.
+</para>
+
+<para>
+The optional <literal>jitter</literal> parameter sets the time within which
+the location content handler will be randomly delayed,
+by default, there is no delay.
+</para>
+
+<para>
+By default, the <literal>js_handler</literal> is executed on worker process 0.
+The optional <literal>worker_affinity</literal> parameter
+allows specifying particular worker processes
+where the location content handler should be executed.
+Each worker process set is represented by a bitmask of allowed worker processes.
+The <literal>all</literal> mask allows the handler to be executed
+in all worker processes.
+</para>
+
+<para>
+Example:
+<example>
+example.conf:
+
+location @periodics {
+    # to be run at 1 minute intervals in worker process 0
+    js_periodic main.handler interval=60s;
+
+    # to be run at 1 minute intervals in all worker processes
+    js_periodic main.handler interval=60s worker_affinity=all;
+
+    # to be run at 1 minute intervals in worker processes 1 and 3
+    js_periodic main.handler interval=60s worker_affinity=0101;
+
+    resolver 10.0.0.1;
+    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
+}
+
+example.js:
+
+async function handler(s) {
+    let reply = async ngx.fetch('https://nginx.org/en/docs/njs/');
+    let body = async reply.text();
+
+    ngx.log(ngx.INFO, body);
+}
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_preload_object">
 <syntax><value>name.json</value> |
 <value>name</value> from <value>file.json</value></syntax>
@@ -644,7 +716,7 @@ key-value pair when the zone storage is 
 </para>
 
 <para>
-Examples:
+Example:
 <example>
 example.conf:
     # Creates a 1Mb dictionary with string values,
--- 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="41">
+        rev="42">
 
 <section id="summary">
 
@@ -540,6 +540,82 @@ function version(r) {
 </directive>
 
 
+<directive name="js_periodic">
+<syntax><value>функция</value> |
+        <value>модуль.функция</value>
+        [<literal>interval</literal>=<value>время</value>]
+        [<literal>jitter</literal>=<value>число</value>]
+        [<literal>worker_affinity</literal>=<value>маска</value>]</syntax>
+<default/>
+<context>location</context>
+<context>if in location</context>
+<context>limit_except</context>
+<appeared-in>0.8.1</appeared-in>
+
+<para>
+Задаёт периодичность запуска обработчика содержимого.
+В качестве первого аргумента обработчик получает объект сессии,
+также у обработчика есть доступ к глобальным объектам таким как
+<link doc="../njs/reference.xml" id="ngx">ngx</link>.
+</para>
+
+<para>
+Необязательный параметр <literal>interval</literal>
+задаёт интервал между двумя последовательными запусками,
+по умолчанию 5 секунд.
+</para>
+
+<para>
+Необязательный параметр <literal>jitter</literal>
+задаёт время, в пределах которого
+случайным образом задерживается каждый запуск,
+по умолчанию задержки нет.
+</para>
+
+<para>
+По умолчанию <literal>js_handler</literal> выполняется для рабочего процесса 0.
+Необязательный параметр <literal>worker_affinity</literal>
+позволяет указать рабочий процесс,
+для которого будет выполняться обработчик содержимого location.
+Рабочие процессы задаются битовой маской разрешённых к использованию рабочих
+процессов.
+Маска <literal>all</literal> позволяет обработчику выполняться
+для всех рабочих процессов.
+</para>
+
+<para>
+Пример:
+<example>
+example.conf:
+
+location @periodics {
+    # интервал выполнения 1 минута для рабочего процесса 0
+    js_periodic main.handler interval=60s;
+
+    # интервал выполнения 1 минута для всех рабочих процессов
+    js_periodic main.handler interval=60s worker_affinity=all;
+
+    # интервал выполнения 1 минута для рабочих процессов 1 и 3
+    js_periodic main.handler interval=60s worker_affinity=0101;
+
+    resolver 10.0.0.1;
+    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
+}
+
+example.js:
+
+async function handler(s) {
+    let reply = async ngx.fetch('https://nginx.org/en/docs/njs/');
+    let body = async reply.text();
+
+    ngx.log(ngx.INFO, body);
+}
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_preload_object">
 <syntax><value>имя.json</value> |
 <value>имя</value> from <value>файл.json</value></syntax>
--- 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="39">
+        rev="40">
 
 <section id="summary">
 
@@ -555,6 +555,80 @@ js_preload_object map.json;
 </directive>
 
 
+<directive name="js_periodic">
+<syntax><value>функция</value> |
+        <value>модуль.функция</value>
+        [<literal>interval</literal>=<value>время</value>]
+        [<literal>jitter</literal>=<value>число</value>]
+        [<literal>worker_affinity</literal>=<value>маска</value>]</syntax>
+<default/>
+<context>server</context>
+<appeared-in>0.8.1</appeared-in>
+
+<para>
+Задаёт периодичность запуска обработчика содержимого.
+В качестве первого аргумента обработчик получает объект сессии,
+также у обработчика есть доступ к глобальным объектам таким как
+<link doc="../njs/reference.xml" id="ngx">ngx</link>.
+</para>
+
+<para>
+Необязательный параметр <literal>interval</literal>
+задаёт интервал между двумя последовательными запусками,
+по умолчанию 5 секунд.
+</para>
+
+<para>
+Необязательный параметр <literal>jitter</literal>
+задаёт время, в пределах которого
+случайным образом задерживается каждый запуск,
+по умолчанию задержки нет.
+</para>
+
+<para>
+По умолчанию <literal>js_handler</literal> выполняется для рабочего процесса 0.
+Необязательный параметр <literal>worker_affinity</literal>
+позволяет указать рабочий процесс,
+для которого будет выполняться обработчик содержимого location.
+Рабочие процессы задаются битовой маской разрешённых к использованию рабочих
+процессов.
+Маска <literal>all</literal> позволяет обработчику выполняться
+для всех рабочих процессов.
+</para>
+
+<para>
+Пример:
+<example>
+example.conf:
+
+location @periodics {
+    # интервал выполнения 1 минута для рабочего процесса 0
+    js_periodic main.handler interval=60s;
+
+    # интервал выполнения 1 минута для всех рабочих процессов
+    js_periodic main.handler interval=60s worker_affinity=all;
+
+    # интервал выполнения 1 минута для рабочих процессов 1 и 3
+    js_periodic main.handler interval=60s worker_affinity=0101;
+
+    resolver 10.0.0.1;
+    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
+}
+
+example.js:
+
+async function handler(s) {
+    let reply = async ngx.fetch('https://nginx.org/en/docs/njs/');
+    let body = async reply.text();
+
+    ngx.log(ngx.INFO, body);
+}
+</example>
+</para>
+
+</directive>
+
+
 <directive name="js_set">
 <syntax>
 <value>$переменная</value> <value>функция</value> |