Development documentation · Some APIs may be unreleased Published release →

Guides

System.IO.Compression

GZipStream implements InputStream and OutputStream in System.Runtime. It adapts async byte streams to the RFC 1952 gzip format. See the design and HTTP follow-through for implementation choices.

Member Contract
CreateCompressor(output: OutputStream, leaveOpen: bool = false) Creates a compressor; preserves output on Close when requested.
CreateDecompressor(input: InputStream, leaveOpen: bool = false) Creates a bounded decoder; preserves input on Close when requested.
Read(buffer: byte[], offset: int, count: int, cancellationToken: CancellationToken = default) Task of Result<int, StreamError>; checks complete gzip before returning bytes, then zero at EOF. Zero count does not read input.
Write(buffer: byte[], offset: int, count: int, cancellationToken: CancellationToken = default) Task of Result<unit, StreamError>; incrementally compresses and writes the complete range. Zero count emits nothing.
Finish(cancellationToken: CancellationToken = default) Task of Result<unit, StreamError>; emits final block and checksum/size trailer, including empty input. Idempotent after success.
Flush(cancellationToken: CancellationToken = default) Task of Result<unit, StreamError>; flushes the destination without finishing gzip.
Close() Idempotent disposal; never writes a trailer or flushes.

Await Finish before closing compressed output, and Flush if required by the consumer. Writes after Finish and wrong-direction operations return WrongAccess. Close defaults to closing the underlying stream; leaveOpen: true borrows it. No seeking or level selector is provided. Do not overlap operations or mutate borrowed buffers until completion.

Pre-cancellation cancels the Task before mutation or validation. Invalid ranges return InvalidRange. After Close, operations return Closed. Once input/output begins, errors or cancellation poison the wrapper; the first stream error is preserved, subsequent operations return IoFailure. Input consumed or output delivered is not rolled back.

Decompression supports all DEFLATE block types, optional headers and concatenated members. It rejects malformed headers/blocks, truncated input, checksum/size mismatch and trailing junk with StreamError.InvalidData. This additive union case may require updating exhaustive matches. It consumes the source to EOF before returning data and limits input to 65536 bytes and total decoded data to 65536 bytes; overflow returns LimitExceeded without modifying the caller's destination. Use an EOF-delimited body, not a live HTTP connection. Incremental decoding and automatic HTTP integration are gaps, not implemented behavior. Compression has no whole-stream size bound and uses bounded blocks; it can expand incompressible data.

The compiled suite demonstrates creation, Write/Finish/Read ordering, ownership and error handling. The factories avoid ambiguous .NET-style constructors when a stream supports both input and output capabilities.

StreamReader preserves binary format failures as TextReadError.InvalidData; this additive text-error case also requires updating exhaustive matches.