adding some additional documentation per bzbarsky, b=192284

netwerk/base/public/nsISyncStreamListener.idl

@@ -40,9 +40,12 @@
 interface nsISyncStreamListener : nsIStreamListener
 {
     /**
-     * Returns an input stream that when read will fetch data delivered
-     * to the sync stream listener.  The nsIInputStream implementation
-     * will wait for OnDataAvailable events before returning from Read.
+     * Returns an input stream that when read will fetch data delivered to the
+     * sync stream listener.  The nsIInputStream implementation will wait for
+     * OnDataAvailable events before returning from Read.
+     *
+     * NOTE: Reading from the returned nsIInputStream may spin the current
+     * thread's event queue, which could result in any event being processed.
      */
     readonly attribute nsIInputStream inputStream;
 };

netwerk/base/public/nsNetUtil.h

@@ -468,6 +468,9 @@ NS_NewSyncStreamListener(nsIStreamListener **aResult,
 /**
  * Implement the nsIChannel::Open(nsIInputStream**) method using the channel's
  * AsyncOpen method.
+ *
+ * NOTE: Reading from the returned nsIInputStream may spin the current
+ * thread's event queue, which could result in any event being processed.
  */
 inline nsresult
 NS_ImplementChannelOpen(nsIChannel      *aChannel,

netwerk/base/src/nsSyncStreamListener.cpp

@@ -116,9 +116,18 @@ nsSyncStreamListener::OnDataAvailable(nsIRequest     *request,
     PRUint32 bytesWritten;
 
     nsresult rv = mPipeOut->WriteFrom(stream, count, &bytesWritten);
+
+    // if we get an error, then return failure.  this will cause the
+    // channel to be canceled, and as a result our OnStopRequest method
+    // will be called immediately.  because of this we do not need to
+    // set mStatus or mKeepWaiting here.
     if (NS_FAILED(rv))
         return rv;
 
+    // we expect that all data will be written to the pipe because
+    // the pipe was created to have "infinite" room.
+    NS_ASSERTION(bytesWritten == count, "did not write all data"); 
+
     mKeepWaiting = PR_FALSE; // unblock Read
     return NS_OK;
 }