Improve documentation on safe defaults

Author: TanayParikh

src/Components/Server/src/Circuits/RemoteJSDataStream.cs

@@ -42,9 +42,9 @@ public static async ValueTask<RemoteJSDataStream> CreateRemoteJSDataStreamAsync(
             long totalLength,
             long maximumIncomingBytes,
             TimeSpan jsInteropDefaultCallTimeout,
-            long pauseIncomingBytesThreshold,
-            long resumeIncomingBytesThreshold,
-            CancellationToken cancellationToken)
+            long pauseIncomingBytesThreshold = -1,
+            long resumeIncomingBytesThreshold = -1,
+            CancellationToken cancellationToken = default)
         {
             // Enforce minimum 1 kb, maximum 50 kb, SignalR message size.
             // We budget 512 bytes overhead for the transfer, thus leaving at least 512 bytes for data

src/Components/Server/src/Circuits/RemoteJSRuntime.cs

@@ -157,7 +157,7 @@ public void MarkPermanentlyDisconnected()
             _clientProxy = null;
         }
 
-        protected override async Task<Stream> ReadJSDataAsStreamAsync(IJSStreamReference jsStreamReference, long totalLength, long pauseIncomingBytesThreshold, long resumeIncomingBytesThreshold, CancellationToken cancellationToken)
+        protected override async Task<Stream> ReadJSDataAsStreamAsync(IJSStreamReference jsStreamReference, long totalLength, long pauseIncomingBytesThreshold = -1, long resumeIncomingBytesThreshold = -1, CancellationToken cancellationToken = default)
             => await RemoteJSDataStream.CreateRemoteJSDataStreamAsync(this, jsStreamReference, totalLength, _maximumIncomingBytes, _options.JSInteropDefaultCallTimeout, pauseIncomingBytesThreshold, resumeIncomingBytesThreshold, cancellationToken);
 
         public static class Log

src/JSInterop/Microsoft.JSInterop/src/IJSStreamReference.cs

@@ -22,8 +22,17 @@ public interface IJSStreamReference : IAsyncDisposable
         /// Opens a <see cref="Stream"/> with the <see cref="JSRuntime"/> for the current data reference.
         /// </summary>
         /// <param name="maxAllowedSize">Maximum number of bytes permitted to be read from JavaScript.</param>
-        /// <param name="pauseIncomingBytesThreshold">The number of unconsumed bytes to accept from JS before blocking. A value of zero prevents JS from blocking, allowing .NET to receive an unlimited number of bytes.</param>
-        /// <param name="resumeIncomingBytesThreshold">The number of unflushed bytes at which point JS stops blocking.</param>
+        /// <param name="pauseIncomingBytesThreshold">
+        /// The number of unconsumed bytes to accept from JS before blocking.
+        /// Defaults to -1, which indicates use of the default <see cref="System.IO.Pipelines.PipeOptions.PauseWriterThreshold" />.
+        /// Avoid specifying an excessively large value because this could allow clients to exhaust memory.
+        /// A value of zero prevents JS from blocking, allowing .NET to receive an unlimited number of bytes.
+        /// </param>
+        /// <param name="resumeIncomingBytesThreshold">
+        /// The number of unflushed bytes at which point JS stops blocking.
+        /// Defaults to -1, which indicates use of the default <see cref="System.IO.Pipelines.PipeOptions.PauseWriterThreshold" />.
+        /// Must be less than the <paramref name="pauseIncomingBytesThreshold"/> to prevent thrashing at the limit.
+        /// </param>
         /// <param name="cancellationToken"><see cref="CancellationToken" /> for cancelling read.</param>
         /// <returns><see cref="Stream"/> which can provide data associated with the current data reference.</returns>
         ValueTask<Stream> OpenReadStreamAsync(long maxAllowedSize = 512000, long pauseIncomingBytesThreshold = -1, long resumeIncomingBytesThreshold = -1, CancellationToken cancellationToken = default);

src/JSInterop/Microsoft.JSInterop/src/JSRuntime.cs

