From 50e9f8df62e2d8a7f05ec6c2fbd01528a96f3468 Mon Sep 17 00:00:00 2001 From: Gerhard Stoebich Date: Mon, 9 Apr 2018 22:43:37 +0200 Subject: [PATCH] doc: improve http.setHeader and getHeader typeinfo http.setHeader() coerces input values. http.getHeader() returns the type as passed to setHeader(). PR-URL: https://github.com/nodejs/node/pull/19902 Fixes: https://github.com/nodejs/node/issues/13825 Reviewed-By: Chen Gang Reviewed-By: Ruben Bridgewater Reviewed-By: Trivikram Kamat Reviewed-By: James M Snell --- doc/api/http.md | 43 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/doc/api/http.md b/doc/api/http.md index eb5eb6b2dbb..e7d4d3b4ac9 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -587,13 +587,24 @@ added: v1.6.0 --> * `name` {string} -* Returns: {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 +[`request.setHeader()`][]. 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.removeHeader(name) @@ -616,11 +627,14 @@ added: v1.6.0 --> * `name` {string} -* `value` {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 -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 @@ -1085,15 +1099,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() @@ -1204,11 +1227,14 @@ 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 -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, [`response.getHeader()`][] may return +non-string values. However, the non-string values will be converted to strings +for network transmission. Example: @@ -2013,11 +2039,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