changeset 2628:0ce45b4edb75

njs-0.5.0.
author Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 02 Dec 2020 09:28:09 +0000
parents 9ded17b148f5
children 5cd72684e5b8
files xml/en/docs/njs/changes.xml xml/en/docs/njs/reference.xml xml/index.xml
diffstat 3 files changed, 410 insertions(+), 22 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/njs/changes.xml
+++ b/xml/en/docs/njs/changes.xml
@@ -9,9 +9,283 @@
 <article name="Changes"
         link="/en/docs/njs/changes.html"
         lang="en"
-        rev="38"
+        rev="39"
         toc="no">
 
+<section id="njs0.5.0" name="Changes with njs 0.5.0">
+
+<para>
+Release Date:
+01 December 2020
+</para>
+
+<para>
+nginx modules:
+<list type="bullet">
+
+<listitem>
+<para>
+Feature:
+introduced global
+<link doc="reference.xml" id="ngx"><literal>ngx</literal></link> object.
+</para>
+
+<para>
+The following methods were added:
+<list type="bullet">
+
+<listitem>
+<para>
+<link doc="reference.xml" id="ngx_log"><literal>ngx.log(level,
+message)</literal></link>
+</para>
+</listitem>
+
+</list>
+</para>
+
+<para>
+The following properties were added:
+<list type="bullet">
+
+<listitem>
+<para>
+<literal>ngx.INFO</literal>,
+<literal>ngx.WARN</literal>,
+<literal>ngx.ERR</literal>.
+</para>
+</listitem>
+
+</list>
+</para>
+
+</listitem>
+
+<listitem>
+<para>
+Feature:
+added support for
+<literal>Buffer</literal> object where string is expected.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Feature:
+added Buffer version of existing properties.
+</para>
+
+<para>
+The following properties were added:
+<list type="bullet">
+
+<listitem>
+<para>
+<link doc="reference.xml" id="r_request_buffer"><literal>r.requestBuffer</literal></link>
+(<link doc="reference.xml" id="r_request_body"><literal>r.requestBody</literal></link>),
+<link doc="reference.xml" id="r_response_buffer"><literal>r.responseBuffer</literal></link>
+(<link doc="reference.xml" id="r_response_body"><literal>r.responseBody</literal></link>),
+<link doc="reference.xml" id="r_raw_variables"><literal>r.rawVariables</literal></link>
+(<link doc="reference.xml" id="r_variables"><literal>r.variables</literal></link>),
+<link doc="reference.xml" id="s_raw_variables"><literal>s.rawVariables</literal></link>
+(<link doc="reference.xml" id="s_variables"><literal>s.variables</literal></link>).
+</para>
+</listitem>
+
+</list>
+</para>
+
+<para>
+The following events were added in the stream module:
+<list type="bullet">
+
+<listitem>
+<para>
+<link doc="reference.xml" id="s_on"><literal>upstream</literal></link>
+(upload),
+<link doc="reference.xml" id="s_on"><literal>downstream</literal></link>
+(download).
+</para>
+</listitem>
+
+</list>
+</para>
+
+</listitem>
+
+<listitem>
+<para>
+Improvement:
+added aliases to existing properties.
+</para>
+
+<para>
+The following properties were added:
+<list type="bullet">
+
+<listitem>
+<para>
+<link doc="reference.xml" id="r_request_text"><literal>r.requestText</literal></link>
+(<link doc="reference.xml" id="r_request_body"><literal>r.requestBody</literal></link>),
+<link doc="reference.xml" id="r_response_text"><literal>r.responseText</literal></link>
+(<link doc="reference.xml" id="r_response_body"><literal>r.responseBody</literal></link>).
+</para>
+</listitem>
+
+</list>
+</para>
+
+</listitem>
+
+<listitem>
+<para>
+Improvement:
+throwing an exception in
+<link doc="reference.xml" id="r_internal_redirect"><literal>r.internalRedirect()</literal></link>
+for a subrequest.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed promise
+<link doc="reference.xml" id="r_subrequest"><literal>r.subrequest()</literal></link>
+with
+<link doc="../http/ngx_http_core_module.xml" id="error_page"><literal>error_page</literal></link>
+redirect.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed
+<literal>promise</literal> events handling.
+</para>
+</listitem>
+
+</list>
+</para>
+
+<para>
+Core:
+<list type="bullet">
+
+<listitem>
+<para>
+Feature:
+added
+<literal>TypeScript</literal> definitions for built-in modules.
+Thanks to Jakub Jirutka.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Feature:
+tracking unhandled <literal>promise</literal> rejection.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Feature:
+added initial iterator support.
+Thanks to Artem S. Povalyukhin.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Improvement:
+<literal>TypeScript</literal> definitions are refactored.
+Thanks to Jakub Jirutka.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Improvement:
+added forgotten support for
+<literal>Object.prototype.valueOf()</literal>
+in
+<literal>Buffer.from()</literal>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed heap-use-after-free in
+<literal>JSON.parse()</literal>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed heap-use-after-free in
+<literal>JSON.stringify()</literal>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed
+<literal>JSON.stringify()</literal> for arrays resizable via getters.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed heap-buffer-overflow for
+<literal>RegExp.prototype[Symbol.replace]</literal>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed returned value for
+<literal>Buffer.prototype.write*</literal>
+functions.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed
+<link doc="reference.xml" id="querystring_stringify"><literal>querystring.stringify()</literal></link>.
+Thanks to Artem S. Povalyukhin.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed the catch handler for
+<literal>Promise.prototype.finally()</literal>.
+</para>
+</listitem>
+
+<listitem>
+<para>
+Bugfix:
+fixed
+<link doc="reference.xml" id="querystring_parse"><literal>querystring.parse()</literal></link>.
+</para>
+</listitem>
+
+</list>
+</para>
+
+</section>
+
+
 <section id="njs0.4.4" name="Changes with njs 0.4.4">
 
 <para>
