Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_js_module.xml @ 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 | 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> |