Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2653:9fc25ea7a92c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented ngx.fetch and Response interface in njs.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 04 Feb 2021 12:49:12 +0000
parents 0085d9f7dc3f
children a33d8f0f48b2
comparison
equal deleted inserted replaced
2652:eb508d8c1c31 2653:9fc25ea7a92c
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="60"> 12 rev="61">
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
578 </para> 578 </para>
579 579
580 </section> 580 </section>
581 581
582 582
583 <section id="response" name="Response">
584
585 <para>
586 The <literal>Response</literal> interface is available since
587 <link doc="changes.xml" id="njs0.5.1">0.5.1</link>.
588
589 <list type="tag">
590
591 <tag-name id="response_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
592 <tag-desc>
593 Takes a <literal>Response</literal> stream and reads it to completion.
594 Returns a <literal>Promise</literal> that resolves with
595 an <literal>ArrayBuffer</literal>.
596 </tag-desc>
597
598 <tag-name id="response_bodyused"><literal>bodyUsed</literal></tag-name>
599 <tag-desc>
600 A boolean value, <literal>true</literal>
601 if the body was read.
602 </tag-desc>
603
604 <tag-name id="response_headers"><literal>headers</literal></tag-name>
605 <tag-desc>
606 The <literal>Headers</literal> read-only object associated with the
607 <link id="global_response"><literal>Response</literal></link>:
608
609 <list type="tag">
610
611 <tag-name id="headers_get"><literal>get(<value>name</value>)</literal></tag-name>
612 <tag-desc>
613 returns a string containing the values of all headers with the specified name
614 separated by a comma and a space
615 </tag-desc>
616
617 <tag-name id="headers_getall"><literal>getAll(<value>name</value>)</literal></tag-name>
618 <tag-desc>
619 returns an array containing the values of all headers with the specified name
620 </tag-desc>
621
622 <tag-name id="headers_has"><literal>has(<value>name</value>)</literal></tag-name>
623 <tag-desc>
624 returns a boolean value
625 indicating whether a header with the specified name exists
626 </tag-desc>
627
628 </list>
629 </tag-desc>
630
631 <tag-name id="response_json"><literal>json()</literal></tag-name>
632 <tag-desc>
633 Takes a <literal>Response</literal> stream and reads it to completion.
634 Returns a <literal>Promise</literal> that resolves with
635 the result of parsing the body text as JSON.
636 </tag-desc>
637
638 <tag-name id="response_ok"><literal>ok</literal></tag-name>
639 <tag-desc>
640 A boolean value, <literal>true</literal>
641 if the response was successful (status codes between 200–299).
642 </tag-desc>
643
644 <tag-name id="response_redirect"><literal>redirected</literal></tag-name>
645 <tag-desc>
646 A boolean value, <literal>true</literal>
647 if the response is the result of a redirect.
648 </tag-desc>
649
650 <tag-name id="response_status"><literal>status</literal></tag-name>
651 <tag-desc>
652 The status code of the response.
653 </tag-desc>
654
655 <tag-name id="response_statustext"><literal>statusText</literal></tag-name>
656 <tag-desc>
657 The status message corresponding to the status code.
658 </tag-desc>
659
660 <tag-name id="response_text"><literal>text()</literal></tag-name>
661 <tag-desc>
662 Takes a <literal>Response</literal> stream and reads it to completion.
663 Returns a <literal>Promise</literal> that resolves with a string.
664 </tag-desc>
665
666 <tag-name id="response_type"><literal>type</literal></tag-name>
667 <tag-desc>
668 The type of the response.
669 </tag-desc>
670
671 <tag-name id="response_url"><literal>url</literal></tag-name>
672 <tag-desc>
673 The URL of the response.
674 </tag-desc>
675
676 </list>
677 </para>
678
679 </section>
680
681
583 <section id="ngx" name="ngx"> 682 <section id="ngx" name="ngx">
584 683
585 <para> 684 <para>
586 The <literal>ngx</literal> global object is available 685 The <literal>ngx</literal> global object is available
587 since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>. 686 since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>.
588 <list type="tag"> 687 <list type="tag">
688
689 <tag-name id="ngx_fetch"><literal>ngx.fetch(<value>url</value>,
690 [<value>options</value>])</literal></tag-name>
691 <tag-desc>
692 Makes a request to fetch an URL
693 (<link doc="changes.xml" id="njs0.5.1">0.5.1</link>),
694 returns a <literal>Promise</literal> that resolves with
695 the <link id="global_response"><literal>Response</literal></link> object.
696 Only the <literal>http://</literal> scheme is supported,
697 redirects are not handled.
698 <para>
699 The <literal>options</literal> parameter is expected to be an object
700 with the following keys:
701 <list type="tag">
702
703 <tag-name id="fetch_body"><literal>body</literal></tag-name>
704 <tag-desc>
705 request body,
706 by default is empty
707 </tag-desc>
708
709 <tag-name id="fetch_buffer_size"><literal>buffer_size</literal></tag-name>
710 <tag-desc>
711 the buffer size for reading the response,
712 by default is <literal>4096</literal>
713 </tag-desc>
714
715 <tag-name id="fetch_headers"><literal>headers</literal></tag-name>
716 <tag-desc>
717 request headers object
718 </tag-desc>
719
720 <tag-name id="fetch_get"><literal>max_response_body_size</literal></tag-name>
721 <tag-desc>
722 the maximum size of the response body in bytes,
723 by default is <literal>32768</literal>
724 </tag-desc>
725
726 <tag-name id="fetch_method"><literal>method</literal></tag-name>
727 <tag-desc>
728 HTTP method,
729 by default the <literal>GET</literal> method is used
730 </tag-desc>
731
732 </list>
733 Example:
734 <example>
735 ngx.fetch('http://nginx.org/')
736 .then(reply => reply.text())
737 .then(body => r.return(200, body))
738 .catch(e => r.return(501, e.message))
739 </example>
740 </para>
741 </tag-desc>
589 742
590 <tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>, 743 <tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>,
591 <value>message</value>)</tag-name> 744 <value>message</value>)</tag-name>
592 <tag-desc> 745 <tag-desc>
593 Writes a message to the error log with the specified level of logging. 746 Writes a message to the error log with the specified level of logging.
596 The following log levels can be specified: 749 The following log levels can be specified:
597 <literal>ngx.INFO</literal>, 750 <literal>ngx.INFO</literal>,
598 <literal>ngx.WARN</literal>, and 751 <literal>ngx.WARN</literal>, and
599 <literal>ngx.ERR</literal>. 752 <literal>ngx.ERR</literal>.
600 </tag-desc> 753 </tag-desc>
754
601 </list> 755 </list>
602 </para> 756 </para>
603 757
604 </section> 758 </section>
605 759