--- a/xml/en/docs/njs/reference.xml
+++ b/xml/en/docs/njs/reference.xml
@@ -9,7 +9,7 @@
 <article name="Reference"
         link="/en/docs/njs/reference.html"
         lang="en"
-        rev="56">
+        rev="57">
 
 <section id="summary">
 
@@ -180,6 +180,36 @@ references the parent request object
 client address, read-only
 </tag-desc>
 
+<tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
+<tag-desc>
+the property is deprecated since
+<link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
+the <link id="r_request_buffer"><literal>r.requestBuffer</literal></link> or
+<link id="r_request_text"><literal>r.requestText</literal></link> property
+should be used instead.
+</tag-desc>
+
+<tag-name id="r_request_buffer"><literal>r.requestBuffer</literal></tag-name>
+<tag-desc>
+client request body if it has not been written to a temporary file
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
+To ensure that the client request body is in memory,
+its size should be limited by
+<link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
+and a sufficient buffer size should be set using
+<link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
+The property is available only in the
+<link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
+</tag-desc>
+
+<tag-name id="r_request_text"><literal>r.requestText</literal></tag-name>
+<tag-desc>
+the same as <link id="r_request_buffer"><literal>r.requestBuffer</literal></link>,
+but returns a <literal>string</literal>.
+Note that
+it may convert bytes invalid in utf8 encoding into the replacement character.
+</tag-desc>
+
 <tag-name id="r_raw_headers_in"><literal>r.rawHeadersIn{}</literal></tag-name>
 <tag-desc>
 returns an array of key-value pairs
@@ -222,31 +252,43 @@ Header field names are not converted to 
 duplicate field values are not merged.
 </tag-desc>
 
-<tag-name id="r_request_body"><literal>r.requestBody</literal></tag-name>
+<tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
 <tag-desc>
-returns the client request body if it has not been
-written to a temporary file.
-To ensure that the client request body is in memory,
-its size should be limited by
-<link doc="../http/ngx_http_core_module.xml" id="client_max_body_size"/>,
-and a sufficient buffer size should be set using
-<link doc="../http/ngx_http_core_module.xml" id="client_body_buffer_size"/>.
-The property is available only in the
-<link doc="../http/ngx_http_js_module.xml" id="js_content"/> directive.
+the property is deprecated since
+<link doc="changes.xml" id="njs0.5.0">0.5.0</link>,
+the <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
+or
+the <link id="r_response_text"><literal>r.responseText</literal></link>
+property
+should be used instead.
 </tag-desc>
 
-<tag-name id="r_response_body"><literal>r.responseBody</literal></tag-name>
+<tag-name id="r_response_buffer"><literal>r.responseBuffer</literal></tag-name>
 <tag-desc>
-holds the <link id="r_subrequest">subrequest</link> response body, read-only.
-The size of <literal>r.responseBody</literal> is limited by the
+holds the <link id="r_subrequest">subrequest</link> response body,
+read-only
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
+The size of <literal>r.responseBuffer</literal> is limited by the
 <link doc="../http/ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
 directive.
 </tag-desc>
 
-<tag-name id="r_return"><literal>r.return(status[, string])</literal></tag-name>
+<tag-name id="r_response_text"><literal>r.responseText</literal></tag-name>
+<tag-desc>
+the same as <link id="r_response_buffer"><literal>r.responseBuffer</literal></link>
+but returns a string
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
+Note that
+it may convert bytes invalid in utf8 encoding into the replacement character.
+</tag-desc>
+
+<tag-name id="r_return"><literal>r.return(status[,
+string | Buffer])</literal></tag-name>
 <tag-desc>
 sends the entire response
-with the specified <literal>status</literal> to the client
+with the specified <literal>status</literal> to the client.
+The response can be a string or Buffer
+(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>).
 <para>
 It is possible to specify either a redirect URL
 (for codes 301, 302, 303, 307, and 308)
