Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2628:0ce45b4edb75

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
njs-0.5.0.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 02 Dec 2020 09:28:09 +0000
parents 6fdefb00858f
children e203e1106fb2
comparison
equal deleted inserted replaced
2627:9ded17b148f5 2628:0ce45b4edb75
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="56"> 12 rev="57">
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
178 <tag-name id="r_remote_address"><literal>r.remoteAddress</literal></tag-name> 178 <tag-name id="r_remote_address"><literal>r.remoteAddress</literal></tag-name>
179 <tag-desc> 179 <tag-desc>
180 client address, read-only 180 client address, read-only
181 </tag-desc> 181 </tag-desc>
182 182
183 <tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
184 <tag-desc>
185 returns an array of key-value pairs
186 exactly as they were received from the client
187 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
188 <para>
189 For example, with the following request headers:
190 <example>
191 Host: localhost
192 Foo: bar
193 foo: bar2
194 </example>
195 the output of <literal>r.rawHeadersIn</literal> will be:
196 <example>
197 [
198 ['Host', 'localhost'],
199 ['Foo', 'bar'],
200 ['foo', 'bar2']
201 ]
202 </example>
203 All <literal>foo</literal> headers
204 can be collected with the syntax:
205 <example>
206 r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
207 </example>
208 the output will be:
209 <example>
210 ['bar', 'bar2']
211 </example>
212 Header field names are not converted to lower case,
213 duplicate field values are not merged.
214 </para>
215 </tag-desc>
216
217 <tag-name id="r_raw_headers_out"><literal>r.rawHeadersOut{}</literal></tag-name>
218 <tag-desc>
219 returns an array of key-value pairs of response headers
220 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
221 Header field names are not converted to lower case,
222 duplicate field values are not merged.
223 </tag-desc>
224
225 <tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name> 183 <tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
226 <tag-desc> 184 <tag-desc>
227 returns the client request body if it has not been 185 the property is deprecated since
228 written to a temporary file. 186 <link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
187 the <link id="r_request_buffer"><literal>r.requestBuffer</literal></link> or
188 <link id="r_request_text"><literal>r.requestText</literal></link> property
189 should be used instead.
190 </tag-desc>
191
192 <tag-name id="r_request_buffer"><literal>r.requestBuffer</literal></tag-name>
193 <tag-desc>
194 client request body if it has not been written to a temporary file
195 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
229 To ensure that the client request body is in memory, 196 To ensure that the client request body is in memory,
230 its size should be limited by 197 its size should be limited by
231 <link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>, 198 <link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
232 and a sufficient buffer size should be set using 199 and a sufficient buffer size should be set using
233 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>. 200 <link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
234 The property is available only in the 201 The property is available only in the
235 <link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive. 202 <link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
236 </tag-desc> 203 </tag-desc>
237 204
205 <tag-name id="r_request_text"><literal>r.requestText</literal></tag-name>
206 <tag-desc>
207 the same as <link id="r_request_buffer"><literal>r.requestBuffer</literal></link>,
208 but returns a <literal>string</literal>.
209 Note that
210 it may convert bytes invalid in utf8 encoding into the replacement character.
211 </tag-desc>
212
213 <tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
214 <tag-desc>
215 returns an array of key-value pairs
216 exactly as they were received from the client
217 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
218 <para>
219 For example, with the following request headers:
220 <example>
221 Host: localhost
222 Foo: bar
223 foo: bar2
224 </example>
225 the output of <literal>r.rawHeadersIn</literal> will be:
226 <example>
227 [
228 ['Host', 'localhost'],
229 ['Foo', 'bar'],
230 ['foo', 'bar2']
231 ]
232 </example>
233 All <literal>foo</literal> headers
234 can be collected with the syntax:
235 <example>
236 r.rawHeadersIn.filter(v=>v[0].toLowerCase() == 'foo').map(v=>v[1])
237 </example>
238 the output will be:
239 <example>
240 ['bar', 'bar2']
241 </example>
242 Header field names are not converted to lower case,
243 duplicate field values are not merged.
244 </para>
245 </tag-desc>
246
247 <tag-name id="r_raw_headers_out"><literal>r.rawHeadersOut{}</literal></tag-name>
248 <tag-desc>
249 returns an array of key-value pairs of response headers
250 (<link doc="changes.xml" id="njs0.4.1">0.4.1</link>).
251 Header field names are not converted to lower case,
252 duplicate field values are not merged.
253 </tag-desc>
254
238 <tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name> 255 <tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
239 <tag-desc> 256 <tag-desc>
240 holds the <link id="r_subrequest">subrequest</link> response body, read-only. 257 the property is deprecated since
241 The size of <literal>r.responseBody</literal> is limited by the 258 <link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
259 the <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
260 or
261 the <link id="r_response_text"><literal>r.responseText</literal></link>
262 property
263 should be used instead.
264 </tag-desc>
265
266 <tag-name id="r_response_buffer"><literal>r.responseBuffer</literal></tag-name>
267 <tag-desc>
268 holds the <link id="r_subrequest">subrequest</link> response body,
269 read-only
270 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
271 The size of <literal>r.responseBuffer</literal> is limited by the
242 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> 272 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
243 directive. 273 directive.
244 </tag-desc> 274 </tag-desc>
245 275
246 <tag-name id="r_return"><literal>r.return(status[, string])</literal></tag-name> 276 <tag-name id="r_response_text"><literal>r.responseText</literal></tag-name>
277 <tag-desc>
278 the same as <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
279 but returns a string
280 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
281 Note that
282 it may convert bytes invalid in utf8 encoding into the replacement character.
283 </tag-desc>
284
285 <tag-name id="r_return"><literal>r.return(status[,
286 string | Buffer])</literal></tag-name>
247 <tag-desc> 287 <tag-desc>
248 sends the entire response 288 sends the entire response
249 with the specified <literal>status</literal> to the client 289 with the specified <literal>status</literal> to the client.
290 The response can be a string or Buffer
291 (<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
250 <para> 292 <para>
251 It is possible to specify either a redirect URL 293 It is possible to specify either a redirect URL
252 (for codes 301, 302, 303, 307, and 308) 294 (for codes 301, 302, 303, 307, and 308)
253 or the response body text (for other codes) as the second argument 295 or the response body text (for other codes) as the second argument
254 </para> 296 </para>
255 </tag-desc> 297 </tag-desc>
256 298
257 <tag-name id="r_send"><literal>r.send(<value>string</value>)</literal></tag-name> 299 <tag-name id="r_send"><literal>r.send(string
258 <tag-desc> 300 | Buffer)</literal></tag-name>
259 sends a part of the response body to the client 301 <tag-desc>
302 sends a part of the response body to the client.
303 The data sent can be a string or Buffer
304 (<link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
260 </tag-desc> 305 </tag-desc>
261 306
262 <tag-name id="r_send_header"><literal>r.sendHeader()</literal></tag-name> 307 <tag-name id="r_send_header"><literal>r.sendHeader()</literal></tag-name>
263 <tag-desc> 308 <tag-desc>
264 sends the HTTP headers to the client 309 sends the HTTP headers to the client
343 in request, 388 in request,
344 <link doc="../http/ngx_http_core_module.xml" id="location">normalized</link>, 389 <link doc="../http/ngx_http_core_module.xml" id="location">normalized</link>,
345 read-only 390 read-only
346 </tag-desc> 391 </tag-desc>
347 392
393 <tag-name id="r_raw_variables"><literal>r.rawVariables{}</literal></tag-name>
394 <tag-desc>
395 nginx <link id="r_variables">variables</link> as Buffers,
396 writable
397 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
398 </tag-desc>
399
348 <tag-name id="r_variables"><literal>r.variables{}</literal></tag-name> 400 <tag-name id="r_variables"><literal>r.variables{}</literal></tag-name>
349 <tag-desc> 401 <tag-desc>
350 nginx variables object, writable 402 nginx variables object, writable
351 (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>) 403 (since <link doc="changes.xml" id="njs0.2.8">0.2.8</link>)
352 </tag-desc> 404 </tag-desc>
428 <para> 480 <para>
429 An <literal>event</literal> may be one of the following strings: 481 An <literal>event</literal> may be one of the following strings:
430 <list type="tag"> 482 <list type="tag">
431 <tag-name><literal>upload</literal></tag-name> 483 <tag-name><literal>upload</literal></tag-name>
432 <tag-desc> 484 <tag-desc>
433 new data from a client 485 new data (string) from a client
434 </tag-desc> 486 </tag-desc>
435 487
436 <tag-name><literal>download</literal></tag-name> 488 <tag-name><literal>download</literal></tag-name>
437 <tag-desc> 489 <tag-desc>
438 new data to a client 490 new data (string) to a client
491 </tag-desc>
492
493 <tag-name><literal>upstream</literal></tag-name>
494 <tag-desc>
495 new data (Buffer) from a client
496 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
497 </tag-desc>
498
499 <tag-name><literal>downstream</literal></tag-name>
500 <tag-desc>
501 new data (Buffer) to a client
502 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
439 </tag-desc> 503 </tag-desc>
440 504
441 </list> 505 </list>
442 </para> 506 </para>
443 507
444 <para> 508 <para>
445 The completion callback has the following prototype: 509 The completion callback has the following prototype:
446 <literal>callback(data, flags)</literal>, where 510 <literal>callback(data, flags)</literal>, where
447 <literal>data</literal> is string, 511 <literal>data</literal> is string or Buffer (depending on the event type)
448 <literal>flags</literal> is an object 512 <literal>flags</literal> is an object
449 with the following properties: 513 with the following properties:
450 <list type="tag"> 514 <list type="tag">
451 <tag-name id="s_on_callback_last"><literal>last</literal></tag-name> 515 <tag-name id="s_on_callback_last"><literal>last</literal></tag-name>
452 <tag-desc> 516 <tag-desc>
460 <tag-name id="s_remote_address"><literal>s.remoteAddress</literal></tag-name> 524 <tag-name id="s_remote_address"><literal>s.remoteAddress</literal></tag-name>
461 <tag-desc> 525 <tag-desc>
462 client address, read-only 526 client address, read-only
463 </tag-desc> 527 </tag-desc>
464 528
529 <tag-name id="s_raw_variables"><literal>s.rawVariables</literal></tag-name>
530 <tag-desc>
531 nginx <link id="s_variables">variables</link> as Buffers,
532 writable
533 (since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
534 </tag-desc>
535
465 <tag-name id="s_send"><literal>s.send(<value>data</value>[, 536 <tag-name id="s_send"><literal>s.send(<value>data</value>[,
466 <value>options</value>])</literal></tag-name> 537 <value>options</value>])</literal></tag-name>
467 <tag-desc> 538 <tag-desc>
468 sends the data to the client 539 sends the data to the client
469 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>). 540 (<link doc="changes.xml" id="njs0.2.4">0.2.4</link>).
541 The data can be a string or Buffer
542 (<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
470 The <literal>options</literal> is an object used 543 The <literal>options</literal> is an object used
471 to override nginx buffer flags derived from an incoming data chunk buffer. 544 to override nginx buffer flags derived from an incoming data chunk buffer.
472 The flags can be overridden with the following flags: 545 The flags can be overridden with the following flags:
473 <para> 546 <para>
474 <list type="tag"> 547 <list type="tag">
499 <tag-desc> 572 <tag-desc>
500 writes a sent <literal>string</literal> to the error log 573 writes a sent <literal>string</literal> to the error log
501 on the <literal>warning</literal> level of logging 574 on the <literal>warning</literal> level of logging
502 </tag-desc> 575 </tag-desc>
503 576
577 </list>
578 </para>
579
580 </section>
581
582
583 <section id="ngx" name="ngx">
584
585 <para>
586 The <literal>ngx</literal> global object is available
587 since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>.
588 <list type="tag">
589
590 <tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>,
591 <value>message</value>)</tag-name>
592 <tag-desc>
593 Writes a message to the error log with the specified level of logging.
594 The <value>level</value> parameter specifies one of the log levels,
595 the <value>message</value> parameter can be a string or Buffer.
596 The following log levels can be specified:
597 <literal>ngx.INFO</literal>,
598 <literal>ngx.WARN</literal>, and
599 <literal>ngx.ERR</literal>.
600 </tag-desc>
504 </list> 601 </list>
505 </para> 602 </para>
506 603
507 </section> 604 </section>
508 605