brotli 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfcc8a08b7351d54f9472ca2b549733eac9d4be139c3ba9f1ebfe41c3f8fb057
-  data.tar.gz: 98764c09827125ba6304a6910a84e1674f4dcd6a3e13793b4438ea5c9a96f815
+  metadata.gz: 439249d900d92fdfbdba0c607d03b1cc52be123ed909bf7971d6c8b89c8134de
+  data.tar.gz: 3ae1816fee964948daedfa0835f2098efd4526def10f855f6a3fcc415ad56ce1
 SHA512:
-  metadata.gz: d24c3f2595c9578a71e9d1a3208bcd74e95197e17f796ba3df72dd36818189a0838e79b9ae5ffcf668f258718a2c260142866e419993b4282bada394199d025b
-  data.tar.gz: 891d4714d76a902d38898e9287063e97e8161be0f4e7af3f91477af5a7412c25d73b881dbd0d1031457458a69b3c4f0b466ab953a519318664acd3332c057fb7
+  metadata.gz: 330cc7d4176f2ede18d615c7c51862131182c5e3826d164b3cced606a490924d44ef349ab746677e8f62f547a87601ddc65c5f95197a7cc43f53e87f1a7f448d
+  data.tar.gz: 711194c375cd78bba734cb5ae4b89270ddcbaa8a457e3e45b055a6334a0a684d1f7351780c868a965c804cab306796949f5e915a60bbeb95f332b6900fea68a6

data/.github/workflows/main.yml

@@ -7,7 +7,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [2.7, 3.1, 3.2, 3.3]
+        ruby: [3.1, 3.2, 3.3, 3.4]
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4

data/Dockerfile

@@ -0,0 +1,38 @@
+ARG GCC_VERSION=14
+FROM gcc:${GCC_VERSION}
+
+ARG USE_SYSTEM_BROTLI=true
+
+# Install Ruby and development dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    libbrotli-dev \
+    pkg-config \
+    ruby \
+    ruby-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Verify GCC version
+RUN gcc --version
+
+# Set working directory
+WORKDIR /app
+
+# Copy source code
+COPY . .
+
+# Install bundler and dependencies
+RUN gem install bundler
+RUN bundle install
+
+# Build and test
+RUN if [ "${USE_SYSTEM_BROTLI}" = "true" ]; then \
+        echo "Building with system Brotli" && \
+        bundle exec rake compile; \
+    else \
+        echo "Building with vendor Brotli" && \
+        bundle exec rake compile -- --enable-vendor; \
+    fi
+RUN bundle exec rake test
+
+CMD ["bash"]

data/README.md

@@ -25,19 +25,180 @@ Or install it yourself as:
 
 ## Usage
 
+### Basic Compression/Decompression
+
 ```ruby
 require 'brotli'
 compressed = Brotli.deflate(string)
 decompressed = Brotli.inflate(compressed)
 ```
 
-See test/brotli_test.rb
+### Custom Dictionary Support
+
+Brotli supports using custom dictionaries to improve compression ratio when you have repetitive data patterns:
+
+```ruby
+# Using a dictionary that contains common patterns in your data
+dictionary = "common patterns in my data"
+data = "This text contains common patterns in my data multiple times"
+
+# Compress with dictionary
+compressed = Brotli.deflate(data, dictionary: dictionary)
+
+# Decompress with the same dictionary
+decompressed = Brotli.inflate(compressed, dictionary: dictionary)
+```
+
+### Compression Options
+
+```ruby
+# Combine dictionary with other compression options
+compressed = Brotli.deflate(data,
+  dictionary: dictionary,
+  quality: 11,        # 0-11, higher = better compression but slower
+  mode: :text,        # :generic (default), :text, or :font
+  lgwin: 22,          # window size (10-24)
+  lgblock: 0          # block size (0 or 16-24)
+)
+```
+
+### Streaming Compression with Writer
+
+```ruby
+# Basic usage
+File.open('output.br', 'wb') do |file|
+  writer = Brotli::Writer.new(file)
+  writer.write(data)
+  writer.close
+end
+
+# With dictionary
+File.open('output.br', 'wb') do |file|
+  writer = Brotli::Writer.new(file, dictionary: dictionary)
+  writer.write(data)
+  writer.close
+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,6 +20,23 @@ 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"]
+  brotli_configs = [true, false]
+  gcc_versions.product(brotli_configs).each do |gcc_version, use_system_brotli|
+    command = "docker build "\
+              "--progress=plain "\
+              "--build-arg GCC_VERSION=#{gcc_version} "\
+              "--build-arg USE_SYSTEM_BROTLI=#{use_system_brotli} "\
+              "-t brotli:#{gcc_version}#{use_system_brotli ? "-use_system_brotli" : ""} ."
+    puts "Running: #{command}"
+    system command
+    unless $?.exited?
+      raise "Docker build failed for GCC version #{gcc_version} with use_system_brotli=#{use_system_brotli}"
+    end
+  end
+end

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