Mercurial > hg > nginx-site
comparison xml/en/docs/njs/reference.xml @ 2628:0ce45b4edb75
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 |