http: replace superfluous connection property with getter/setter

PR-URL: #29015
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>

doc/api/deprecations.md

@@ -2500,6 +2500,20 @@ Type: Runtime
 Passing a callback to [`worker.terminate()`][] is deprecated. Use the returned
 `Promise` instead, or a listener to the worker’s `'exit'` event.
 
+<a id="DEP0XXX"></a>
+### DEP0XXX: http connection
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29015
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+Prefer [`response.socket`][] over [`response.connection`] and
+[`request.socket`][] over [`request.connection`].
+
 [`--http-parser=legacy`]: cli.html#cli_http_parser_library
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`--throw-deprecation`]: cli.html#cli_throw_deprecation
@@ -2555,6 +2569,10 @@ Passing a callback to [`worker.terminate()`][] is deprecated. Use the returned
 [`process.env`]: process.html#process_process_env
 [`punycode`]: punycode.html
 [`require.extensions`]: modules.html#modules_require_extensions
+[`request.socket`]: http.html#http_request_socket
+[`request.connection`]: http.html#http_request_connection
+[`response.socket`]: http.html#http_response_socket
+[`response.connection`]: http.html#http_response_connection
 [`script.createCachedData()`]: vm.html#vm_script_createcacheddata
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args

doc/api/http.md

@@ -568,8 +568,11 @@ been aborted.
 ### request.connection
 <!-- YAML
 added: v0.3.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated. Use [`request.socket`][].
+
 * {net.Socket}
 
 See [`request.socket`][].
@@ -1166,10 +1169,13 @@ will result in a [`TypeError`][] being thrown.
 ### response.connection
 <!-- YAML
 added: v0.3.0
+deprecated: REPLACEME
 -->
 
 * {net.Socket}
 
+> Stability: 0 - Deprecated. Use [`response.socket`][].
+
 See [`response.socket`][].
 
 ### response.end([data][, encoding][, callback])

doc/api/http2.md

@@ -2702,6 +2702,18 @@ added: v8.4.0
 The request authority pseudo header field. It can also be accessed via
 `req.headers[':authority']`.
 
+#### request.connection
+<!-- YAML
+added: v8.4.0
+deprecated: REPLACEME
+-->
+
+> Stability: 0 - Deprecated. Use [`request.socket`][].
+
+* {net.Socket|tls.TLSSocket}
+
+See [`request.socket`][].
+
 #### request.destroy([error])
 <!-- YAML
 added: v8.4.0
@@ -2995,8 +3007,11 @@ will result in a [`TypeError`][] being thrown.
 #### response.connection
 <!-- YAML
 added: v8.4.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated. Use [`response.socket`][].
+
 * {net.Socket|tls.TLSSocket}
 
 See [`response.socket`][].
@@ -3508,6 +3523,7 @@ following additional properties:
 [`net.Socket.prototype.unref()`]: net.html#net_socket_unref
 [`net.Socket`]: net.html#net_class_net_socket
 [`net.connect()`]: net.html#net_net_connect
