From 3699198e1792200ed48f3019d07f1a385bbd9fff Mon Sep 17 00:00:00 2001 From: Gerhard Stoebich Date: Mon, 9 Apr 2018 22:43:37 +0200 Subject: [PATCH 1/5] doc: improve http.setHeader and getHeader typeinfo http.setHeader() coerces input values. http.getHeader() returns the type as passed to setHeader() fixes #13825 --- doc/api/http.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index f69ac112745a38..9165c75e1475f5 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -587,9 +587,11 @@ added: v1.6.0 --> * `name` {string} -* Returns: {string} +* Returns: {string, string[]} - type as set via `setHeader()` Reads out a header on the request. Note that the name is case insensitive. +The return value is that one set via `setHeader()` as coercing to string +happens during transmission. Example: ```js @@ -1210,7 +1212,8 @@ added: v0.4.0 Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings -here to send multiple headers with the same name. +here to send multiple headers with the same name. Values are coerced to +strings if needed during transmission. Example: From 32685cf6c502ae205eb7d5b55c322209f6358d87 Mon Sep 17 00:00:00 2001 From: Gerhard Stoebich Date: Tue, 10 Apr 2018 10:05:02 +0200 Subject: [PATCH 2/5] fix review items --- doc/api/http.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index 9165c75e1475f5..6b9842298e75fd 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -587,15 +587,21 @@ added: v1.6.0 --> * `name` {string} -* Returns: {string, string[]} - type as set via `setHeader()` +* Returns: {string|string[]} Reads out a header on the request. Note that the name is case insensitive. -The return value is that one set via `setHeader()` as coercing to string -happens during transmission. +The type of the return value depends on the arguments provided to +[`response.setHeader()`][]. Example: ```js -const contentType = request.getHeader('Content-Type'); +request.setHeader('content-type', 'text/html'); +request.setHeader('Content-Length': Buffer.byteLength(body)); +request.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']) +const contentType = request.getHeader('Content-Type'); // contentType is 'text/html' +const contentLength = request.getHeader('Content-Length'); // contentLength is of type number +const setCookie = request.getHeader('set-cookie'); // setCookie is of type string[] + ``` ### request.removeHeader(name) @@ -1212,8 +1218,8 @@ added: v0.4.0 Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings -here to send multiple headers with the same name. Values are coerced to -strings if needed during transmission. +here to send multiple headers with the same name. Non-string values will be +coerced to strings. Example: From 1d5c3e2057dbe95b027a4c32ec46b9e7281be6ef Mon Sep 17 00:00:00 2001 From: Gerhard Stoebich Date: Tue, 10 Apr 2018 11:01:16 +0200 Subject: [PATCH 3/5] fix review items --- doc/api/http.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index 6b9842298e75fd..d468cb396134e1 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -596,11 +596,14 @@ The type of the return value depends on the arguments provided to Example: ```js request.setHeader('content-type', 'text/html'); -request.setHeader('Content-Length': Buffer.byteLength(body)); -request.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']) -const contentType = request.getHeader('Content-Type'); // contentType is 'text/html' -const contentLength = request.getHeader('Content-Length'); // contentLength is of type number -const setCookie = request.getHeader('set-cookie'); // setCookie is of type string[] +request.setHeader('Content-Length', Buffer.byteLength(body)); +request.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); +const contentType = request.getHeader('Content-Type'); +// contentType is 'text/html' +const contentLength = request.getHeader('Content-Length'); +// contentLength is of type number +const setCookie = request.getHeader('set-cookie'); +// setCookie is of type string[] ``` From 5dc2a5d0e207e3b9b2c0a8f15a68601537437c7c Mon Sep 17 00:00:00 2001 From: Gerhard Stoebich Date: Wed, 11 Apr 2018 00:19:37 +0200 Subject: [PATCH 4/5] fix review findings, correct request and response APIs --- doc/api/http.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index d468cb396134e1..98313825c752df 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -587,11 +587,11 @@ added: v1.6.0 --> * `name` {string} -* Returns: {string|string[]} +* Returns: {any} Reads out a header on the request. Note that the name is case insensitive. The type of the return value depends on the arguments provided to -[`response.setHeader()`][]. +[`request.setHeader()`][]. Example: ```js @@ -627,11 +627,14 @@ added: v1.6.0 --> * `name` {string} -* `value` {string} +* `value` {string|string[]} Sets a single header value for headers object. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings -here to send multiple headers with the same name. +here to send multiple headers with the same name. Non-string values will be +stored without modification. Therefore, [`request.getHeader()`][] may return +non-string values. However, the non-string values will be converted to strings +for network transmission. Example: ```js @@ -1098,15 +1101,24 @@ added: v0.4.0 --> * `name` {string} -* Returns: {string} +* Returns: {any} Reads out a header that's already been queued but not sent to the client. -Note that the name is case insensitive. +Note that the name is case insensitive. The type of the return value depends +on the arguments provided to [`response.setHeader()`][]. Example: ```js +response.setHeader('Content-Type', 'text/html'); +response.setHeader('Content-Length', Buffer.byteLength(body)); +response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); const contentType = response.getHeader('content-type'); +// contentType is 'text/html' +const contentLength = response.getHeader('Content-Length'); +// contentLength is of type number +const setCookie = response.getHeader('set-cookie'); +// setCookie is of type string[] ``` ### response.getHeaderNames() @@ -1222,7 +1234,9 @@ added: v0.4.0 Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings here to send multiple headers with the same name. Non-string values will be -coerced to strings. +stored without modification. Therefore, [`response.getHeader()`][] may return +non-string values. However, the non-string values will be converted to strings +for network transmission. Example: @@ -2029,11 +2043,14 @@ not abort the request or do anything besides add a `timeout` event. [`net.createConnection()`]: net.html#net_net_createconnection_options_connectlistener [`removeHeader(name)`]: #http_request_removeheader_name [`request.end()`]: #http_request_end_data_encoding_callback +[`request.getHeader()`]: #http_request_getheader_name +[`request.setHeader()`]: #http_request_setheader_name_value [`request.setTimeout()`]: #http_request_settimeout_timeout_callback [`request.socket`]: #http_request_socket [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed [`request.write(data, encoding)`]: #http_request_write_chunk_encoding_callback [`response.end()`]: #http_response_end_data_encoding_callback +[`response.getHeader()`]: #http_response_getheader_name [`response.setHeader()`]: #http_response_setheader_name_value [`response.socket`]: #http_response_socket [`response.write()`]: #http_response_write_chunk_encoding_callback From 3ab5dc7c99a4e5166dd82c84e145cec5bbaa119e Mon Sep 17 00:00:00 2001 From: Gerhard Stoebich Date: Wed, 11 Apr 2018 09:45:03 +0200 Subject: [PATCH 5/5] setHeader accepts type any --- doc/api/http.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index 98313825c752df..cd084a6bef3efa 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -627,7 +627,7 @@ added: v1.6.0 --> * `name` {string} -* `value` {string|string[]} +* `value` {any} Sets a single header value for headers object. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings @@ -1229,7 +1229,7 @@ added: v0.4.0 --> * `name` {string} -* `value` {string | string[]} +* `value` {any} Sets a single header value for implicit headers. If this header already exists in the to-be-sent headers, its value will be replaced. Use an array of strings