Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2247:0f16ef9a8dbe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>