Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_js_module.xml @ 2878:fd8ec06ceafa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 a3aee2697d4e
children 986e1f930e3b
comparison
equal deleted inserted replaced
2877:0280b6c71d38 2878:fd8ec06ceafa
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8 8
9 <module name="Module ngx_stream_js_module" 9 <module name="Module ngx_stream_js_module"
10 link="/en/docs/stream/ngx_stream_js_module.html" 10 link="/en/docs/stream/ngx_stream_js_module.html"
11 lang="en" 11 lang="en"
12 rev="31"> 12 rev="32">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 The <literal>ngx_stream_js_module</literal> module is used to implement 17 The <literal>ngx_stream_js_module</literal> module is used to implement
140 <link doc="stream_processing.xml" id="access_phase">access</link> phase. 140 <link doc="stream_processing.xml" id="access_phase">access</link> phase.
141 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, 141 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
142 a module function can be referenced. 142 a module function can be referenced.
143 </para> 143 </para>
144 144
145 <para>
146 The function is called once at the moment when the stream session reaches
147 the <link doc="stream_processing.xml" id="access_phase">access</link> phase
148 for the first time.
149 The function is called with the following arguments:
150
151 <list type="tag">
152 <tag-name><literal>s</literal></tag-name>
153 <tag-desc>
154 the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object
155 </tag-desc>
156
157 </list>
158 </para>
159
160 <para>
161 At this phase, it is possible to perform initialization
162 or register a callback with
163 the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
164 method
165 for each incoming data chunk until one of the following methods are called:
166 <link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>,
167 <link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>,
168 <link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link>.
169 As soon as one of these methods is called, the stream session processing
170 switches to the <link doc="stream_processing.xml">next phase</link>
171 and all current
172 <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
173 callbacks are dropped.
174 </para>
175
176 <para>
177 <note>
178 As the <literal>js_access</literal> handler
179 returns its result immediately, it supports
180 only synchronous callbacks.
181 Thus, asynchronous callbacks such as
182 <link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link>
183 or
184 <link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>
185 are not supported.
186 </note>
187 </para>
188
145 </directive> 189 </directive>
146 190
147 191
148 <directive name="js_fetch_buffer_size"> 192 <directive name="js_fetch_buffer_size">
149 <syntax><value>size</value></syntax> 193 <syntax><value>size</value></syntax>
289 333
290 <para> 334 <para>
291 Sets a data filter. 335 Sets a data filter.
292 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, 336 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
293 a module function can be referenced. 337 a module function can be referenced.
338 The filter function is called once at the moment when the stream session reaches
339 the <link doc="stream_processing.xml" id="content_phase">content</link> phase.
340 </para>
341
342 <para>
343 The filter function is called with the following arguments:
344 <list type="tag">
345 <tag-name><literal>s</literal></tag-name>
346 <tag-desc>
347 the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object
348 </tag-desc>
349
350 </list>
351 </para>
352
353 <para>
354 At this phase, it is possible to perform initialization
355 or register a callback with
356 the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
357 method for each incoming data chunk.
358 The
359 <link doc="../njs/reference.xml" id="s_off"><literal>s.off()</literal></link>
360 method may be used to unregister a callback and stop filtering.
361 </para>
362
363 <para>
364 <note>
365 As the <literal>js_filter</literal> handler
366 returns its result immediately, it supports
367 only synchronous operations.
368 Thus, asynchronous operations such as
369 <link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link>
370 or
371 <link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>
372 are not supported.
373 </note>
294 </para> 374 </para>
295 375
296 </directive> 376 </directive>
297 377
298 378
384 <link doc="stream_processing.xml" id="preread_phase">preread</link> phase. 464 <link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
385 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>, 465 Since <link doc="../njs/changes.xml" id="njs0.4.0">0.4.0</link>,
386 a module function can be referenced. 466 a module function can be referenced.
387 </para> 467 </para>
388 468
469 <para>
470 The function is called once
471 at the moment when the stream session reaches the
472 <link doc="stream_processing.xml" id="preread_phase">preread</link> phase
473 for the first time.
474 The function is called with the following arguments:
475
476 <list type="tag">
477 <tag-name><literal>s</literal></tag-name>
478 <tag-desc>
479 the <link doc="../njs/reference.xml" id="stream">Stream Session</link> object
480 </tag-desc>
481
482 </list>
483 </para>
484
485 <para>
486 At this phase, it is possible to perform initialization
487 or register a callback with
488 the <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
489 method
490 for each incoming data chunk until one of the following methods are called:
491 <link doc="../njs/reference.xml" id="s_allow"><literal>s.allow()</literal></link>,
492 <link doc="../njs/reference.xml" id="s_decline"><literal>s.decline()</literal></link>,
493 <link doc="../njs/reference.xml" id="s_done"><literal>s.done()</literal></link>.
494 When one of these methods is called,
495 the stream session switches to the
496 <link doc="stream_processing.xml">next phase</link>
497 and all current
498 <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
499 callbacks are dropped.
500 </para>
501
502 <para>
503 <note>
504 As the <literal>js_preread</literal> handler
505 returns its result immediately, it supports
506 only synchronous callbacks.
507 Thus, asynchronous callbacks such as
508 <link doc="../njs/reference.xml" id="ngx_fetch"><literal>ngx.fetch()</literal></link>
509 or
510 <link doc="../njs/reference.xml" id="settimeout"><literal>setTimeout()</literal></link>
511 are not supported.
512 Nevertheless, asynchronous operations are supported in
513 <link doc="../njs/reference.xml" id="s_on"><literal>s.on()</literal></link>
514 callbacks in the
515 <link doc="stream_processing.xml" id="preread_phase">preread</link> phase.
516 See
517 <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.
518 </note>
519 </para>
520
389 </directive> 521 </directive>
390 522
391 523
392 <directive name="js_set"> 524 <directive name="js_set">
393 <syntax> 525 <syntax>