http: docs deprecate ServerResponse.prototype.writeHeader() #11355

jasnell · 2017-02-13T21:02:25Z

The ServerResponse class has an undocumented writeHeader()
API that simply forwards on to the documented writeHead()
method. This adds a docs-only deprecation for the undocumented
method.

TODO: This will need to update the static deprecation identifier before landing

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

http

evanlucas · 2017-02-13T21:09:14Z

-1, searching on github had a bunch of hits. What does 3 lines of code cost us to maintain?

jasnell · 2017-02-13T21:10:54Z

If we keep it, then it should either be docs only deprecated or added to the API documentation.

…

On Mon, Feb 13, 2017 at 1:09 PM Evan Lucas ***@***.***> wrote: -1, searching on github had a bunch of hits. What does 3 lines of code cost us to maintain? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#11355 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAa2ee_1mLv1XanXfk2jt1c5F7rei_t-ks5rcMZ_gaJpZM4L_t8d> .

evanlucas · 2017-02-13T21:13:08Z

+1 to documenting

jasnell · 2017-02-13T21:19:57Z

What about docs-only deprecation? It doesn't make much sense to have two supported methods that do identical things.

evanlucas · 2017-02-13T21:22:45Z

It doesn't make much sense to have two supported methods that do identical things.

Sure it does if it doesn't break working code. I think it should be documented as an alias to writeHead().

bnoordhuis · 2017-02-13T21:52:19Z

I'm inclined to disagree, it increases the cognitive overhead. Imagine you type res.writeH^N (or whatever your editor uses for auto-completion), wouldn't it be nice when it marked one of the suggestions as deprecated? You won't have to spend a second thinking which one you should use.

jasnell · 2017-02-13T22:24:59Z

I have to agree with @bnoordhuis.

mscdex · 2017-02-14T00:37:48Z

doc/api/deprecations.md

@@ -523,6 +523,12 @@ Type: Runtime
 of V8 5.8. It is replaced by Inspector which is activated with `--inspect`
 instead.

+<a id="DEP00XX"></a>


Do these placeholders get replaced when making a release, like with the API version metadata or when landing or ?

It will get replaced before landing. There's no automated check, however

Ok, I just had noticed that one of the other deprecation PRs already had a number assigned, so I was confused...

jasnell · 2017-02-14T22:04:06Z

@nodejs/ctc ... please give this one some thought. Should we deprecate writeHeader or document it as an acceptable alias for writeHead

addaleax · 2017-02-15T15:48:06Z

A documentation-only deprecation sounds fine to me.

ChALkeR · 2017-02-16T14:50:48Z

+1 to documenting as doc-only deprecated for now. I will do a search and perhaps report some issues to the modules that are using that, if needed.

jasnell · 2017-02-16T14:51:54Z

Will change to a docs deprecation! Thanks!

jasnell · 2017-02-16T21:14:06Z

@nodejs/ctc ... PTAL, updated to be a docs-only deprecation for the time being

jasnell · 2017-02-20T15:53:50Z

@evanlucas ... any objections to the docs-only deprecation?

jasnell · 2017-02-24T17:30:58Z

ping @evanlucas :-)

evanlucas · 2017-02-24T18:13:13Z

Fine with me. Thanks!

Doc-only deprecation of the undocumented res.writeHeader() API. Also makes res.writeHeader an alias of res.writeHead since the previous implementation simply deferred to that method.

Doc-only deprecation of the undocumented res.writeHeader() API. Also makes res.writeHeader an alias of res.writeHead since the previous implementation simply deferred to that method. PR-URL: #11355 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rod Vagg <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]>

jasnell · 2017-02-25T02:08:48Z

Landed in fb71ba4

ChALkeR · 2017-02-26T11:55:11Z

The grep is here: https://gist.github.com/ChALkeR/c153d517454a72f96ab758d7286e5495 =).

