Fix StreamReader#close and align #read with Ruby's IO conventions

[sribalakumar]

Fixes #149.

Opening this as a concrete proposal — happy to close it if you'd prefer the non-breaking route I mentioned in the issue (leave StreamReader as-is, add a separate IO-conformant class instead). No hard feelings either way.

What changed

Two bugs here, plus one convention fix:

• StreamReader#read passed length straight through to the underlying IO, so it read that many compressed bytes and returned however many decompressed bytes fell out. The return size tracked the compression ratio instead of the caller's request.
• close raised NoMethodError on every call — it tried to call @stream.finish, which StreamingDecompress doesn't define, and wrote to @io, which is only open for reading.

This patch buffers decompressed output and serves reads from that buffer, so length means decompressed bytes, and fixes close to just close the IO.

	before	after
read(512), 44-byte frame	240000 bytes	512
read(512) x4, 20 KB frame	[0, 0, 0, 0]	[512, 512, 512, 512]
at EOF	raises StandardError	nil
close	NoMethodError	closes the IO

Also adds eof?, read with no length, and an outbuf argument.

Why stream_writer.rb is in this diff

It's a one-character change, not a behaviour change: the @todo Exprimental marker was misspelled, so this fixes it to @todo Experimental on both StreamReader and StreamWriter. The marker itself is deliberately kept on StreamReader — this PR doesn't promote it to a stable API, it stays experimental.

On decompress_with_pos

Refills use decompress_with_pos rather than decompress. decompress loops until all input is consumed, so output per call is unbounded — with a high compression ratio a 64 KB read can expand to hundreds of MB in the buffer. decompress_with_pos writes at most ZSTD_DStreamOutSize bytes per call and reports how much input it consumed, which keeps the buffer bounded regardless of ratio. That matters when the compressed input isn't trusted.

Measured on a 14.3 MB archive (64x ratio), peak buffer: decompress 4.6 MB -> decompress_with_pos 0.57 MB.

Breaking change

read's semantics change, so this is breaking for anyone depending on the current behaviour. The existing spec's expectations change accordingly:

# before
expect(reader.read(10)).to eq('a')
expect(reader.read(10)).to eq('bcdef')
expect(reader.read(10)).to eq('')

# after
expect(reader.read(10)).to eq('abcdef')
expect(reader.read(10)).to be_nil

read also becomes arity-optional to match IO#read.

Tests

Full suite passes — 88 examples, 0 failures (was 69). New coverage: exact-length reads across block boundaries, ratio independence, nil at EOF, read with no args, read(0), negative length, outbuf (including the EOF case), eof?, close, custom chunk_size, round-trip integrity for both compressible and incompressible input, and an end-to-end test driving Gem::Package::TarReader through the reader.

[sribalakumar]

@SpringMT @Watson1978 — thanks for all the work on this gem!

Since this is my first PR here, GitHub is holding the CI workflow runs pending approval (the standard first-time-contributor gate), so the checks show as empty rather than failing. Would one of you be able to approve the pending runs when you get a chance? The full suite passes locally (88 examples, 0 failures), so hopefully it won't cost much CI time.

On the open question in #149 — whether changing read(n)'s semantics is too breaking — I'm genuinely happy to rework this as a non-breaking addition alongside the existing StreamReader#read if you'd prefer.

[sribalakumar]

@SpringMT I addressed pipeline failures noticed with Ruby 2.7 syntaxError. Can you reapprove the workflows so a new pipeline is run.