Mercurial > hg > nginx-site
comparison xml/en/docs/njs/reference.xml @ 2247:0f16ef9a8dbe
Created "nginx objects" section in reference.xml.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Mon, 24 Sep 2018 19:24:12 +0300 |
parents | 32ba43abf9cd |
children | 9644ecb67081 |
comparison
equal
deleted
inserted
replaced
2246:32ba43abf9cd | 2247:0f16ef9a8dbe |
---|---|
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> | 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> |
8 | 8 |
9 <article name="Reference" | 9 <article name="Reference" |
10 link="/en/docs/njs/reference.html" | 10 link="/en/docs/njs/reference.html" |
11 lang="en" | 11 lang="en" |
12 rev="9"> | 12 rev="10"> |
13 | 13 |
14 <section id="summary"> | 14 <section id="summary"> |
15 | 15 |
16 <para> | 16 <para> |
17 <link doc="index.xml">njs</link> provides objects, methods and properties | 17 <link doc="index.xml">njs</link> provides objects, methods and properties |
18 for extending nginx functionality. | 18 for extending nginx functionality. |
19 </para> | 19 </para> |
20 | |
21 </section> | |
22 | |
23 | |
24 <section id="http_stream" name="nginx objects"> | |
25 | |
26 | |
27 <section id="http" name="HTTP Request"> | |
28 | |
29 <para> | |
30 The HTTP request object is available only in the | |
31 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. | |
32 All string properties of the object are <link id="string">byte strings</link>. | |
33 | |
34 <list type="tag"> | |
35 | |
36 <tag-name><literal>r.args{}</literal></tag-name> | |
37 <tag-desc> | |
38 request arguments object, read-only | |
39 </tag-desc> | |
40 | |
41 <tag-name><literal>r.error(<value>string</value>)</literal></tag-name> | |
42 <tag-desc> | |
43 writes a <literal>string</literal> to the error log | |
44 on the <literal>error</literal> level of logging | |
45 </tag-desc> | |
46 | |
47 <tag-name><literal>r.finish()</literal></tag-name> | |
48 <tag-desc> | |
49 finishes sending a response to the client | |
50 </tag-desc> | |
51 | |
52 <tag-name><literal>r.headersIn{}</literal></tag-name> | |
53 <tag-desc> | |
54 incoming headers object, read-only. | |
55 <para> | |
56 For example, the <literal>Foo</literal> header | |
57 can be accessed with the syntax <literal>headersIn.foo</literal> | |
58 or <literal>headersIn['Foo']</literal> | |
59 </para> | |
60 </tag-desc> | |
61 | |
62 <tag-name><literal>r.headersOut{}</literal></tag-name> | |
63 <tag-desc> | |
64 outgoing headers object, writable. | |
65 <para> | |
66 For example, the <literal>Foo</literal> header | |
67 can be accessed with the syntax <literal>headersOut.foo</literal> | |
68 or <literal>headersOut['Foo']</literal> | |
69 </para> | |
70 </tag-desc> | |
71 | |
72 <tag-name><literal>r.httpVersion</literal></tag-name> | |
73 <tag-desc> | |
74 HTTP version, read-only | |
75 </tag-desc> | |
76 | |
77 <tag-name><literal>r.log(<value>string</value>)</literal></tag-name> | |
78 <tag-desc> | |
79 writes a <literal>string</literal> to the error log | |
80 on the <literal>info</literal> level of logging | |
81 </tag-desc> | |
82 | |
83 <tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name> | |
84 <tag-desc> | |
85 performs an internal redirect to the specified <literal>uri</literal>. | |
86 If the uri starts with the “<literal>@</literal>” prefix, | |
87 it is considered a named location. | |
88 </tag-desc> | |
89 | |
90 <tag-name><literal>r.method</literal></tag-name> | |
91 <tag-desc> | |
92 HTTP method, read-only | |
93 </tag-desc> | |
94 | |
95 <tag-name><literal>r.parent</literal></tag-name> | |
96 <tag-desc> | |
97 references the parent request object | |
98 </tag-desc> | |
99 | |
100 <tag-name><literal>r.remoteAddress</literal></tag-name> | |
101 <tag-desc> | |
102 client address, read-only | |
103 </tag-desc> | |
104 | |
105 <tag-name><literal>r.requestBody</literal></tag-name> | |
106 <tag-desc> | |
107 holds the request body, read-only | |
108 </tag-desc> | |
109 | |
110 <tag-name><literal>r.responseBody</literal></tag-name> | |
111 <tag-desc> | |
112 holds the <link id="subrequest">subrequest</link> response body, read-only. | |
113 The size of <literal>r.responseBody</literal> is limited by the | |
114 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> | |
115 directive. | |
116 </tag-desc> | |
117 | |
118 <tag-name><literal>r.return(status[, string])</literal></tag-name> | |
119 <tag-desc> | |
120 sends the entire response | |
121 with the specified <literal>status</literal> to the client | |
122 <para> | |
123 It is possible to specify either a redirect URL | |
124 (for codes 301, 302, 303, 307, and 308) | |
125 or the response body text (for other codes) as the second argument | |
126 </para> | |
127 </tag-desc> | |
128 | |
129 <tag-name><literal>r.send(<value>string</value>)</literal></tag-name> | |
130 <tag-desc> | |
131 sends a part of the response body to the client | |
132 </tag-desc> | |
133 | |
134 <tag-name><literal>r.sendHeader()</literal></tag-name> | |
135 <tag-desc> | |
136 sends the HTTP headers to the client | |
137 </tag-desc> | |
138 | |
139 <tag-name><literal>r.status</literal></tag-name> | |
140 <tag-desc> | |
141 status, writable | |
142 </tag-desc> | |
143 | |
144 <tag-name><literal>r.variables{}</literal></tag-name> | |
145 <tag-desc> | |
146 nginx variables object, read-only | |
147 </tag-desc> | |
148 | |
149 <tag-name><literal>r.warn(<value>string</value>)</literal></tag-name> | |
150 <tag-desc> | |
151 writes a <literal>string</literal> to the error log | |
152 on the <literal>warning</literal> level of logging | |
153 </tag-desc> | |
154 | |
155 <tag-name><literal>r.uri</literal></tag-name> | |
156 <tag-desc> | |
157 current URI, read-only | |
158 </tag-desc> | |
159 | |
160 <tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, | |
161 <value>options</value>[, <value>callback</value>]])</literal></tag-name> | |
162 <tag-desc> | |
163 creates a subrequest with the given <literal>uri</literal> and | |
164 <literal>options</literal>, and installs | |
165 an optional completion <literal>callback</literal>. | |
166 | |
167 <para> | |
168 If <literal>options</literal> is a string, then it | |
169 holds the subrequest arguments string. | |
170 Otherwise, <literal>options</literal> is expected to be | |
171 an object with the following keys: | |
172 <list type="tag"> | |
173 <tag-name><literal>args</literal></tag-name> | |
174 <tag-desc> | |
175 arguments string | |
176 </tag-desc> | |
177 <tag-name><literal>body</literal></tag-name> | |
178 <tag-desc> | |
179 request body | |
180 </tag-desc> | |
181 | |
182 <tag-name><literal>method</literal></tag-name> | |
183 <tag-desc> | |
184 HTTP method | |
185 </tag-desc> | |
186 | |
187 </list> | |
188 </para> | |
189 | |
190 <para> | |
191 The completion <literal>callback</literal> receives | |
192 a subrequest response object with methods and properties | |
193 identical to the parent request object. | |
194 </para> | |
195 </tag-desc> | |
196 | |
197 </list> | |
198 </para> | |
199 | |
200 </section> | |
201 | |
202 | |
203 <section id="stream" name="Stream Session"> | |
204 | |
205 <para> | |
206 The stream session object is available only in the | |
207 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> | |
208 module. | |
209 All string properties of the object are <link id="string">byte strings</link>. | |
210 </para> | |
211 | |
212 <para> | |
213 <note> | |
214 Prior to njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
215 the stream session object had some properties which are currently | |
216 <link id="stream_obsolete">removed</link>. | |
217 </note> | |
218 </para> | |
219 | |
220 <para> | |
221 <list type="tag"> | |
222 | |
223 <tag-name id="s_allow"><literal>s.allow()</literal></tag-name> | |
224 <tag-desc> | |
225 successfully finalizes the phase handler | |
226 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
227 </tag-desc> | |
228 | |
229 <tag-name id="s_decline"><literal>s.decline()</literal></tag-name> | |
230 <tag-desc> | |
231 finalizes the phase handler and passes control to the next handler | |
232 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
233 </tag-desc> | |
234 | |
235 <tag-name id="s_deny"><literal>s.deny()</literal></tag-name> | |
236 <tag-desc> | |
237 finalizes the phase handler with the access error code | |
238 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
239 </tag-desc> | |
240 | |
241 <tag-name id="s_done"><literal>s.done</literal>(<value>[code]</value>)</tag-name> | |
242 <tag-desc> | |
243 successfully finalizes the current phase handler | |
244 or finalizes it with the specified numeric code | |
245 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). | |
246 </tag-desc> | |
247 | |
248 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name> | |
249 <tag-desc> | |
250 writes a sent <literal>string</literal> to the error log | |
251 on the <literal>error</literal> level of logging | |
252 </tag-desc> | |
253 | |
254 <tag-name><literal>s.log(<value>string</value>)</literal></tag-name> | |
255 <tag-desc> | |
256 writes a sent <value>string</value> to the error log | |
257 on the <literal>info</literal> level of logging | |
258 </tag-desc> | |
259 | |
260 <tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name> | |
261 <tag-desc> | |
262 unregisters the callback set by the <link id="s_on">s.on()</link> method | |
263 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
264 </tag-desc> | |
265 | |
266 <tag-name id="s_on"><literal>s.on(<value>event</value>, | |
267 <value>callback</value>)</literal></tag-name> | |
268 <tag-desc> | |
269 registers a <literal>callback</literal> for the specified <literal>event</literal> | |
270 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). | |
271 | |
272 <para> | |
273 An <literal>event</literal> may be one of the following strings: | |
274 <list type="tag"> | |
275 <tag-name><literal>upload</literal></tag-name> | |
276 <tag-desc> | |
277 new data from a client | |
278 </tag-desc> | |
279 | |
280 <tag-name><literal>download</literal></tag-name> | |
281 <tag-desc> | |
282 new data to a client | |
283 </tag-desc> | |
284 | |
285 </list> | |
286 </para> | |
287 | |
288 <para> | |
289 The completion callback has the following prototype: | |
290 <literal>callback(data, flags)</literal>, where | |
291 <literal>data</literal> is string, | |
292 <literal>flags</literal> is an object | |
293 with the following properties: | |
294 <list type="tag"> | |
295 <tag-name id="s_on_callback_last"><literal>last</literal></tag-name> | |
296 <tag-desc> | |
297 a boolean value, true if data is a last buffer. | |
298 </tag-desc> | |
299 | |
300 </list> | |
301 </para> | |
302 </tag-desc> | |
303 | |
304 <tag-name><literal>s.remoteAddress</literal></tag-name> | |
305 <tag-desc> | |
306 client address, read-only | |
307 </tag-desc> | |
308 | |
309 <tag-name id="s_send"><literal>s.send(<value>data</value>[, | |
310 <value>options</value>])</literal></tag-name> | |
311 <tag-desc> | |
312 sends the data to the client | |
313 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). | |
314 The <literal>options</literal> is an object used | |
315 to override nginx buffer flags derived from an incoming data chunk buffer. | |
316 The flags can be overriden with the following flags: | |
317 <para> | |
318 <list type="tag"> | |
319 | |
320 <tag-name><literal>last</literal></tag-name> | |
321 <tag-desc> | |
322 boolean, true if the buffer is the last buffer | |
323 </tag-desc> | |
324 | |
325 <tag-name><literal>flush</literal></tag-name> | |
326 <tag-desc> | |
327 boolean, true if the buffer should have the <literal>flush</literal> flag | |
328 </tag-desc> | |
329 </list> | |
330 </para> | |
331 The method can be called multiple times per callback invocation. | |
332 </tag-desc> | |
333 | |
334 <tag-name><literal>s.variables{}</literal></tag-name> | |
335 <tag-desc> | |
336 nginx variables object, read-only | |
337 </tag-desc> | |
338 | |
339 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> | |
340 <tag-desc> | |
341 writes a sent <literal>string</literal> to the error log | |
342 on the <literal>warning</literal> level of logging | |
343 </tag-desc> | |
344 | |
345 </list> | |
346 </para> | |
347 | |
348 | |
349 <section id="stream_obsolete" name="Obsolete properties"> | |
350 | |
351 <para> | |
352 These properties have been removed | |
353 in njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link> | |
354 and are not backward compatible with the existing njs code. | |
355 </para> | |
356 | |
357 <para> | |
358 <list type="tag"> | |
359 | |
360 <tag-name id="s_abort"><literal>s.ABORT</literal></tag-name> | |
361 <tag-desc> | |
362 the <literal>ABORT</literal> return code | |
363 <note> | |
364 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
365 the <link id="s_deny">s.deny()</link> method should be used instead. | |
366 </note> | |
367 </tag-desc> | |
368 | |
369 <tag-name><literal>s.AGAIN</literal></tag-name> | |
370 <tag-desc> | |
371 the <literal>AGAIN</literal> return code | |
372 <note> | |
373 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
374 the corresponding behavior is achieved if no | |
375 <link id="s_allow">s.allow()</link>, | |
376 <link id="s_deny">s.deny()</link>, | |
377 <link id="s_decline">s.decline()</link>, | |
378 <link id="s_done">s.done()</link> | |
379 is invoked and a callback is registered. | |
380 </note> | |
381 </tag-desc> | |
382 | |
383 <tag-name id="s_buffer"><literal>s.buffer</literal></tag-name> | |
384 <tag-desc> | |
385 the current buffer, writable | |
386 <note> | |
387 Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
388 the <link id="s_send">s.send()</link> method should be used for writing. | |
389 For reading, the current buffer is available as the first argument of the | |
390 <literal>event</literal> callback. | |
391 </note> | |
392 </tag-desc> | |
393 | |
394 <tag-name><literal>s.DECLINED</literal></tag-name> | |
395 <tag-desc> | |
396 the <literal>DECLINED</literal> return code | |
397 <note> | |
398 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
399 the <link id="s_decline">s.decline()</link> method should be used instead. | |
400 </note> | |
401 </tag-desc> | |
402 | |
403 <tag-name><literal>s.eof</literal></tag-name> | |
404 <tag-desc> | |
405 a boolean read-only property, true if the current buffer is the last buffer | |
406 <note> | |
407 Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
408 the <link id="s_on_callback_last">flags.last</link> property | |
409 should be used instead. | |
410 </note> | |
411 </tag-desc> | |
412 | |
413 <tag-name><literal>s.ERROR</literal></tag-name> | |
414 <tag-desc> | |
415 the <literal>ERROR</literal> return code | |
416 <note> | |
417 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
418 an appropriate exception can be thrown to report an error. | |
419 </note> | |
420 </tag-desc> | |
421 | |
422 <tag-name><literal>s.fromUpstream</literal></tag-name> | |
423 <tag-desc> | |
424 a boolean read-only property, | |
425 true if the current buffer is from the upstream server to the client | |
426 <note> | |
427 Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
428 a corresponding <link id="s_on">event</link> | |
429 (<literal>upload</literal> or <literal>download</literal>) | |
430 should be used to handle data to or from client. | |
431 </note> | |
432 </tag-desc> | |
433 | |
434 <tag-name id="s_ok"><literal>s.OK</literal></tag-name> | |
435 <tag-desc> | |
436 the <literal>OK</literal> return code | |
437 <note> | |
438 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
439 the <link id="s_allow">s.allow()</link> method should be used instead. | |
440 </note> | |
441 </tag-desc> | |
442 | |
443 </list> | |
444 </para> | |
445 | |
446 </section> | |
447 | |
448 </section> | |
20 | 449 |
21 </section> | 450 </section> |
22 | 451 |
23 | 452 |
24 <section id="core" name="Core"> | 453 <section id="core" name="Core"> |
851 | 1280 |
852 </section> | 1281 </section> |
853 | 1282 |
854 </section> | 1283 </section> |
855 | 1284 |
856 | |
857 <section id="http" name="HTTP Request"> | |
858 | |
859 <para> | |
860 The HTTP request object is available only in the | |
861 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. | |
862 All string properties of the object are <link id="string">byte strings</link>. | |
863 | |
864 <list type="tag"> | |
865 | |
866 <tag-name><literal>r.args{}</literal></tag-name> | |
867 <tag-desc> | |
868 request arguments object, read-only | |
869 </tag-desc> | |
870 | |
871 <tag-name><literal>r.error(<value>string</value>)</literal></tag-name> | |
872 <tag-desc> | |
873 writes a <literal>string</literal> to the error log | |
874 on the <literal>error</literal> level of logging | |
875 </tag-desc> | |
876 | |
877 <tag-name><literal>r.finish()</literal></tag-name> | |
878 <tag-desc> | |
879 finishes sending a response to the client | |
880 </tag-desc> | |
881 | |
882 <tag-name><literal>r.headersIn{}</literal></tag-name> | |
883 <tag-desc> | |
884 incoming headers object, read-only. | |
885 <para> | |
886 For example, the <literal>Foo</literal> header | |
887 can be accessed with the syntax <literal>headersIn.foo</literal> | |
888 or <literal>headersIn['Foo']</literal> | |
889 </para> | |
890 </tag-desc> | |
891 | |
892 <tag-name><literal>r.headersOut{}</literal></tag-name> | |
893 <tag-desc> | |
894 outgoing headers object, writable. | |
895 <para> | |
896 For example, the <literal>Foo</literal> header | |
897 can be accessed with the syntax <literal>headersOut.foo</literal> | |
898 or <literal>headersOut['Foo']</literal> | |
899 </para> | |
900 </tag-desc> | |
901 | |
902 <tag-name><literal>r.httpVersion</literal></tag-name> | |
903 <tag-desc> | |
904 HTTP version, read-only | |
905 </tag-desc> | |
906 | |
907 <tag-name><literal>r.log(<value>string</value>)</literal></tag-name> | |
908 <tag-desc> | |
909 writes a <literal>string</literal> to the error log | |
910 on the <literal>info</literal> level of logging | |
911 </tag-desc> | |
912 | |
913 <tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name> | |
914 <tag-desc> | |
915 performs an internal redirect to the specified <literal>uri</literal>. | |
916 If the uri starts with the “<literal>@</literal>” prefix, | |
917 it is considered a named location. | |
918 </tag-desc> | |
919 | |
920 <tag-name><literal>r.method</literal></tag-name> | |
921 <tag-desc> | |
922 HTTP method, read-only | |
923 </tag-desc> | |
924 | |
925 <tag-name><literal>r.parent</literal></tag-name> | |
926 <tag-desc> | |
927 references the parent request object | |
928 </tag-desc> | |
929 | |
930 <tag-name><literal>r.remoteAddress</literal></tag-name> | |
931 <tag-desc> | |
932 client address, read-only | |
933 </tag-desc> | |
934 | |
935 <tag-name><literal>r.requestBody</literal></tag-name> | |
936 <tag-desc> | |
937 holds the request body, read-only | |
938 </tag-desc> | |
939 | |
940 <tag-name><literal>r.responseBody</literal></tag-name> | |
941 <tag-desc> | |
942 holds the <link id="subrequest">subrequest</link> response body, read-only. | |
943 The size of <literal>r.responseBody</literal> is limited by the | |
944 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> | |
945 directive. | |
946 </tag-desc> | |
947 | |
948 <tag-name><literal>r.return(status[, string])</literal></tag-name> | |
949 <tag-desc> | |
950 sends the entire response | |
951 with the specified <literal>status</literal> to the client | |
952 <para> | |
953 It is possible to specify either a redirect URL | |
954 (for codes 301, 302, 303, 307, and 308) | |
955 or the response body text (for other codes) as the second argument | |
956 </para> | |
957 </tag-desc> | |
958 | |
959 <tag-name><literal>r.send(<value>string</value>)</literal></tag-name> | |
960 <tag-desc> | |
961 sends a part of the response body to the client | |
962 </tag-desc> | |
963 | |
964 <tag-name><literal>r.sendHeader()</literal></tag-name> | |
965 <tag-desc> | |
966 sends the HTTP headers to the client | |
967 </tag-desc> | |
968 | |
969 <tag-name><literal>r.status</literal></tag-name> | |
970 <tag-desc> | |
971 status, writable | |
972 </tag-desc> | |
973 | |
974 <tag-name><literal>r.variables{}</literal></tag-name> | |
975 <tag-desc> | |
976 nginx variables object, read-only | |
977 </tag-desc> | |
978 | |
979 <tag-name><literal>r.warn(<value>string</value>)</literal></tag-name> | |
980 <tag-desc> | |
981 writes a <literal>string</literal> to the error log | |
982 on the <literal>warning</literal> level of logging | |
983 </tag-desc> | |
984 | |
985 <tag-name><literal>r.uri</literal></tag-name> | |
986 <tag-desc> | |
987 current URI, read-only | |
988 </tag-desc> | |
989 | |
990 <tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, | |
991 <value>options</value>[, <value>callback</value>]])</literal></tag-name> | |
992 <tag-desc> | |
993 creates a subrequest with the given <literal>uri</literal> and | |
994 <literal>options</literal>, and installs | |
995 an optional completion <literal>callback</literal>. | |
996 | |
997 <para> | |
998 If <literal>options</literal> is a string, then it | |
999 holds the subrequest arguments string. | |
1000 Otherwise, <literal>options</literal> is expected to be | |
1001 an object with the following keys: | |
1002 <list type="tag"> | |
1003 <tag-name><literal>args</literal></tag-name> | |
1004 <tag-desc> | |
1005 arguments string | |
1006 </tag-desc> | |
1007 <tag-name><literal>body</literal></tag-name> | |
1008 <tag-desc> | |
1009 request body | |
1010 </tag-desc> | |
1011 | |
1012 <tag-name><literal>method</literal></tag-name> | |
1013 <tag-desc> | |
1014 HTTP method | |
1015 </tag-desc> | |
1016 | |
1017 </list> | |
1018 </para> | |
1019 | |
1020 <para> | |
1021 The completion <literal>callback</literal> receives | |
1022 a subrequest response object with methods and properties | |
1023 identical to the parent request object. | |
1024 </para> | |
1025 </tag-desc> | |
1026 | |
1027 </list> | |
1028 </para> | |
1029 | |
1030 </section> | |
1031 | |
1032 | |
1033 <section id="stream" name="Stream Session"> | |
1034 | |
1035 <para> | |
1036 The stream session object is available only in the | |
1037 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> | |
1038 module. | |
1039 All string properties of the object are <link id="string">byte strings</link>. | |
1040 </para> | |
1041 | |
1042 <para> | |
1043 <note> | |
1044 Prior to njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1045 the stream session object had some properties which are currently | |
1046 <link id="stream_obsolete">removed</link>. | |
1047 </note> | |
1048 </para> | |
1049 | |
1050 <para> | |
1051 <list type="tag"> | |
1052 | |
1053 <tag-name id="s_allow"><literal>s.allow()</literal></tag-name> | |
1054 <tag-desc> | |
1055 successfully finalizes the phase handler | |
1056 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
1057 </tag-desc> | |
1058 | |
1059 <tag-name id="s_decline"><literal>s.decline()</literal></tag-name> | |
1060 <tag-desc> | |
1061 finalizes the phase handler and passes control to the next handler | |
1062 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
1063 </tag-desc> | |
1064 | |
1065 <tag-name id="s_deny"><literal>s.deny()</literal></tag-name> | |
1066 <tag-desc> | |
1067 finalizes the phase handler with the access error code | |
1068 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
1069 </tag-desc> | |
1070 | |
1071 <tag-name id="s_done"><literal>s.done</literal>(<value>[code]</value>)</tag-name> | |
1072 <tag-desc> | |
1073 successfully finalizes the current phase handler | |
1074 or finalizes it with the specified numeric code | |
1075 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). | |
1076 </tag-desc> | |
1077 | |
1078 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name> | |
1079 <tag-desc> | |
1080 writes a sent <literal>string</literal> to the error log | |
1081 on the <literal>error</literal> level of logging | |
1082 </tag-desc> | |
1083 | |
1084 <tag-name><literal>s.log(<value>string</value>)</literal></tag-name> | |
1085 <tag-desc> | |
1086 writes a sent <value>string</value> to the error log | |
1087 on the <literal>info</literal> level of logging | |
1088 </tag-desc> | |
1089 | |
1090 <tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name> | |
1091 <tag-desc> | |
1092 unregisters the callback set by the <link id="s_on">s.on()</link> method | |
1093 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) | |
1094 </tag-desc> | |
1095 | |
1096 <tag-name id="s_on"><literal>s.on(<value>event</value>, | |
1097 <value>callback</value>)</literal></tag-name> | |
1098 <tag-desc> | |
1099 registers a <literal>callback</literal> for the specified <literal>event</literal> | |
1100 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). | |
1101 | |
1102 <para> | |
1103 An <literal>event</literal> may be one of the following strings: | |
1104 <list type="tag"> | |
1105 <tag-name><literal>upload</literal></tag-name> | |
1106 <tag-desc> | |
1107 new data from a client | |
1108 </tag-desc> | |
1109 | |
1110 <tag-name><literal>download</literal></tag-name> | |
1111 <tag-desc> | |
1112 new data to a client | |
1113 </tag-desc> | |
1114 | |
1115 </list> | |
1116 </para> | |
1117 | |
1118 <para> | |
1119 The completion callback has the following prototype: | |
1120 <literal>callback(data, flags)</literal>, where | |
1121 <literal>data</literal> is string, | |
1122 <literal>flags</literal> is an object | |
1123 with the following properties: | |
1124 <list type="tag"> | |
1125 <tag-name id="s_on_callback_last"><literal>last</literal></tag-name> | |
1126 <tag-desc> | |
1127 a boolean value, true if data is a last buffer. | |
1128 </tag-desc> | |
1129 | |
1130 </list> | |
1131 </para> | |
1132 </tag-desc> | |
1133 | |
1134 <tag-name><literal>s.remoteAddress</literal></tag-name> | |
1135 <tag-desc> | |
1136 client address, read-only | |
1137 </tag-desc> | |
1138 | |
1139 <tag-name id="s_send"><literal>s.send(<value>data</value>[, | |
1140 <value>options</value>])</literal></tag-name> | |
1141 <tag-desc> | |
1142 sends the data to the client | |
1143 (<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). | |
1144 The <literal>options</literal> is an object used | |
1145 to override nginx buffer flags derived from an incoming data chunk buffer. | |
1146 The flags can be overriden with the following flags: | |
1147 <para> | |
1148 <list type="tag"> | |
1149 | |
1150 <tag-name><literal>last</literal></tag-name> | |
1151 <tag-desc> | |
1152 boolean, true if the buffer is the last buffer | |
1153 </tag-desc> | |
1154 | |
1155 <tag-name><literal>flush</literal></tag-name> | |
1156 <tag-desc> | |
1157 boolean, true if the buffer should have the <literal>flush</literal> flag | |
1158 </tag-desc> | |
1159 </list> | |
1160 </para> | |
1161 The method can be called multiple times per callback invocation. | |
1162 </tag-desc> | |
1163 | |
1164 <tag-name><literal>s.variables{}</literal></tag-name> | |
1165 <tag-desc> | |
1166 nginx variables object, read-only | |
1167 </tag-desc> | |
1168 | |
1169 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> | |
1170 <tag-desc> | |
1171 writes a sent <literal>string</literal> to the error log | |
1172 on the <literal>warning</literal> level of logging | |
1173 </tag-desc> | |
1174 | |
1175 </list> | |
1176 </para> | |
1177 | |
1178 | |
1179 <section id="stream_obsolete" name="Obsolete properties"> | |
1180 | |
1181 <para> | |
1182 These properties have been removed | |
1183 in njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link> | |
1184 and are not backward compatible with the existing njs code. | |
1185 </para> | |
1186 | |
1187 <para> | |
1188 <list type="tag"> | |
1189 | |
1190 <tag-name id="s_abort"><literal>s.ABORT</literal></tag-name> | |
1191 <tag-desc> | |
1192 the <literal>ABORT</literal> return code | |
1193 <note> | |
1194 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1195 the <link id="s_deny">s.deny()</link> method should be used instead. | |
1196 </note> | |
1197 </tag-desc> | |
1198 | |
1199 <tag-name><literal>s.AGAIN</literal></tag-name> | |
1200 <tag-desc> | |
1201 the <literal>AGAIN</literal> return code | |
1202 <note> | |
1203 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1204 the corresponding behavior is achieved if no | |
1205 <link id="s_allow">s.allow()</link>, | |
1206 <link id="s_deny">s.deny()</link>, | |
1207 <link id="s_decline">s.decline()</link>, | |
1208 <link id="s_done">s.done()</link> | |
1209 is invoked and a callback is registered. | |
1210 </note> | |
1211 </tag-desc> | |
1212 | |
1213 <tag-name id="s_buffer"><literal>s.buffer</literal></tag-name> | |
1214 <tag-desc> | |
1215 the current buffer, writable | |
1216 <note> | |
1217 Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1218 the <link id="s_send">s.send()</link> method should be used for writing. | |
1219 For reading, the current buffer is available as the first argument of the | |
1220 <literal>event</literal> callback. | |
1221 </note> | |
1222 </tag-desc> | |
1223 | |
1224 <tag-name><literal>s.DECLINED</literal></tag-name> | |
1225 <tag-desc> | |
1226 the <literal>DECLINED</literal> return code | |
1227 <note> | |
1228 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1229 the <link id="s_decline">s.decline()</link> method should be used instead. | |
1230 </note> | |
1231 </tag-desc> | |
1232 | |
1233 <tag-name><literal>s.eof</literal></tag-name> | |
1234 <tag-desc> | |
1235 a boolean read-only property, true if the current buffer is the last buffer | |
1236 <note> | |
1237 Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1238 the <link id="s_on_callback_last">flags.last</link> property | |
1239 should be used instead. | |
1240 </note> | |
1241 </tag-desc> | |
1242 | |
1243 <tag-name><literal>s.ERROR</literal></tag-name> | |
1244 <tag-desc> | |
1245 the <literal>ERROR</literal> return code | |
1246 <note> | |
1247 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1248 an appropriate exception can be thrown to report an error. | |
1249 </note> | |
1250 </tag-desc> | |
1251 | |
1252 <tag-name><literal>s.fromUpstream</literal></tag-name> | |
1253 <tag-desc> | |
1254 a boolean read-only property, | |
1255 true if the current buffer is from the upstream server to the client | |
1256 <note> | |
1257 Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1258 a corresponding <link id="s_on">event</link> | |
1259 (<literal>upload</literal> or <literal>download</literal>) | |
1260 should be used to handle data to or from client. | |
1261 </note> | |
1262 </tag-desc> | |
1263 | |
1264 <tag-name id="s_ok"><literal>s.OK</literal></tag-name> | |
1265 <tag-desc> | |
1266 the <literal>OK</literal> return code | |
1267 <note> | |
1268 Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, | |
1269 the <link id="s_allow">s.allow()</link> method should be used instead. | |
1270 </note> | |
1271 </tag-desc> | |
1272 | |
1273 </list> | |
1274 </para> | |
1275 | |
1276 </section> | |
1277 | |
1278 </section> | |
1279 | |
1280 | |
1281 </article> | 1285 </article> |