Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2933:386ba17fac23

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented Request, Response, Headers in Fetch API.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 02 Feb 2023 14:06:03 +0000
parents 16613b91c584
children 41870b949ac9
comparison
equal deleted inserted replaced
2932:16613b91c584 2933:386ba17fac23
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="96"> 12 rev="97">
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
909 </para> 909 </para>
910 910
911 </section> 911 </section>
912 912
913 913
914 <section id="headers" name="Headers">
915
916 <para>
917 The <literal>Headers</literal> interface of the
918 <link id="ngx_fetch"><literal>Fetch API</literal></link>
919 is available since <link doc="changes.xml" id="njs0.5.1">0.5.1</link>.
920 </para>
921
922 <para>
923 A new <literal>Headers</literal> object can be created using
924 the <literal>Headers()</literal> constructor
925 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>)
926 with the following properties and methods:
927
928 <list type="tag">
929
930 <tag-name id="headers_append"><literal>append()</literal></tag-name>
931 <tag-desc>
932 Appends a new value into an existing header in the
933 <literal>Headers</literal> object,
934 or adds the header if it does not already exist
935 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
936 </tag-desc>
937
938 <tag-name id="headers_delete"><literal>delete()</literal></tag-name>
939 <tag-desc>
940 Deletes a header from the <literal>Headers</literal> object
941 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
942 </tag-desc>
943
944 <tag-name id="headers_get"><literal>get()</literal></tag-name>
945 <tag-desc>
946 Returns a string containing the values of all headers with the specified name
947 separated by a comma and a space.
948 </tag-desc>
949
950 <tag-name id="response_headers_getall"><literal>getAll(<value>name</value>)</literal></tag-name>
951 <tag-desc>
952 Returns an array containing the values of all headers with the specified name.
953 </tag-desc>
954
955 <tag-name id="headers_foreach"><literal>forEach()</literal></tag-name>
956 <tag-desc>
957 Executes a provided function once for each key/value pair
958 in the <literal>Headers</literal> object
959 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
960 </tag-desc>
961
962 <tag-name id="headers_has"><literal>has()</literal></tag-name>
963 <tag-desc>
964 Returns a boolean value
965 indicating whether a header with the specified name exists.
966 </tag-desc>
967
968 <tag-name id="headers_set"><literal>set()</literal></tag-name>
969 <tag-desc>
970 Sets a new value for an existing header inside
971 the <literal>Headers</literal> object,
972 or adds the header if it does not already exist
973 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
974 </tag-desc>
975
976 </list>
977 </para>
978
979 </section>
980
981
982 <section id="request" name="Request">
983
984 <para>
985 The <literal>Request</literal> interface of the
986 <link id="ngx_fetch"><literal>Fetch API</literal></link>
987 is available since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>.
988 </para>
989
990 <para>
991 A new <literal>Request</literal> object can be created using
992 the <literal>Request()</literal> constructor
993 with the following properties and methods:
994
995 <list type="tag">
996
997 <tag-name id="request_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
998 <tag-desc>
999 Returns a <literal>Promise</literal> that resolves with
1000 an <literal>ArrayBuffer</literal>.
1001 </tag-desc>
1002
1003 <tag-name id="request_bodyused"><literal>bodyUsed</literal></tag-name>
1004 <tag-desc>
1005 A boolean value, <literal>true</literal>
1006 if the body was used in the request.
1007 </tag-desc>
1008
1009 <tag-name id="request_cache"><literal>cache</literal></tag-name>
1010 <tag-desc>
1011 Contains the cache mode of the request.
1012 </tag-desc>
1013
1014 <tag-name id="request_credentials"><literal>credentials</literal></tag-name>
1015 <tag-desc>
1016 Contains the credentials of the request,
1017 by default is <literal>same-origin</literal>.
1018 </tag-desc>
1019
1020 <tag-name id="request_headers"><literal>headers</literal></tag-name>
1021 <tag-desc>
1022 The <link id="headers"><literal>Headers</literal></link> read-only object
1023 associated with the
1024 <link id="request"><literal>Request</literal></link>.
1025 </tag-desc>
1026
1027 <tag-name id="request_json"><literal>json()</literal></tag-name>
1028 <tag-desc>
1029 Returns a <literal>Promise</literal> that resolves with
1030 the result of parsing the request body as JSON.
1031 </tag-desc>
1032
1033 <tag-name id="request_method"><literal>method</literal></tag-name>
1034 <tag-desc>
1035 Contains the request method.
1036 </tag-desc>
1037
1038 <tag-name id="request_mode"><literal>mode</literal></tag-name>
1039 <tag-desc>
1040 Contains the mode of the request.
1041 </tag-desc>
1042
1043 <tag-name id="request_text"><literal>text()</literal></tag-name>
1044 <tag-desc>
1045 Returns a <literal>Promise</literal> that resolves with a
1046 string representation of the request body.
1047 </tag-desc>
1048
1049 <tag-name id="request_url"><literal>url</literal></tag-name>
1050 <tag-desc>
1051 Contains the URL of the request.
1052 </tag-desc>
1053
1054 </list>
1055 </para>
1056
1057 </section>
1058
1059
914 <section id="response" name="Response"> 1060 <section id="response" name="Response">
915 1061
916 <para> 1062 <para>
917 The <literal>Response</literal> interface is available since 1063 The <literal>Response</literal> interface is available since
918 <link doc="changes.xml" id="njs0.5.1">0.5.1</link>. 1064 <link doc="changes.xml" id="njs0.5.1">0.5.1</link>.
1065 </para>
1066
1067 <para>
1068 A new <literal>Response</literal> object can be created using
1069 the <literal>Response()</literal> constructor
1070 (since <link doc="changes.xml" id="njs0.7.10">0.7.10</link>)
1071 with the following properties and methods:
919 1072
920 <list type="tag"> 1073 <list type="tag">
921 1074
922 <tag-name id="response_arraybuffer"><literal>arrayBuffer()</literal></tag-name> 1075 <tag-name id="response_arraybuffer"><literal>arrayBuffer()</literal></tag-name>
923 <tag-desc> 1076 <tag-desc>
932 if the body was read. 1085 if the body was read.
933 </tag-desc> 1086 </tag-desc>
934 1087
935 <tag-name id="response_headers"><literal>headers</literal></tag-name> 1088 <tag-name id="response_headers"><literal>headers</literal></tag-name>
936 <tag-desc> 1089 <tag-desc>
937 The <literal>Headers</literal> read-only object associated with the 1090 The <link id="headers"><literal>Headers</literal></link> read-only object
938 <link id="response"><literal>Response</literal></link>: 1091 associated with the
939 1092 <link id="response"><literal>Response</literal></link>.
940 <list type="tag">
941
942 <tag-name id="headers_get"><literal>get(<value>name</value>)</literal></tag-name>
943 <tag-desc>
944 returns a string containing the values of all headers with the specified name
945 separated by a comma and a space
946 </tag-desc>
947
948 <tag-name id="headers_getall"><literal>getAll(<value>name</value>)</literal></tag-name>
949 <tag-desc>
950 returns an array containing the values of all headers with the specified name
951 </tag-desc>
952
953 <tag-name id="headers_has"><literal>has(<value>name</value>)</literal></tag-name>
954 <tag-desc>
955 returns a boolean value
956 indicating whether a header with the specified name exists
957 </tag-desc>
958
959 </list>
960 </tag-desc> 1093 </tag-desc>
961 1094
962 <tag-name id="response_json"><literal>json()</literal></tag-name> 1095 <tag-name id="response_json"><literal>json()</literal></tag-name>
963 <tag-desc> 1096 <tag-desc>
964 Takes a <literal>Response</literal> stream and reads it to completion. 1097 Takes a <literal>Response</literal> stream and reads it to completion.
1023 <link doc="../configure.xml" id="prefix">nginx configuration prefix</link>&mdash; 1156 <link doc="../configure.xml" id="prefix">nginx configuration prefix</link>&mdash;
1024 the directory where nginx is currently looking for configuration 1157 the directory where nginx is currently looking for configuration
1025 (<link doc="changes.xml" id="njs0.7.8">0.7.8</link>) 1158 (<link doc="changes.xml" id="njs0.7.8">0.7.8</link>)
1026 </tag-desc> 1159 </tag-desc>
1027 1160
1028 <tag-name id="ngx_fetch"><literal>ngx.fetch(<value>url</value>, 1161 <tag-name id="ngx_fetch"><literal>ngx.fetch(<value>resource</value>,
1029 [<value>options</value>])</literal></tag-name> 1162 [<value>options</value>])</literal></tag-name>
1030 <tag-desc> 1163 <tag-desc>
1031 Makes a request to fetch an URL 1164 Makes a request to fetch a <value>resource</value>
1032 (<link doc="changes.xml" id="njs0.5.1">0.5.1</link>), 1165 (<link doc="changes.xml" id="njs0.5.1">0.5.1</link>), which can be an
1033 returns a <literal>Promise</literal> that resolves with 1166 URL or the <link id="request"><literal>Request</literal></link> object
1167 (<link doc="changes.xml" id="njs0.7.10">0.7.10</link>).
1168 Returns a <literal>Promise</literal> that resolves with
1034 the <link id="response"><literal>Response</literal></link> object. 1169 the <link id="response"><literal>Response</literal></link> object.
1035 Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>, 1170 Since <link doc="changes.xml" id="njs0.7.0">0.7.0</link>,
1036 the <literal>https://</literal> scheme is supported, 1171 the <literal>https://</literal> scheme is supported,
1037 redirects are not handled. 1172 redirects are not handled.
1038 <para> 1173 <para>
1052 by default is <literal>4096</literal> 1187 by default is <literal>4096</literal>
1053 </tag-desc> 1188 </tag-desc>
1054 1189
1055 <tag-name id="fetch_headers"><literal>headers</literal></tag-name> 1190 <tag-name id="fetch_headers"><literal>headers</literal></tag-name>
1056 <tag-desc> 1191 <tag-desc>
1057 request headers object 1192 request <link id="headers">headers</link> object
1058 </tag-desc> 1193 </tag-desc>
1059 1194
1060 <tag-name id="fetch_get"><literal>max_response_body_size</literal></tag-name> 1195 <tag-name id="fetch_get"><literal>max_response_body_size</literal></tag-name>
1061 <tag-desc> 1196 <tag-desc>
1062 the maximum size of the response body in bytes, 1197 the maximum size of the response body in bytes,