changeset 2532:423d813dc8bb

Documented support for multi-value headers in r.headersOut.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 23 Apr 2020 12:57:43 +0100
parents 9c8a89d3876f
children 617bc29bd759
files xml/en/docs/njs/reference.xml xml/ru/docs/njs/reference.xml
diffstat 2 files changed, 83 insertions(+), 7 deletions(-) [+]
line wrap: on
line diff
--- 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="38">
+        rev="39">
 
 <section id="summary">
 
@@ -75,9 +75,47 @@ should be used.
 <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>
+The <header>Foo</header> response header
+can be accessed with the syntax:
+<literal>headersOut.foo</literal> or <literal>headersOut['Foo']</literal>.
+</para>
+
+<para>
+Field values of multi-value response headers
+(<link doc="changes.xml" id="njs0.4.0">0.4.0</link>)
+can be set with the syntax:
+<example>
+r.headersOut[‘Foo’] = [‘a’, ‘b’]
+</example>
+where the output will be:
+<example>
+Foo: a
+Foo: b
+</example>
+All previous field values of the <header>Foo</header> response header
+will be deleted.
+</para>
+
+<para>
+For standard response headers
+that accept only a single field value such as
+<header>Content-Type</header>,
+only the last element of the array will take effect.
+Duplicate field values in
+<header>Age</header>,
+<header>Content-Encoding</header>,
+<header>Content-Length</header>,
+<header>Content-Type</header>,
+<header>ETag</header>,
+<header>Expires</header>,
+<header>Last-Modified</header>,
+<header>Location</header>,
+<header>Retry-After</header>
+response headers are ignored.
+All other duplicate field values of the response header
+are joined together with comma “<literal>,</literal>”.
+Field values of the <header>Set-Cookie</header> response header
+are always returned as an array.
 </para>
 </tag-desc>
 
--- a/xml/ru/docs/njs/reference.xml
+++ b/xml/ru/docs/njs/reference.xml
@@ -76,9 +76,47 @@
 <tag-desc>
 объект исходящих заголовков, доступно для записи.
 <para>
-Например, доступ к заголовку <literal>Foo</literal>
-можно получить при помощи синтаксиса <literal>headersOut.foo</literal>
-или <literal>headersOut['Foo']</literal>
+Доступ к заголовку ответа <literal>Foo</literal>
+можно получить при помощи синтаксиса:
+<literal>headersOut.foo</literal> или <literal>headersOut['Foo']</literal>
+</para>
+
+<para>
+Значения полей многозначных заголовков ответа
+(<link doc="changes.xml" id="njs0.4.0">0.4.0</link>)
+можно задать при помощи синтаксиса:
+<example>
+r.headersOut[‘Foo’] = [‘a’, ‘b’]
+</example>
+результат:
+<example>
+Foo: a
+Foo: b
+</example>
+Все предыдущие значения поля заголовка ответа <header>Foo</header>
+будут удалены.
+</para>
+
+<para>
+В стандартных заголовках ответа,
+поля которых могут принимать только одно значение, например
+<header>Content-Type</header>,
+учитывается только последний элемент массива.
+Дубликаты значений поля в заголовках ответа
+<header>Age</header>,
+<header>Content-Encoding</header>,
+<header>Content-Length</header>,
+<header>Content-Type</header>,
+<header>ETag</header>,
+<header>Expires</header>,
+<header>Last-Modified</header>,
+<header>Location</header>,
+<header>Retry-After</header>
+игнорируются.
+Все другие дубликаты значений поля заголовка ответа
+соединяются при помощи запятой (“<literal>,</literal>”).
+Значения поля в заголовке ответа <header>Set-Cookie</header>
+всегда возвращаются в виде массива.
 </para>
 </tag-desc>