@@ -254,9 +296,12 @@ or the response body text (for other cod
 </para>
 </tag-desc>
 
-<tag-name id="r_send"><literal>r.send(<value>string</value>)</literal></tag-name>
+<tag-name id="r_send"><literal>r.send(string
+| Buffer)</literal></tag-name>
 <tag-desc>
-sends a part of the response body to the client
+sends a part of the response body to the client.
+The data sent can be a string or Buffer
+(<link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
 </tag-desc>
 
 <tag-name id="r_send_header"><literal>r.sendHeader()</literal></tag-name>
@@ -345,6 +390,13 @@ in request,
 read-only
 </tag-desc>
 
+<tag-name id="r_raw_variables"><literal>r.rawVariables{}</literal></tag-name>
+<tag-desc>
+nginx <link id="r_variables">variables</link> as Buffers,
+writable
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
+</tag-desc>
+
 <tag-name id="r_variables"><literal>r.variables{}</literal></tag-name>
 <tag-desc>
 nginx variables object, writable
@@ -430,12 +482,24 @@ An <literal>event</literal> may be one o
 <list type="tag">
 <tag-name><literal>upload</literal></tag-name>
 <tag-desc>
-new data from a client
+new data (string) from a client
 </tag-desc>
 
 <tag-name><literal>download</literal></tag-name>
 <tag-desc>
-new data to a client
+new data (string) to a client
+</tag-desc>
+
+<tag-name><literal>upstream</literal></tag-name>
+<tag-desc>
+new data (Buffer) from a client
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
+</tag-desc>
+
+<tag-name><literal>downstream</literal></tag-name>
+<tag-desc>
+new data (Buffer) to a client
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
 </tag-desc>
 
 </list>
@@ -444,7 +508,7 @@ new data to a client
 <para>
 The completion callback has the following prototype:
 <literal>callback(data, flags)</literal>, where
-<literal>data</literal> is string,
+<literal>data</literal> is string or Buffer (depending on the event type)
 <literal>flags</literal> is an object
 with the following properties:
 <list type="tag">
@@ -462,11 +526,20 @@ a boolean value, true if data is a last 
 client address, read-only
 </tag-desc>
 
+<tag-name id="s_raw_variables"><literal>s.rawVariables</literal></tag-name>
+<tag-desc>
+nginx <link id="s_variables">variables</link> as Buffers,
+writable
+(since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>)
+</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="changes.xml" id="njs0.2.4">0.2.4</link>).
+The data can be a string or Buffer
+(<link doc="changes.xml" id="njs0.5.0">0.5.0</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 overridden with the following flags:
@@ -506,6 +579,30 @@ on the <literal>warning</literal> level 
 
 </section>
 
+
+<section id="ngx" name="ngx">
+
+<para>
+The <literal>ngx</literal> global object is available
+since <link doc="changes.xml" id="njs0.5.0">0.5.0</link>.
+<list type="tag">
+
+<tag-name id="ngx_log"><literal>ngx.log</literal>(<value>level</value>,
+<value>message</value>)</tag-name>
+<tag-desc>
+Writes a message to the error log with the specified level of logging.
+The <value>level</value> parameter specifies one of the log levels,
+the <value>message</value> parameter can be a string or Buffer.
+The following log levels can be specified:
+<literal>ngx.INFO</literal>,
+<literal>ngx.WARN</literal>, and
+<literal>ngx.ERR</literal>.
+</tag-desc>
+</list>
+</para>
+
+</section>
+
 </section>
 
 
--- a/xml/index.xml
+++ b/xml/index.xml
@@ -7,6 +7,23 @@
 
 <news name="nginx news" link="/" lang="en">
 
+<event date="2020-12-01">
+<para>
+<link doc="en/docs/njs/index.xml">njs-0.5.0</link>
+version has been
+<link doc="en/docs/njs/changes.xml" id="njs0.5.0">released</link>,
+featuring
+<link doc="en/docs/njs/reference.xml" id="r_raw_variables">r.rawVariables</link>,
+<link doc="en/docs/njs/reference.xml" id="r_request_buffer">r.requestBuffer</link>,
+<link doc="en/docs/njs/reference.xml" id="r_request_text">r.requestText</link>,
+<link doc="en/docs/njs/reference.xml" id="r_response_buffer">r.responseBuffer</link>,
+<link doc="en/docs/njs/reference.xml" id="r_response_text">r.responseText</link>,
+<link doc="en/docs/njs/reference.xml" id="s_raw_variables">s.rawVariables</link>,
+and global
+<link doc="en/docs/njs/reference.xml" id="ngx">ngx</link> object.
+</para>
+</event>
+
 <event date="2020-11-24">
 <para>
 <link doc="en/download.xml">nginx-1.19.5</link>