Mercurial > hg > nginx-site
comparison xml/en/docs/njs/njs_api.xml @ 2237:5268c13196f2
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> |