+[`request.socket`]: #http2_request_socket
 [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed
 [`response.end()`]: #http2_response_end_data_encoding_callback
 [`response.setHeader()`]: #http2_response_setheader_name_value

lib/_http_client.js

@@ -299,7 +299,7 @@ Object.setPrototypeOf(ClientRequest.prototype, OutgoingMessage.prototype);
 Object.setPrototypeOf(ClientRequest, OutgoingMessage);
 
 ClientRequest.prototype._finish = function _finish() {
-  DTRACE_HTTP_CLIENT_REQUEST(this, this.connection);
+  DTRACE_HTTP_CLIENT_REQUEST(this, this.socket);
   OutgoingMessage.prototype._finish.call(this);
 };
 
@@ -643,7 +643,6 @@ function emitFreeNT(socket) {
 function tickOnSocket(req, socket) {
   const parser = parsers.alloc();
   req.socket = socket;
-  req.connection = socket;
   parser.initialize(HTTPParser.RESPONSE,
                     new HTTPClientAsyncResource('HTTPINCOMINGMESSAGE', req));
   parser.socket = socket;

lib/_http_incoming.js

@@ -42,7 +42,6 @@ function IncomingMessage(socket) {
   this._readableState.readingMore = true;
 
   this.socket = socket;
-  this.connection = socket;
 
   this.httpVersionMajor = null;
   this.httpVersionMinor = null;
@@ -76,6 +75,15 @@ function IncomingMessage(socket) {
 Object.setPrototypeOf(IncomingMessage.prototype, Stream.Readable.prototype);
 Object.setPrototypeOf(IncomingMessage, Stream.Readable);
 
+Object.defineProperty(IncomingMessage.prototype, 'connection', {
+  get: function() {
+    return this.socket;
+  },
+  set: function(val) {
+    this.socket = val;
+  }
+});
+
 IncomingMessage.prototype.setTimeout = function setTimeout(msecs, callback) {
   if (callback)
     this.on('timeout', callback);

lib/_http_outgoing.js

@@ -102,7 +102,6 @@ function OutgoingMessage() {
   this[kIsCorked] = false;
 
   this.socket = null;
-  this.connection = null;
   this._header = null;
   this[kOutHeaders] = null;
 
@@ -157,6 +156,15 @@ Object.defineProperty(OutgoingMessage.prototype, '_headers', {
   }, 'OutgoingMessage.prototype._headers is deprecated', 'DEP0066')
 });
 
+Object.defineProperty(OutgoingMessage.prototype, 'connection', {
+  get: function() {
+    return this.socket;
+  },
+  set: function(val) {
+    this.socket = val;
+  }
+});
+
 Object.defineProperty(OutgoingMessage.prototype, '_headerNames', {
   get: internalUtil.deprecate(function() {
     const headers = this[kOutHeaders];
@@ -273,7 +281,7 @@ OutgoingMessage.prototype._send = function _send(data, encoding, callback) {
 
 OutgoingMessage.prototype._writeRaw = _writeRaw;
 function _writeRaw(data, encoding, callback) {
-  const conn = this.connection;
+  const conn = this.socket;
   if (conn && conn.destroyed) {
     // The socket was destroyed. If we're still trying to write to it,
     // then we haven't gotten the 'close' event yet.
@@ -615,10 +623,10 @@ function write_(msg, chunk, encoding, callback, fromEnd) {
                                    ['string', 'Buffer'], chunk);
   }
 
-  if (!fromEnd && msg.connection && !msg[kIsCorked]) {
-    msg.connection.cork();
+  if (!fromEnd && msg.socket && !msg[kIsCorked]) {
+    msg.socket.cork();
     msg[kIsCorked] = true;
-    process.nextTick(connectionCorkNT, msg, msg.connection);
+    process.nextTick(connectionCorkNT, msg, msg.socket);
   }
 
   var len, ret;
@@ -706,8 +714,8 @@ OutgoingMessage.prototype.end = function end(chunk, encoding, callback) {
       else
         this._contentLength = chunk.length;
     }
-    if (this.connection) {
-      this.connection.cork();
+    if (this.socket) {
+      this.socket.cork();
       uncork = true;
     }
     write_(this, chunk, encoding, null, true);
@@ -729,16 +737,16 @@ OutgoingMessage.prototype.end = function end(chunk, encoding, callback) {
   }
 
   if (uncork)
-    this.connection.uncork();
+    this.socket.uncork();
 
   this.finished = true;
 
   // There is the first message on the outgoing queue, and we've sent
   // everything to the socket.
   debug('outgoing message end.');
   if (this.outputData.length === 0 &&
-      this.connection &&
-      this.connection._httpMessage === this) {
+      this.socket &&
+      this.socket._httpMessage === this) {
     this._finish();
   }
 
@@ -747,7 +755,7 @@ OutgoingMessage.prototype.end = function end(chunk, encoding, callback) {
 
 
 OutgoingMessage.prototype._finish = function _finish() {
-  assert(this.connection);
+  assert(this.socket);
   this.emit('prefinish');
 };
 

lib/_http_server.js

@@ -167,7 +167,7 @@ Object.setPrototypeOf(ServerResponse.prototype, OutgoingMessage.prototype);
 Object.setPrototypeOf(ServerResponse, OutgoingMessage);
 
 ServerResponse.prototype._finish = function _finish() {
-  DTRACE_HTTP_SERVER_RESPONSE(this.connection);
+  DTRACE_HTTP_SERVER_RESPONSE(this.socket);
   if (this[kServerResponseStatistics] !== undefined) {
     emitStatistics(this[kServerResponseStatistics]);
   }
@@ -205,7 +205,6 @@ ServerResponse.prototype.assignSocket = function assignSocket(socket) {
   socket._httpMessage = this;
   socket.on('close', onServerResponseClose);
   this.socket = socket;
-  this.connection = socket;
   this.emit('socket', socket);
   this._flush();
 };
@@ -214,7 +213,7 @@ ServerResponse.prototype.detachSocket = function detachSocket(socket) {
   assert(socket._httpMessage === this);
   socket.removeListener('close', onServerResponseClose);
   socket._httpMessage = null;
-  this.socket = this.connection = null;
+  this.socket = null;
 };
 
 ServerResponse.prototype.writeContinue = function writeContinue(cb) {