SPRXCLT-12: improve comments

lib/sproxyd.js

@@ -321,6 +321,8 @@ class SproxydClient {
             });
 
             const startPayloadStreaming = () => {
+                // Once we start piping the stream, it starts being consumed and
+                // we can't replay it (in the current implementation)
                 streamingStarted = true;
                 stream.pipe(request);
                 finished(stream, err => {
@@ -334,9 +336,20 @@ class SproxydClient {
                 });
             };
 
-            // Only start streaming when connection is guaranteed: either on a
-            // new connection or a reused one.
-            // There is a possible race that makes 
+            // We have two goals:
+            // - Ensure we properly handle connection reuse: 'connect' event
+            //   won't happen for every request.
+            // - Be able to retry (see _failover) the request when we can't
+            //   connect to sproxyd. For this, we must only start consuming the
+            //   stream when a socket is available: either on 'connect' or when
+            //   reusing a socket. If we get a failure after starting to send
+            //   the data, this implementation cannot retry.
+            //
+            // There is a possible race when an open socket is reused, but
+            // closed by the server for inactivity before we can use it. In this
+            // case, the current implementation cannot retry and will return a
+            // 50x. This can be avoided by ensuring servers have a longer HTTP
+            // keepalive time than clients.
             request.on('socket', (socket) => {
                 // We can start streaming when reusing a socket
                 if (request.reusedSocket) {