http: add flushHeaders and deprecate flush

[yosuke-furukawa]

I found a different API from Node.js v0.12 and io.js.
the detail is here nodejs/node-v0.x-archive@89f3c90

http module in io.js has a method req.flush.
Node.js v0.12 also has a same behavior method but the different name req.flushHeaders.

the difference may cause to block migrations from Node.js v0.12 to io.js.
But if we rename req.flush to req.flushHeaders now, we should update the major version.

So I add req.flushHeaders method and deprecate req.flush.

If we bump the io.js master version, we would be better to rethink req.flush is removed.

[bnoordhuis]

Tiny nit: blank line at EOF.

[bnoordhuis]

LGTM and seems like a reasonable change.

@iojs/collaborators Opinions?

[cjihrig]

LGTM. This actually seems more comprehensive than the original commit in joyent/node.

[Fishrock123]

@dougwilson I know I've seen flush around express before, how annoying is a deprecation like this?

[dougwilson]

This change is probably better for Express, because we don't use this method directly (yet), but also our compression middleware actually adds a res.flush() method for users to flush the zlib buffer to the client. With this change, it means io.js users of compression can more easily access this feature, since we won't be stomping on the method any longer :)

[Fishrock123]

LGTM

[evanlucas]

Wouldn't this be semver-major?

[dougwilson]

Deprecations are only semver minor. See rule #7 on http://semver.org/

Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated.

Just making something as deprecated is not backwards-incompatible, as all code using a deprecation function works exactly the same.

[evanlucas]

Ah, didn't see that flush() was still there but deprecated :/

[tellnes]

LGTM

[bnoordhuis]

Thanks Yosuke, landed in b2e00e3.