brotli 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3722424560d3f3491399e46108213ae088a809ca502fe2c9f8a83d5c9383434
-  data.tar.gz: 4584239a0597b0c2e5cf47ba0d6c8a96e0198cc8af7c7b217f8bf1312bab56d8
+  metadata.gz: 439249d900d92fdfbdba0c607d03b1cc52be123ed909bf7971d6c8b89c8134de
+  data.tar.gz: 3ae1816fee964948daedfa0835f2098efd4526def10f855f6a3fcc415ad56ce1
 SHA512:
-  metadata.gz: ca8b9c2bfae436c8b19d657948e0a2f2a3137d05ef9af070f2de4625ffcbe9cb7dd2e6eb011c8e475ea16a74ac5825b9dc074ab95b809e68ce722a06ce72798d
-  data.tar.gz: b5864a5aeb5630e8ad9b491621d89aa4c12f65131a261e49b0499d35cd5b32d43288ddbccb10cfe2ab7201d140e1ae311a0cbb1328cc0a010fad4ad775db8f2d
+  metadata.gz: 330cc7d4176f2ede18d615c7c51862131182c5e3826d164b3cced606a490924d44ef349ab746677e8f62f547a87601ddc65c5f95197a7cc43f53e87f1a7f448d
+  data.tar.gz: 711194c375cd78bba734cb5ae4b89270ddcbaa8a457e3e45b055a6334a0a684d1f7351780c868a965c804cab306796949f5e915a60bbeb95f332b6900fea68a6

data/README.md

@@ -80,13 +80,125 @@ File.open('output.br', 'wb') do |file|
 end
 ```
 
+### Streaming Decompression with Reader
+
+```ruby
+# Basic usage
+File.open('output.br', 'rb') do |file|
+  reader = Brotli::Reader.new(file)
+  data = reader.read
+  reader.close
+end
+
+# With dictionary
+File.open('output.br', 'rb') do |file|
+  reader = Brotli::Reader.new(file, dictionary: dictionary)
+  data = reader.read
+  reader.close
+end
+```
+
+`Brotli::Reader` is the preferred API when you already have an IO-like input.
+It handles incremental decompression for you, including small `read` and
+`readpartial` calls.
+
+### Low-level Streaming with Compressor and Decompressor
+
+`Brotli::Writer` and `Brotli::Reader` are the preferred high-level streaming
+interfaces. `Brotli::Compressor` and `Brotli::Decompressor` are lower-level
+primitives intended for integrations which already manage their own buffering
+and chunk boundaries.
+
+Use `Brotli::Writer` and `Brotli::Reader` when you have an IO-like stream and
+want Brotli to handle the streaming lifecycle for you.
+
+Use `Brotli::Compressor` and `Brotli::Decompressor` when your application
+already owns the buffering model, for example when working with framed
+protocols, event loops, chunked transports, or custom body transcoders.
+
+This is a typical chunk-by-chunk compression pattern:
+
+```ruby
+compressor = Brotli::Compressor.new
+
+compressed_chunk = compressor.process(input_chunk)
+compressed_chunk << compressor.flush
+
+# when the input stream is finished
+compressed_tail = compressor.finish
+```
+
+And this is the corresponding incremental decompression pattern:
+
+```ruby
+decompressor = Brotli::Decompressor.new
+output = +""
+
+compressed_chunks.each do |input_chunk|
+  output << decompressor.process(input_chunk)
+end
+
+unless decompressor.finished?
+  raise Brotli::Error, "Unexpected end of compressed stream"
+end
+```
+
+For fully chunked or frame-based transports, call `#process` once per received
+compressed chunk and append the returned output. `#finished?` tells you whether
+the full Brotli stream has been decoded, and `#can_accept_more_data` indicates
+whether the decompressor is ready for more input or still has buffered output to
+drain first.
+
+These low-level classes are useful when you need to plug Brotli into an
+existing incremental pipeline without wrapping the stream in an IO-like object.
+
+### `output_buffer_limit`
+
+`Brotli::Decompressor#process` also accepts `output_buffer_limit:`:
+
+```ruby
+decompressor = Brotli::Decompressor.new
+output = +""
+
+compressed_chunks.each do |chunk|
+  output << decompressor.process(chunk, output_buffer_limit: 16 * 1024)
+
+  until decompressor.can_accept_more_data || decompressor.finished?
+    output << decompressor.process("", output_buffer_limit: 16 * 1024)
+  end
+end
+
+unless decompressor.finished?
+  raise Brotli::Error, "Unexpected end of compressed stream"
+end
+```
+
+`output_buffer_limit:` caps how many decompressed bytes are returned from a
+single `#process` call. When the limit is reached, the decompressor may still
+have buffered state to drain. In that case `#can_accept_more_data` returns
+`false`, and you should keep calling `#process("")` until it becomes `true`
+again or the stream is finished.
+
+Use `output_buffer_limit:` when:
+
+- you want to bound memory usage or work per iteration
+- you are feeding decompressed bytes into a downstream consumer with backpressure
+- you are integrating Brotli into an event loop, framed protocol, or chunked transport
+- you are reading small slices from a large compressed payload and do not want a single call to return a very large output buffer
+
+You usually do not need `output_buffer_limit:` when:
+
+- you are using `Brotli.inflate` for one-shot decompression
+- you are using `Brotli::Reader`, which already handles incremental buffering for IO-style reads
+- you are happy for each `#process` call to return all currently available output
+
 See test/brotli_test.rb for more examples.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install bundle and Brotli C library dependencies.
 
-Run `rake build` to build brotli extension for ruby. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Run `rake build` to build the Brotli extension for Ruby. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -20,9 +20,9 @@ Rake::ExtensionTask.new("brotli") do |ext|
   ext.lib_dir = "lib/brotli"
 end
 
-task :build => :compile
-task :test => :compile
-task :default => :test
+task build: :compile
+task test: :compile
+task default: :test
 
 task :docker do
   gcc_versions = ["14", "15"]

data/brotli.gemspec

@@ -1,7 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "brotli/version"
+require_relative "lib/brotli/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "brotli"
@@ -14,14 +11,17 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/miyucy/brotli"
   spec.license       = "MIT"
 
-  spec.test_files    = `git ls-files -z -- test`.split("\x0")
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.files        -= spec.test_files
-  spec.files        -= ["vendor/brotli"]
-  spec.files        += Dir["vendor/brotli/c/{common,enc,dec,include}/**/*"]
-  spec.files        += ["vendor/brotli/LICENSE"]
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  tracked_files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  vendored_brotli_files = Dir.chdir(__dir__) do
+    Dir["vendor/brotli/c/{common,enc,dec,include}/**/*"].select { |path| File.file?(path) }
+  end
+
+  spec.files = tracked_files
+               .reject { |path| path == "vendor/brotli" || path.start_with?("test/") }
+               .concat(vendored_brotli_files)
+               .append("vendor/brotli/LICENSE")
+               .sort
+               .uniq
   spec.require_paths = ["lib"]
   spec.extensions    = ["ext/brotli/extconf.rb"]
 end