Mercurial > hg > nginx-site
changeset 1840:15632fc2d548
Documented http and stream nginScript modules.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 18 Nov 2016 17:51:14 +0300 |
parents | 4035f9146bbf |
children | 7ce8bc5521b8 |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_js_module.xml |
diffstat | 4 files changed, 610 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -59,6 +59,7 @@ REFS = \ http/ngx_http_hls_module \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \ + http/ngx_http_js_module \ http/ngx_http_limit_conn_module \ http/ngx_http_limit_req_module \ http/ngx_http_log_module \ @@ -99,6 +100,7 @@ REFS = \ stream/ngx_stream_core_module \ stream/ngx_stream_geo_module \ stream/ngx_stream_geoip_module \ + stream/ngx_stream_js_module \ stream/ngx_stream_limit_conn_module \ stream/ngx_stream_log_module \ stream/ngx_stream_map_module \
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_js_module.xml @@ -0,0 +1,277 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_js_module" + link="/en/docs/http/ngx_http_js_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_js_module</literal> module is used to implement +location and variable handlers in JavaScript. +</para> + +<para> +This module is not built by default, it should be compiled with +nginx JavaScript module using the +<literal>--add_module</literal> configuration parameter: +<example> +./configure --add-module=<value>path-to-njs</value>/nginx +</example> +The <link url="http://hg.nginx.org/njs">repository</link> +with nginx JavaScript module can be cloned with the following command +(requires <link url="https://www.mercurial-scm.org">Mercurial</link> client): +<example> +hg clone http://hg.nginx.org/njs +</example> +This module can also be built as +<link doc="../ngx_core_module.xml" id="load_module">dynamic</link>: +<example> +./configure --add-dynamic_module=<value>path-to-njs</value>/nginx +</example> +</para> + +</section> + + +<section id="issues" name="Known Issues"> + +<para> +The module is experimental, caveat emptor applies. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +js_include http.js; + +server { + listen 8000; + + location / { + js_set $foo foo; + add_header X-Foo $foo; + js_content baz; + } + + location /summary { + js_set $summary summary; + return 200 $summary; + } +} +</example> +</para> + +<para> +The <path>http.js</path> file: +<example> +function foo(req, res) { + req.log("hello from foo() handler"); + return "foo"; +} + +function summary(req, res) { + var a, s, h; + + s = "JS summary\n\n"; + + s += "Method: " + req.method + "\n"; + s += "HTTP version: " + req.httpVersion + "\n"; + s += "Host: " + req.headers.host + "\n"; + s += "Remote Address: " + req.remoteAddress + "\n"; + s += "URI: " + req.uri + "\n"; + + s += "Headers:\n"; + for (h in req.headers) { + s += " header '" + h + "' is '" + req.headers[h] + "'\n"; + } + + s += "Args:\n"; + for (a in req.args) { + s += " arg '" + a + "' is '" + req.args[a] + "'\n"; + } + + return s; +} + +function baz(req, res) { + res.headers.foo = 1234; + res.status = 200; + res.contentType = "text/plain; charset=utf-8"; + res.contentLength = 15; + res.sendHeader(); + res.send("nginx"); + res.send("java"); + res.send("script"); + + res.finish(); +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="js_include"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies a file that implements location and variable handlers in JavaScript. +</para> + +</directive> + + +<directive name="js_content"> +<syntax><value>function</value></syntax> +<default/> +<context>location</context> +<context>limit_except</context> + +<para> +Sets a JavaScript function as a location content handler. +</para> + +</directive> + + +<directive name="js_set"> +<syntax> +<value>$variable</value> <value>function</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets a JavaScript function for the specified variable. +</para> + +</directive> + +</section> + + +<section id="arguments" name="Request and Response Arguments"> +<para> +Each HTTP JavaScript handler receives two arguments, request and response. +</para> + +<para> +The request object has the following properties: +<list type="tag"> + +<tag-name><literal>uri</literal></tag-name> +<tag-desc> +current URI in a request, read-only +</tag-desc> + +<tag-name><literal>method</literal></tag-name> +<tag-desc> +request method, read-only +</tag-desc> + +<tag-name><literal>httpVersion</literal></tag-name> +<tag-desc> +HTTP version, read-only +</tag-desc> + +<tag-name><literal>remoteAddress</literal></tag-name> +<tag-desc> +client address, read-only +</tag-desc> + +<tag-name><literal>headers{}</literal></tag-name> +<tag-desc> +request headers object, read-only. +<para> +For example, the <literal>Header-Name</literal> header +can be accessed with the syntax <literal>headers['Header-Name']</literal> +or <literal>headers.Header_name</literal> +</para> +</tag-desc> + +<tag-name><literal>args{}</literal></tag-name> +<tag-desc> +request arguments object, read-only +</tag-desc> + +<tag-name><literal>variables{}</literal></tag-name> +<tag-desc> +nginx variables object, read-only +</tag-desc> + +<tag-name><literal>log(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a <literal>string</literal> to the error log +</tag-desc> +</list> +</para> + +<para> +The response object has the following properties: +<list type="tag"> + +<tag-name><literal>status</literal></tag-name> +<tag-desc> +response status, writable +</tag-desc> + +<tag-name><literal>headers{}</literal></tag-name> +<tag-desc> +response headers object +</tag-desc> + +<tag-name><literal>contentType</literal></tag-name> +<tag-desc> +the response <header>Content-Type</header> header field value, writable +</tag-desc> + +<tag-name><literal>contentLength</literal></tag-name> +<tag-desc> +the response <header>Content-Length</header> header field value, writable +</tag-desc> +</list> +</para> + +<para> +The response object has the following methods: +<list type="tag"> + +<tag-name><literal>sendHeader()</literal></tag-name> +<tag-desc> +sends the HTTP header to the client +</tag-desc> + +<tag-name><literal>send(<value>string</value>)</literal></tag-name> +<tag-desc> +sends a part of the response body to the client +</tag-desc> + +<tag-name><literal>finish()</literal></tag-name> +<tag-desc> +finishes sending a response to the client +</tag-desc> +</list> +</para> + +</section> + +</module>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="34" + rev="35" toc="no"> @@ -303,6 +303,11 @@ ngx_http_index_module</link> </listitem> <listitem> +<link doc="http/ngx_http_js_module.xml"> +ngx_http_js_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_limit_conn_module.xml"> ngx_http_limit_conn_module</link> </listitem> @@ -515,6 +520,11 @@ ngx_stream_geoip_module</link> </listitem> <listitem> +<link doc="stream/ngx_stream_js_module.xml"> +ngx_stream_js_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_limit_conn_module.xml"> ngx_stream_limit_conn_module</link> </listitem>
new file mode 100644 --- /dev/null +++ b/xml/en/docs/stream/ngx_stream_js_module.xml @@ -0,0 +1,320 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_js_module" + link="/en/docs/stream/ngx_stream_js_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_js_module</literal> module is used to +implement handlers in JavaScript. +</para> + +<para> +This module is not built by default, it should be compiled with +nginx JavaScript module using the +<literal>--add_module</literal> configuration parameter: +<example> +./configure --add-module=<value>path-to-njs</value>/nginx +</example> +The <link url="http://hg.nginx.org/njs">repository</link> +with nginx JavaScript module can be cloned with the following command +(requires <link url="https://www.mercurial-scm.org">Mercurial</link> client): +<example> +hg clone http://hg.nginx.org/njs +</example> +This module can also be built as +<link doc="../ngx_core_module.xml" id="load_module">dynamic</link>: +<example> +./configure --add-dynamic_module=<value>path-to-njs</value>/nginx +</example> +</para> + +</section> + + +<section id="issues" name="Known Issues"> + +<para> +The module is experimental, caveat emptor applies. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +stream { + js_include stream.js; + + server { + listen 12345; + + js_preread qux; + + js_set $foo foo; + js_set $bar bar; + + return foo; + } + + server { + listen 12346; + + js_access xyz; + proxy_pass 127.0.0.1:8000; + js_filter baz; + } +} + +http { + server { + listen 8000; + location / { + return 200 $http_foo\n; + } + } +} +</example> +</para> + +<para> +The <path>stream.js</path> file: +<example> +var req = ''; +var matched = 0; +var line = ''; + +function qux(s) { + n = s.buffer.indexOf('\n'); + if (n == -1) { + return s.AGAIN; + } + + line = s.buffer.substr(0, n); +} + +function foo(s) { + return line; +} + +function bar(s) { + var v = s.variables; + s.log("hello from bar() handler!"); + return "foo-var" + v.remote_port + "; pid=" + v.pid; +} + +// The filter processes one buffer per call. +// The buffer is available in s.buffer both for +// reading and writing. Called for both directions. + +function baz(s) { + if (s.fromUpstream || matched) { + return; + } + + // Disable certain addresses. + + if (s.remoteAddress.match('^192.*')) { + return s.ERROR; + } + + // Read HTTP request line. + // Collect bytes in 'req' until request + // line is read. Clear current buffer to + // disable output. + + req = req + s.buffer; + s.buffer = ''; + + n = req.search('\n'); + + if (n != -1) { + // Inject a new HTTP header. + var rest = req.substr(n + 1); + req = req.substr(0, n + 1); + + addr = s.remoteAddress; + + s.log('req:' + req); + s.log('rest:' + rest); + + // Output the result and skip further + // processing. + + s.buffer = req + 'Foo: addr_' + addr + '\r\n' + rest; + matched = 1; + } +} + +function xyz(s) { + if (s.remoteAddress.match('^192.*')) { + return s.ABORT; + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="js_access"> +<syntax><value>function</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Sets a JavaScript function which will be called at the +<link doc="stream_processing.xml" id="access_phase">access</link> phase. +</para> + +</directive> + + +<directive name="js_filter"> +<syntax><value>function</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Sets a data filter. +</para> + +</directive> + + +<directive name="js_include"> +<syntax><value>file</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Specifies a file that implements server and variable handlers in JavaScript. +</para> + +</directive> + + +<directive name="js_preread"> +<syntax><value>function</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Sets a JavaScript function which will be called at the +<link doc="stream_processing.xml" id="preread_phase">preread</link> phase. +</para> + +</directive> + + +<directive name="js_set"> +<syntax> +<value>$variable</value> <value>function</value></syntax> +<default/> +<context>stream</context> +<context>server</context> + +<para> +Sets a JavaScript function for the specified variable. +</para> + +</directive> + +</section> + + +<section id="properties" name="Session Object Properties"> +<para> +Each stream JavaScript handler receives one argument, a stream session object. +</para> + +<para> +The session object has the following properties: + +<list type="tag"> + +<tag-name><literal>remoteAddress</literal></tag-name> +<tag-desc> +client address, read-only +</tag-desc> + +<tag-name><literal>eof</literal></tag-name> +<tag-desc> +a boolean read-only property, true if the current buffer is the last buffer +</tag-desc> + +<tag-name><literal>fromUpstream</literal></tag-name> +<tag-desc> +a boolean read-only property, +true if the current buffer is from the upstream server to the client +</tag-desc> + +<tag-name><literal>buffer</literal></tag-name> +<tag-desc> +the current buffer, writable +</tag-desc> + +<tag-name><literal>variables{}</literal></tag-name> +<tag-desc> +nginx variables object, read-only +</tag-desc> + +<tag-name><literal>OK</literal></tag-name> +<tag-desc> +the <literal>OK</literal> return code +</tag-desc> + +<tag-name><literal>DECLINED</literal></tag-name> +<tag-desc> +the <literal>DECLINED</literal> return code +</tag-desc> + +<tag-name><literal>AGAIN</literal></tag-name> +<tag-desc> +the <literal>AGAIN</literal> return code +</tag-desc> + +<tag-name><literal>ERROR</literal></tag-name> +<tag-desc> +the <literal>ERROR</literal> return code +</tag-desc> + +<tag-name><literal>ABORT</literal></tag-name> +<tag-desc> +the <literal>ABORT</literal> return code +</tag-desc> +</list> +</para> + +<para> +The session object has the following methods: + +<list type="tag"> + +<tag-name><literal>log(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a sent <value>string</value> to the error log +</tag-desc> +</list> +</para> + +</section> + +</module>