http-signature is a false positive (it defines its own .writeHeader(). There are probably more false positives.

That's 426 modules total and 35 modules above 1000 downloads/month.
Excluding tests/examples — 334 modules total and 24 modules above 1000 downloads/month.

res.writeHeader is an undocumented alias to res.writeHead It's docs-deprecated in nodejs/node#11355

ChALkeR · 2017-02-26T12:34:23Z

doc/api/deprecations.md

@@ -523,6 +523,17 @@ Type: Runtime
 of V8 5.8. It is replaced by Inspector which is activated with `--inspect`
 instead.

+<a id="DEP0063"></a>
+#### DEP0063: ServerResponse.prototype.writeHeader()


This should have been ### probably, atm its style is different from all the other deprecation entries on that page.

@ChALkeR

res.writeHeader is an undocumented alias to res.writeHead It's docs-deprecated in nodejs/node#11355 PR-URL: #15874 Credit: @ChALkeR Reviewed-By: @zkat

@ChALkeR

res.writeHeader is an undocumented alias to res.writeHead It's docs-deprecated in nodejs/node#11355 PR-URL: #15874 Credit: @ChALkeR Reviewed-By: @zkat

@ChALkeR

res.writeHeader is an undocumented alias to res.writeHead It's docs-deprecated in nodejs/node#11355 PR-URL: #15874 Credit: @ChALkeR Reviewed-By: @zkat

* **Async Hooks** * The `async_hooks` module has landed in core [[`4a7233c178`](nodejs@4a7233c178)] [nodejs#12892](nodejs#12892). * **Buffer** * Using the `--pending-deprecation` flag will cause Node.js to emit a deprecation warning when using `new Buffer(num)` or `Buffer(num)`. [[`d2d32ea5a2`](nodejs@d2d32ea5a2)] [nodejs#11968](nodejs#11968). * `new Buffer(num)` and `Buffer(num)` will zero-fill new `Buffer` instances [[`7eb1b4658e`](nodejs@7eb1b4658e)] [nodejs#12141](nodejs#12141). * Many `Buffer` methods now accept `Uint8Array` as input [[`beca3244e2`](nodejs@beca3244e2)] [nodejs#10236](nodejs#10236). * **Child Process** * Argument and kill signal validations have been improved [[`97a77288ce`](nodejs@97a77288ce)] [nodejs#12348](nodejs#12348), [[`d75fdd96aa`](nodejs@d75fdd96aa)] [nodejs#10423](nodejs#10423). * Child Process methods accept `Uint8Array` as input [[`627ecee9ed`](nodejs@627ecee9ed)] [nodejs#10653](nodejs#10653). * **Console** * Error events emitted when using `console` methods are now supressed. [[`f18e08d820`](nodejs@f18e08d820)] [nodejs#9744](nodejs#9744). * **Dependencies** * The npm client has been updated to 5.0.0 [[`3c3b36af0f`](nodejs@3c3b36af0f)] [nodejs#12936](nodejs#12936). * V8 has been updated to 5.8 with forward ABI stability to 6.0 [[`60d1aac8d2`](nodejs@60d1aac8d2)] [nodejs#12784](nodejs#12784). * **Domains** * Native `Promise` instances are now `Domain` aware [[`84dabe8373`](nodejs@84dabe8373)] [nodejs#12489](nodejs#12489). * **Errors** * We have started assigning static error codes to errors generated by Node.js. This has been done through multiple commits and is still a work in progress. * **File System** * The utility class `fs.SyncWriteStream` has been deprecated [[`7a55e34ef4`](nodejs@7a55e34ef4)] [nodejs#10467](nodejs#10467). * The deprecated `fs.read()` string interface has been removed [[`3c2a9361ff`](nodejs@3c2a9361ff)] [nodejs#9683](nodejs#9683). * **HTTP** * Improved support for userland implemented Agents [[`90403dd1d0`](nodejs@90403dd1d0)] [nodejs#11567](nodejs#11567). * Outgoing Cookie headers are concatenated into a single string [[`d3480776c7`](nodejs@d3480776c7)] [nodejs#11259](nodejs#11259). * The `httpResponse.writeHeader()` method has been deprecated [[`fb71ba4921`](nodejs@fb71ba4921)] [nodejs#11355](nodejs#11355). * New methods for accessing HTTP headers have been added to `OutgoingMessage` [[`3e6f1032a4`](nodejs@3e6f1032a4)] [nodejs#10805](nodejs#10805). * **Lib** * All deprecation messages have been assigned static identifiers [[`5de3cf099c`](nodejs@5de3cf099c)] [nodejs#10116](nodejs#10116). * The legacy `linkedlist` module has been removed [[`84a23391f6`](nodejs@84a23391f6)] [nodejs#12113](nodejs#12113). * **N-API** * Experimental support for the new N-API API has been added [[`56e881d0b0`](nodejs@56e881d0b0)] [nodejs#11975](nodejs#11975). * **Process** * Process warning output can be redirected to a file using the `--redirect-warnings` command-line argument [[`03e89b3ff2`](nodejs@03e89b3ff2)] [nodejs#10116](nodejs#10116). * Process warnings may now include additional detail [[`dd20e68b0f`](nodejs@dd20e68b0f)] [nodejs#12725](nodejs#12725). * **REPL** * REPL magic mode has been deprecated [[`3f27f02da0`](nodejs@3f27f02da0)] [nodejs#11599](nodejs#11599). * **Src** * `NODE_MODULE_VERSION` has been updated to 57 (nodejs@ec7cbaf266)] [nodejs#12995](nodejs#12995). * Add `--pending-deprecation` command-line argument and `NODE_PENDING_DEPRECATION` environment variable [[`a16b570f8c`](nodejs@a16b570f8c)] [nodejs#11968](nodejs#11968). * The `--debug` command-line argument has been deprecated. Note that using `--debug` will enable the *new* Inspector-based debug protocol as the legacy Debugger protocol previously used by Node.js has been removed. [[`010f864426`](nodejs@010f864426)] [nodejs#12949](nodejs#12949). * Throw when the `-c` and `-e` command-line arguments are used at the same time [[`a5f91ab230`](nodejs@a5f91ab230)] [nodejs#11689](nodejs#11689). * Throw when the `--use-bundled-ca` and `--use-openssl-ca` command-line arguments are used at the same time. [[`8a7db9d4b5`](nodejs@8a7db9d4b5)] [nodejs#12087](nodejs#12087). * **Stream** * `Stream` now supports `destroy()` and `_destroy()` APIs [[`b6e1d22fa6`](nodejs@b6e1d22fa6)] [nodejs#12925](nodejs#12925). * `Stream` now supports the `_final()` API [[`07c7f198db`](nodejs@07c7f198db)] [nodejs#12828](nodejs#12828). * **TLS** * The `rejectUnauthorized` option now defaults to `true` [[`348cc80a3c`](nodejs@348cc80a3c)] [nodejs#5923](nodejs#5923). * The `tls.createSecurePair()` API now emits a runtime deprecation [[`a2ae08999b`](nodejs@a2ae08999b)] [nodejs#11349](nodejs#11349). * A runtime deprecation will now be emitted when `dhparam` is less than 2048 bits [[`d523eb9c40`](nodejs@d523eb9c40)] [nodejs#11447](nodejs#11447). * **URL** * The WHATWG URL implementation is now a fully-supported Node.js API [[`d080ead0f9`](nodejs@d080ead0f9)] [nodejs#12710](nodejs#12710). * **Util** * `Symbol` keys are now displayed by default when using `util.inspect()` [[`5bfd13b81e`](nodejs@5bfd13b81e)] [nodejs#9726](nodejs#9726). * `toJSON` errors will be thrown when formatting `%j` [[`455e6f1dd8`](nodejs@455e6f1dd8)] [nodejs#11708](nodejs#11708). * Convert `inspect.styles` and `inspect.colors` to prototype-less objects [[`aab0d202f8`](nodejs@aab0d202f8)] [nodejs#11624](nodejs#11624). * The new `util.promisify()` API has been added [[`99da8e8e02`](nodejs@99da8e8e02)] [nodejs#12442](nodejs#12442). * **Zlib** * Support `Uint8Array` in Zlib convenience methods [[`91383e47fd`](nodejs@91383e47fd)] [nodejs#12001](nodejs#12001). * Zlib errors now use `RangeError` and `TypeError` consistently [[`b514bd231e`](nodejs@b514bd231e)] [nodejs#11391](nodejs#11391).

* **Async Hooks** * The `async_hooks` module has landed in core [[`4a7233c178`](4a7233c178)] [#12892](#12892). * **Buffer** * Using the `--pending-deprecation` flag will cause Node.js to emit a deprecation warning when using `new Buffer(num)` or `Buffer(num)`. [[`d2d32ea5a2`](d2d32ea5a2)] [#11968](#11968). * `new Buffer(num)` and `Buffer(num)` will zero-fill new `Buffer` instances [[`7eb1b4658e`](7eb1b4658e)] [#12141](#12141). * Many `Buffer` methods now accept `Uint8Array` as input [[`beca3244e2`](beca3244e2)] [#10236](#10236). * **Child Process** * Argument and kill signal validations have been improved [[`97a77288ce`](97a77288ce)] [#12348](#12348), [[`d75fdd96aa`](d75fdd96aa)] [#10423](#10423). * Child Process methods accept `Uint8Array` as input [[`627ecee9ed`](627ecee9ed)] [#10653](#10653). * **Console** * Error events emitted when using `console` methods are now supressed. [[`f18e08d820`](f18e08d820)] [#9744](#9744). * **Dependencies** * The npm client has been updated to 5.0.0 [[`3c3b36af0f`](3c3b36af0f)] [#12936](#12936). * V8 has been updated to 5.8 with forward ABI stability to 6.0 [[`60d1aac8d2`](60d1aac8d2)] [#12784](#12784). * **Domains** * Native `Promise` instances are now `Domain` aware [[`84dabe8373`](84dabe8373)] [#12489](#12489). * **Errors** * We have started assigning static error codes to errors generated by Node.js. This has been done through multiple commits and is still a work in progress. * **File System** * The utility class `fs.SyncWriteStream` has been deprecated [[`7a55e34ef4`](7a55e34ef4)] [#10467](#10467). * The deprecated `fs.read()` string interface has been removed [[`3c2a9361ff`](3c2a9361ff)] [#9683](#9683). * **HTTP** * Improved support for userland implemented Agents [[`90403dd1d0`](90403dd1d0)] [#11567](#11567). * Outgoing Cookie headers are concatenated into a single string [[`d3480776c7`](d3480776c7)] [#11259](#11259). * The `httpResponse.writeHeader()` method has been deprecated [[`fb71ba4921`](fb71ba4921)] [#11355](#11355). * New methods for accessing HTTP headers have been added to `OutgoingMessage` [[`3e6f1032a4`](3e6f1032a4)] [#10805](#10805). * **Lib** * All deprecation messages have been assigned static identifiers [[`5de3cf099c`](5de3cf099c)] [#10116](#10116). * The legacy `linkedlist` module has been removed [[`84a23391f6`](84a23391f6)] [#12113](#12113). * **N-API** * Experimental support for the new N-API API has been added [[`56e881d0b0`](56e881d0b0)] [#11975](#11975). * **Process** * Process warning output can be redirected to a file using the `--redirect-warnings` command-line argument [[`03e89b3ff2`](03e89b3ff2)] [#10116](#10116). * Process warnings may now include additional detail [[`dd20e68b0f`](dd20e68b0f)] [#12725](#12725). * **REPL** * REPL magic mode has been deprecated [[`3f27f02da0`](3f27f02da0)] [#11599](#11599). * **Src** * `NODE_MODULE_VERSION` has been updated to 57 (ec7cbaf266)] [#12995](#12995). * Add `--pending-deprecation` command-line argument and `NODE_PENDING_DEPRECATION` environment variable [[`a16b570f8c`](a16b570f8c)] [#11968](#11968). * The `--debug` command-line argument has been deprecated. Note that using `--debug` will enable the *new* Inspector-based debug protocol as the legacy Debugger protocol previously used by Node.js has been removed. [[`010f864426`](010f864426)] [#12949](#12949). * Throw when the `-c` and `-e` command-line arguments are used at the same time [[`a5f91ab230`](a5f91ab230)] [#11689](#11689). * Throw when the `--use-bundled-ca` and `--use-openssl-ca` command-line arguments are used at the same time. [[`8a7db9d4b5`](8a7db9d4b5)] [#12087](#12087). * **Stream** * `Stream` now supports `destroy()` and `_destroy()` APIs [[`b6e1d22fa6`](b6e1d22fa6)] [#12925](#12925). * `Stream` now supports the `_final()` API [[`07c7f198db`](07c7f198db)] [#12828](#12828). * **TLS** * The `rejectUnauthorized` option now defaults to `true` [[`348cc80a3c`](348cc80a3c)] [#5923](#5923). * The `tls.createSecurePair()` API now emits a runtime deprecation [[`a2ae08999b`](a2ae08999b)] [#11349](#11349). * A runtime deprecation will now be emitted when `dhparam` is less than 2048 bits [[`d523eb9c40`](d523eb9c40)] [#11447](#11447). * **URL** * The WHATWG URL implementation is now a fully-supported Node.js API [[`d080ead0f9`](d080ead0f9)] [#12710](#12710). * **Util** * `Symbol` keys are now displayed by default when using `util.inspect()` [[`5bfd13b81e`](5bfd13b81e)] [#9726](#9726). * `toJSON` errors will be thrown when formatting `%j` [[`455e6f1dd8`](455e6f1dd8)] [#11708](#11708). * Convert `inspect.styles` and `inspect.colors` to prototype-less objects [[`aab0d202f8`](aab0d202f8)] [#11624](#11624). * The new `util.promisify()` API has been added [[`99da8e8e02`](99da8e8e02)] [#12442](#12442). * **Zlib** * Support `Uint8Array` in Zlib convenience methods [[`91383e47fd`](91383e47fd)] [#12001](#12001). * Zlib errors now use `RangeError` and `TypeError` consistently [[`b514bd231e`](b514bd231e)] [#11391](#11391).

jasnell added the semver-major PRs that contain breaking changes and should be released in the next major version. label Feb 13, 2017

nodejs-github-bot added the http Issues or PRs related to the http subsystem. label Feb 13, 2017

mscdex reviewed Feb 14, 2017

View reviewed changes

jasnell added the ctc-review label Feb 14, 2017

jasnell force-pushed the deprecate-writeheader branch from 65f0887 to 76d7771 Compare February 16, 2017 21:13

jasnell changed the title ~~http: deprecate ServerResponse.prototype.writeHeader()~~ http: docs deprecate ServerResponse.prototype.writeHeader() Feb 16, 2017

cjihrig approved these changes Feb 16, 2017

View reviewed changes

ChALkeR self-requested a review February 19, 2017 09:29

Trott mentioned this pull request Feb 19, 2017

Node.js Foundation Core Technical Committee (CTC) Meeting 2017-02-22 nodejs/CTC#71

Closed

rvagg approved these changes Feb 20, 2017

View reviewed changes

jasnell force-pushed the deprecate-writeheader branch from 76d7771 to fd7229d Compare February 20, 2017 15:50

thefourtheye approved these changes Feb 22, 2017

View reviewed changes

http: docs-only deprecation of res.writeHeader()

d326364

Doc-only deprecation of the undocumented res.writeHeader() API. Also makes res.writeHeader an alias of res.writeHead since the previous implementation simply deferred to that method.

jasnell force-pushed the deprecate-writeheader branch from fd7229d to d326364 Compare February 25, 2017 02:03

jasnell closed this Feb 25, 2017

ChALkeR added a commit to ChALkeR/npm that referenced this pull request Feb 26, 2017

test: don't use undocumented res.writeHeader alias

1653c7e

res.writeHeader is an undocumented alias to res.writeHead It's docs-deprecated in nodejs/node#11355

ChALkeR mentioned this pull request Feb 26, 2017

test: don't use undocumented res.writeHeader alias npm/npm#15874

Merged

ChALkeR removed their request for review February 26, 2017 12:05

ChALkeR reviewed Feb 26, 2017

View reviewed changes

Trott removed the ctc-review label Feb 27, 2017

jasnell mentioned this pull request Apr 4, 2017

8.0.0 Release Proposal #12220

Closed

refack mentioned this pull request Aug 7, 2017

meta: handling of undocumented endpoint #14679

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

http: docs deprecate ServerResponse.prototype.writeHeader() #11355

http: docs deprecate ServerResponse.prototype.writeHeader() #11355

jasnell commented Feb 13, 2017 •

edited

Loading

evanlucas commented Feb 13, 2017

jasnell commented Feb 13, 2017 via email

evanlucas commented Feb 13, 2017

jasnell commented Feb 13, 2017

evanlucas commented Feb 13, 2017

bnoordhuis commented Feb 13, 2017

jasnell commented Feb 13, 2017

mscdex Feb 14, 2017 •

edited

Loading

jasnell Feb 14, 2017

mscdex Feb 14, 2017

jasnell commented Feb 14, 2017

addaleax commented Feb 15, 2017

ChALkeR commented Feb 16, 2017

jasnell commented Feb 16, 2017

jasnell commented Feb 16, 2017

jasnell commented Feb 20, 2017

jasnell commented Feb 24, 2017

evanlucas commented Feb 24, 2017

jasnell commented Feb 25, 2017

ChALkeR commented Feb 26, 2017

ChALkeR Feb 26, 2017 •

edited

Loading

http: docs deprecate ServerResponse.prototype.writeHeader() #11355

http: docs deprecate ServerResponse.prototype.writeHeader() #11355

Conversation

jasnell commented Feb 13, 2017 • edited Loading

Checklist

Affected core subsystem(s)

evanlucas commented Feb 13, 2017

jasnell commented Feb 13, 2017 via email

evanlucas commented Feb 13, 2017

jasnell commented Feb 13, 2017

evanlucas commented Feb 13, 2017

bnoordhuis commented Feb 13, 2017

jasnell commented Feb 13, 2017

mscdex Feb 14, 2017 • edited Loading

Choose a reason for hiding this comment

jasnell Feb 14, 2017

Choose a reason for hiding this comment

mscdex Feb 14, 2017

Choose a reason for hiding this comment

jasnell commented Feb 14, 2017

addaleax commented Feb 15, 2017

ChALkeR commented Feb 16, 2017

jasnell commented Feb 16, 2017

jasnell commented Feb 16, 2017

jasnell commented Feb 20, 2017

jasnell commented Feb 24, 2017

evanlucas commented Feb 24, 2017

jasnell commented Feb 25, 2017

ChALkeR commented Feb 26, 2017

ChALkeR Feb 26, 2017 • edited Loading

Choose a reason for hiding this comment

jasnell commented Feb 13, 2017 •

edited

Loading

mscdex Feb 14, 2017 •

edited

Loading

ChALkeR Feb 26, 2017 •

edited

Loading