@@ -215,11 +215,20 @@ protected internal virtual void ReceiveByteArray(int id, byte[] data)
         /// </summary>
         /// <param name="jsStreamReference"><see cref="IJSStreamReference"/> to produce a data stream for.</param>
         /// <param name="totalLength">Expected length of the incoming data stream.</param>
-        /// <param name="pauseIncomingBytesThreshold">The number of unconsumed bytes to accept from JS before blocking. A value of zero prevents JS from blocking, allowing .NET to receive an unlimited number of bytes.</param>
-        /// <param name="resumeIncomingBytesThreshold">The number of unflushed bytes at which point JS stops blocking.</param>
+        /// <param name="pauseIncomingBytesThreshold">
+        /// The number of unconsumed bytes to accept from JS before blocking.
+        /// Defaults to -1, which indicates use of the default <see cref="System.IO.Pipelines.PipeOptions.PauseWriterThreshold" />.
+        /// Avoid specifying an excessively large value because this could allow clients to exhaust memory.
+        /// A value of zero prevents JS from blocking, allowing .NET to receive an unlimited number of bytes.
+        /// </param>
+        /// <param name="resumeIncomingBytesThreshold">
+        /// The number of unflushed bytes at which point JS stops blocking.
+        /// Defaults to -1, which indicates use of the default <see cref="System.IO.Pipelines.PipeOptions.PauseWriterThreshold" />.
+        /// Must be less than the <paramref name="pauseIncomingBytesThreshold"/> to prevent thrashing at the limit.
+        /// </param>
         /// <param name="cancellationToken"><see cref="CancellationToken" /> for cancelling read.</param>
         /// <returns><see cref="Stream"/> for the data reference represented by <paramref name="jsStreamReference"/>.</returns>
-        protected internal virtual Task<Stream> ReadJSDataAsStreamAsync(IJSStreamReference jsStreamReference, long totalLength, long pauseIncomingBytesThreshold, long resumeIncomingBytesThreshold, CancellationToken cancellationToken)
+        protected internal virtual Task<Stream> ReadJSDataAsStreamAsync(IJSStreamReference jsStreamReference, long totalLength, long pauseIncomingBytesThreshold = -1, long resumeIncomingBytesThreshold = -1, CancellationToken cancellationToken = default)
         {
             // The reason it's virtual and not abstract is just for back-compat
 

src/JSInterop/Microsoft.JSInterop/src/PublicAPI.Unshipped.txt

@@ -36,7 +36,7 @@ static Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync(this Microsoft.JS
 static Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync(this Microsoft.JSInterop.IJSRuntime! jsRuntime, string! identifier, System.TimeSpan timeout, params object?[]? args) -> System.Threading.Tasks.ValueTask
 *REMOVED*static Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync(this Microsoft.JSInterop.IJSRuntime! jsRuntime, string! identifier, params object![]! args) -> System.Threading.Tasks.ValueTask
 static Microsoft.JSInterop.JSRuntimeExtensions.InvokeVoidAsync(this Microsoft.JSInterop.IJSRuntime! jsRuntime, string! identifier, params object?[]? args) -> System.Threading.Tasks.ValueTask
-virtual Microsoft.JSInterop.JSRuntime.ReadJSDataAsStreamAsync(Microsoft.JSInterop.IJSStreamReference! jsStreamReference, long totalLength, long pauseIncomingBytesThreshold, long resumeIncomingBytesThreshold, System.Threading.CancellationToken cancellationToken) -> System.Threading.Tasks.Task<System.IO.Stream!>!
+virtual Microsoft.JSInterop.JSRuntime.ReadJSDataAsStreamAsync(Microsoft.JSInterop.IJSStreamReference! jsStreamReference, long totalLength, long pauseIncomingBytesThreshold = -1, long resumeIncomingBytesThreshold = -1, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.IO.Stream!>!
 virtual Microsoft.JSInterop.JSRuntime.ReceiveByteArray(int id, byte[]! data) -> void
 virtual Microsoft.JSInterop.JSRuntime.SendByteArray(int id, byte[]! data) -> void
 Microsoft.JSInterop.JSDisconnectedException