Mercurial > hg > nginx-site

comparison xml/en/docs/njs/njs_api.xml @ 2237:5268c13196f2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented njs changes triggered by njs-0.2.4.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 13 Sep 2018 21:10:42 +0300
parents e029f4bc7ede
children 467aef18bf12
comparison
equal deleted inserted replaced
2236:9f0f4f5c1a30 2237:5268c13196f2
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="njs API" 9 <article name="njs API"
10 link="/en/docs/njs/njs_api.html" 10 link="/en/docs/njs/njs_api.html"
11 lang="en" 11 lang="en"
12 rev="6"> 12 rev="7">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="../njs_about.xml">njs</link> provides objects, methods and properties 17 <link doc="../njs_about.xml">njs</link> provides objects, methods and properties
1002 <list type="tag"> 1002 <list type="tag">
1003 <tag-name><literal>args</literal></tag-name> 1003 <tag-name><literal>args</literal></tag-name>
1004 <tag-desc> 1004 <tag-desc>
1005 arguments string 1005 arguments string
1006 </tag-desc> 1006 </tag-desc>
1007
1008 <tag-name><literal>body</literal></tag-name> 1007 <tag-name><literal>body</literal></tag-name>
1009 <tag-desc> 1008 <tag-desc>
1010 request body 1009 request body
1011 </tag-desc> 1010 </tag-desc>
1012 1011
1036 <para> 1035 <para>
1037 The stream session object is available only in the 1036 The stream session object is available only in the
1038 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> 1037 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>
1039 module. 1038 module.
1040 All string properties of the object are <link id="string">byte strings</link>. 1039 All string properties of the object are <link id="string">byte strings</link>.
1041 1040 </para>
1041
1042 <para>
1043 <note>
1044 Prior to njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1045 the stream session object had some properties which are currently
1046 <link id="stream_obsolete">removed</link>.
1047 </note>
1048 </para>
1049
1050 <para>
1042 <list type="tag"> 1051 <list type="tag">
1043 1052
1053 <tag-name id="s_allow"><literal>s.allow()</literal></tag-name>
1054 <tag-desc>
1055 successfully finalizes the phase handler
1056 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>)
1057 </tag-desc>
1058
1059 <tag-name id="s_decline"><literal>s.decline()</literal></tag-name>
1060 <tag-desc>
1061 finalizes the phase handler and passes control to the next handler
1062 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>)
1063 </tag-desc>
1064
1065 <tag-name id="s_deny"><literal>s.deny()</literal></tag-name>
1066 <tag-desc>
1067 finalizes the phase handler with the access error code
1068 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>)
1069 </tag-desc>
1070
1071 <tag-name id="s_done"><literal>s.done</literal>(<value>[code]</value>)</tag-name>
1072 <tag-desc>
1073 successfully finalizes the current phase handler
1074 or finalizes it with the specified numeric code
1075 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>).
1076 </tag-desc>
1077
1078 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name>
1079 <tag-desc>
1080 writes a sent <literal>string</literal> to the error log
1081 on the <literal>error</literal> level of logging
1082 </tag-desc>
1083
1084 <tag-name><literal>s.log(<value>string</value>)</literal></tag-name>
1085 <tag-desc>
1086 writes a sent <value>string</value> to the error log
1087 on the <literal>info</literal> level of logging
1088 </tag-desc>
1089
1090 <tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name>
1091 <tag-desc>
1092 unregisters the callback set by the <link id="s_on">s.on()</link> method
1093 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>)
1094 </tag-desc>
1095
1096 <tag-name id="s_on"><literal>s.on(<value>event</value>,
1097 <value>callback</value>)</literal></tag-name>
1098 <tag-desc>
1099 registers a <literal>callback</literal> for the specified <literal>event</literal>
1100 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>).
1101
1102 <para>
1103 An <literal>event</literal> may be one of the following strings:
1104 <list type="tag">
1105 <tag-name><literal>upload</literal></tag-name>
1106 <tag-desc>
1107 new data from a client
1108 </tag-desc>
1109
1110 <tag-name><literal>download</literal></tag-name>
1111 <tag-desc>
1112 new data to a client
1113 </tag-desc>
1114
1115 </list>
1116 </para>
1117
1118 <para>
1119 The completion callback has the following prototype:
1120 <literal>callback(data, flags)</literal>, where
1121 <literal>data</literal> is string,
1122 <literal>flags</literal> is an object
1123 with the following properties:
1124 <list type="tag">
1125 <tag-name id="s_on_callback_last"><literal>last</literal></tag-name>
1126 <tag-desc>
1127 a boolean value, true if data is a last buffer.
1128 </tag-desc>
1129
1130 </list>
1131 </para>
1132 </tag-desc>
1133
1044 <tag-name><literal>s.remoteAddress</literal></tag-name> 1134 <tag-name><literal>s.remoteAddress</literal></tag-name>
1045 <tag-desc> 1135 <tag-desc>
1046 client address, read-only 1136 client address, read-only
1047 </tag-desc> 1137 </tag-desc>
1048 1138
1139 <tag-name id="s_send"><literal>s.send(<value>data</value>[,
1140 <value>options</value>])</literal></tag-name>
1141 <tag-desc>
1142 sends the data to the client
1143 (<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>).
1144 The <literal>options</literal> is an object used
1145 to override nginx buffer flags derived from an incoming data chunk buffer.
1146 The flags can be overriden with the following flags:
1147 <para>
1148 <list type="tag">
1149
1150 <tag-name><literal>last</literal></tag-name>
1151 <tag-desc>
1152 boolean, true if the buffer is the last buffer
1153 </tag-desc>
1154
1155 <tag-name><literal>flush</literal></tag-name>
1156 <tag-desc>
1157 boolean, true if the buffer should have the <literal>flush</literal> flag
1158 </tag-desc>
1159 </list>
1160 </para>
1161 The method can be called multiple times per callback invocation.
1162 </tag-desc>
1163
1164 <tag-name><literal>s.variables{}</literal></tag-name>
1165 <tag-desc>
1166 nginx variables object, read-only
1167 </tag-desc>
1168
1169 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name>
1170 <tag-desc>
1171 writes a sent <literal>string</literal> to the error log
1172 on the <literal>warning</literal> level of logging
1173 </tag-desc>
1174
1175 </list>
1176 </para>
1177
1178
1179 <section id="stream_obsolete" name="Obsolete properties">
1180
1181 <para>
1182 These properties have been removed
1183 in njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>
1184 and are not backward compatible with the existing njs code.
1185 </para>
1186
1187 <para>
1188 <list type="tag">
1189
1190 <tag-name id="s_abort"><literal>s.ABORT</literal></tag-name>
1191 <tag-desc>
1192 the <literal>ABORT</literal> return code
1193 <note>
1194 Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1195 the <link id="s_deny">s.deny()</link> method should be used instead.
1196 </note>
1197 </tag-desc>
1198
1199 <tag-name><literal>s.AGAIN</literal></tag-name>
1200 <tag-desc>
1201 the <literal>AGAIN</literal> return code
1202 <note>
1203 Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1204 the corresponding behavior is achieved if no
1205 <link id="s_allow">s.allow()</link>,
1206 <link id="s_deny">s.deny()</link>,
1207 <link id="s_decline">s.decline()</link>,
1208 <link id="s_done">s.done()</link>
1209 is invoked and a callback is registered.
1210 </note>
1211 </tag-desc>
1212
1213 <tag-name id="s_buffer"><literal>s.buffer</literal></tag-name>
1214 <tag-desc>
1215 the current buffer, writable
1216 <note>
1217 Starting from <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1218 the <link id="s_send">s.send()</link> method should be used for writing.
1219 For reading, the current buffer is available as the first argument of the
1220 <literal>event</literal> callback.
1221 </note>
1222 </tag-desc>
1223
1224 <tag-name><literal>s.DECLINED</literal></tag-name>
1225 <tag-desc>
1226 the <literal>DECLINED</literal> return code
1227 <note>
1228 Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1229 the <link id="s_decline">s.decline()</link> method should be used instead.
1230 </note>
1231 </tag-desc>
1232
1049 <tag-name><literal>s.eof</literal></tag-name> 1233 <tag-name><literal>s.eof</literal></tag-name>
1050 <tag-desc> 1234 <tag-desc>
1051 a boolean read-only property, true if the current buffer is the last buffer 1235 a boolean read-only property, true if the current buffer is the last buffer
1236 <note>
1237 Starting from <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1238 the <link id="s_on_callback_last">flags.last</link> property
1239 should be used instead.
1240 </note>
1241 </tag-desc>
1242
1243 <tag-name><literal>s.ERROR</literal></tag-name>
1244 <tag-desc>
1245 the <literal>ERROR</literal> return code
1246 <note>
1247 Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1248 an appropriate exception can be thrown to report an error.
1249 </note>
1052 </tag-desc> 1250 </tag-desc>
1053 1251
1054 <tag-name><literal>s.fromUpstream</literal></tag-name> 1252 <tag-name><literal>s.fromUpstream</literal></tag-name>
1055 <tag-desc> 1253 <tag-desc>
1056 a boolean read-only property, 1254 a boolean read-only property,
1057 true if the current buffer is from the upstream server to the client 1255 true if the current buffer is from the upstream server to the client
1058 </tag-desc> 1256 <note>
1059 1257 Starting from <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1060 <tag-name><literal>s.buffer</literal></tag-name> 1258 a corresponding <link id="s_on">event</link>
1061 <tag-desc> 1259 (<literal>upload</literal> or <literal>download</literal>)
1062 the current buffer, writable 1260 should be used to handle data to or from client.
1063 </tag-desc> 1261 </note>
1064 1262 </tag-desc>
1065 <tag-name><literal>s.variables{}</literal></tag-name> 1263
1066 <tag-desc> 1264 <tag-name id="s_ok"><literal>s.OK</literal></tag-name>
1067 nginx variables object, read-only
1068 </tag-desc>
1069
1070 <tag-name><literal>s.OK</literal></tag-name>
1071 <tag-desc> 1265 <tag-desc>
1072 the <literal>OK</literal> return code 1266 the <literal>OK</literal> return code
1073 </tag-desc> 1267 <note>
1074 1268 Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1075 <tag-name><literal>s.DECLINED</literal></tag-name> 1269 the <link id="s_allow">s.allow()</link> method should be used instead.
1076 <tag-desc> 1270 </note>
1077 the <literal>DECLINED</literal> return code 1271 </tag-desc>
1078 </tag-desc> 1272
1079 1273 </list>
1080 <tag-name><literal>s.AGAIN</literal></tag-name> 1274 </para>
1081 <tag-desc> 1275
1082 the <literal>AGAIN</literal> return code 1276 </section>
1083 </tag-desc>
1084
1085 <tag-name><literal>s.ERROR</literal></tag-name>
1086 <tag-desc>
1087 the <literal>ERROR</literal> return code
1088 </tag-desc>
1089
1090 <tag-name><literal>s.ABORT</literal></tag-name>
1091 <tag-desc>
1092 the <literal>ABORT</literal> return code
1093 </tag-desc>
1094
1095 <tag-name><literal>s.log(<value>string</value>)</literal></tag-name>
1096 <tag-desc>
1097 writes a sent <value>string</value> to the error log
1098 on the <literal>info</literal> level of logging
1099 </tag-desc>
1100
1101 <tag-name><literal>s.warn(<value>string</value>)</literal></tag-name>
1102 <tag-desc>
1103 writes a sent <literal>string</literal> to the error log
1104 on the <literal>warning</literal> level of logging
1105 </tag-desc>
1106
1107 <tag-name><literal>s.error(<value>string</value>)</literal></tag-name>
1108 <tag-desc>
1109 writes a sent <literal>string</literal> to the error log
1110 on the <literal>error</literal> level of logging
1111 </tag-desc>
1112
1113 </list>
1114 </para>
1115 1277
1116 </section> 1278 </section>
1117 1279
1118 1280
1119 <section id="example" name="Examples"> 1281 <section id="example" name="Examples">
1368 </example> 1530 </example>
1369 </para> 1531 </para>
1370 1532
1371 </section> 1533 </section>
1372 1534
1535
1536 <section id="example_legacy" name="Legacy Examples">
1537
1538
1539 <section id="example_legacy_stream" name="Stream Example">
1540
1541 <para>
1542 Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>,
1543 stream configuration
1544 <link doc="../stream/ngx_stream_js_module.xml" id="example">example</link>
1545 has been changed.
1546 For njs <link doc="../njs/njs_changes.xml" id="njs-0.2.3">0.2.3</link>
1547 and earlier, use this configuration example:
1548 <example>
1549 load_module modules/ngx_stream_js_module.so;
1550 ...
1551
1552 stream {
1553 js_include stream.js;
1554
1555 js_set $foo foo;
1556 js_set $bar bar;
1557
1558 server {
1559 listen 12345;
1560
1561 js_preread qux;
1562 return $foo;
1563 }
1564
1565 server {
1566 listen 12346;
1567
1568 js_access xyz;
1569 proxy_pass 127.0.0.1:8000;
1570 js_filter baz;
1571 }
1572 }
1573
1574 http {
1575 server {
1576 listen 8000;
1577 location / {
1578 return 200 $http_foo\n;
1579 }
1580 }
1581 }
1582 </example>
1583 </para>
1584
1585 <para>
1586 The <path>stream.js</path> file:
1587 <example>
1588 var req = '';
1589 var matched = 0;
1590 var line = '';
1591
1592 function qux(s) {
1593 var n = s.buffer.indexOf('\n');
1594 if (n == -1) {
1595 return s.AGAIN;
1596 }
1597
1598 line = s.buffer.substr(0, n);
1599 }
1600
1601 function foo(s) {
1602 return line;
1603 }
1604
1605 function bar(s) {
1606 var v = s.variables;
1607 s.log("hello from bar() handler!");
1608 return "foo-var" + v.remote_port + "; pid=" + v.pid;
1609 }
1610
1611 // The filter processes one buffer per call.
1612 // The buffer is available in s.buffer both for
1613 // reading and writing. Called for both directions.
1614
1615 function baz(s) {
1616 if (s.fromUpstream || matched) {
1617 return;
1618 }
1619
1620 // Disable certain addresses.
1621
1622 if (s.remoteAddress.match('^192.*')) {
1623 return s.ERROR;
1624 }
1625
1626 // Read HTTP request line.
1627 // Collect bytes in 'req' until request
1628 // line is read. Clear current buffer to
1629 // disable output.
1630
1631 req = req + s.buffer;
1632 s.buffer = '';
1633
1634 var n = req.search('\n');
1635
1636 if (n != -1) {
1637 // Inject a new HTTP header.
1638 var rest = req.substr(n + 1);
1639 req = req.substr(0, n + 1);
1640
1641 var addr = s.remoteAddress;
1642
1643 s.log('req:' + req);
1644 s.log('rest:' + rest);
1645
1646 // Output the result and skip further
1647 // processing.
1648
1649 s.buffer = req + 'Foo: addr_' + addr + '\r\n' + rest;
1650 matched = 1;
1651 }
1652 }
1653
1654 function xyz(s) {
1655 if (s.remoteAddress.match('^192.*')) {
1656 return s.ABORT;
1657 }
1658 }
1659 </example>
1660 </para>
1661
1662 </section>
1663
1664 </section>
1665
1373 </section> 1666 </section>
1374 1667
1375 </article> 1668 </article>