Mercurial > hg > nginx-site
changeset 2246:32ba43abf9cd
Renamed njs API, njs Changes.
| author | Yaroslav Zhuravlev <yar@nginx.com> |
|---|---|
| date | Mon, 24 Sep 2018 19:24:04 +0300 |
| parents | 87a0e2c73a25 |
| children | 0f16ef9a8dbe |
| files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_js_module.xml xml/en/docs/njs/changes.xml xml/en/docs/njs/cli.xml xml/en/docs/njs/examples.xml xml/en/docs/njs/index.xml xml/en/docs/njs/njs_api.xml xml/en/docs/njs/njs_changes.xml xml/en/docs/njs/reference.xml xml/en/docs/stream/ngx_stream_js_module.xml xml/index.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_js_module.xml xml/ru/docs/njs/cli.xml xml/ru/docs/njs/examples.xml xml/ru/docs/njs/index.xml xml/ru/docs/njs/njs_api.xml xml/ru/docs/njs/reference.xml xml/ru/docs/stream/ngx_stream_js_module.xml |
| diffstat | 19 files changed, 3062 insertions(+), 3062 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/en/GNUmakefile Mon Sep 24 19:24:04 2018 +0300 @@ -123,12 +123,12 @@ ngx_google_perftools_module \ dev/development_guide \ njs/index \ - njs/njs_changes \ - njs/njs_api \ + njs/changes \ njs/cli \ njs/compatibility \ njs/examples \ njs/install \ + njs/reference \ TOP = \ download \
--- a/xml/en/docs/http/ngx_http_js_module.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/en/docs/http/ngx_http_js_module.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_http_js_module" link="/en/docs/http/ngx_http_js_module.html" lang="en" - rev="17"> + rev="18"> <section id="summary"> @@ -162,7 +162,7 @@ <para> Each HTTP njs handler receives one argument, a request -<link doc="../njs/njs_api.xml" id="http_request">object</link>. +<link doc="../njs/reference.xml" id="http">object</link>. </para> </section>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/njs/changes.xml Mon Sep 24 19:24:04 2018 +0300 @@ -0,0 +1,1209 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> + +<article name="Changes" + link="/en/docs/njs/changes.html" + lang="en" + rev="8" + toc="no"> + +<section id="njs0.2.4" name="Changes with 0.2.4"> + +<para> +Release Date: +18 September 2018 +</para> + +<para> +nginx modules: +<list type="bullet"> + +<listitem> +<para> +Change: +stream module handlers refactored. +</para> + +<para> +New methods and properties: +<link doc="njs_api.xml" id="s_on">s.on()</link>, +<link doc="njs_api.xml" id="s_off">s.off()</link>, +<link doc="njs_api.xml" id="s_allow">s.allow()</link>, +<link doc="njs_api.xml" id="s_done">s.done()</link>, +<link doc="njs_api.xml" id="s_decline">s.decline()</link>, +<link doc="njs_api.xml" id="s_deny">s.deny()</link>. +</para> + +<para> +Removed properties of the +<link doc="njs_api.xml" id="stream">Stream</link> object: +<literal>s.OK</literal>, +<literal>s.ABORT</literal>, +<literal>s.AGAIN</literal>, +<literal>s.DECLINED</literal>, +<literal>s.ERROR</literal> +(replaced with +<link doc="njs_api.xml" id="s_allow">s.allow()</link>, +<link doc="njs_api.xml" id="s_done">s.done()</link>, +<link doc="njs_api.xml" id="s_deny">s.deny()</link>). +</para> + +<para> +<literal>s.buffer</literal> +(for reading replaced with data argument of +the corresponding callback, for writing use +<link doc="njs_api.xml" id="s_send">s.send()</link>). +</para> + +<para> +<literal>s.fromUpstream</literal> +(replaced with a callback for a corresponding event). +</para> + +<para> +<literal>s.eof</literal> +(replaced with <literal></literal> +<link doc="njs_api.xml" id="s_on_callback_last">flags.last</link>). +</para> + +</listitem> + +</list> +</para> + +<para> +Core: +<list type="bullet"> + +<listitem> +<para> +Feature: +added <literal>Function.prototype.length</literal>. +</para> +</listitem> + +<listitem> +<para> +Feature: +introduced sandboxing mode. +</para> +</listitem> + +<listitem> +<para> +Improvement: +added exception strings where appropriate. +</para> +</listitem> + +<listitem> +<para> +Improvement: +improved wording for primitive type conversion exception. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +throwing <literal>TypeError</literal> +for attempts to change frozen properties. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>Object.defineProperty()</literal> for existing properties. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +respecting the enumerable attribute while iterating by for in. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +respecting writable attribute for property handlers. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed exception handling in arguments of a function. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>Object.prototype.toString</literal> for different value types. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>Object()</literal> constructor for object types arguments. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed comparison of objects and strings. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>String.slice()</literal> for undefined arguments. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous additional bugs have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.2.3" name="Changes with 0.2.3"> + +<para> +Release Date: +31 July 2018 +</para> + +<para> +nginx modules: +<list type="bullet"> + +<listitem> +<para> +Bugfix: +making a subrequest from a <literal>Reply</literal> object caused +a segmentation fault. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +getting the parent property of the main +<link doc="njs_api.xml" id="http">HTTP Request</link> +object caused a segmentation fault. +</para> +</listitem> + +</list> +</para> + +<para> +Core: +<list type="bullet"> + +<listitem> +<para> +Feature: +added the pretty string representation for values. +</para> +</listitem> + +<listitem> +<para> +Feature: +correctly printing floating point numbers. +</para> +</listitem> + +<listitem> +<para> +Feature: +correctly parsing floating point numbers. +</para> +</listitem> + +<listitem> +<para> +Feature: +<link doc="njs_api.xml" id="string_bytesfrom">String.bytesFrom()</link> method +(decoding <literal>hex</literal>, +<literal>base64</literal>, +<literal>base64url</literal> into a byte string). +</para> +</listitem> + +<listitem> +<para> +Feature: +<link doc="njs_api.xml" id="string_padstart">String.padStart()</link> and +<link doc="njs_api.xml" id="string_padend">String.padEnd()</link> methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +added support of binary literals. +</para> +</listitem> + +<listitem> +<para> +Improvement: +added information about illegal token in number parsing. +</para> +</listitem> + +<listitem> +<para> +Improvement: +allowed uppercased <literal>O</literal> in octal literal values. +</para> +</listitem> + +<listitem> +<para> +Improvement: +added support for multiple arguments in <literal>console.log()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed applying <literal>call()</literal> to methods of external values. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed addition operator applied to an object. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed exception handling in <literal>njs_vm_value_to_ext_string()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>Number()</literal> with boolean, null and undefined arguments. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed error handling of setting non-numeric <literal>Array.length</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed autocompletion for global objects. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous additional bugs have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.2.2" name="Changes with 0.2.2"> + +<para> +Release Date: +19 June 2018 +</para> + +<para> +nginx modules: +<list type="bullet"> + +<listitem> +<para> +Change: +merged HTTP <literal>Response</literal> and <literal>Reply</literal> +into <link doc="njs_api.xml" id="http">HTTP Request</link>. +New members of <literal>Request</literal>: + +<list type="bullet"> + +<listitem> +<para> +<literal>req.status</literal> (<literal>res.status</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.parent</literal> (<literal>reply.parent</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.requestBody</literal> (<literal>req.body</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.responseBody</literal> (<literal>reply.body</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.headersIn</literal> (<literal>req.headers</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.headersOut</literal> (<literal>res.headers</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.sendHeader()</literal> (<literal>res.sendHeader()</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.send()</literal> (<literal>res.send()</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.finish()</literal> (<literal>res.finish()</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.return()</literal> (<literal>res.return()</literal>) +</para> +</listitem> + +</list> +Deprecated members of <literal>Request</literal>: + +<list type="bullet"> + +<listitem> +<para> +<literal>req.body</literal> (use <literal>req.requestBody</literal> +or <literal>req.responseBody</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.headers</literal> (use <literal>req.headersIn</literal> +or <literal>req.headersOut</literal>) +</para> +</listitem> + +<listitem> +<para> +<literal>req.response</literal> +</para> +</listitem> + +</list> +The deprecated properties will be removed in next releases. +</para> +</listitem> + +<listitem> +<para> +Feature: +HTTP <link doc="njs_api.xml" id="r_internal_redirect">internalRedirect()</link> +method. +</para> +</listitem> + +</list> +</para> + +<para> +Core: +<list type="bullet"> + +<listitem> +<para> +Bugfix: +fixed heap-buffer-overflow in <literal>crypto.createHmac()</literal>. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.2.1" name="Changes with 0.2.1"> + +<para> +Release Date: +31 May 2018 +</para> + +<para> +nginx modules: +<list type="bullet"> + +<listitem> +<para> +Feature: +HTTP request body getter. +</para> +</listitem> + +<listitem> +<para> +Improvement: +moved njs vm to the <literal>main</literal> configuration. +</para> +</listitem> + +<listitem> +<para> +Improvement: +improved logging for +<link doc="../http/ngx_http_js_module.xml" id="js_set"/> and +<link doc="../http/ngx_http_js_module.xml" id="js_content"/> directives. +</para> +</listitem> + +<listitem> +<para> +Improvement: +setting status code to 500 by default in the +<link doc="../http/ngx_http_js_module.xml" id="js_content"/> handler +</para> +</listitem> + +<listitem> +<para> +Improvement: +added the debug for the returned status code in +<link doc="../http/ngx_http_js_module.xml" id="js_content"/> handler +</para> +</listitem> + +<listitem> +<para> +Bugfix: fixed error logging in +<link doc="../http/ngx_http_js_module.xml" id="js_include"/>. +</para> +</listitem> + +</list> +</para> + +<para> +Core: +<list type="bullet"> + +<listitem> +<para> +Feature: +added array length setter. +</para> +</listitem> + +<listitem> +<para> +Improvement: +public header <literal>cleanup. njscript.h</literal> is renamed to +<literal>njs.h</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed crypto <literal>update()</literal> method after +<literal>digest()</literal> is called. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>crypto.createHmac()</literal> for keys with size <= alg size +and > 64. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>JSON.stringify()</literal> for arrays with empty cells. +</para> +</listitem> + +<listitem> +<para> + Bugfix: +fixed exception type for unsupported types in +<literal>JSON.stringify()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed handling of undefined arguments of functions. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed handling of missing <literal>arg</literal> of +<literal>Object.getOwnPropertyDescriptor()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed handling of properties in +<literal>Object.getOwnPropertyDescriptor()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed the writeable flag of <literal>Array.length</literal> property. +</para> +</listitem> + +<listitem> +<para> +Bugfix: fixed return value type of <literal>clearTimeout()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +fixed <literal>njs_vm_external_bind()</literal>. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous additional bugs have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.2.0" name="Changes with 0.2.0"> + +<para> +Release Date: +3 Apr 2018 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +reporting njs version by CLI. +</para> +</listitem> + +<listitem> +<para> +Feature: +textual description for type converting exceptions. +</para> +</listitem> + +<listitem> +Feature: +<literal>setTimeout()</literal> and +<literal>clearTimeout()</literal> methods. +</listitem> + +<listitem> +<para> +Feature: +Byte string to +<literal>hex</literal>, +<literal>base64</literal>, +<literal>base64url</literal> encodings. +</para> +</listitem> + +<listitem> +<para> +Feature: +<link url="https://nodejs.org/api/crypto.html#crypto_class_hash">Node.js style</link> +<literal>Crypto</literal> methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +HTTP and stream +<literal>warn()</literal> and +<literal>error()</literal> methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +HTTP <literal>subrequest()</literal> method. +</para> +</listitem> + +<listitem> +<para> +Feature: +HTTP <literal>return()</literal> method. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs have been fixed in the core and +interactive shell. +</para> +</listitem> + +</list> +</para> + +</section> + +<section id="njs0.1.15" name="Changes with 0.1.15"> + +<para> +Release Date: +20 Nov 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +<literal>Error</literal>, +<literal>EvalError</literal>, +<literal>InternalError</literal>, +<literal>RangeError</literal>, +<literal>ReferenceError</literal>, +<literal>SyntaxError</literal>, +<literal>TypeError</literal>, +<literal>URIError</literal> objects. +</para> +</listitem> + +<listitem> +<para> +Feature: +octal literals support. +</para> +</listitem> + +<listitem> +<para> +Feature: +<link url="https://nodejs.org/api/fs.html#fs_file_system">Node.js style</link> +<literal>File system</literal> access methods: +<literal>fs.readFile()</literal>, +<literal>fs.readFileSync()</literal>, +<literal>fs.appendFile()</literal>, +<literal>fs.appendFileSync()</literal>, +<literal>fs.writeFile()</literal>, +<literal>fs.writeFileSync()</literal>. +</para> +</listitem> + +<listitem> +<para> +Feature: +nginx modules print backtrace on exception. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.14" name="Changes with 0.1.14"> + +<para> +Release Date: +09 Oct 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +JSON object. +</para> +</listitem> + +<listitem> +<para> +Feature: +object level completions in interactive shell. +</para> +</listitem> + +<listitem> +<para> +Feature: +various configure improvements. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs have been fixed in the core and +interactive shell. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.13" name="Changes with 0.1.13"> + +<para> +Release Date: +31 Aug 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +<literal>console.log()</literal> and +<literal>console.help()</literal> +methods in interactive shell. +</para> +</listitem> + +<listitem> +<para> +Feature: +interactive shell prints backtrace on exception. +</para> +</listitem> + +<listitem> +<para> +Feature: +interactive shell by default +if <literal>libedit</literal> is available. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +processing of large files from +<literal>stdin</literal> in command line mode. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +improved <literal>editline</literal> detection. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.12" name="Changes with 0.1.12"> + +<para> +Release Date: +08 Aug 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +Interactive shell. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +in <literal>Object.isSealed()</literal>. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.11" name="Changes with 0.1.11"> + +<para> +Release Date: +27 Jun 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +<literal>Object.keys()</literal>, +<literal>Object.prototype.hasOwnProperty()</literal> +methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +<literal>Object.defineProperty()</literal>, +<literal>Object.defineProperties()</literal>, +<literal>Object.getOwnPropertyDescriptor()</literal> +methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +<literal>Object.getPrototypeOf()</literal>, +<literal>Object.prototype.isPrototypeOf()</literal> +methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +<literal>Object.preventExtensions()</literal>, +<literal>Object.isExtensible()</literal>, +<literal>Object.freeze()</literal>, +<literal>Object.isFrozen()</literal>, +<literal>Object.seal()</literal>, +<literal>Object.isSealed()</literal> +methods. +</para> +</listitem> + +<listitem> +<para> +Feature: +scientific notation (<literal>3.35e10</literal>) literals support. +</para> +</listitem> + +<listitem> +<para> +Feature: +hexadecimal (<literal>0x1123</literal>) literals support. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +processing of large array indexes. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +in <literal>parseInt()</literal> and +<literal>Date.parse()</literal>. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.10" name="Changes with 0.1.10"> + +<para> +Release Date: +04 Apr 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Feature: +nested functions and function closures. +</para> +</listitem> + +<listitem> +<para> +Feature: +<literal>Array.of()</literal>, +<literal>Array.prototype.fill()</literal>, +<literal>Array.prototype.find()</literal>, +<literal>Array.prototype.findIndex()</literal> +methods. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs and segmentation faults have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.9" name="Changes with 0.1.9"> + +<para> +Release Date: +01 Feb 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Bugfix: +global variables were not initialized when njs was used +in nginx. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.8" name="Changes with 0.1.8"> + +<para> +Release Date: +24 Jan 2017 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Change: +the <literal>strict</literal> mode is enforced, +variables must be explicitly declared. +</para> +</listitem> + + +<listitem> +<para> +Feature: +<literal>for</literal> and +<literal>for-in</literal> loops support variable declaration. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +global and function scopes have been fixed. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +now <literal>for-in</literal> loop does not discard the last value +of property variable. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs and segmentation faults have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.7" name="Changes with 0.1.7"> + +<para> +Release Date: +27 Dec 2016 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Change: +the <link doc="../http/ngx_http_js_module.xml" id="js_include"/> directive +has been disabled at server and location levels. +</para> +</listitem> + +<listitem> +<para> +Feature: +exponentiation operators. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs and segmentation faults have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + + +<section id="njs0.1.6" name="Changes with 0.1.6"> + +<para> +Release Date: +13 Dec 2016 +</para> + +<para> +<list type="bullet"> + +<listitem> +<para> +Change: +the <link doc="../http/ngx_http_js_module.xml" id="js_set"/> directive +has been disabled at server and location levels. +</para> +</listitem> + +<listitem> +<para> +Feature: +ES6 <literal>Math</literal> methods. +</para> +</listitem> + +<listitem> +<para> +Bugfix: +miscellaneous bugs and segmentation faults have been fixed. +</para> +</listitem> + +</list> +</para> + +</section> + +</article>
--- a/xml/en/docs/njs/cli.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/en/docs/njs/cli.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <article name="Command-line interface" link="/en/docs/njs/cli.html" lang="en" - rev="1"> + rev="2"> <section> <para> @@ -21,8 +21,8 @@ <link doc="install.xml" id="install_sources">sources</link>. Compared to njs running inside nginx, nginx objects -(<link doc="njs_api.xml" id="http">HTTP</link> and -<link doc="njs_api.xml" id="stream">Stream</link>) +(<link doc="reference.xml" id="http">HTTP</link> and +<link doc="reference.xml" id="stream">Stream</link>) are not available in the utility. <example> $ echo "2**3" | njs -
--- a/xml/en/docs/njs/examples.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/en/docs/njs/examples.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <article name="Examples" link="/en/docs/njs/examples.html" lang="en" - rev="1"> + rev="2"> <section id="helloword" name="Hello World"> @@ -311,11 +311,11 @@ <section id="legacy_stream" name="Injecting HTTP header using stream proxy"> <para> -Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, +Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, stream configuration <link doc="../stream/ngx_stream_js_module.xml" id="example">example</link> has been changed. -For njs <link doc="../njs/njs_changes.xml" id="njs0.2.3">0.2.3</link> +For njs <link doc="../njs/changes.xml" id="njs0.2.3">0.2.3</link> and earlier, use this configuration example: <example> load_module modules/ngx_stream_js_module.so;
--- a/xml/en/docs/njs/index.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/en/docs/njs/index.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <article name="njs scripting language" link="/en/docs/njs/index.html" lang="en" - rev="24" + rev="25" toc="no"> <section id="links"> @@ -22,11 +22,11 @@ </listitem> <listitem> -<link doc="njs_changes.xml"/> +<link doc="changes.xml"/> </listitem> <listitem> -<link doc="njs_api.xml"/> +<link doc="reference.xml"/> </listitem> <listitem> @@ -121,7 +121,7 @@ <listitem id="hello_world"> <para> create an njs script file, for example, <path>hello_world.js</path>. -See <link doc="njs_api.xml">Reference</link> +See <link doc="reference.xml">Reference</link> for the list of njs properties and methods. <example> function hello(r) {
--- a/xml/en/docs/njs/njs_api.xml Mon Sep 24 19:10:29 2018 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1281 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> - -<article name="njs API" - link="/en/docs/njs/njs_api.html" - lang="en" - rev="8"> - -<section id="summary"> - -<para> -<link doc="index.xml">njs</link> provides objects, methods and properties -for extending nginx functionality. -</para> - -</section> - - -<section id="core" name="Core"> - - -<section id="string" name="String"> - -<para> -There are two types of strings: -a <literal>Unicode string</literal> (default) and -a <literal>byte string</literal>. -</para> - -<para> -A <literal>Unicode string</literal> corresponds to an ECMAScript string -which contains Unicode characters. -</para> - -<para> -<literal>Byte strings</literal> contain a sequence of bytes. -They are used to serialize Unicode strings -to external data and deserialize from external sources. -For example, the <link id="string_toutf8">toUTF8()</link> method serializes -a Unicode string to a byte string using UTF8 encoding: -<example> ->> '£'.toUTF8().toString('hex') -'c2a3' /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */ -</example> -The <link id="string_tobytes">toBytes()</link> method serializes -a Unicode string with code points up to 255 into a byte string, -otherwise, <literal>null</literal> is returned: -<example> ->> '£'.toBytes().toString('hex') -'a3' /* a3 is a byte equal to 00A3 ('£') code point */ -</example> -Only byte strings can be converted to different encodings. -For example, a string cannot be encoded to <literal>hex</literal> directly: -<example> ->> 'αβγδ'.toString('base64') -TypeError: argument must be a byte string - at String.prototype.toString (native) - at main (native) -</example> -To convert a Unicode string to hex, -first, it should be converted to a byte string and then to hex: -<example> ->> 'αβγδ'.toUTF8().toString('base64') -'zrHOss6zzrQ=' -</example> - -<list type="tag"> - -<tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value> -| <value>string</value>, <value>encoding</value>)</literal></tag-name> -<tag-desc> -(njs specific) Creates a byte string either from an array that contains octets, -or from an encoded string (0.2.3). -The encoding can be -<literal>hex</literal>, -<literal>base64</literal>, and -<literal>base64url</literal>. -<example> ->> String.bytesFrom([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]) -'buffer' - ->> String.bytesFrom('YnVmZmVy', 'base64') -'buffer' -</example> -</tag-desc> - -<tag-name><literal>String.fromCodePoint(<value>codePoint1</value>[, ...[, -<value>codePoint2</value>]])</literal></tag-name> -<tag-desc> -Returns a string from one or more Unicode code points. -<example> ->> String.fromCodePoint(97, 98, 99, 100) -'abcd' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.concat(<value>string1</value>[, ..., -<value>stringN</value>])</literal></tag-name> -<tag-desc> -Returns a string that contains the concatenation of specified -<literal>strings</literal>. -<example> ->> "a".concat("b", "c") -'abc' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.endsWith(<value>searchString</value>[, -<value>length</value>])</literal></tag-name> -<tag-desc> -Returns <literal>true</literal> if a string ends with the characters -of a specified string, otherwise <literal>false</literal>. -The optional <literal>length</literal> parameter is the the length of string. -If omitted, the default value is the length of the string. -<example> ->> 'abc'.endsWith('abc') -true ->> 'abca'.endsWith('abc') -false -</example> -</tag-desc> - -<tag-name><literal>String.prototype.fromBytes(<value>start</value>[, -<value>end</value>])</literal></tag-name> -<tag-desc> -(njs specific) Returns a new Unicode string from a byte string -where each byte is replaced with a corresponding Unicode code point. -</tag-desc> - -<tag-name><literal>String.prototype.fromUTF8(<value>start</value>[, -<value>end</value>])</literal></tag-name> -<tag-desc> -(njs specific) Converts a byte string containing a valid UTF8 string -into a Unicode string, -otherwise <literal>null</literal> is returned. -</tag-desc> - -<tag-name><literal>String.prototype.includes(<value>searchString</value>[, -<value>position</value>]))</literal></tag-name> -<tag-desc> -Returns <literal>true</literal> if a string is found within another string, -otherwise <literal>false</literal>. -The optional <literal>position</literal> parameter is the position -within the string at which to begin search for <literal>searchString</literal>. -Default value is 0. -<example> ->> 'abc'.includes('bc') -true -</example> -</tag-desc> - -<tag-name><literal>String.prototype.indexOf(<value>searchString</value>[, -<value>fromIndex</value>])</literal></tag-name> -<tag-desc> -Returns the position of the first occurrence -of the <literal>searchString</literal> -The search is started at <literal>fromIndex</literal>. -Returns <value>-1</value> if the value is not found. -The <literal>fromIndex</literal> is an integer, -default value is 0. -If <literal>fromIndex</literal> is lower than 0 -or greater than -<link id="string_length">String.prototype.length</link><value></value>, -the search starts at index <value>0</value> and -<value>String.prototype.length</value>. -<example> ->> 'abcdef'.indexOf('de', 2) -3 -</example> -</tag-desc> - -<tag-name><literal>String.prototype.lastIndexOf(<value>searchString</value>[, -<value>fromIndex</value>])</literal></tag-name> -<tag-desc> -Returns the position of the last occurrence -of the <literal>searchString</literal>, -searching backwards from <literal>fromIndex</literal>. -Returns <value>-1</value> if the value is not found. -If <literal>searchString</literal> is empty, -then <literal>fromIndex</literal> is returned. -<example> ->> "nginx".lastIndexOf("gi") -1 -</example> -</tag-desc> - -<tag-name id="string_length"><literal>String.prototype.length</literal></tag-name> -<tag-desc> -Returns the length of the string. -<example> ->> 'αβγδ'.length -4 -</example> -</tag-desc> - -<tag-name><literal>String.prototype.match([<value>regexp</value>])</literal></tag-name> -<tag-desc> -Matches a string against a <literal>regexp</literal>. -<example> ->> 'nginx'.match( /ng/i ) -'ng' -</example> -</tag-desc> - -<tag-name id="string_padend"><literal>String.prototype.padEnd(<value>length</value> -[, <value>string</value>])</literal></tag-name> -<tag-desc> -Returns a string of a specified <literal>length</literal> -with the pad <literal>string</literal> applied -to the end of the specified string (0.2.3). -<example> ->> '1234'.padEnd(8, 'abcd') -'1234abcd' -</example> -</tag-desc> - -<tag-name id="string_padstart"><literal>String.prototype.padStart(<value>length</value> -[, <value>string</value>])</literal></tag-name> -<tag-desc> -Returns a string of a specified <literal>length</literal> -with the pad <literal>string</literal> applied -to the start of the specified string (0.2.3). -<example> ->> '1234'.padStart(8, 'abcd') -'abcd1234' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.repeat(<value>number</value>)</literal></tag-name> -<tag-desc> -Returns a string -with the specified <literal>number</literal> of copies of the string. -<example> ->> 'abc'.repeat(3) -'abcabcabc' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.replace([<value>regexp</value>|<value>string</value>[, -<value>string</value>|<value>function</value>]])</literal></tag-name> -<tag-desc> -Returns a new string with matches of a pattern -(<literal>string</literal> or a <literal>regexp</literal>) -replaced by a <literal>string</literal> or a <literal>function</literal>. -<example> ->> 'abcdefgh'.replace('d', 1) -'abc1efgh' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.search([<value>regexp</value>])</literal></tag-name> -<tag-desc> -Searches for a string using a <literal>regexp</literal> -<example> ->> 'abcdefgh'.search('def') -3 -</example> -</tag-desc> - -<tag-name><literal>String.prototype.slice(<value>start</value>[, -<value>end</value>])</literal></tag-name> -<tag-desc> -Returns a new string containing a part of an -original string between <literal>start</literal> -and <literal>end</literal> or -from <literal>start</literal> to the end of the string. -<example> ->> 'abcdefghijklmno'.slice(NaN, 5) -'abcde' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.startsWith(<value>searchString</value>[, -<value>position</value>])</literal></tag-name> -<tag-desc> -Returns <literal>true</literal> if a string begins with the characters -of a specified string, otherwise <literal>false</literal>. -The optional <literal>position</literal> parameter is the position -in this string at which to begin search for <literal>searchString</literal>. -Default value is 0. -<example> ->> 'abc'.startsWith('abc') -true -> 'aabc'.startsWith('abc') -false -</example> -</tag-desc> - -<tag-name><literal>String.prototype.substr(<value>start</value>[, -<value>length</value>])</literal></tag-name> -<tag-desc> -Returns the part of the string of the specified <literal>length</literal> -from <literal>start</literal> -or from <literal>start</literal> to the end of the string. -<example> ->> 'abcdefghijklmno'.substr(3, 5) -'defgh' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.substring(<value>start</value>[, -<value>end</value>])</literal></tag-name> -<tag-desc> -Returns the part of the string between -<literal>start</literal> and <literal>end</literal> or -from <literal>start</literal> to the end of the string. -<example> ->> 'abcdefghijklmno'.substring(3, 5) -'de' -</example> -</tag-desc> - -<tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[, -end])</literal></tag-name> -<tag-desc> -(njs specific) Serializes a Unicode string to a byte string. -Returns <literal>null</literal> if a character larger than 255 is -found in the string. -</tag-desc> - -<tag-name><literal>String.prototype.toLowerCase()</literal></tag-name> -<tag-desc> -Converts a string to lower case. -The method supports only simple Unicode folding. -<example> ->> 'ΑΒΓΔ'.toLowerCase() -'αβγδ' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name> -<tag-desc> -<para> -If no <literal>encoding</literal> is specified, -returns a specified Unicode string or byte string as in ECMAScript. -</para> - -<para> -(njs specific) If <literal>encoding</literal> is specified, -encodes a <link id="string_tobytes">byte string</link> to -<literal>hex</literal>, -<literal>base64</literal>, or -<literal>base64url</literal>. -</para> -<example> ->> 'αβγδ'.toUTF8().toString('base64url') -'zrHOss6zzrQ' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.toUpperCase()</literal></tag-name> -<tag-desc> -Converts a string to upper case. -The method supports only simple Unicode folding. -<example> ->> 'αβγδ'.toUpperCase() -'ΑΒΓΔ' -</example> -</tag-desc> - -<tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[, -<value>end</value>])</literal></tag-name> -<tag-desc> -(njs specific) Serializes a Unicode string -to a byte string using UTF8 encoding. -<example> ->> 'αβγδ'.toUTF8().length -8 ->> 'αβγδ'.length -4 -</example> -</tag-desc> - -<tag-name><literal>String.prototype.trim()</literal></tag-name> -<tag-desc> -Removes whitespaces from both ends of a string. -<example> ->> ' abc '.trim() -'abc' -</example> -</tag-desc> - -<tag-name><literal>String.prototype.split(([<value>string</value>|<value>regexp</value>[, -<value>limit</value>]]))</literal></tag-name> -<tag-desc> -Returns match of a string against a <literal>regexp</literal>. -The optional <literal>limit</literal> parameter is an integer that specifies -a limit on the number of splits to be found. -<example> ->> 'abc'.split('') -[ - 'a', - 'b', - 'c' -] -</example> -</tag-desc> - -<tag-name id="encodeuri"><literal>encodeURI(<value>URI</value>)</literal></tag-name> -<tag-desc> -encodes a URI by replacing each instance of certain characters by -one, two, three, or four escape sequences -representing the UTF-8 encoding of the character -<example> ->> encodeURI('012αβγδ') -'012%CE%B1%CE%B2%CE%B3%CE%B4' -</example> -</tag-desc> - -<tag-name><literal>encodeURIComponent(<value>encodedURIString</value>)</literal></tag-name> -<tag-desc> -Encodes a URI by replacing each instance of certain characters -by one, two, three, or four escape sequences -representing the UTF-8 encoding of the character. -<example> ->> encodeURIComponent('[@?=') -'%5B%40%3F%3D' -</example> -</tag-desc> - -<tag-name><literal>decodeURI(<value>encodedURI</value>)</literal></tag-name> -<tag-desc> -Decodes a previously <link id="encodeuri">encoded</link> URI. -<example> ->> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4') -'012αβγδ' -</example> -</tag-desc> - -<tag-name><literal>decodeURIComponent(<value>decodedURIString</value>)</literal></tag-name> -<tag-desc> -Decodes an encoded component of a previously encoded URI. -<example> ->> decodeURIComponent('%5B%40%3F%3D') -'[@?=' -</example> -</tag-desc> - -</list> -</para> - -</section> - - -<section id="core_json" name="JSON"> - -<para> -The <literal>JSON</literal> object (ES 5.1) provides functions -to convert njs values to and from JSON format. -<list type="tag"> - -<tag-name><literal>JSON.parse(<value>string</value>[, -<value>reviver</value>])</literal></tag-name> -<tag-desc> -Converts a <literal>string</literal> that represents JSON data -into an njs object (<literal>{...}</literal>) or -array (<literal>[...]</literal>). -The optional <literal>reviver</literal> parameter is a function (key, value) -that will be called for each (key,value) pair and can transform the value. -</tag-desc> - -<tag-name><literal>JSON.stringify(<value>value</value>[, -<value>replacer</value>] [, <value>space</value>])</literal></tag-name> -<tag-desc> -Converts an njs object back to JSON. -The obligatory <literal>value</literal> parameter is generally a JSON -<literal>object</literal> or <literal>array</literal> that will be converted. -If the value has a <literal>toJSON()</literal> method, -it defines how the object will be serialized. -The optional <literal>replacer</literal> parameter is -a <literal>function</literal> or <literal>array</literal> -that transforms results. -The optional <literal>space</literal> parameter is -a <literal>string</literal> or <literal>number</literal>. -If it is a <literal>number</literal>, -it indicates the number of white spaces placed before a result -(no more than 10). -If it is a <literal>string</literal>, -it is used as a white space (or first 10 characters of it). -If omitted or is <literal>null</literal>, no white space is used. -</tag-desc> -</list> -</para> - -<para> -<example> ->> var json = JSON.parse('{"a":1, "b":true}') ->> json.a -1 - ->> JSON.stringify(json) -'{"a":1,"b":true}' - ->> JSON.stringify(json, undefined, 1) -'{\n "a": 1,\n "b": true\n}' - ->> JSON.stringify({ x: [10, undefined, function(){}] }) -'{"x":[10,null,null]}' - ->> JSON.stringify({"a":1, "toJSON": function() {return "xxx"}}) -'"xxx"' - -# Example with function replacer - ->> function replacer(key, value) {return (typeof value === 'string') ? undefined : value} ->>JSON.stringify({a:1, b:"b", c:true}, replacer) -'{"a":1,"c":true}' -</example> -</para> - -</section> - - -<section id="crypto" name="Crypto"> - -<para> -The Crypto module provides cryptographic functionality support. -The Crypto module object is returned by <literal>require('crypto')</literal>. -</para> - -<para> -<list type="tag"> - -<tag-name><literal>crypto.createHash(<value>algorithm</value>)</literal></tag-name> -<tag-desc> -Creates and returns a <link id="crypto_hash">Hash</link> object -that can be used to generate hash digests -using the given <value>algorithm</value>. -The algorighm can be -<literal>md5</literal>, -<literal>sha1</literal>, and -<literal>sha256</literal>. -</tag-desc> - -<tag-name><literal>crypto.createHmac(<value>algorithm</value>, -<value>secret key</value>)</literal></tag-name> -<tag-desc> -Creates and returns an <link id="crypto_hmac">HMAC</link> object -that uses the given <value>algorithm</value> and <value>secret key</value>. -The algorighm can be -<literal>md5</literal>, -<literal>sha1</literal>, and -<literal>sha256</literal>. -</tag-desc> - -</list> -</para> - - -<section id="crypto_hash" name="Hash"> - -<para> -<list type="tag"> - -<tag-name><literal>hash.update(<value>data</value>)</literal></tag-name> -<tag-desc> -Updates the hash content with the given <value>data</value>. -</tag-desc> - -<tag-name><literal>hash.digest([<value>encoding</value>])</literal></tag-name> -<tag-desc> -Calculates the digest of all of the data passed using -<literal>hash.update()</literal>. -The encoding can be -<literal>hex</literal>, -<literal>base64</literal>, and -<literal>base64url</literal>. -If encoding is not provided, a byte string is returned. -</tag-desc> - -</list> -</para> - -<para> -<example> ->> var cr = require('crypto') -undefined - ->> cr.createHash('sha1').update('A').update('B').digest('base64url') -'BtlFlCqiamG-GMPiK_GbvKjdK10' -</example> -</para> - -</section> - - -<section id="crypto_hmac" name="HMAC"> - -<para> -<list type="tag"> - -<tag-name><literal>hmac.update(<value>data</value>)</literal></tag-name> -<tag-desc> -Updates the HMAC content with the given <value>data</value>. -</tag-desc> - -<tag-name><literal>hmac.digest([<value>encoding</value>])</literal></tag-name> -<tag-desc> -Calculates the HMAC digest of all of the data passed using -<literal>hmac.update()</literal>. -The encoding can be -<literal>hex</literal>, -<literal>base64</literal>, and -<literal>base64url</literal>. -If encoding is not provided, a byte string is returned. -</tag-desc> -</list> -</para> - -<para> -<example> ->> var cr = require('crypto') -undefined - ->> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url') -'Oglm93xn23_MkiaEq_e9u8zk374' -</example> -</para> - -</section> - -</section> - -<section id="njs_api_timers" name="Timers"> - -<para> - -<list type="tag"> - -<tag-name id="cleartimeout"><literal>clearTimeout(<value>timeout</value>)</literal></tag-name> -<tag-desc> -Cancels a <literal>timeout</literal> object -created by <link id="settimeout">setTimeout()</link>. -</tag-desc> - -<tag-name id="settimeout"><literal>setTimeout(<value>function</value>, -<value>ms</value>[, <value>arg1</value>, <value>argN</value>])</literal></tag-name> -<tag-desc> -Calls a <literal>function</literal> -after a specified number of <literal>milliseconds</literal>. -One or more optional <literal>arguments</literal> -can be passed to the specified function. -Returns a <literal>timeout</literal> object. -<example> -function handler(v) -{ - // ... -} - -t = setTimeout(handler, 12); - -// ... - -clearTimeout(t); -</example> -</tag-desc> - -</list> -</para> - -</section> - - -<section id="njs_api_fs" name="File System"> - -<para> -The File System module provides operations with files. -The module object is returned by <literal>require('fs')</literal>. -<list type="tag"> - -<tag-name id="appendfilesync"><literal>appendFileSync(<value>filename</value>, -<value>data</value>[, <value>options</value>])</literal></tag-name> -<tag-desc> -Synchronously appends specified <literal>data</literal> -to a file with provided <literal>filename</literal>. -If the file does not exist, it will be created. -The <literal>options</literal> parameter is expected to be -an object with the following keys: -<list type="tag"> - -<tag-name><literal>mode</literal></tag-name> -<tag-desc> -mode option, by default is <literal>0o666</literal> -</tag-desc> - -<tag-name><literal>flag</literal></tag-name> -<tag-desc> -file system <link id="njs_api_fs_flags">flag</link>, -by default is <literal>a</literal> -</tag-desc> - -</list> -</tag-desc> - -<tag-name id="readfilesync"><literal>readFileSync(<value>filename</value>[, -<value>options</value>])</literal></tag-name> -<tag-desc> -Synchronously returns the contents of the file -with provided <literal>filename</literal>. -The <literal>options</literal> parameter holds -<literal>string</literal> that specifies encoding. -If not specified, a <link id="string_tobytes">byte string</link> is returned. -If <literal>utf8</literal> encoding is specified, a Unicode string is returned. -Otherwise, <literal>options</literal> is expected to be -an object with the following keys: -<list type="tag"> - -<tag-name><literal>encoding</literal></tag-name> -<tag-desc> -encoding, by default is not specified. -The encoding can be <literal>utf8</literal> -</tag-desc> - -<tag-name><literal>flag</literal></tag-name> -<tag-desc> -file system <link id="njs_api_fs_flags">flag</link>, -by default is <literal>r</literal> -</tag-desc> - -</list> -<example> ->> var fs = require('fs') -undefined ->> var file = fs.readFileSync('/file/path.tar.gz') -undefined ->> var gzipped = /^\x1f\x8b/.test(file); gzipped -true -</example> -</tag-desc> - -<tag-name id="writefilesync"><literal>writeFileSync(<value>filename</value>, -<value>data</value>[, -<value>options</value>])</literal></tag-name> -<tag-desc> -Synchronously writes <literal>data</literal> to a file -with provided <literal>filename</literal>. -If the file does not exist, it will be created, -if the file exists, it will be replaced. -The <literal>options</literal> parameter is expected to be -an object with the following keys: -<list type="tag"> -<tag-name><literal>mode</literal></tag-name> -<tag-desc> -mode option, by default is <literal>0o666</literal> -</tag-desc> - -<tag-name><literal>flag</literal></tag-name> -<tag-desc> -file system <link id="njs_api_fs_flags">flag</link>, -by default is <literal>w</literal> -</tag-desc> - -</list> -<example> ->> var fs = require('fs') -undefined ->> var file = fs.writeFileSync('hello.txt', 'Hello world') -undefined -</example> -</tag-desc> - -</list> -</para> - - -<section id="njs_api_fs_flags" name="File System Flags"> - -<para> -The <literal>flag</literal> option can accept the following values: - -<list type= "bullet" compact="no"> - -<listitem> -<literal>a</literal>—open a file for appending. -The file is created if it does not exist -</listitem> - -<listitem> -<literal>ax</literal>—the same as <literal>a</literal> -but fails if the file already exists -</listitem> - -<listitem> -<literal>a+</literal>—open a file for reading and appending. -If the file does not exist, it will be created -</listitem> - -<listitem> -<literal>ax+</literal>—the same as <literal>a+</literal> -but fails if the file already exists -</listitem> - -<listitem> -<literal>as</literal>—open a file for appending in synchronous mode. -If the file does not exist, it will be created -</listitem> - -<listitem> -<literal>as+</literal>—open a file for reading and appending -in synchronous mode. -If the file does not exist, it will be created -</listitem> - -<listitem> -<literal>r</literal>—open a file for reading. -An exception occurs if the file does not exist -</listitem> - -<listitem> -<literal>r+</literal>—open a file for reading and writing. -An exception occurs if the file does not exist -</listitem> - -<listitem> -<literal>rs+</literal>—open a file for reading and writing -in synchronous mode. -Instructs the operating system to bypass the local file system cache -</listitem> - -<listitem> -<literal>w</literal>—open a file for writing. -If the file does not exist, it will be created. -If the file exists, it will be replaced -</listitem> - -<listitem> -<literal>wx</literal>—the same as <literal>w</literal> -but fails if the file already exists -</listitem> - -<listitem> -<literal>w+</literal>—open a file for reading and writing. -If the file does not exist, it will be created. -If the file exists, it will be replaced -</listitem> - -<listitem> -<literal>wx+</literal>—the same as <literal>w+</literal> -but fails if the file already exists -</listitem> - -</list> -</para> - -</section> - -</section> - -</section> - - -<section id="http" name="HTTP Request"> - -<para> -The HTTP request object is available only in the -<link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. -All string properties of the object are <link id="string">byte strings</link>. - -<list type="tag"> - -<tag-name><literal>r.args{}</literal></tag-name> -<tag-desc> -request arguments object, read-only -</tag-desc> - -<tag-name><literal>r.error(<value>string</value>)</literal></tag-name> -<tag-desc> -writes a <literal>string</literal> to the error log -on the <literal>error</literal> level of logging -</tag-desc> - -<tag-name><literal>r.finish()</literal></tag-name> -<tag-desc> -finishes sending a response to the client -</tag-desc> - -<tag-name><literal>r.headersIn{}</literal></tag-name> -<tag-desc> -incoming headers object, read-only. -<para> -For example, the <literal>Foo</literal> header -can be accessed with the syntax <literal>headersIn.foo</literal> -or <literal>headersIn['Foo']</literal> -</para> -</tag-desc> - -<tag-name><literal>r.headersOut{}</literal></tag-name> -<tag-desc> -outgoing headers object, writable. -<para> -For example, the <literal>Foo</literal> header -can be accessed with the syntax <literal>headersOut.foo</literal> -or <literal>headersOut['Foo']</literal> -</para> -</tag-desc> - -<tag-name><literal>r.httpVersion</literal></tag-name> -<tag-desc> -HTTP version, read-only -</tag-desc> - -<tag-name><literal>r.log(<value>string</value>)</literal></tag-name> -<tag-desc> -writes a <literal>string</literal> to the error log -on the <literal>info</literal> level of logging -</tag-desc> - -<tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name> -<tag-desc> -performs an internal redirect to the specified <literal>uri</literal>. -If the uri starts with the “<literal>@</literal>” prefix, -it is considered a named location. -</tag-desc> - -<tag-name><literal>r.method</literal></tag-name> -<tag-desc> -HTTP method, read-only -</tag-desc> - -<tag-name><literal>r.parent</literal></tag-name> -<tag-desc> -references the parent request object -</tag-desc> - -<tag-name><literal>r.remoteAddress</literal></tag-name> -<tag-desc> -client address, read-only -</tag-desc> - -<tag-name><literal>r.requestBody</literal></tag-name> -<tag-desc> -holds the request body, read-only -</tag-desc> - -<tag-name><literal>r.responseBody</literal></tag-name> -<tag-desc> -holds the <link id="subrequest">subrequest</link> response body, read-only. -The size of <literal>r.responseBody</literal> is limited by the -<link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> -directive. -</tag-desc> - -<tag-name><literal>r.return(status[, string])</literal></tag-name> -<tag-desc> -sends the entire response -with the specified <literal>status</literal> to the client -<para> -It is possible to specify either a redirect URL -(for codes 301, 302, 303, 307, and 308) -or the response body text (for other codes) as the second argument -</para> -</tag-desc> - -<tag-name><literal>r.send(<value>string</value>)</literal></tag-name> -<tag-desc> -sends a part of the response body to the client -</tag-desc> - -<tag-name><literal>r.sendHeader()</literal></tag-name> -<tag-desc> -sends the HTTP headers to the client -</tag-desc> - -<tag-name><literal>r.status</literal></tag-name> -<tag-desc> -status, writable -</tag-desc> - -<tag-name><literal>r.variables{}</literal></tag-name> -<tag-desc> -nginx variables object, read-only -</tag-desc> - -<tag-name><literal>r.warn(<value>string</value>)</literal></tag-name> -<tag-desc> -writes a <literal>string</literal> to the error log -on the <literal>warning</literal> level of logging -</tag-desc> - -<tag-name><literal>r.uri</literal></tag-name> -<tag-desc> -current URI, read-only -</tag-desc> - -<tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, -<value>options</value>[, <value>callback</value>]])</literal></tag-name> -<tag-desc> -creates a subrequest with the given <literal>uri</literal> and -<literal>options</literal>, and installs -an optional completion <literal>callback</literal>. - -<para> -If <literal>options</literal> is a string, then it -holds the subrequest arguments string. -Otherwise, <literal>options</literal> is expected to be -an object with the following keys: -<list type="tag"> -<tag-name><literal>args</literal></tag-name> -<tag-desc> -arguments string -</tag-desc> -<tag-name><literal>body</literal></tag-name> -<tag-desc> -request body -</tag-desc> - -<tag-name><literal>method</literal></tag-name> -<tag-desc> -HTTP method -</tag-desc> - -</list> -</para> - -<para> -The completion <literal>callback</literal> receives -a subrequest response object with methods and properties -identical to the parent request object. -</para> -</tag-desc> - -</list> -</para> - -</section> - - -<section id="stream" name="Stream Session"> - -<para> -The stream session object is available only in the -<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> -module. -All string properties of the object are <link id="string">byte strings</link>. -</para> - -<para> -<note> -Prior to njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the stream session object had some properties which are currently -<link id="stream_obsolete">removed</link>. -</note> -</para> - -<para> -<list type="tag"> - -<tag-name id="s_allow"><literal>s.allow()</literal></tag-name> -<tag-desc> -successfully finalizes the phase handler -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>) -</tag-desc> - -<tag-name id="s_decline"><literal>s.decline()</literal></tag-name> -<tag-desc> -finalizes the phase handler and passes control to the next handler -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>) -</tag-desc> - -<tag-name id="s_deny"><literal>s.deny()</literal></tag-name> -<tag-desc> -finalizes the phase handler with the access error code -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>) -</tag-desc> - -<tag-name id="s_done"><literal>s.done</literal>(<value>[code]</value>)</tag-name> -<tag-desc> -successfully finalizes the current phase handler -or finalizes it with the specified numeric code -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>). -</tag-desc> - -<tag-name><literal>s.error(<value>string</value>)</literal></tag-name> -<tag-desc> -writes a sent <literal>string</literal> to the error log -on the <literal>error</literal> level of logging -</tag-desc> - -<tag-name><literal>s.log(<value>string</value>)</literal></tag-name> -<tag-desc> -writes a sent <value>string</value> to the error log -on the <literal>info</literal> level of logging -</tag-desc> - -<tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name> -<tag-desc> -unregisters the callback set by the <link id="s_on">s.on()</link> method -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>) -</tag-desc> - -<tag-name id="s_on"><literal>s.on(<value>event</value>, -<value>callback</value>)</literal></tag-name> -<tag-desc> -registers a <literal>callback</literal> for the specified <literal>event</literal> -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>). - -<para> -An <literal>event</literal> may be one of the following strings: -<list type="tag"> -<tag-name><literal>upload</literal></tag-name> -<tag-desc> -new data from a client -</tag-desc> - -<tag-name><literal>download</literal></tag-name> -<tag-desc> -new data to a client -</tag-desc> - -</list> -</para> - -<para> -The completion callback has the following prototype: -<literal>callback(data, flags)</literal>, where -<literal>data</literal> is string, -<literal>flags</literal> is an object -with the following properties: -<list type="tag"> -<tag-name id="s_on_callback_last"><literal>last</literal></tag-name> -<tag-desc> -a boolean value, true if data is a last buffer. -</tag-desc> - -</list> -</para> -</tag-desc> - -<tag-name><literal>s.remoteAddress</literal></tag-name> -<tag-desc> -client address, read-only -</tag-desc> - -<tag-name id="s_send"><literal>s.send(<value>data</value>[, -<value>options</value>])</literal></tag-name> -<tag-desc> -sends the data to the client -(<link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>). -The <literal>options</literal> is an object used -to override nginx buffer flags derived from an incoming data chunk buffer. -The flags can be overriden with the following flags: -<para> -<list type="tag"> - -<tag-name><literal>last</literal></tag-name> -<tag-desc> -boolean, true if the buffer is the last buffer -</tag-desc> - -<tag-name><literal>flush</literal></tag-name> -<tag-desc> -boolean, true if the buffer should have the <literal>flush</literal> flag -</tag-desc> -</list> -</para> -The method can be called multiple times per callback invocation. -</tag-desc> - -<tag-name><literal>s.variables{}</literal></tag-name> -<tag-desc> -nginx variables object, read-only -</tag-desc> - -<tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> -<tag-desc> -writes a sent <literal>string</literal> to the error log -on the <literal>warning</literal> level of logging -</tag-desc> - -</list> -</para> - - -<section id="stream_obsolete" name="Obsolete properties"> - -<para> -These properties have been removed -in njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link> -and are not backward compatible with the existing njs code. -</para> - -<para> -<list type="tag"> - -<tag-name id="s_abort"><literal>s.ABORT</literal></tag-name> -<tag-desc> -the <literal>ABORT</literal> return code -<note> -Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the <link id="s_deny">s.deny()</link> method should be used instead. -</note> -</tag-desc> - -<tag-name><literal>s.AGAIN</literal></tag-name> -<tag-desc> -the <literal>AGAIN</literal> return code -<note> -Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the corresponding behavior is achieved if no -<link id="s_allow">s.allow()</link>, -<link id="s_deny">s.deny()</link>, -<link id="s_decline">s.decline()</link>, -<link id="s_done">s.done()</link> -is invoked and a callback is registered. -</note> -</tag-desc> - -<tag-name id="s_buffer"><literal>s.buffer</literal></tag-name> -<tag-desc> -the current buffer, writable -<note> -Starting from <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the <link id="s_send">s.send()</link> method should be used for writing. -For reading, the current buffer is available as the first argument of the -<literal>event</literal> callback. -</note> -</tag-desc> - -<tag-name><literal>s.DECLINED</literal></tag-name> -<tag-desc> -the <literal>DECLINED</literal> return code -<note> -Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the <link id="s_decline">s.decline()</link> method should be used instead. -</note> -</tag-desc> - -<tag-name><literal>s.eof</literal></tag-name> -<tag-desc> -a boolean read-only property, true if the current buffer is the last buffer -<note> -Starting from <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the <link id="s_on_callback_last">flags.last</link> property -should be used instead. -</note> -</tag-desc> - -<tag-name><literal>s.ERROR</literal></tag-name> -<tag-desc> -the <literal>ERROR</literal> return code -<note> -Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -an appropriate exception can be thrown to report an error. -</note> -</tag-desc> - -<tag-name><literal>s.fromUpstream</literal></tag-name> -<tag-desc> -a boolean read-only property, -true if the current buffer is from the upstream server to the client -<note> -Starting from <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -a corresponding <link id="s_on">event</link> -(<literal>upload</literal> or <literal>download</literal>) -should be used to handle data to or from client. -</note> -</tag-desc> - -<tag-name id="s_ok"><literal>s.OK</literal></tag-name> -<tag-desc> -the <literal>OK</literal> return code -<note> -Starting from njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link>, -the <link id="s_allow">s.allow()</link> method should be used instead. -</note> -</tag-desc> - -</list> -</para> - -</section> - -</section> - - -</article>
--- a/xml/en/docs/njs/njs_changes.xml Mon Sep 24 19:10:29 2018 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1209 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> - -<article name="njs Changes" - link="/en/docs/njs/njs_changes.html" - lang="en" - rev="7" - toc="no"> - -<section id="njs0.2.4" name="Changes with 0.2.4"> - -<para> -Release Date: -18 September 2018 -</para> - -<para> -nginx modules: -<list type="bullet"> - -<listitem> -<para> -Change: -stream module handlers refactored. -</para> - -<para> -New methods and properties: -<link doc="njs_api.xml" id="s_on">s.on()</link>, -<link doc="njs_api.xml" id="s_off">s.off()</link>, -<link doc="njs_api.xml" id="s_allow">s.allow()</link>, -<link doc="njs_api.xml" id="s_done">s.done()</link>, -<link doc="njs_api.xml" id="s_decline">s.decline()</link>, -<link doc="njs_api.xml" id="s_deny">s.deny()</link>. -</para> - -<para> -Removed properties of the -<link doc="njs_api.xml" id="stream">Stream</link> object: -<literal>s.OK</literal>, -<literal>s.ABORT</literal>, -<literal>s.AGAIN</literal>, -<literal>s.DECLINED</literal>, -<literal>s.ERROR</literal> -(replaced with -<link doc="njs_api.xml" id="s_allow">s.allow()</link>, -<link doc="njs_api.xml" id="s_done">s.done()</link>, -<link doc="njs_api.xml" id="s_deny">s.deny()</link>). -</para> - -<para> -<literal>s.buffer</literal> -(for reading replaced with data argument of -the corresponding callback, for writing use -<link doc="njs_api.xml" id="s_send">s.send()</link>). -</para> - -<para> -<literal>s.fromUpstream</literal> -(replaced with a callback for a corresponding event). -</para> - -<para> -<literal>s.eof</literal> -(replaced with <literal></literal> -<link doc="njs_api.xml" id="s_on_callback_last">flags.last</link>). -</para> - -</listitem> - -</list> -</para> - -<para> -Core: -<list type="bullet"> - -<listitem> -<para> -Feature: -added <literal>Function.prototype.length</literal>. -</para> -</listitem> - -<listitem> -<para> -Feature: -introduced sandboxing mode. -</para> -</listitem> - -<listitem> -<para> -Improvement: -added exception strings where appropriate. -</para> -</listitem> - -<listitem> -<para> -Improvement: -improved wording for primitive type conversion exception. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -throwing <literal>TypeError</literal> -for attempts to change frozen properties. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>Object.defineProperty()</literal> for existing properties. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -respecting the enumerable attribute while iterating by for in. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -respecting writable attribute for property handlers. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed exception handling in arguments of a function. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>Object.prototype.toString</literal> for different value types. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>Object()</literal> constructor for object types arguments. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed comparison of objects and strings. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>String.slice()</literal> for undefined arguments. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous additional bugs have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.2.3" name="Changes with 0.2.3"> - -<para> -Release Date: -31 July 2018 -</para> - -<para> -nginx modules: -<list type="bullet"> - -<listitem> -<para> -Bugfix: -making a subrequest from a <literal>Reply</literal> object caused -a segmentation fault. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -getting the parent property of the main -<link doc="njs_api.xml" id="http">HTTP Request</link> -object caused a segmentation fault. -</para> -</listitem> - -</list> -</para> - -<para> -Core: -<list type="bullet"> - -<listitem> -<para> -Feature: -added the pretty string representation for values. -</para> -</listitem> - -<listitem> -<para> -Feature: -correctly printing floating point numbers. -</para> -</listitem> - -<listitem> -<para> -Feature: -correctly parsing floating point numbers. -</para> -</listitem> - -<listitem> -<para> -Feature: -<link doc="njs_api.xml" id="string_bytesfrom">String.bytesFrom()</link> method -(decoding <literal>hex</literal>, -<literal>base64</literal>, -<literal>base64url</literal> into a byte string). -</para> -</listitem> - -<listitem> -<para> -Feature: -<link doc="njs_api.xml" id="string_padstart">String.padStart()</link> and -<link doc="njs_api.xml" id="string_padend">String.padEnd()</link> methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -added support of binary literals. -</para> -</listitem> - -<listitem> -<para> -Improvement: -added information about illegal token in number parsing. -</para> -</listitem> - -<listitem> -<para> -Improvement: -allowed uppercased <literal>O</literal> in octal literal values. -</para> -</listitem> - -<listitem> -<para> -Improvement: -added support for multiple arguments in <literal>console.log()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed applying <literal>call()</literal> to methods of external values. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed addition operator applied to an object. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed exception handling in <literal>njs_vm_value_to_ext_string()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>Number()</literal> with boolean, null and undefined arguments. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed error handling of setting non-numeric <literal>Array.length</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed autocompletion for global objects. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous additional bugs have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.2.2" name="Changes with 0.2.2"> - -<para> -Release Date: -19 June 2018 -</para> - -<para> -nginx modules: -<list type="bullet"> - -<listitem> -<para> -Change: -merged HTTP <literal>Response</literal> and <literal>Reply</literal> -into <link doc="njs_api.xml" id="http">HTTP Request</link>. -New members of <literal>Request</literal>: - -<list type="bullet"> - -<listitem> -<para> -<literal>req.status</literal> (<literal>res.status</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.parent</literal> (<literal>reply.parent</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.requestBody</literal> (<literal>req.body</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.responseBody</literal> (<literal>reply.body</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.headersIn</literal> (<literal>req.headers</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.headersOut</literal> (<literal>res.headers</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.sendHeader()</literal> (<literal>res.sendHeader()</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.send()</literal> (<literal>res.send()</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.finish()</literal> (<literal>res.finish()</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.return()</literal> (<literal>res.return()</literal>) -</para> -</listitem> - -</list> -Deprecated members of <literal>Request</literal>: - -<list type="bullet"> - -<listitem> -<para> -<literal>req.body</literal> (use <literal>req.requestBody</literal> -or <literal>req.responseBody</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.headers</literal> (use <literal>req.headersIn</literal> -or <literal>req.headersOut</literal>) -</para> -</listitem> - -<listitem> -<para> -<literal>req.response</literal> -</para> -</listitem> - -</list> -The deprecated properties will be removed in next releases. -</para> -</listitem> - -<listitem> -<para> -Feature: -HTTP <link doc="njs_api.xml" id="r_internal_redirect">internalRedirect()</link> -method. -</para> -</listitem> - -</list> -</para> - -<para> -Core: -<list type="bullet"> - -<listitem> -<para> -Bugfix: -fixed heap-buffer-overflow in <literal>crypto.createHmac()</literal>. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.2.1" name="Changes with 0.2.1"> - -<para> -Release Date: -31 May 2018 -</para> - -<para> -nginx modules: -<list type="bullet"> - -<listitem> -<para> -Feature: -HTTP request body getter. -</para> -</listitem> - -<listitem> -<para> -Improvement: -moved njs vm to the <literal>main</literal> configuration. -</para> -</listitem> - -<listitem> -<para> -Improvement: -improved logging for -<link doc="../http/ngx_http_js_module.xml" id="js_set"/> and -<link doc="../http/ngx_http_js_module.xml" id="js_content"/> directives. -</para> -</listitem> - -<listitem> -<para> -Improvement: -setting status code to 500 by default in the -<link doc="../http/ngx_http_js_module.xml" id="js_content"/> handler -</para> -</listitem> - -<listitem> -<para> -Improvement: -added the debug for the returned status code in -<link doc="../http/ngx_http_js_module.xml" id="js_content"/> handler -</para> -</listitem> - -<listitem> -<para> -Bugfix: fixed error logging in -<link doc="../http/ngx_http_js_module.xml" id="js_include"/>. -</para> -</listitem> - -</list> -</para> - -<para> -Core: -<list type="bullet"> - -<listitem> -<para> -Feature: -added array length setter. -</para> -</listitem> - -<listitem> -<para> -Improvement: -public header <literal>cleanup. njscript.h</literal> is renamed to -<literal>njs.h</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed crypto <literal>update()</literal> method after -<literal>digest()</literal> is called. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>crypto.createHmac()</literal> for keys with size <= alg size -and > 64. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>JSON.stringify()</literal> for arrays with empty cells. -</para> -</listitem> - -<listitem> -<para> - Bugfix: -fixed exception type for unsupported types in -<literal>JSON.stringify()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed handling of undefined arguments of functions. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed handling of missing <literal>arg</literal> of -<literal>Object.getOwnPropertyDescriptor()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed handling of properties in -<literal>Object.getOwnPropertyDescriptor()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed the writeable flag of <literal>Array.length</literal> property. -</para> -</listitem> - -<listitem> -<para> -Bugfix: fixed return value type of <literal>clearTimeout()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -fixed <literal>njs_vm_external_bind()</literal>. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous additional bugs have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.2.0" name="Changes with 0.2.0"> - -<para> -Release Date: -3 Apr 2018 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -reporting njs version by CLI. -</para> -</listitem> - -<listitem> -<para> -Feature: -textual description for type converting exceptions. -</para> -</listitem> - -<listitem> -Feature: -<literal>setTimeout()</literal> and -<literal>clearTimeout()</literal> methods. -</listitem> - -<listitem> -<para> -Feature: -Byte string to -<literal>hex</literal>, -<literal>base64</literal>, -<literal>base64url</literal> encodings. -</para> -</listitem> - -<listitem> -<para> -Feature: -<link url="https://nodejs.org/api/crypto.html#crypto_class_hash">Node.js style</link> -<literal>Crypto</literal> methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -HTTP and stream -<literal>warn()</literal> and -<literal>error()</literal> methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -HTTP <literal>subrequest()</literal> method. -</para> -</listitem> - -<listitem> -<para> -Feature: -HTTP <literal>return()</literal> method. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs have been fixed in the core and -interactive shell. -</para> -</listitem> - -</list> -</para> - -</section> - -<section id="njs0.1.15" name="Changes with 0.1.15"> - -<para> -Release Date: -20 Nov 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -<literal>Error</literal>, -<literal>EvalError</literal>, -<literal>InternalError</literal>, -<literal>RangeError</literal>, -<literal>ReferenceError</literal>, -<literal>SyntaxError</literal>, -<literal>TypeError</literal>, -<literal>URIError</literal> objects. -</para> -</listitem> - -<listitem> -<para> -Feature: -octal literals support. -</para> -</listitem> - -<listitem> -<para> -Feature: -<link url="https://nodejs.org/api/fs.html#fs_file_system">Node.js style</link> -<literal>File system</literal> access methods: -<literal>fs.readFile()</literal>, -<literal>fs.readFileSync()</literal>, -<literal>fs.appendFile()</literal>, -<literal>fs.appendFileSync()</literal>, -<literal>fs.writeFile()</literal>, -<literal>fs.writeFileSync()</literal>. -</para> -</listitem> - -<listitem> -<para> -Feature: -nginx modules print backtrace on exception. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.14" name="Changes with 0.1.14"> - -<para> -Release Date: -09 Oct 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -JSON object. -</para> -</listitem> - -<listitem> -<para> -Feature: -object level completions in interactive shell. -</para> -</listitem> - -<listitem> -<para> -Feature: -various configure improvements. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs have been fixed in the core and -interactive shell. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.13" name="Changes with 0.1.13"> - -<para> -Release Date: -31 Aug 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -<literal>console.log()</literal> and -<literal>console.help()</literal> -methods in interactive shell. -</para> -</listitem> - -<listitem> -<para> -Feature: -interactive shell prints backtrace on exception. -</para> -</listitem> - -<listitem> -<para> -Feature: -interactive shell by default -if <literal>libedit</literal> is available. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -processing of large files from -<literal>stdin</literal> in command line mode. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -improved <literal>editline</literal> detection. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.12" name="Changes with 0.1.12"> - -<para> -Release Date: -08 Aug 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -Interactive shell. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -in <literal>Object.isSealed()</literal>. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.11" name="Changes with 0.1.11"> - -<para> -Release Date: -27 Jun 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -<literal>Object.keys()</literal>, -<literal>Object.prototype.hasOwnProperty()</literal> -methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -<literal>Object.defineProperty()</literal>, -<literal>Object.defineProperties()</literal>, -<literal>Object.getOwnPropertyDescriptor()</literal> -methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -<literal>Object.getPrototypeOf()</literal>, -<literal>Object.prototype.isPrototypeOf()</literal> -methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -<literal>Object.preventExtensions()</literal>, -<literal>Object.isExtensible()</literal>, -<literal>Object.freeze()</literal>, -<literal>Object.isFrozen()</literal>, -<literal>Object.seal()</literal>, -<literal>Object.isSealed()</literal> -methods. -</para> -</listitem> - -<listitem> -<para> -Feature: -scientific notation (<literal>3.35e10</literal>) literals support. -</para> -</listitem> - -<listitem> -<para> -Feature: -hexadecimal (<literal>0x1123</literal>) literals support. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -processing of large array indexes. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -in <literal>parseInt()</literal> and -<literal>Date.parse()</literal>. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.10" name="Changes with 0.1.10"> - -<para> -Release Date: -04 Apr 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Feature: -nested functions and function closures. -</para> -</listitem> - -<listitem> -<para> -Feature: -<literal>Array.of()</literal>, -<literal>Array.prototype.fill()</literal>, -<literal>Array.prototype.find()</literal>, -<literal>Array.prototype.findIndex()</literal> -methods. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs and segmentation faults have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.9" name="Changes with 0.1.9"> - -<para> -Release Date: -01 Feb 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Bugfix: -global variables were not initialized when njs was used -in nginx. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.8" name="Changes with 0.1.8"> - -<para> -Release Date: -24 Jan 2017 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Change: -the <literal>strict</literal> mode is enforced, -variables must be explicitly declared. -</para> -</listitem> - - -<listitem> -<para> -Feature: -<literal>for</literal> and -<literal>for-in</literal> loops support variable declaration. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -global and function scopes have been fixed. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -now <literal>for-in</literal> loop does not discard the last value -of property variable. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs and segmentation faults have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.7" name="Changes with 0.1.7"> - -<para> -Release Date: -27 Dec 2016 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Change: -the <link doc="../http/ngx_http_js_module.xml" id="js_include"/> directive -has been disabled at server and location levels. -</para> -</listitem> - -<listitem> -<para> -Feature: -exponentiation operators. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs and segmentation faults have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - - -<section id="njs0.1.6" name="Changes with 0.1.6"> - -<para> -Release Date: -13 Dec 2016 -</para> - -<para> -<list type="bullet"> - -<listitem> -<para> -Change: -the <link doc="../http/ngx_http_js_module.xml" id="js_set"/> directive -has been disabled at server and location levels. -</para> -</listitem> - -<listitem> -<para> -Feature: -ES6 <literal>Math</literal> methods. -</para> -</listitem> - -<listitem> -<para> -Bugfix: -miscellaneous bugs and segmentation faults have been fixed. -</para> -</listitem> - -</list> -</para> - -</section> - -</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/njs/reference.xml Mon Sep 24 19:24:04 2018 +0300 @@ -0,0 +1,1281 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> + +<article name="Reference" + link="/en/docs/njs/reference.html" + lang="en" + rev="9"> + +<section id="summary"> + +<para> +<link doc="index.xml">njs</link> provides objects, methods and properties +for extending nginx functionality. +</para> + +</section> + + +<section id="core" name="Core"> + + +<section id="string" name="String"> + +<para> +There are two types of strings: +a <literal>Unicode string</literal> (default) and +a <literal>byte string</literal>. +</para> + +<para> +A <literal>Unicode string</literal> corresponds to an ECMAScript string +which contains Unicode characters. +</para> + +<para> +<literal>Byte strings</literal> contain a sequence of bytes. +They are used to serialize Unicode strings +to external data and deserialize from external sources. +For example, the <link id="string_toutf8">toUTF8()</link> method serializes +a Unicode string to a byte string using UTF8 encoding: +<example> +>> '£'.toUTF8().toString('hex') +'c2a3' /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */ +</example> +The <link id="string_tobytes">toBytes()</link> method serializes +a Unicode string with code points up to 255 into a byte string, +otherwise, <literal>null</literal> is returned: +<example> +>> '£'.toBytes().toString('hex') +'a3' /* a3 is a byte equal to 00A3 ('£') code point */ +</example> +Only byte strings can be converted to different encodings. +For example, a string cannot be encoded to <literal>hex</literal> directly: +<example> +>> 'αβγδ'.toString('base64') +TypeError: argument must be a byte string + at String.prototype.toString (native) + at main (native) +</example> +To convert a Unicode string to hex, +first, it should be converted to a byte string and then to hex: +<example> +>> 'αβγδ'.toUTF8().toString('base64') +'zrHOss6zzrQ=' +</example> + +<list type="tag"> + +<tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value> +| <value>string</value>, <value>encoding</value>)</literal></tag-name> +<tag-desc> +(njs specific) Creates a byte string either from an array that contains octets, +or from an encoded string (0.2.3). +The encoding can be +<literal>hex</literal>, +<literal>base64</literal>, and +<literal>base64url</literal>. +<example> +>> String.bytesFrom([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]) +'buffer' + +>> String.bytesFrom('YnVmZmVy', 'base64') +'buffer' +</example> +</tag-desc> + +<tag-name><literal>String.fromCodePoint(<value>codePoint1</value>[, ...[, +<value>codePoint2</value>]])</literal></tag-name> +<tag-desc> +Returns a string from one or more Unicode code points. +<example> +>> String.fromCodePoint(97, 98, 99, 100) +'abcd' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.concat(<value>string1</value>[, ..., +<value>stringN</value>])</literal></tag-name> +<tag-desc> +Returns a string that contains the concatenation of specified +<literal>strings</literal>. +<example> +>> "a".concat("b", "c") +'abc' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.endsWith(<value>searchString</value>[, +<value>length</value>])</literal></tag-name> +<tag-desc> +Returns <literal>true</literal> if a string ends with the characters +of a specified string, otherwise <literal>false</literal>. +The optional <literal>length</literal> parameter is the the length of string. +If omitted, the default value is the length of the string. +<example> +>> 'abc'.endsWith('abc') +true +>> 'abca'.endsWith('abc') +false +</example> +</tag-desc> + +<tag-name><literal>String.prototype.fromBytes(<value>start</value>[, +<value>end</value>])</literal></tag-name> +<tag-desc> +(njs specific) Returns a new Unicode string from a byte string +where each byte is replaced with a corresponding Unicode code point. +</tag-desc> + +<tag-name><literal>String.prototype.fromUTF8(<value>start</value>[, +<value>end</value>])</literal></tag-name> +<tag-desc> +(njs specific) Converts a byte string containing a valid UTF8 string +into a Unicode string, +otherwise <literal>null</literal> is returned. +</tag-desc> + +<tag-name><literal>String.prototype.includes(<value>searchString</value>[, +<value>position</value>]))</literal></tag-name> +<tag-desc> +Returns <literal>true</literal> if a string is found within another string, +otherwise <literal>false</literal>. +The optional <literal>position</literal> parameter is the position +within the string at which to begin search for <literal>searchString</literal>. +Default value is 0. +<example> +>> 'abc'.includes('bc') +true +</example> +</tag-desc> + +<tag-name><literal>String.prototype.indexOf(<value>searchString</value>[, +<value>fromIndex</value>])</literal></tag-name> +<tag-desc> +Returns the position of the first occurrence +of the <literal>searchString</literal> +The search is started at <literal>fromIndex</literal>. +Returns <value>-1</value> if the value is not found. +The <literal>fromIndex</literal> is an integer, +default value is 0. +If <literal>fromIndex</literal> is lower than 0 +or greater than +<link id="string_length">String.prototype.length</link><value></value>, +the search starts at index <value>0</value> and +<value>String.prototype.length</value>. +<example> +>> 'abcdef'.indexOf('de', 2) +3 +</example> +</tag-desc> + +<tag-name><literal>String.prototype.lastIndexOf(<value>searchString</value>[, +<value>fromIndex</value>])</literal></tag-name> +<tag-desc> +Returns the position of the last occurrence +of the <literal>searchString</literal>, +searching backwards from <literal>fromIndex</literal>. +Returns <value>-1</value> if the value is not found. +If <literal>searchString</literal> is empty, +then <literal>fromIndex</literal> is returned. +<example> +>> "nginx".lastIndexOf("gi") +1 +</example> +</tag-desc> + +<tag-name id="string_length"><literal>String.prototype.length</literal></tag-name> +<tag-desc> +Returns the length of the string. +<example> +>> 'αβγδ'.length +4 +</example> +</tag-desc> + +<tag-name><literal>String.prototype.match([<value>regexp</value>])</literal></tag-name> +<tag-desc> +Matches a string against a <literal>regexp</literal>. +<example> +>> 'nginx'.match( /ng/i ) +'ng' +</example> +</tag-desc> + +<tag-name id="string_padend"><literal>String.prototype.padEnd(<value>length</value> +[, <value>string</value>])</literal></tag-name> +<tag-desc> +Returns a string of a specified <literal>length</literal> +with the pad <literal>string</literal> applied +to the end of the specified string (0.2.3). +<example> +>> '1234'.padEnd(8, 'abcd') +'1234abcd' +</example> +</tag-desc> + +<tag-name id="string_padstart"><literal>String.prototype.padStart(<value>length</value> +[, <value>string</value>])</literal></tag-name> +<tag-desc> +Returns a string of a specified <literal>length</literal> +with the pad <literal>string</literal> applied +to the start of the specified string (0.2.3). +<example> +>> '1234'.padStart(8, 'abcd') +'abcd1234' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.repeat(<value>number</value>)</literal></tag-name> +<tag-desc> +Returns a string +with the specified <literal>number</literal> of copies of the string. +<example> +>> 'abc'.repeat(3) +'abcabcabc' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.replace([<value>regexp</value>|<value>string</value>[, +<value>string</value>|<value>function</value>]])</literal></tag-name> +<tag-desc> +Returns a new string with matches of a pattern +(<literal>string</literal> or a <literal>regexp</literal>) +replaced by a <literal>string</literal> or a <literal>function</literal>. +<example> +>> 'abcdefgh'.replace('d', 1) +'abc1efgh' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.search([<value>regexp</value>])</literal></tag-name> +<tag-desc> +Searches for a string using a <literal>regexp</literal> +<example> +>> 'abcdefgh'.search('def') +3 +</example> +</tag-desc> + +<tag-name><literal>String.prototype.slice(<value>start</value>[, +<value>end</value>])</literal></tag-name> +<tag-desc> +Returns a new string containing a part of an +original string between <literal>start</literal> +and <literal>end</literal> or +from <literal>start</literal> to the end of the string. +<example> +>> 'abcdefghijklmno'.slice(NaN, 5) +'abcde' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.startsWith(<value>searchString</value>[, +<value>position</value>])</literal></tag-name> +<tag-desc> +Returns <literal>true</literal> if a string begins with the characters +of a specified string, otherwise <literal>false</literal>. +The optional <literal>position</literal> parameter is the position +in this string at which to begin search for <literal>searchString</literal>. +Default value is 0. +<example> +>> 'abc'.startsWith('abc') +true +> 'aabc'.startsWith('abc') +false +</example> +</tag-desc> + +<tag-name><literal>String.prototype.substr(<value>start</value>[, +<value>length</value>])</literal></tag-name> +<tag-desc> +Returns the part of the string of the specified <literal>length</literal> +from <literal>start</literal> +or from <literal>start</literal> to the end of the string. +<example> +>> 'abcdefghijklmno'.substr(3, 5) +'defgh' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.substring(<value>start</value>[, +<value>end</value>])</literal></tag-name> +<tag-desc> +Returns the part of the string between +<literal>start</literal> and <literal>end</literal> or +from <literal>start</literal> to the end of the string. +<example> +>> 'abcdefghijklmno'.substring(3, 5) +'de' +</example> +</tag-desc> + +<tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[, +end])</literal></tag-name> +<tag-desc> +(njs specific) Serializes a Unicode string to a byte string. +Returns <literal>null</literal> if a character larger than 255 is +found in the string. +</tag-desc> + +<tag-name><literal>String.prototype.toLowerCase()</literal></tag-name> +<tag-desc> +Converts a string to lower case. +The method supports only simple Unicode folding. +<example> +>> 'ΑΒΓΔ'.toLowerCase() +'αβγδ' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name> +<tag-desc> +<para> +If no <literal>encoding</literal> is specified, +returns a specified Unicode string or byte string as in ECMAScript. +</para> + +<para> +(njs specific) If <literal>encoding</literal> is specified, +encodes a <link id="string_tobytes">byte string</link> to +<literal>hex</literal>, +<literal>base64</literal>, or +<literal>base64url</literal>. +</para> +<example> +>> 'αβγδ'.toUTF8().toString('base64url') +'zrHOss6zzrQ' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.toUpperCase()</literal></tag-name> +<tag-desc> +Converts a string to upper case. +The method supports only simple Unicode folding. +<example> +>> 'αβγδ'.toUpperCase() +'ΑΒΓΔ' +</example> +</tag-desc> + +<tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[, +<value>end</value>])</literal></tag-name> +<tag-desc> +(njs specific) Serializes a Unicode string +to a byte string using UTF8 encoding. +<example> +>> 'αβγδ'.toUTF8().length +8 +>> 'αβγδ'.length +4 +</example> +</tag-desc> + +<tag-name><literal>String.prototype.trim()</literal></tag-name> +<tag-desc> +Removes whitespaces from both ends of a string. +<example> +>> ' abc '.trim() +'abc' +</example> +</tag-desc> + +<tag-name><literal>String.prototype.split(([<value>string</value>|<value>regexp</value>[, +<value>limit</value>]]))</literal></tag-name> +<tag-desc> +Returns match of a string against a <literal>regexp</literal>. +The optional <literal>limit</literal> parameter is an integer that specifies +a limit on the number of splits to be found. +<example> +>> 'abc'.split('') +[ + 'a', + 'b', + 'c' +] +</example> +</tag-desc> + +<tag-name id="encodeuri"><literal>encodeURI(<value>URI</value>)</literal></tag-name> +<tag-desc> +encodes a URI by replacing each instance of certain characters by +one, two, three, or four escape sequences +representing the UTF-8 encoding of the character +<example> +>> encodeURI('012αβγδ') +'012%CE%B1%CE%B2%CE%B3%CE%B4' +</example> +</tag-desc> + +<tag-name><literal>encodeURIComponent(<value>encodedURIString</value>)</literal></tag-name> +<tag-desc> +Encodes a URI by replacing each instance of certain characters +by one, two, three, or four escape sequences +representing the UTF-8 encoding of the character. +<example> +>> encodeURIComponent('[@?=') +'%5B%40%3F%3D' +</example> +</tag-desc> + +<tag-name><literal>decodeURI(<value>encodedURI</value>)</literal></tag-name> +<tag-desc> +Decodes a previously <link id="encodeuri">encoded</link> URI. +<example> +>> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4') +'012αβγδ' +</example> +</tag-desc> + +<tag-name><literal>decodeURIComponent(<value>decodedURIString</value>)</literal></tag-name> +<tag-desc> +Decodes an encoded component of a previously encoded URI. +<example> +>> decodeURIComponent('%5B%40%3F%3D') +'[@?=' +</example> +</tag-desc> + +</list> +</para> + +</section> + + +<section id="core_json" name="JSON"> + +<para> +The <literal>JSON</literal> object (ES 5.1) provides functions +to convert njs values to and from JSON format. +<list type="tag"> + +<tag-name><literal>JSON.parse(<value>string</value>[, +<value>reviver</value>])</literal></tag-name> +<tag-desc> +Converts a <literal>string</literal> that represents JSON data +into an njs object (<literal>{...}</literal>) or +array (<literal>[...]</literal>). +The optional <literal>reviver</literal> parameter is a function (key, value) +that will be called for each (key,value) pair and can transform the value. +</tag-desc> + +<tag-name><literal>JSON.stringify(<value>value</value>[, +<value>replacer</value>] [, <value>space</value>])</literal></tag-name> +<tag-desc> +Converts an njs object back to JSON. +The obligatory <literal>value</literal> parameter is generally a JSON +<literal>object</literal> or <literal>array</literal> that will be converted. +If the value has a <literal>toJSON()</literal> method, +it defines how the object will be serialized. +The optional <literal>replacer</literal> parameter is +a <literal>function</literal> or <literal>array</literal> +that transforms results. +The optional <literal>space</literal> parameter is +a <literal>string</literal> or <literal>number</literal>. +If it is a <literal>number</literal>, +it indicates the number of white spaces placed before a result +(no more than 10). +If it is a <literal>string</literal>, +it is used as a white space (or first 10 characters of it). +If omitted or is <literal>null</literal>, no white space is used. +</tag-desc> +</list> +</para> + +<para> +<example> +>> var json = JSON.parse('{"a":1, "b":true}') +>> json.a +1 + +>> JSON.stringify(json) +'{"a":1,"b":true}' + +>> JSON.stringify(json, undefined, 1) +'{\n "a": 1,\n "b": true\n}' + +>> JSON.stringify({ x: [10, undefined, function(){}] }) +'{"x":[10,null,null]}' + +>> JSON.stringify({"a":1, "toJSON": function() {return "xxx"}}) +'"xxx"' + +# Example with function replacer + +>> function replacer(key, value) {return (typeof value === 'string') ? undefined : value} +>>JSON.stringify({a:1, b:"b", c:true}, replacer) +'{"a":1,"c":true}' +</example> +</para> + +</section> + + +<section id="crypto" name="Crypto"> + +<para> +The Crypto module provides cryptographic functionality support. +The Crypto module object is returned by <literal>require('crypto')</literal>. +</para> + +<para> +<list type="tag"> + +<tag-name><literal>crypto.createHash(<value>algorithm</value>)</literal></tag-name> +<tag-desc> +Creates and returns a <link id="crypto_hash">Hash</link> object +that can be used to generate hash digests +using the given <value>algorithm</value>. +The algorighm can be +<literal>md5</literal>, +<literal>sha1</literal>, and +<literal>sha256</literal>. +</tag-desc> + +<tag-name><literal>crypto.createHmac(<value>algorithm</value>, +<value>secret key</value>)</literal></tag-name> +<tag-desc> +Creates and returns an <link id="crypto_hmac">HMAC</link> object +that uses the given <value>algorithm</value> and <value>secret key</value>. +The algorighm can be +<literal>md5</literal>, +<literal>sha1</literal>, and +<literal>sha256</literal>. +</tag-desc> + +</list> +</para> + + +<section id="crypto_hash" name="Hash"> + +<para> +<list type="tag"> + +<tag-name><literal>hash.update(<value>data</value>)</literal></tag-name> +<tag-desc> +Updates the hash content with the given <value>data</value>. +</tag-desc> + +<tag-name><literal>hash.digest([<value>encoding</value>])</literal></tag-name> +<tag-desc> +Calculates the digest of all of the data passed using +<literal>hash.update()</literal>. +The encoding can be +<literal>hex</literal>, +<literal>base64</literal>, and +<literal>base64url</literal>. +If encoding is not provided, a byte string is returned. +</tag-desc> + +</list> +</para> + +<para> +<example> +>> var cr = require('crypto') +undefined + +>> cr.createHash('sha1').update('A').update('B').digest('base64url') +'BtlFlCqiamG-GMPiK_GbvKjdK10' +</example> +</para> + +</section> + + +<section id="crypto_hmac" name="HMAC"> + +<para> +<list type="tag"> + +<tag-name><literal>hmac.update(<value>data</value>)</literal></tag-name> +<tag-desc> +Updates the HMAC content with the given <value>data</value>. +</tag-desc> + +<tag-name><literal>hmac.digest([<value>encoding</value>])</literal></tag-name> +<tag-desc> +Calculates the HMAC digest of all of the data passed using +<literal>hmac.update()</literal>. +The encoding can be +<literal>hex</literal>, +<literal>base64</literal>, and +<literal>base64url</literal>. +If encoding is not provided, a byte string is returned. +</tag-desc> +</list> +</para> + +<para> +<example> +>> var cr = require('crypto') +undefined + +>> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url') +'Oglm93xn23_MkiaEq_e9u8zk374' +</example> +</para> + +</section> + +</section> + +<section id="njs_api_timers" name="Timers"> + +<para> + +<list type="tag"> + +<tag-name id="cleartimeout"><literal>clearTimeout(<value>timeout</value>)</literal></tag-name> +<tag-desc> +Cancels a <literal>timeout</literal> object +created by <link id="settimeout">setTimeout()</link>. +</tag-desc> + +<tag-name id="settimeout"><literal>setTimeout(<value>function</value>, +<value>ms</value>[, <value>arg1</value>, <value>argN</value>])</literal></tag-name> +<tag-desc> +Calls a <literal>function</literal> +after a specified number of <literal>milliseconds</literal>. +One or more optional <literal>arguments</literal> +can be passed to the specified function. +Returns a <literal>timeout</literal> object. +<example> +function handler(v) +{ + // ... +} + +t = setTimeout(handler, 12); + +// ... + +clearTimeout(t); +</example> +</tag-desc> + +</list> +</para> + +</section> + + +<section id="njs_api_fs" name="File System"> + +<para> +The File System module provides operations with files. +The module object is returned by <literal>require('fs')</literal>. +<list type="tag"> + +<tag-name id="appendfilesync"><literal>appendFileSync(<value>filename</value>, +<value>data</value>[, <value>options</value>])</literal></tag-name> +<tag-desc> +Synchronously appends specified <literal>data</literal> +to a file with provided <literal>filename</literal>. +If the file does not exist, it will be created. +The <literal>options</literal> parameter is expected to be +an object with the following keys: +<list type="tag"> + +<tag-name><literal>mode</literal></tag-name> +<tag-desc> +mode option, by default is <literal>0o666</literal> +</tag-desc> + +<tag-name><literal>flag</literal></tag-name> +<tag-desc> +file system <link id="njs_api_fs_flags">flag</link>, +by default is <literal>a</literal> +</tag-desc> + +</list> +</tag-desc> + +<tag-name id="readfilesync"><literal>readFileSync(<value>filename</value>[, +<value>options</value>])</literal></tag-name> +<tag-desc> +Synchronously returns the contents of the file +with provided <literal>filename</literal>. +The <literal>options</literal> parameter holds +<literal>string</literal> that specifies encoding. +If not specified, a <link id="string_tobytes">byte string</link> is returned. +If <literal>utf8</literal> encoding is specified, a Unicode string is returned. +Otherwise, <literal>options</literal> is expected to be +an object with the following keys: +<list type="tag"> + +<tag-name><literal>encoding</literal></tag-name> +<tag-desc> +encoding, by default is not specified. +The encoding can be <literal>utf8</literal> +</tag-desc> + +<tag-name><literal>flag</literal></tag-name> +<tag-desc> +file system <link id="njs_api_fs_flags">flag</link>, +by default is <literal>r</literal> +</tag-desc> + +</list> +<example> +>> var fs = require('fs') +undefined +>> var file = fs.readFileSync('/file/path.tar.gz') +undefined +>> var gzipped = /^\x1f\x8b/.test(file); gzipped +true +</example> +</tag-desc> + +<tag-name id="writefilesync"><literal>writeFileSync(<value>filename</value>, +<value>data</value>[, +<value>options</value>])</literal></tag-name> +<tag-desc> +Synchronously writes <literal>data</literal> to a file +with provided <literal>filename</literal>. +If the file does not exist, it will be created, +if the file exists, it will be replaced. +The <literal>options</literal> parameter is expected to be +an object with the following keys: +<list type="tag"> +<tag-name><literal>mode</literal></tag-name> +<tag-desc> +mode option, by default is <literal>0o666</literal> +</tag-desc> + +<tag-name><literal>flag</literal></tag-name> +<tag-desc> +file system <link id="njs_api_fs_flags">flag</link>, +by default is <literal>w</literal> +</tag-desc> + +</list> +<example> +>> var fs = require('fs') +undefined +>> var file = fs.writeFileSync('hello.txt', 'Hello world') +undefined +</example> +</tag-desc> + +</list> +</para> + + +<section id="njs_api_fs_flags" name="File System Flags"> + +<para> +The <literal>flag</literal> option can accept the following values: + +<list type= "bullet" compact="no"> + +<listitem> +<literal>a</literal>—open a file for appending. +The file is created if it does not exist +</listitem> + +<listitem> +<literal>ax</literal>—the same as <literal>a</literal> +but fails if the file already exists +</listitem> + +<listitem> +<literal>a+</literal>—open a file for reading and appending. +If the file does not exist, it will be created +</listitem> + +<listitem> +<literal>ax+</literal>—the same as <literal>a+</literal> +but fails if the file already exists +</listitem> + +<listitem> +<literal>as</literal>—open a file for appending in synchronous mode. +If the file does not exist, it will be created +</listitem> + +<listitem> +<literal>as+</literal>—open a file for reading and appending +in synchronous mode. +If the file does not exist, it will be created +</listitem> + +<listitem> +<literal>r</literal>—open a file for reading. +An exception occurs if the file does not exist +</listitem> + +<listitem> +<literal>r+</literal>—open a file for reading and writing. +An exception occurs if the file does not exist +</listitem> + +<listitem> +<literal>rs+</literal>—open a file for reading and writing +in synchronous mode. +Instructs the operating system to bypass the local file system cache +</listitem> + +<listitem> +<literal>w</literal>—open a file for writing. +If the file does not exist, it will be created. +If the file exists, it will be replaced +</listitem> + +<listitem> +<literal>wx</literal>—the same as <literal>w</literal> +but fails if the file already exists +</listitem> + +<listitem> +<literal>w+</literal>—open a file for reading and writing. +If the file does not exist, it will be created. +If the file exists, it will be replaced +</listitem> + +<listitem> +<literal>wx+</literal>—the same as <literal>w+</literal> +but fails if the file already exists +</listitem> + +</list> +</para> + +</section> + +</section> + +</section> + + +<section id="http" name="HTTP Request"> + +<para> +The HTTP request object is available only in the +<link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link> module. +All string properties of the object are <link id="string">byte strings</link>. + +<list type="tag"> + +<tag-name><literal>r.args{}</literal></tag-name> +<tag-desc> +request arguments object, read-only +</tag-desc> + +<tag-name><literal>r.error(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a <literal>string</literal> to the error log +on the <literal>error</literal> level of logging +</tag-desc> + +<tag-name><literal>r.finish()</literal></tag-name> +<tag-desc> +finishes sending a response to the client +</tag-desc> + +<tag-name><literal>r.headersIn{}</literal></tag-name> +<tag-desc> +incoming headers object, read-only. +<para> +For example, the <literal>Foo</literal> header +can be accessed with the syntax <literal>headersIn.foo</literal> +or <literal>headersIn['Foo']</literal> +</para> +</tag-desc> + +<tag-name><literal>r.headersOut{}</literal></tag-name> +<tag-desc> +outgoing headers object, writable. +<para> +For example, the <literal>Foo</literal> header +can be accessed with the syntax <literal>headersOut.foo</literal> +or <literal>headersOut['Foo']</literal> +</para> +</tag-desc> + +<tag-name><literal>r.httpVersion</literal></tag-name> +<tag-desc> +HTTP version, read-only +</tag-desc> + +<tag-name><literal>r.log(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a <literal>string</literal> to the error log +on the <literal>info</literal> level of logging +</tag-desc> + +<tag-name id="r_internal_redirect"><literal>r.internalRedirect(<value>uri</value>)</literal></tag-name> +<tag-desc> +performs an internal redirect to the specified <literal>uri</literal>. +If the uri starts with the “<literal>@</literal>” prefix, +it is considered a named location. +</tag-desc> + +<tag-name><literal>r.method</literal></tag-name> +<tag-desc> +HTTP method, read-only +</tag-desc> + +<tag-name><literal>r.parent</literal></tag-name> +<tag-desc> +references the parent request object +</tag-desc> + +<tag-name><literal>r.remoteAddress</literal></tag-name> +<tag-desc> +client address, read-only +</tag-desc> + +<tag-name><literal>r.requestBody</literal></tag-name> +<tag-desc> +holds the request body, read-only +</tag-desc> + +<tag-name><literal>r.responseBody</literal></tag-name> +<tag-desc> +holds the <link id="subrequest">subrequest</link> response body, read-only. +The size of <literal>r.responseBody</literal> is limited by the +<link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/> +directive. +</tag-desc> + +<tag-name><literal>r.return(status[, string])</literal></tag-name> +<tag-desc> +sends the entire response +with the specified <literal>status</literal> to the client +<para> +It is possible to specify either a redirect URL +(for codes 301, 302, 303, 307, and 308) +or the response body text (for other codes) as the second argument +</para> +</tag-desc> + +<tag-name><literal>r.send(<value>string</value>)</literal></tag-name> +<tag-desc> +sends a part of the response body to the client +</tag-desc> + +<tag-name><literal>r.sendHeader()</literal></tag-name> +<tag-desc> +sends the HTTP headers to the client +</tag-desc> + +<tag-name><literal>r.status</literal></tag-name> +<tag-desc> +status, writable +</tag-desc> + +<tag-name><literal>r.variables{}</literal></tag-name> +<tag-desc> +nginx variables object, read-only +</tag-desc> + +<tag-name><literal>r.warn(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a <literal>string</literal> to the error log +on the <literal>warning</literal> level of logging +</tag-desc> + +<tag-name><literal>r.uri</literal></tag-name> +<tag-desc> +current URI, read-only +</tag-desc> + +<tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, +<value>options</value>[, <value>callback</value>]])</literal></tag-name> +<tag-desc> +creates a subrequest with the given <literal>uri</literal> and +<literal>options</literal>, and installs +an optional completion <literal>callback</literal>. + +<para> +If <literal>options</literal> is a string, then it +holds the subrequest arguments string. +Otherwise, <literal>options</literal> is expected to be +an object with the following keys: +<list type="tag"> +<tag-name><literal>args</literal></tag-name> +<tag-desc> +arguments string +</tag-desc> +<tag-name><literal>body</literal></tag-name> +<tag-desc> +request body +</tag-desc> + +<tag-name><literal>method</literal></tag-name> +<tag-desc> +HTTP method +</tag-desc> + +</list> +</para> + +<para> +The completion <literal>callback</literal> receives +a subrequest response object with methods and properties +identical to the parent request object. +</para> +</tag-desc> + +</list> +</para> + +</section> + + +<section id="stream" name="Stream Session"> + +<para> +The stream session object is available only in the +<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link> +module. +All string properties of the object are <link id="string">byte strings</link>. +</para> + +<para> +<note> +Prior to njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the stream session object had some properties which are currently +<link id="stream_obsolete">removed</link>. +</note> +</para> + +<para> +<list type="tag"> + +<tag-name id="s_allow"><literal>s.allow()</literal></tag-name> +<tag-desc> +successfully finalizes the phase handler +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) +</tag-desc> + +<tag-name id="s_decline"><literal>s.decline()</literal></tag-name> +<tag-desc> +finalizes the phase handler and passes control to the next handler +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) +</tag-desc> + +<tag-name id="s_deny"><literal>s.deny()</literal></tag-name> +<tag-desc> +finalizes the phase handler with the access error code +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) +</tag-desc> + +<tag-name id="s_done"><literal>s.done</literal>(<value>[code]</value>)</tag-name> +<tag-desc> +successfully finalizes the current phase handler +or finalizes it with the specified numeric code +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). +</tag-desc> + +<tag-name><literal>s.error(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a sent <literal>string</literal> to the error log +on the <literal>error</literal> level of logging +</tag-desc> + +<tag-name><literal>s.log(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a sent <value>string</value> to the error log +on the <literal>info</literal> level of logging +</tag-desc> + +<tag-name id="s_off"><literal>s.off(<value>eventName</value>)</literal></tag-name> +<tag-desc> +unregisters the callback set by the <link id="s_on">s.on()</link> method +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>) +</tag-desc> + +<tag-name id="s_on"><literal>s.on(<value>event</value>, +<value>callback</value>)</literal></tag-name> +<tag-desc> +registers a <literal>callback</literal> for the specified <literal>event</literal> +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). + +<para> +An <literal>event</literal> may be one of the following strings: +<list type="tag"> +<tag-name><literal>upload</literal></tag-name> +<tag-desc> +new data from a client +</tag-desc> + +<tag-name><literal>download</literal></tag-name> +<tag-desc> +new data to a client +</tag-desc> + +</list> +</para> + +<para> +The completion callback has the following prototype: +<literal>callback(data, flags)</literal>, where +<literal>data</literal> is string, +<literal>flags</literal> is an object +with the following properties: +<list type="tag"> +<tag-name id="s_on_callback_last"><literal>last</literal></tag-name> +<tag-desc> +a boolean value, true if data is a last buffer. +</tag-desc> + +</list> +</para> +</tag-desc> + +<tag-name><literal>s.remoteAddress</literal></tag-name> +<tag-desc> +client address, read-only +</tag-desc> + +<tag-name id="s_send"><literal>s.send(<value>data</value>[, +<value>options</value>])</literal></tag-name> +<tag-desc> +sends the data to the client +(<link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>). +The <literal>options</literal> is an object used +to override nginx buffer flags derived from an incoming data chunk buffer. +The flags can be overriden with the following flags: +<para> +<list type="tag"> + +<tag-name><literal>last</literal></tag-name> +<tag-desc> +boolean, true if the buffer is the last buffer +</tag-desc> + +<tag-name><literal>flush</literal></tag-name> +<tag-desc> +boolean, true if the buffer should have the <literal>flush</literal> flag +</tag-desc> +</list> +</para> +The method can be called multiple times per callback invocation. +</tag-desc> + +<tag-name><literal>s.variables{}</literal></tag-name> +<tag-desc> +nginx variables object, read-only +</tag-desc> + +<tag-name><literal>s.warn(<value>string</value>)</literal></tag-name> +<tag-desc> +writes a sent <literal>string</literal> to the error log +on the <literal>warning</literal> level of logging +</tag-desc> + +</list> +</para> + + +<section id="stream_obsolete" name="Obsolete properties"> + +<para> +These properties have been removed +in njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link> +and are not backward compatible with the existing njs code. +</para> + +<para> +<list type="tag"> + +<tag-name id="s_abort"><literal>s.ABORT</literal></tag-name> +<tag-desc> +the <literal>ABORT</literal> return code +<note> +Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the <link id="s_deny">s.deny()</link> method should be used instead. +</note> +</tag-desc> + +<tag-name><literal>s.AGAIN</literal></tag-name> +<tag-desc> +the <literal>AGAIN</literal> return code +<note> +Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the corresponding behavior is achieved if no +<link id="s_allow">s.allow()</link>, +<link id="s_deny">s.deny()</link>, +<link id="s_decline">s.decline()</link>, +<link id="s_done">s.done()</link> +is invoked and a callback is registered. +</note> +</tag-desc> + +<tag-name id="s_buffer"><literal>s.buffer</literal></tag-name> +<tag-desc> +the current buffer, writable +<note> +Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the <link id="s_send">s.send()</link> method should be used for writing. +For reading, the current buffer is available as the first argument of the +<literal>event</literal> callback. +</note> +</tag-desc> + +<tag-name><literal>s.DECLINED</literal></tag-name> +<tag-desc> +the <literal>DECLINED</literal> return code +<note> +Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the <link id="s_decline">s.decline()</link> method should be used instead. +</note> +</tag-desc> + +<tag-name><literal>s.eof</literal></tag-name> +<tag-desc> +a boolean read-only property, true if the current buffer is the last buffer +<note> +Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the <link id="s_on_callback_last">flags.last</link> property +should be used instead. +</note> +</tag-desc> + +<tag-name><literal>s.ERROR</literal></tag-name> +<tag-desc> +the <literal>ERROR</literal> return code +<note> +Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +an appropriate exception can be thrown to report an error. +</note> +</tag-desc> + +<tag-name><literal>s.fromUpstream</literal></tag-name> +<tag-desc> +a boolean read-only property, +true if the current buffer is from the upstream server to the client +<note> +Starting from <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +a corresponding <link id="s_on">event</link> +(<literal>upload</literal> or <literal>download</literal>) +should be used to handle data to or from client. +</note> +</tag-desc> + +<tag-name id="s_ok"><literal>s.OK</literal></tag-name> +<tag-desc> +the <literal>OK</literal> return code +<note> +Starting from njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>, +the <link id="s_allow">s.allow()</link> method should be used instead. +</note> +</tag-desc> + +</list> +</para> + +</section> + +</section> + + +</article>
--- a/xml/en/docs/stream/ngx_stream_js_module.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/en/docs/stream/ngx_stream_js_module.xml Mon Sep 24 19:24:04 2018 +0300 @@ -33,8 +33,8 @@ <para> <note> This example is valid for -njs <link doc="../njs/njs_changes.xml" id="njs-0.2.4">0.2.4</link>. -For njs <link doc="../njs/njs_changes.xml" id="njs-0.2.3">0.2.3</link> +njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link>. +For njs <link doc="../njs/changes.xml" id="njs0.2.3">0.2.3</link> and earlier, use <link doc="../njs/examples.xml" id="legacy">this</link> example. </note> @@ -208,7 +208,7 @@ <para> Each stream njs handler receives one argument, a stream session -<link doc="../njs/njs_api.xml" id="stream_session">object</link>. +<link doc="../njs/reference.xml" id="stream">object</link>. </para> </section>
--- a/xml/index.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/index.xml Mon Sep 24 19:24:04 2018 +0300 @@ -36,14 +36,14 @@ <para> <link doc="en/docs/njs/index.xml">njs-0.2.4</link> version has been released, featuring -<link doc="en/docs/njs/njs_api.xml" id="s_on">s.on()</link>, -<link doc="en/docs/njs/njs_api.xml" id="s_off">s.off()</link>, -<link doc="en/docs/njs/njs_api.xml" id="s_allow">s.allow()</link>, -<link doc="en/docs/njs/njs_api.xml" id="s_done">s.done()</link>, -<link doc="en/docs/njs/njs_api.xml" id="s_decline">s.decline()</link>, -<link doc="en/docs/njs/njs_api.xml" id="s_deny">s.deny()</link> +<link doc="en/docs/njs/reference.xml" id="s_on">s.on()</link>, +<link doc="en/docs/njs/reference.xml" id="s_off">s.off()</link>, +<link doc="en/docs/njs/reference.xml" id="s_allow">s.allow()</link>, +<link doc="en/docs/njs/reference.xml" id="s_done">s.done()</link>, +<link doc="en/docs/njs/reference.xml" id="s_decline">s.decline()</link>, +<link doc="en/docs/njs/reference.xml" id="s_deny">s.deny()</link> methods support -and <link doc="en/docs/njs/njs_changes.xml" id="njs0.2.4">more</link>. +and <link doc="en/docs/njs/changes.xml" id="njs0.2.4">more</link>. </para> </event> @@ -58,11 +58,11 @@ <para> <link doc="en/docs/njs/index.xml">njs-0.2.3</link> version has been released, featuring -<link doc="en/docs/njs/njs_api.xml" id="string_bytesfrom">String.bytesFrom()</link>, -<link doc="en/docs/njs/njs_api.xml" id="string_padstart">String.padStart()</link>, -<link doc="en/docs/njs/njs_api.xml" id="string_padend">String.padEnd()</link> +<link doc="en/docs/njs/reference.xml" id="string_bytesfrom">String.bytesFrom()</link>, +<link doc="en/docs/njs/reference.xml" id="string_padstart">String.padStart()</link>, +<link doc="en/docs/njs/reference.xml" id="string_padend">String.padEnd()</link> methods support -and <link doc="en/docs/njs/njs_changes.xml" id="njs0.2.3">more</link>. +and <link doc="en/docs/njs/changes.xml" id="njs0.2.3">more</link>. </para> </event> @@ -95,9 +95,9 @@ <para> <link doc="en/docs/njs/index.xml">njs-0.2.2</link> version has been released, featuring HTTP -<link doc="en/docs/njs/njs_api.xml" id="r_internal_redirect">internalRedirect()</link> +<link doc="en/docs/njs/reference.xml" id="r_internal_redirect">internalRedirect()</link> method support -and <link doc="en/docs/njs/njs_changes.xml" id="njs0.2.2">more</link>. +and <link doc="en/docs/njs/changes.xml" id="njs0.2.2">more</link>. </para> </event> @@ -121,7 +121,7 @@ <para> <link doc="en/docs/njs/index.xml">njs-0.2.1</link> version has been -<link doc="en/docs/njs/njs_changes.xml" id="njs0.2.1">released</link>. +<link doc="en/docs/njs/changes.xml" id="njs0.2.1">released</link>. </para> </event> @@ -180,9 +180,9 @@ <para> <link doc="en/docs/njs/index.xml">njs-0.2.0</link> version has been released, featuring HTTP -<link doc="en/docs/njs/njs_api.xml" id="subrequest">subrequest()</link> +<link doc="en/docs/njs/reference.xml" id="subrequest">subrequest()</link> method support -and <link doc="en/docs/njs/njs_changes.xml" id="njs0.2.0">more</link>. +and <link doc="en/docs/njs/changes.xml" id="njs0.2.0">more</link>. </para> </event>
--- a/xml/ru/GNUmakefile Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/ru/GNUmakefile Mon Sep 24 19:24:04 2018 +0300 @@ -107,11 +107,11 @@ stream/stream_processing \ ngx_google_perftools_module \ njs/index \ - njs/njs_api \ njs/cli \ njs/compatibility \ njs/examples \ njs/install \ + njs/reference \ TOP = \ download \
--- a/xml/ru/docs/http/ngx_http_js_module.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/ru/docs/http/ngx_http_js_module.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <module name="Модуль ngx_http_js_module" link="/ru/docs/http/ngx_http_js_module.html" lang="ru" - rev="17"> + rev="18"> <section id="summary">
--- a/xml/ru/docs/njs/cli.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/ru/docs/njs/cli.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <article name="Интерфейс командной строки" link="/ru/docs/njs/cli.html" lang="ru" - rev="1"> + rev="2"> <section> <para> @@ -21,8 +21,8 @@ <link doc="install.xml" id="install_sources">исходных файлов</link>. В отличие от njs, запущенном внутри nginx, в утилите недоступны объекты nginx -(<link doc="njs_api.xml" id="http">HTTP</link> и -<link doc="njs_api.xml" id="stream">Stream</link>). +(<link doc="reference.xml" id="http">HTTP</link> и +<link doc="reference.xml" id="stream">Stream</link>). <example> $ echo "2**3" | njs - 8
--- a/xml/ru/docs/njs/examples.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/ru/docs/njs/examples.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <article name="Примеры использования" link="/ru/docs/njs/examples.html" lang="ru" - rev="1"> + rev="2"> <section id="helloword" name="Hello World"> @@ -311,11 +311,11 @@ <section id="legacy_stream" name="Внедрение HTTP-заголовка при помощи stream proxy"> <para> -Начиная с версии njs <link doc="../njs/njs_changes.xml" id="njs0.2.4">0.2.4</link> +Начиная с версии njs <link doc="../njs/changes.xml" id="njs0.2.4">0.2.4</link> <link doc="../stream/ngx_stream_js_module.xml" id="example">пример</link> конфигурации в stream был изменён. -Для njs <link doc="../njs/njs_changes.xml" id="njs0.2.3">0.2.3</link> +Для njs <link doc="../njs/changes.xml" id="njs0.2.3">0.2.3</link> и более ранних версий необходимо использовать следующий пример конфигурации: <example> load_module modules/ngx_stream_js_module.so;
--- a/xml/ru/docs/njs/index.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/ru/docs/njs/index.xml Mon Sep 24 19:24:04 2018 +0300 @@ -9,7 +9,7 @@ <article name="Сценарный язык njs" link="/ru/docs/njs/index.html" lang="ru" - rev="24" + rev="25" toc="no"> <section id="links"> @@ -22,11 +22,11 @@ </listitem> <listitem> -<link doc="njs_changes.xml">Изменения в njs</link> +<link doc="changes.xml">Изменения в njs</link> </listitem> <listitem> -<link doc="njs_api.xml"/> +<link doc="reference.xml"/> </listitem> <listitem> @@ -123,7 +123,7 @@ <para> создать файл сценария njs, например <path>hello_world.js</path>. Описание свойств и методов языка njs -см. в <link doc="njs_api.xml">справочнике</link>. +см. в <link doc="reference.xml">справочнике</link>. <example> function hello(r) { r.return(200, “Hello world!”);
--- a/xml/ru/docs/njs/njs_api.xml Mon Sep 24 19:10:29 2018 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,525 +0,0 @@ -<?xml version="1.0"?> - -<!-- - Copyright (C) Nginx, Inc. - --> - -<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> - -<article name="njs API" - link="/ru/docs/njs/njs_api.html" - lang="ru" - rev="1"> - -<section id="summary"> - -<para> -<link doc="index.xml">njs</link> предоставляет объекты, методы и свойства -для расширения функциональности nginx. -</para> - -</section> - - -<section id="http" name="HTTP"> - -<para> -Объект <literal>HTTP</literal> доступен только в -модуле <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>. -Все строки в объекте <literal>HTTP</literal> являются -<link id="strings">байтовыми строками</link>. -</para> - - -<section id="http_request" name="Запрос"> - -<para> -<list type="tag"> - -<tag-name><literal>r.args{}</literal></tag-name> -<tag-desc> -объект аргументов запроса, только чтение -</tag-desc> - -<tag-name><literal>r.error(<value>строка</value>)</literal></tag-name> -<tag-desc> -записывает <literal>строку</literal> в лог-файл ошибок -на уровне лога <literal>error</literal> -</tag-desc> - -<tag-name><literal>r.finish()</literal></tag-name> -<tag-desc> -завершает отправку ответа клиенту -</tag-desc> - -<tag-name><literal>r.headersIn{}</literal></tag-name> -<tag-desc> -объект исходящих заголовков, только чтение. -<para> -Например, доступ к заголовку <literal>Header-Name</literal> -можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal> -или <literal>headers.Header_name</literal> -</para> -</tag-desc> - -<tag-name><literal>r.headersOut{}</literal></tag-name> -<tag-desc> -объект исходящих заголовков, доступно для записи. -<para> -Например, доступ к заголовку <literal>Header-Name</literal> -можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal> -или <literal>headers.Header_name</literal> -</para> -</tag-desc> - -<tag-name><literal>r.httpVersion</literal></tag-name> -<tag-desc> -версия HTTP, только чтение -</tag-desc> - -<tag-name><literal>r.log(<value>строка</value>)</literal></tag-name> -<tag-desc> -записывает <literal>строку</literal> в лог-файл ошибок -на уровне лога <literal>info</literal> -</tag-desc> - -<tag-name><literal>r.method</literal></tag-name> -<tag-desc> -HTTP метод, только чтение -</tag-desc> - -<tag-name><literal>r.parent</literal></tag-name> -<tag-desc> -ссылается на родительский объект запроса -</tag-desc> - -<tag-name><literal>r.remoteAddress</literal></tag-name> -<tag-desc> -адрес клиента, только чтение -</tag-desc> - -<tag-name><literal>r.requestBody</literal></tag-name> -<tag-desc> -хранит тело запроса, только чтение -</tag-desc> - -<tag-name><literal>r.responseBody</literal></tag-name> -<tag-desc> -хранит тело ответа <link id="subrequest">подзапроса</link>, только чтение -</tag-desc> - -<tag-name><literal>r.return(код[, строка])</literal></tag-name> -<tag-desc> -отправляет -клиенту полный ответ с указанным <literal>кодом</literal> -<para> -Можно задать или URL перенаправления -(для кодов 301, 302, 303, 307 и 308), -или текст тела ответа (для остальных кодов) в качестве второго аргумента -</para> -</tag-desc> - -<tag-name><literal>r.send(<value>строка</value>)</literal></tag-name> -<tag-desc> -отправляет часть тела ответа клиенту -</tag-desc> - -<tag-name><literal>r.sendHeader()</literal></tag-name> -<tag-desc> -отправляет заголовок HTTP клиенту -</tag-desc> - -<tag-name><literal>r.status</literal></tag-name> -<tag-desc> -статус, доступно для записи -</tag-desc> - -<tag-name><literal>req.variables{}</literal></tag-name> -<tag-desc> -объект переменных nginx, только чтение -</tag-desc> - -<tag-name><literal>r.warn(<value>строка</value>)</literal></tag-name> -<tag-desc> -записывает <literal>строку</literal> в лог-файл ошибок -на уровне лога <literal>warning</literal> -</tag-desc> - -<tag-name><literal>r.uri</literal></tag-name> -<tag-desc> -текущий URI, только чтение -</tag-desc> - -<tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, -<value>options</value>[, <value>callback</value>]])</literal></tag-name> -<tag-desc> -создаёт подзапрос с заданными <literal>uri</literal> и -<literal>options</literal> и -устанавливает необязательный <literal>callback</literal> завершения. - -<para> -Если <literal>options</literal> является строкой, то в ней -содержится срока аргументов подзапроса. -В противном случае ожидается, что <literal>options</literal> является объектом -со следующими ключами: - -<list type="tag"> -<tag-name><literal>args</literal></tag-name> -<tag-desc> -строка с аргументами -</tag-desc> - -<tag-name><literal>body</literal></tag-name> -<tag-desc> -тело запроса -</tag-desc> - -<tag-name><literal>method</literal></tag-name> -<tag-desc ->метод HTTP -</tag-desc> - -</list> -</para> - -<para> -<literal>callback</literal> получает -объект ответа подзапроса с методами и свойствами, -идентичными родительскому объекту запроса. -</para> -</tag-desc> - -</list> -</para> - -</section> - -</section> - - -<section id="stream" name="Stream"> - -<para> -Объект <literal>stream</literal> доступен только в -модуле -<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>. -Все строки в объекте <literal>stream</literal> являются -<link id="strings">байтовыми строками</link>. -</para> - - -<section id="stream_session" name="Сессия"> - -<para> -<list type="tag"> - -<tag-name><literal>s.remoteAddress</literal></tag-name> -<tag-desc> -адрес клиента, только чтение -</tag-desc> - -<tag-name><literal>s.eof</literal></tag-name> -<tag-desc> -логическое свойство, -true, если текущий буфер является последним буфером, -только чтение -</tag-desc> - -<tag-name><literal>s.fromUpstream</literal></tag-name> -<tag-desc> -логическое свойство, -true, если текущий буфер является буфером от проксируемого сервера к клиенту, -только чтение -</tag-desc> - -<tag-name><literal>s.buffer</literal></tag-name> -<tag-desc> -текущий буфер, доступен для записи -</tag-desc> - -<tag-name><literal>s.variables{}</literal></tag-name> -<tag-desc> -объект переменных nginx, только чтение -</tag-desc> - -<tag-name><literal>s.OK</literal></tag-name> -<tag-desc> -код <literal>OK</literal> -</tag-desc> - -<tag-name><literal>s.DECLINED</literal></tag-name> -<tag-desc> -код <literal>DECLINED</literal> -</tag-desc> - -<tag-name><literal>s.AGAIN</literal></tag-name> -<tag-desc> -код <literal>AGAIN</literal> -</tag-desc> - -<tag-name><literal>s.ERROR</literal></tag-name> -<tag-desc> -код <literal>ERROR</literal> -</tag-desc> - -<tag-name><literal>s.ABORT</literal></tag-name> -<tag-desc> -код <literal>ABORT</literal> -</tag-desc> - -<tag-name><literal>s.log(<value>строка</value>)</literal></tag-name> -<tag-desc> -записывает отправленную <value>строку</value> в лог-файл ошибок -на уровне лога <literal>info</literal> -</tag-desc> - -<tag-name><literal>s.warn(<value>строка</value>)</literal></tag-name> -<tag-desc> -записывает отправленную <literal>строку</literal> в лог-файл ошибок -на уровне лога <literal>warning</literal> -</tag-desc> - -<tag-name><literal>s.error(<value>строка</value>)</literal></tag-name> -<tag-desc> -записывает отправленную <literal>строку</literal> в лог-файл ошибок -на уровне лога <literal>error</literal> -</tag-desc> - -</list> -</para> - -</section> - -</section> - - -<section id="example" name="Примеры"> - - -<section id="example_urldecode" name="Декодирование URL"> - -<para> -<example> -js_include urldecode.js; - -js_set $decoded_foo decoded_foo; -</example> -</para> - -<para> -Файл <path>urldecode.js</path>: -<example> -function decoded_foo(r) { - return decodeURIComponent(r.args.foo); -} -</example> -</para> - -</section> - - -<section id="example_urlencode" name="Кодирование URL"> - -<para> -<example> -js_include urlencode.js; - -js_set $encoded_foo encoded_foo; -... - -location / { - proxy_pass http://example.com?foo=$encoded_foo; -} -</example> -</para> - -<para> -Файл <path>urlencode.js</path>: -<example> -function encoded_foo(r) { - return encodeURIComponent('foo & bar?'); -} -</example> -</para> - -</section> - - -<section id="example_fast_response" name="Возврат самого быстрого ответа от прокси"> - -<para> -<example> -js_include fastresponse.js; - -location /start { - js_content content; -} - -location /foo { - proxy_pass http://backend1; -} - -location /bar { - proxy_pass http://backend2; -} -</example> -</para> - -<para> -Файл <path>fastresponse.js</path>: -<example> -function content(r) { - var n = 0; - - function done(res) { - if (n++ == 0) { - r.return(res.status, res.responseBody); - } - } - - r.subrequest('/foo', r.variables.args, done); - r.subrequest('/bar', r.variables.args, done);TBD -} -</example> -</para> - -</section> - - -<section id="example_jwt" name="Создание HS JWT"> - -<para> -<example> -js_include hs_jwt.js; - -js_set $jwt jwt; -</example> -</para> - -<para> -Файл <path>hs_jwt.js</path>: -<example> -function create_hs256_jwt(claims, key, valid) { - var header = { "typ" : "JWT", "alg" : "HS256", "exp" : Date.now() + valid }; - - var s = JSON.stringify(header).toBytes().toString('base64url') + '.' - + JSON.stringify(claims).toBytes().toString('base64url'); - - var h = require('crypto').createHmac('sha256', key); - - return s + '.' + h.update(s).digest().toString('base64url'); -} - -function jwt(r) { - var claims = { - "iss" : "nginx", - "sub" : "alice", - "foo" : 123, - "bar" : "qq", - "zyx" : false - }; - - return create_hs256_jwt(claims, 'foo', 600); -} -</example> -</para> - -</section> - - -<section id="example_subrequest" name="Доступ к API при помощи подзапроса"> - -<para> -<example> -js_include subrequest.js; - -keyval_zone zone=foo:10m; -... - -location /keyval { - js_content set_keyval; -} - -location /version { - js_content version; -} - -location /api { - api write=on; -} -</example> -</para> - -<para> -Файл <path>subrequest.js</path>: -<example> -function set_keyval(r) { - r.subrequest('/api/3/http/keyvals/foo', - { method: 'POST', - body: JSON.stringify({ foo: 789, bar: "ss dd 00" })}, - - function(res) { - if (res.status >= 300) { - r.return(res.status, res.responseBody); - return; - } - r.return(500); - }); -} - -function version(r) { - r.subrequest('/api/3/nginx', { method: 'GET' }, function(res) { - if (res.status != 200) { - r.return(res.status); - return; - } - - var json = JSON.parse(res.responseBody); - r.return(200, json.version); - }); -} -</example> -</para> - -</section> - - -<section id="example_secure_link" name="Создание хэша secure_link"> - -<para> -<example> -js_include hash.js; - -js_set $new_foo create_secure_link; -... - -location / { - secure_link $cookie_foo; - secure_link_md5 "$uri mykey"; - ... -} - -location @login { - add_header Set-Cookie "foo=$new_foo; Max-Age=60"; - return 302 /; -} -</example> -</para> - -<para> -Файл <path>hash.js</path>: -<example> -function create_secure_link(r) { - return require('crypto').createHash('md5') - .update(r.uri).update(" mykey") - .digest('base64url'); -} -</example> -</para> - -</section> - -</section> - -</article> -
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/njs/reference.xml Mon Sep 24 19:24:04 2018 +0300 @@ -0,0 +1,525 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> + +<article name="Справочник" + link="/ru/docs/njs/reference.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +<link doc="index.xml">njs</link> предоставляет объекты, методы и свойства +для расширения функциональности nginx. +</para> + +</section> + + +<section id="http" name="HTTP"> + +<para> +Объект <literal>HTTP</literal> доступен только в +модуле <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>. +Все строки в объекте <literal>HTTP</literal> являются +<link id="strings">байтовыми строками</link>. +</para> + + +<section id="http_request" name="Запрос"> + +<para> +<list type="tag"> + +<tag-name><literal>r.args{}</literal></tag-name> +<tag-desc> +объект аргументов запроса, только чтение +</tag-desc> + +<tag-name><literal>r.error(<value>строка</value>)</literal></tag-name> +<tag-desc> +записывает <literal>строку</literal> в лог-файл ошибок +на уровне лога <literal>error</literal> +</tag-desc> + +<tag-name><literal>r.finish()</literal></tag-name> +<tag-desc> +завершает отправку ответа клиенту +</tag-desc> + +<tag-name><literal>r.headersIn{}</literal></tag-name> +<tag-desc> +объект исходящих заголовков, только чтение. +<para> +Например, доступ к заголовку <literal>Header-Name</literal> +можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal> +или <literal>headers.Header_name</literal> +</para> +</tag-desc> + +<tag-name><literal>r.headersOut{}</literal></tag-name> +<tag-desc> +объект исходящих заголовков, доступно для записи. +<para> +Например, доступ к заголовку <literal>Header-Name</literal> +можно получить при помощи синтаксиса <literal>headers['Header-Name']</literal> +или <literal>headers.Header_name</literal> +</para> +</tag-desc> + +<tag-name><literal>r.httpVersion</literal></tag-name> +<tag-desc> +версия HTTP, только чтение +</tag-desc> + +<tag-name><literal>r.log(<value>строка</value>)</literal></tag-name> +<tag-desc> +записывает <literal>строку</literal> в лог-файл ошибок +на уровне лога <literal>info</literal> +</tag-desc> + +<tag-name><literal>r.method</literal></tag-name> +<tag-desc> +HTTP метод, только чтение +</tag-desc> + +<tag-name><literal>r.parent</literal></tag-name> +<tag-desc> +ссылается на родительский объект запроса +</tag-desc> + +<tag-name><literal>r.remoteAddress</literal></tag-name> +<tag-desc> +адрес клиента, только чтение +</tag-desc> + +<tag-name><literal>r.requestBody</literal></tag-name> +<tag-desc> +хранит тело запроса, только чтение +</tag-desc> + +<tag-name><literal>r.responseBody</literal></tag-name> +<tag-desc> +хранит тело ответа <link id="subrequest">подзапроса</link>, только чтение +</tag-desc> + +<tag-name><literal>r.return(код[, строка])</literal></tag-name> +<tag-desc> +отправляет +клиенту полный ответ с указанным <literal>кодом</literal> +<para> +Можно задать или URL перенаправления +(для кодов 301, 302, 303, 307 и 308), +или текст тела ответа (для остальных кодов) в качестве второго аргумента +</para> +</tag-desc> + +<tag-name><literal>r.send(<value>строка</value>)</literal></tag-name> +<tag-desc> +отправляет часть тела ответа клиенту +</tag-desc> + +<tag-name><literal>r.sendHeader()</literal></tag-name> +<tag-desc> +отправляет заголовок HTTP клиенту +</tag-desc> + +<tag-name><literal>r.status</literal></tag-name> +<tag-desc> +статус, доступно для записи +</tag-desc> + +<tag-name><literal>req.variables{}</literal></tag-name> +<tag-desc> +объект переменных nginx, только чтение +</tag-desc> + +<tag-name><literal>r.warn(<value>строка</value>)</literal></tag-name> +<tag-desc> +записывает <literal>строку</literal> в лог-файл ошибок +на уровне лога <literal>warning</literal> +</tag-desc> + +<tag-name><literal>r.uri</literal></tag-name> +<tag-desc> +текущий URI, только чтение +</tag-desc> + +<tag-name id="subrequest"><literal>r.subrequest(<value>uri</value>[, +<value>options</value>[, <value>callback</value>]])</literal></tag-name> +<tag-desc> +создаёт подзапрос с заданными <literal>uri</literal> и +<literal>options</literal> и +устанавливает необязательный <literal>callback</literal> завершения. + +<para> +Если <literal>options</literal> является строкой, то в ней +содержится срока аргументов подзапроса. +В противном случае ожидается, что <literal>options</literal> является объектом +со следующими ключами: + +<list type="tag"> +<tag-name><literal>args</literal></tag-name> +<tag-desc> +строка с аргументами +</tag-desc> + +<tag-name><literal>body</literal></tag-name> +<tag-desc> +тело запроса +</tag-desc> + +<tag-name><literal>method</literal></tag-name> +<tag-desc +>метод HTTP +</tag-desc> + +</list> +</para> + +<para> +<literal>callback</literal> получает +объект ответа подзапроса с методами и свойствами, +идентичными родительскому объекту запроса. +</para> +</tag-desc> + +</list> +</para> + +</section> + +</section> + + +<section id="stream" name="Stream"> + +<para> +Объект <literal>stream</literal> доступен только в +модуле +<link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>. +Все строки в объекте <literal>stream</literal> являются +<link id="strings">байтовыми строками</link>. +</para> + + +<section id="stream_session" name="Сессия"> + +<para> +<list type="tag"> + +<tag-name><literal>s.remoteAddress</literal></tag-name> +<tag-desc> +адрес клиента, только чтение +</tag-desc> + +<tag-name><literal>s.eof</literal></tag-name> +<tag-desc> +логическое свойство, +true, если текущий буфер является последним буфером, +только чтение +</tag-desc> + +<tag-name><literal>s.fromUpstream</literal></tag-name> +<tag-desc> +логическое свойство, +true, если текущий буфер является буфером от проксируемого сервера к клиенту, +только чтение +</tag-desc> + +<tag-name><literal>s.buffer</literal></tag-name> +<tag-desc> +текущий буфер, доступен для записи +</tag-desc> + +<tag-name><literal>s.variables{}</literal></tag-name> +<tag-desc> +объект переменных nginx, только чтение +</tag-desc> + +<tag-name><literal>s.OK</literal></tag-name> +<tag-desc> +код <literal>OK</literal> +</tag-desc> + +<tag-name><literal>s.DECLINED</literal></tag-name> +<tag-desc> +код <literal>DECLINED</literal> +</tag-desc> + +<tag-name><literal>s.AGAIN</literal></tag-name> +<tag-desc> +код <literal>AGAIN</literal> +</tag-desc> + +<tag-name><literal>s.ERROR</literal></tag-name> +<tag-desc> +код <literal>ERROR</literal> +</tag-desc> + +<tag-name><literal>s.ABORT</literal></tag-name> +<tag-desc> +код <literal>ABORT</literal> +</tag-desc> + +<tag-name><literal>s.log(<value>строка</value>)</literal></tag-name> +<tag-desc> +записывает отправленную <value>строку</value> в лог-файл ошибок +на уровне лога <literal>info</literal> +</tag-desc> + +<tag-name><literal>s.warn(<value>строка</value>)</literal></tag-name> +<tag-desc> +записывает отправленную <literal>строку</literal> в лог-файл ошибок +на уровне лога <literal>warning</literal> +</tag-desc> + +<tag-name><literal>s.error(<value>строка</value>)</literal></tag-name> +<tag-desc> +записывает отправленную <literal>строку</literal> в лог-файл ошибок +на уровне лога <literal>error</literal> +</tag-desc> + +</list> +</para> + +</section> + +</section> + + +<section id="example" name="Примеры"> + + +<section id="example_urldecode" name="Декодирование URL"> + +<para> +<example> +js_include urldecode.js; + +js_set $decoded_foo decoded_foo; +</example> +</para> + +<para> +Файл <path>urldecode.js</path>: +<example> +function decoded_foo(r) { + return decodeURIComponent(r.args.foo); +} +</example> +</para> + +</section> + + +<section id="example_urlencode" name="Кодирование URL"> + +<para> +<example> +js_include urlencode.js; + +js_set $encoded_foo encoded_foo; +... + +location / { + proxy_pass http://example.com?foo=$encoded_foo; +} +</example> +</para> + +<para> +Файл <path>urlencode.js</path>: +<example> +function encoded_foo(r) { + return encodeURIComponent('foo & bar?'); +} +</example> +</para> + +</section> + + +<section id="example_fast_response" name="Возврат самого быстрого ответа от прокси"> + +<para> +<example> +js_include fastresponse.js; + +location /start { + js_content content; +} + +location /foo { + proxy_pass http://backend1; +} + +location /bar { + proxy_pass http://backend2; +} +</example> +</para> + +<para> +Файл <path>fastresponse.js</path>: +<example> +function content(r) { + var n = 0; + + function done(res) { + if (n++ == 0) { + r.return(res.status, res.responseBody); + } + } + + r.subrequest('/foo', r.variables.args, done); + r.subrequest('/bar', r.variables.args, done);TBD +} +</example> +</para> + +</section> + + +<section id="example_jwt" name="Создание HS JWT"> + +<para> +<example> +js_include hs_jwt.js; + +js_set $jwt jwt; +</example> +</para> + +<para> +Файл <path>hs_jwt.js</path>: +<example> +function create_hs256_jwt(claims, key, valid) { + var header = { "typ" : "JWT", "alg" : "HS256", "exp" : Date.now() + valid }; + + var s = JSON.stringify(header).toBytes().toString('base64url') + '.' + + JSON.stringify(claims).toBytes().toString('base64url'); + + var h = require('crypto').createHmac('sha256', key); + + return s + '.' + h.update(s).digest().toString('base64url'); +} + +function jwt(r) { + var claims = { + "iss" : "nginx", + "sub" : "alice", + "foo" : 123, + "bar" : "qq", + "zyx" : false + }; + + return create_hs256_jwt(claims, 'foo', 600); +} +</example> +</para> + +</section> + + +<section id="example_subrequest" name="Доступ к API при помощи подзапроса"> + +<para> +<example> +js_include subrequest.js; + +keyval_zone zone=foo:10m; +... + +location /keyval { + js_content set_keyval; +} + +location /version { + js_content version; +} + +location /api { + api write=on; +} +</example> +</para> + +<para> +Файл <path>subrequest.js</path>: +<example> +function set_keyval(r) { + r.subrequest('/api/3/http/keyvals/foo', + { method: 'POST', + body: JSON.stringify({ foo: 789, bar: "ss dd 00" })}, + + function(res) { + if (res.status >= 300) { + r.return(res.status, res.responseBody); + return; + } + r.return(500); + }); +} + +function version(r) { + r.subrequest('/api/3/nginx', { method: 'GET' }, function(res) { + if (res.status != 200) { + r.return(res.status); + return; + } + + var json = JSON.parse(res.responseBody); + r.return(200, json.version); + }); +} +</example> +</para> + +</section> + + +<section id="example_secure_link" name="Создание хэша secure_link"> + +<para> +<example> +js_include hash.js; + +js_set $new_foo create_secure_link; +... + +location / { + secure_link $cookie_foo; + secure_link_md5 "$uri mykey"; + ... +} + +location @login { + add_header Set-Cookie "foo=$new_foo; Max-Age=60"; + return 302 /; +} +</example> +</para> + +<para> +Файл <path>hash.js</path>: +<example> +function create_secure_link(r) { + return require('crypto').createHash('md5') + .update(r.uri).update(" mykey") + .digest('base64url'); +} +</example> +</para> + +</section> + +</section> + +</article> +
--- a/xml/ru/docs/stream/ngx_stream_js_module.xml Mon Sep 24 19:10:29 2018 +0300 +++ b/xml/ru/docs/stream/ngx_stream_js_module.xml Mon Sep 24 19:24:04 2018 +0300 @@ -33,8 +33,8 @@ <para> <note> Данный пример необходимо использовать с -версией njs <link doc="../njs_changes.xml" id="njs-0.2.4">0.2.4</link>. -Для версий njs <link doc="../njs_changes.xml" id="njs-0.2.3">0.2.3</link> +версией njs <link doc="../changes.xml" id="njs0.2.4">0.2.4</link>. +Для версий njs <link doc="../changes.xml" id="njs0.2.3">0.2.3</link> и ранее необходимо использовать <link doc="../examples.xml" id="legacy">этот</link> пример. </note>