Mercurial > hg > nginx-site
comparison xml/en/docs/njs/njs_api.xml @ 2182:7865ca0da0ab
Merged HTTP request,response, and reply in njs.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 19 Jun 2018 15:43:42 +0300 |
parents | cb431c861670 |
children | 97526b8346f4 |
comparison
equal
deleted
inserted
replaced
2181:b73ccabb852b | 2182:7865ca0da0ab |
---|---|
209 </section> | 209 </section> |
210 | 210 |
211 | 211 |
212 <section id="http" name="HTTP"> | 212 <section id="http" name="HTTP"> |
213 | 213 |
214 <para> | 214 |
215 The <literal>HTTP</literal> objects are available only in the | 215 <section id="http_request" name="Request"> |
216 | |
217 <para> | |
218 The <literal>HTTP</literal> object is available only in the | |
216 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. | 219 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. |
217 </para> | 220 </para> |
218 | 221 |
219 | |
220 <section id="http_request" name="Request"> | |
221 | |
222 <para> | 222 <para> |
223 <list type="tag"> | 223 <list type="tag"> |
224 | 224 |
225 <tag-name><literal>req.uri</literal></tag-name> | 225 <tag-name><literal>r.args{}</literal></tag-name> |
226 <tag-desc> | 226 <tag-desc> |
227 current URI in a request, read-only | 227 request arguments object, read-only |
228 </tag-desc> | 228 </tag-desc> |
229 | 229 |
230 <tag-name><literal>req.method</literal></tag-name> | 230 <tag-name><literal>r.error(<value>string</value>)</literal></tag-name> |
231 <tag-desc> | 231 <tag-desc> |
232 request method, read-only | 232 writes a <literal>string</literal> to the error log |
233 </tag-desc> | 233 on the <literal>error</literal> level of logging |
234 | 234 </tag-desc> |
235 <tag-name><literal>req.httpVersion</literal></tag-name> | 235 |
236 <tag-desc> | 236 <tag-name><literal>r.finish()</literal></tag-name> |
237 HTTP version, read-only | 237 <tag-desc> |
238 </tag-desc> | 238 finishes sending a response to the client |
239 | 239 </tag-desc> |
240 <tag-name><literal>req.remoteAddress</literal></tag-name> | 240 |
241 <tag-desc> | 241 <tag-name><literal>r.headersIn{}</literal></tag-name> |
242 client address, read-only | 242 <tag-desc> |
243 </tag-desc> | 243 incoming headers object, read-only. |
244 | |
245 <tag-name><literal>req.headers{}</literal></tag-name> | |
246 <tag-desc> | |
247 request headers object, read-only. | |
248 <para> | 244 <para> |
249 For example, the <literal>Header-Name</literal> header | 245 For example, the <literal>Header-Name</literal> header |
250 can be accessed with the syntax <literal>headers['Header-Name']</literal> | 246 can be accessed with the syntax <literal>headers['Header-Name']</literal> |
251 or <literal>headers.Header_name</literal> | 247 or <literal>headers.Header_name</literal> |
252 </para> | 248 </para> |
253 </tag-desc> | 249 </tag-desc> |
254 | 250 |
255 <tag-name><literal>req.args{}</literal></tag-name> | 251 <tag-name><literal>r.headersOut{}</literal></tag-name> |
256 <tag-desc> | 252 <tag-desc> |
257 request arguments object, read-only | 253 outgoing headers object, writable. |
258 </tag-desc> | 254 <para> |
259 | 255 For example, the <literal>Header-Name</literal> header |
260 <tag-name><literal>request.variables{}</literal></tag-name> | 256 can be accessed with the syntax <literal>headers['Header-Name']</literal> |
261 <tag-desc> | 257 or <literal>headers.Header_name</literal> |
262 nginx variables object, read-only | 258 </para> |
263 </tag-desc> | 259 </tag-desc> |
264 | 260 |
265 <tag-name><literal>req.response</literal></tag-name> | 261 <tag-name><literal>r.httpVersion</literal></tag-name> |
266 <tag-desc> | 262 <tag-desc> |
267 the <link id="http_response">response</link> object (0.2.0), read-only | 263 HTTP version, read-only |
268 </tag-desc> | 264 </tag-desc> |
269 | 265 |
270 <tag-name><literal>req.log(<value>string</value>)</literal></tag-name> | 266 <tag-name><literal>r.log(<value>string</value>)</literal></tag-name> |
271 <tag-desc> | 267 <tag-desc> |
272 writes a <literal>string</literal> to the error log | 268 writes a <literal>string</literal> to the error log |
273 on the <literal>info</literal> level of logging | 269 on the <literal>info</literal> level of logging |
274 </tag-desc> | 270 </tag-desc> |
275 | 271 |
276 <tag-name><literal>req.warn(<value>string</value>)</literal></tag-name> | 272 <tag-name><literal>r.method</literal></tag-name> |
273 <tag-desc> | |
274 HTTP method, read-only | |
275 </tag-desc> | |
276 | |
277 <tag-name><literal>r.parent</literal></tag-name> | |
278 <tag-desc> | |
279 references the parent request object | |
280 </tag-desc> | |
281 | |
282 <tag-name><literal>r.remoteAddress</literal></tag-name> | |
283 <tag-desc> | |
284 client address, read-only | |
285 </tag-desc> | |
286 | |
287 <tag-name><literal>r.requestBody</literal></tag-name> | |
288 <tag-desc> | |
289 holds the request body, read-only | |
290 </tag-desc> | |
291 | |
292 <tag-name><literal>r.responseBody</literal></tag-name> | |
293 <tag-desc> | |
294 holds the <link id="subrequest">subrequest</link> response body, read-only | |
295 </tag-desc> | |
296 | |
297 <tag-name><literal>r.return(status[, string])</literal></tag-name> | |
298 <tag-desc> | |
299 sends the entire response | |
300 with the specified <literal>status</literal> to the client | |
301 <para> | |
302 It is possible to specify either a redirect URL | |
303 (for codes 301, 302, 303, 307, and 308) | |
304 or the response body text (for other codes) as the second argument | |
305 </para> | |
306 </tag-desc> | |
307 | |
308 <tag-name><literal>r.send(<value>string</value>)</literal></tag-name> | |
309 <tag-desc> | |
310 sends a part of the response body to the client | |
311 </tag-desc> | |
312 | |
313 <tag-name><literal>r.sendHeader()</literal></tag-name> | |
314 <tag-desc> | |
315 sends the HTTP headers to the client | |
316 </tag-desc> | |
317 | |
318 <tag-name><literal>r.status</literal></tag-name> | |
319 <tag-desc> | |
320 status, writable | |
321 </tag-desc> | |
322 | |
323 <tag-name><literal>r.variables{}</literal></tag-name> | |
324 <tag-desc> | |
325 nginx variables object, read-only | |
326 </tag-desc> | |
327 | |
328 <tag-name><literal>r.warn(<value>string</value>)</literal></tag-name> | |
277 <tag-desc> | 329 <tag-desc> |
278 writes a <literal>string</literal> to the error log | 330 writes a <literal>string</literal> to the error log |
279 on the <literal>warning</literal> level of logging (0.2.0) | 331 on the <literal>warning</literal> level of logging |
280 </tag-desc> | 332 </tag-desc> |
281 | 333 |
282 <tag-name><literal>req.error(<value>string</value>)</literal></tag-name> | 334 <tag-name><literal>r.uri</literal></tag-name> |
283 <tag-desc> | 335 <tag-desc> |
284 writes a <literal>string</literal> to the error log | 336 current URI, read-only |
285 on the <literal>error</literal> level of logging (0.2.0) | 337 </tag-desc> |
286 </tag-desc> | 338 |
287 | 339 <tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, |
288 <tag-name id="subrequest"><literal>req.subrequest(<value>uri</value>[, | |
289 <value>options</value>[, <value>callback</value>]])</literal></tag-name> | 340 <value>options</value>[, <value>callback</value>]])</literal></tag-name> |
290 <tag-desc> | 341 <tag-desc> |
291 creates a subrequest with the given <literal>uri</literal> and | 342 creates a subrequest with the given <literal>uri</literal> and |
292 <literal>options</literal>, and installs | 343 <literal>options</literal>, and installs |
293 an optional completion <literal>callback</literal> (0.2.0). | 344 an optional completion <literal>callback</literal>. |
294 | 345 |
295 <para> | 346 <para> |
296 If <literal>options</literal> is a string, then it | 347 If <literal>options</literal> is a string, then it |
297 holds the subrequest arguments string. | 348 holds the subrequest arguments string. |
298 Otherwise, <literal>options</literal> is expected to be | 349 Otherwise, <literal>options</literal> is expected to be |
311 | 362 |
312 <tag-name><literal>method</literal></tag-name> | 363 <tag-name><literal>method</literal></tag-name> |
313 <tag-desc> | 364 <tag-desc> |
314 HTTP method | 365 HTTP method |
315 </tag-desc> | 366 </tag-desc> |
367 | |
316 </list> | 368 </list> |
317 </para> | 369 </para> |
318 | 370 |
319 <para> | 371 <para> |
320 The completion <literal>callback</literal> | 372 The completion <literal>callback</literal> receives |
321 receives a <link id="http_reply_object">reply</link> object. | 373 a subrequest response object with methods and properties |
374 identical to the parent request object. | |
322 </para> | 375 </para> |
323 </tag-desc> | 376 </tag-desc> |
324 | 377 |
325 </list> | 378 </list> |
326 </para> | 379 </para> |
327 | 380 |
328 </section> | 381 </section> |
329 | 382 |
330 | |
331 <section id="http_response" name="Response"> | |
332 | |
333 <para> | |
334 <list type="tag"> | |
335 | |
336 <tag-name><literal>res.status</literal></tag-name> | |
337 <tag-desc> | |
338 response status, writable | |
339 </tag-desc> | |
340 | |
341 <tag-name><literal>res.headers{}</literal></tag-name> | |
342 <tag-desc> | |
343 response headers object | |
344 </tag-desc> | |
345 | |
346 <tag-name><literal>res.contentType</literal></tag-name> | |
347 <tag-desc> | |
348 the response <header>Content-Type</header> header field value, writable | |
349 </tag-desc> | |
350 | |
351 <tag-name><literal>res.contentLength</literal></tag-name> | |
352 <tag-desc> | |
353 the response <header>Content-Length</header> header field value, writable | |
354 </tag-desc> | |
355 | |
356 <tag-name><literal>res.sendHeader()</literal></tag-name> | |
357 <tag-desc> | |
358 sends the HTTP header to the client | |
359 </tag-desc> | |
360 | |
361 <tag-name><literal>res.send(<value>string</value>)</literal></tag-name> | |
362 <tag-desc> | |
363 sends a part of the response body to the client | |
364 </tag-desc> | |
365 | |
366 <tag-name><literal>res.finish()</literal></tag-name> | |
367 <tag-desc> | |
368 finishes sending a response to the client | |
369 </tag-desc> | |
370 | |
371 <tag-name><literal>res.return(status[, string])</literal></tag-name> | |
372 <tag-desc> | |
373 sends | |
374 the entire response with the specified <literal>status</literal> to the client | |
375 (0.2.0) | |
376 <para> | |
377 It is possible to specify either a redirect URL | |
378 (for codes 301, 302, 303, 307, and 308) | |
379 or the response body text (for other codes) as the second argument | |
380 </para> | |
381 </tag-desc> | |
382 | |
383 </list> | |
384 </para> | |
385 | |
386 </section> | |
387 | |
388 | |
389 <section id="http_reply" name="Reply"> | |
390 | |
391 <para> | |
392 <list type="tag"> | |
393 | |
394 <tag-name><literal>reply.uri</literal></tag-name> | |
395 <tag-desc> | |
396 current URI in a reply, read-only | |
397 </tag-desc> | |
398 | |
399 <tag-name><literal>reply.method</literal></tag-name> | |
400 <tag-desc> | |
401 reply method, read-only | |
402 </tag-desc> | |
403 | |
404 <tag-name><literal>reply.status</literal></tag-name> | |
405 <tag-desc> | |
406 reply status, writable | |
407 </tag-desc> | |
408 | |
409 <tag-name><literal>reply.contentType</literal></tag-name> | |
410 <tag-desc> | |
411 the response <header>Content-Type</header> header field value, writable | |
412 </tag-desc> | |
413 | |
414 <tag-name><literal>reply.contentLength</literal></tag-name> | |
415 <tag-desc> | |
416 the response <header>Content-Length</header> header field value, writable | |
417 </tag-desc> | |
418 | |
419 <tag-name><literal>reply.headers{}</literal></tag-name> | |
420 <tag-desc> | |
421 reply headers object, read-only | |
422 </tag-desc> | |
423 | |
424 </list> | |
425 </para> | |
426 | |
427 <para> | |
428 Additionally, the <literal>reply</literal> object has | |
429 the following properties: | |
430 | |
431 <list type="tag"> | |
432 | |
433 <tag-name><literal>reply.body</literal></tag-name> | |
434 <tag-desc> | |
435 holds the subrequest response body | |
436 </tag-desc> | |
437 | |
438 <tag-name><literal>reply.parent</literal></tag-name> | |
439 <tag-desc> | |
440 references the parent request object | |
441 </tag-desc> | |
442 | |
443 </list> | |
444 </para> | |
445 | |
446 </section> | |
447 | |
448 </section> | 383 </section> |
449 | 384 |
450 | 385 |
451 <section id="stream" name="Stream"> | 386 <section id="stream" name="Stream"> |
452 | 387 |
453 <para> | 388 <para> |
454 The <literal>stream</literal> objects are available only in the | 389 The <literal>stream</literal> object is available only in the |
455 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> | 390 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> |
456 module. | 391 module. |
457 </para> | 392 </para> |
458 | 393 |
459 | 394 |
520 </tag-desc> | 455 </tag-desc> |
521 | 456 |
522 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> | 457 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> |
523 <tag-desc> | 458 <tag-desc> |
524 writes a sent <literal>string</literal> to the error log | 459 writes a sent <literal>string</literal> to the error log |
525 on the <literal>warning</literal> level of logging (0.2.0) | 460 on the <literal>warning</literal> level of logging |
526 </tag-desc> | 461 </tag-desc> |
527 | 462 |
528 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name> | 463 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name> |
529 <tag-desc> | 464 <tag-desc> |
530 writes a sent <literal>string</literal> to the error log | 465 writes a sent <literal>string</literal> to the error log |
531 on the <literal>error</literal> level of logging (0.2.0) | 466 on the <literal>error</literal> level of logging |
532 </tag-desc> | 467 </tag-desc> |
533 | 468 |
534 </list> | 469 </list> |
535 </para> | 470 </para> |
536 | 471 |
553 </para> | 488 </para> |
554 | 489 |
555 <para> | 490 <para> |
556 The <path>urldecode.js</path> file: | 491 The <path>urldecode.js</path> file: |
557 <example> | 492 <example> |
558 function decoded_foo(req, res) { | 493 function decoded_foo(r) { |
559 return decodeURIComponent(req.args.foo); | 494 return decodeURIComponent(r.args.foo); |
560 } | 495 } |
561 </example> | 496 </example> |
562 </para> | 497 </para> |
563 | 498 |
564 </section> | 499 </section> |
580 </para> | 515 </para> |
581 | 516 |
582 <para> | 517 <para> |
583 The <path>urlencode.js</path> file: | 518 The <path>urlencode.js</path> file: |
584 <example> | 519 <example> |
585 function encoded_foo(req, res) { | 520 function encoded_foo(r) { |
586 return encodeURIComponent('foo & bar?'); | 521 return encodeURIComponent('foo & bar?'); |
587 } | 522 } |
588 </example> | 523 </example> |
589 </para> | 524 </para> |
590 | 525 |
612 </para> | 547 </para> |
613 | 548 |
614 <para> | 549 <para> |
615 The <path>fastresponse.js</path> file: | 550 The <path>fastresponse.js</path> file: |
616 <example> | 551 <example> |
617 function content(req, res) { | 552 function content(r) { |
618 var n = 0; | 553 var n = 0; |
619 | 554 |
620 function done(reply) { | 555 function done(res) { |
621 if (n++ == 0) { | 556 if (n++ == 0) { |
622 res.return(reply.status, reply.body); | 557 r.return(res.status, res.responseBody); |
623 } | 558 } |
624 } | 559 } |
625 | 560 |
626 req.subrequest('/foo', req.variables.args, done); | 561 r.subrequest('/foo', r.variables.args, done); |
627 req.subrequest('/bar', req.variables.args, done); | 562 r.subrequest('/bar', r.variables.args, done); |
628 } | 563 } |
629 </example> | 564 </example> |
630 </para> | 565 </para> |
631 | 566 |
632 </section> | 567 </section> |
654 var h = require('crypto').createHmac('sha256', key); | 589 var h = require('crypto').createHmac('sha256', key); |
655 | 590 |
656 return s + '.' + h.update(s).digest().toString('base64url'); | 591 return s + '.' + h.update(s).digest().toString('base64url'); |
657 } | 592 } |
658 | 593 |
659 function jwt(req, res) { | 594 function jwt(r) { |
660 var claims = { | 595 var claims = { |
661 "iss" : "nginx", | 596 "iss" : "nginx", |
662 "sub" : "alice", | 597 "sub" : "alice", |
663 "foo" : 123, | 598 "foo" : 123, |
664 "bar" : "qq", | 599 "bar" : "qq", |
697 </para> | 632 </para> |
698 | 633 |
699 <para> | 634 <para> |
700 The <path>subrequest.js</path> file: | 635 The <path>subrequest.js</path> file: |
701 <example> | 636 <example> |
702 function set_keyval(req, res) { | 637 function set_keyval(r) { |
703 req.subrequest('/api/3/http/keyvals/foo', | 638 r.subrequest('/api/3/http/keyvals/foo', |
704 { method: 'POST', | 639 { method: 'POST', |
705 body: JSON.stringify({ foo: 789, bar: "ss dd 00" })}, | 640 body: JSON.stringify({ foo: 789, bar: "ss dd 00" })}, |
706 | 641 |
707 function(reply) { | 642 function(res) { |
708 if (reply.status >= 300) { | 643 if (res.status >= 300) { |
709 res.return(reply.status, reply.body); | 644 r.return(res.status, res.responseBody); |
710 return; | 645 return; |
711 } | 646 } |
712 res.return(500); | 647 r.return(500); |
713 }); | 648 }); |
714 } | 649 } |
715 function version(req, res) { | 650 function version(r) { |
716 req.subrequest('/api/3/nginx', { method: 'GET' }, function(reply) { | 651 r.subrequest('/api/3/nginx', { method: 'GET' }, function(res) { |
717 if (reply.status != 200) { | 652 if (res.status != 200) { |
718 res.return(reply.status); | 653 r.return(res.status); |
719 return; | 654 return; |
720 } | 655 } |
721 | 656 |
722 var json = JSON.parse(reply.body); | 657 var json = JSON.parse(res.responseBody); |
723 res.return(200, json.version); | 658 r.return(200, json.version); |
724 }); | 659 }); |
725 } | 660 } |
726 </example> | 661 </example> |
727 </para> | 662 </para> |
728 | 663 |
752 </para> | 687 </para> |
753 | 688 |
754 <para> | 689 <para> |
755 The <path>hash.js</path> file: | 690 The <path>hash.js</path> file: |
756 <example> | 691 <example> |
757 function create_secure_link(req, res) { | 692 function create_secure_link(r) { |
758 return require('crypto').createHash('md5') | 693 return require('crypto').createHash('md5') |
759 .update(req.uri).update(" mykey") | 694 .update(r.uri).update(" mykey") |
760 .digest('base64url'); | 695 .digest('base64url'); |
761 } | 696 } |
762 </example> | 697 </example> |
763 </para> | 698 </para> |
764 | 699 |