Mercurial > hg > nginx-site

comparison xml/en/docs/njs/njs_api.xml @ 2182:7865ca0da0ab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 &amp; bar?'); 521 return encodeURIComponent('foo &amp; 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