[Breaking change]: BrotliStream ctor no longer allows values not defined in CompressionLevel enum

[jozkee]

Description

BrotliStream ctor no longer allows values not defined in CompressionLevel enum, an ArgumentException is thrown if that's the case.

Version

.NET 7

Previous behavior

BrotliStream allowed to pass in the level to the ctor by casting the desired level directly to CompressionLevel, like this:

BrotliStream brotli = new BrotliStream(baseStream,
                                       CompressionMode.Compress,
                                       leaveOpen,
                                       bufferSize,
                                       (CompressionLevel)5); // Use level 5

New behavior

BrotliStream only allows the values defined in CompressionLevel, passing an undefined defined will result in an ArgumentException.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.

Reason for change

The purpose of the CompressionLevel enumeration is to let folks use compression algorithms without needing to understand the meaning of their tuning parameters.

If an arbitrary level was provided, that was passed through as-is to the underlying library, resulting in inconsistent and potentially unexpected behavior. With this change the behavior is aligned with other compression streams e.g: DeflateStream.

With the tuning of the CompressionLevel values made in dotnet/runtime#72266 and with the addition of CompressionLevel.SmallestSize dotnet/runtime#41960, it is now possible to have a variety of trade-offs in the compression algorithms and users can keep relying in CompressionLevel as being an abstraction of such trade-off.

Recommended action

If you were relying in passing undefined values as the CompressionLevel, be advised that you need to re-visit your use case and decide which documented value is the most optimal for it.

Feature area

Core .NET libraries

Affected APIs

public BrotliStream (System.IO.Stream stream, System.IO.Compression.CompressionLevel compressionLevel);
public BrotliStream (System.IO.Stream stream, System.IO.Compression.CompressionMode mode);
public BrotliStream (System.IO.Stream stream, System.IO.Compression.CompressionLevel compressionLevel, bool leaveOpen);
public BrotliStream (System.IO.Stream stream, System.IO.Compression.CompressionMode mode, bool leaveOpen);

[jozkee]

I listed all ctors as affected APIs, it should only be the ones with compressionLevel argument. Sorry.