]
+ def parse_accept_encoding(header)
+ return Set.new if header.empty?
+
+ encodings = Set.new
+ header.split(',').each do |part|
+ encoding, quality = part.strip.split(';', 2)
+ encoding = encoding.strip.downcase
+ if quality
+ q_val = quality.strip.match(/q=(\d+\.?\d*)/)
+ next if q_val && q_val[1].to_f == 0
+ end
+ encodings << encoding.to_sym
+ end
+ encodings
+ end
+ end
+end
diff --git a/lib/datastar/compressor/brotli.rb b/lib/datastar/compressor/brotli.rb
new file mode 100644
index 0000000..698bba3
--- /dev/null
+++ b/lib/datastar/compressor/brotli.rb
@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'brotli'
+
+module Datastar
+ module Compressor
+ # Brotli compressor — built once at config time, reused across requests.
+ # Eagerly requires the brotli gem; raises LoadError at boot if missing.
+ class Brotli
+ attr_reader :encoding
+
+ def initialize(options)
+ @options = options.freeze
+ @encoding = :br
+ freeze
+ end
+
+ def prepare_response(response)
+ response.headers['Content-Encoding'] = 'br'
+ response.headers['Vary'] = 'Accept-Encoding'
+ end
+
+ def wrap_socket(socket)
+ CompressedSocket.new(socket, @options)
+ end
+
+ # Brotli compressed socket using the `brotli` gem.
+ # Options are passed directly to Brotli::Compressor.new:
+ # :quality - Compression quality (0-11, default: 11). Lower is faster, higher compresses better.
+ # :lgwin - Base-2 log of the sliding window size (10-24, default: 22).
+ # :lgblock - Base-2 log of the maximum input block size (16-24, 0 = auto, default: 0).
+ # :mode - Compression mode (:generic, :text, or :font, default: :generic).
+ # Use :text for UTF-8 formatted text (HTML, JSON — good for SSE).
+ class CompressedSocket
+ def initialize(socket, options = {})
+ @socket = socket
+ @compressor = ::Brotli::Compressor.new(options)
+ end
+
+ def <<(data)
+ compressed = @compressor.process(data)
+ @socket << compressed if compressed && !compressed.empty?
+ flushed = @compressor.flush
+ @socket << flushed if flushed && !flushed.empty?
+ self
+ end
+
+ def close
+ final = @compressor.finish
+ @socket << final if final && !final.empty?
+ @socket.close
+ end
+ end
+ end
+ end
+end
diff --git a/lib/datastar/compressor/gzip.rb b/lib/datastar/compressor/gzip.rb
new file mode 100644
index 0000000..21b3b6d
--- /dev/null
+++ b/lib/datastar/compressor/gzip.rb
@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'zlib'
+
+module Datastar
+ module Compressor
+ # Gzip compressor — built once at config time, reused across requests.
+ class Gzip
+ attr_reader :encoding
+
+ def initialize(options)
+ @options = options.freeze
+ @encoding = :gzip
+ freeze
+ end
+
+ def prepare_response(response)
+ response.headers['Content-Encoding'] = 'gzip'
+ response.headers['Vary'] = 'Accept-Encoding'
+ end
+
+ def wrap_socket(socket)
+ CompressedSocket.new(socket, @options)
+ end
+
+ # Gzip compressed socket using Ruby's built-in zlib.
+ # Options:
+ # :level - Compression level (0-9, default: Zlib::DEFAULT_COMPRESSION).
+ # 0 = no compression, 1 = best speed, 9 = best compression.
+ # Zlib::BEST_SPEED (1) and Zlib::BEST_COMPRESSION (9) also work.
+ # :mem_level - Memory usage level (1-9, default: 8). Higher uses more memory for better compression.
+ # :strategy - Compression strategy (default: Zlib::DEFAULT_STRATEGY).
+ # Zlib::FILTERED, Zlib::HUFFMAN_ONLY, Zlib::RLE, Zlib::FIXED are also available.
+ class CompressedSocket
+ def initialize(socket, options = {})
+ level = options.fetch(:level, Zlib::DEFAULT_COMPRESSION)
+ mem_level = options.fetch(:mem_level, Zlib::DEF_MEM_LEVEL)
+ strategy = options.fetch(:strategy, Zlib::DEFAULT_STRATEGY)
+ # Use raw deflate with gzip wrapping (window_bits 31 = 15 + 16)
+ @socket = socket
+ @deflate = Zlib::Deflate.new(level, 31, mem_level, strategy)
+ end
+
+ def <<(data)
+ compressed = @deflate.deflate(data, Zlib::SYNC_FLUSH)
+ @socket << compressed if compressed && !compressed.empty?
+ self
+ end
+
+ def close
+ final = @deflate.finish
+ @socket << final if final && !final.empty?
+ @socket.close
+ ensure
+ @deflate.close
+ end
+ end
+ end
+ end
+end
diff --git a/lib/datastar/configuration.rb b/lib/datastar/configuration.rb
index 3df339b..12cb0d4 100644
--- a/lib/datastar/configuration.rb
+++ b/lib/datastar/configuration.rb
@@ -35,6 +35,7 @@ class Configuration
DEFAULT_HEARTBEAT = 3
attr_accessor :executor, :error_callback, :finalize, :heartbeat, :logger
+ attr_reader :compression
def initialize
@executor = ThreadExecutor.new
@@ -44,6 +45,11 @@ def initialize
@error_callback = proc do |e|
@logger.error("#{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
end
+ @compression = CompressionConfig.build(false)
+ end
+
+ def compression=(value)
+ @compression = value.is_a?(CompressionConfig) ? value : CompressionConfig.build(value)
end
def on_error(callable = nil, &block)
diff --git a/lib/datastar/dispatcher.rb b/lib/datastar/dispatcher.rb
index 98e4600..053ee96 100644
--- a/lib/datastar/dispatcher.rb
+++ b/lib/datastar/dispatcher.rb
@@ -44,7 +44,8 @@ def initialize(
executor: Datastar.config.executor,
error_callback: Datastar.config.error_callback,
finalize: Datastar.config.finalize,
- heartbeat: Datastar.config.heartbeat
+ heartbeat: Datastar.config.heartbeat,
+ compression: Datastar.config.compression
)
@on_connect = []
@on_client_disconnect = []
@@ -68,6 +69,11 @@ def initialize(
@heartbeat = heartbeat
@heartbeat_on = false
+
+ # Negotiate compression
+ compression = CompressionConfig.build(compression) unless compression.is_a?(CompressionConfig)
+ @compressor = compression.negotiate(request)
+ @compressor.prepare_response(@response)
end
# Check if the request accepts SSE responses
@@ -283,6 +289,7 @@ def stream_no_heartbeat(&block)
# @api private
def stream_one(streamer)
proc do |socket|
+ socket = wrap_socket(socket)
generator = ServerSentEventGenerator.new(socket, signals:, view_context: @view_context)
@on_connect.each { |callable| callable.call(generator) }
handling_sync_errors(generator, socket) do
@@ -308,6 +315,7 @@ def stream_many(streamer)
@queue ||= @executor.new_queue
proc do |socket|
+ socket = wrap_socket(socket)
signs = signals
conn_generator = ServerSentEventGenerator.new(socket, signals: signs, view_context: @view_context)
@on_connect.each { |callable| callable.call(conn_generator) }
@@ -360,6 +368,13 @@ def stream_many(streamer)
end
end
+ # Wrap socket in a CompressedSocket if compression is negotiated
+ # @param socket [IO]
+ # @return [CompressedSocket, IO]
+ def wrap_socket(socket)
+ @compressor.wrap_socket(socket)
+ end
+
# Handle errors caught during streaming
# @param error [Exception] the error that occurred
# @param socket [IO] the socket to pass to error handlers
diff --git a/spec/compressed_socket_spec.rb b/spec/compressed_socket_spec.rb
new file mode 100644
index 0000000..f208ab6
--- /dev/null
+++ b/spec/compressed_socket_spec.rb
@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'datastar'
+require 'datastar/compressor/gzip'
+require 'datastar/compressor/brotli'
+
+RSpec.describe 'Compressor compressed sockets' do
+ let(:raw_socket) { StringSocket.new }
+ let(:sse_data) { "event: datastar-patch-signals\ndata: signals {\"foo\":\"bar\"}\n\n" }
+
+ # A simple socket that collects binary data
+ class StringSocket
+ attr_reader :closed
+
+ def initialize
+ @buffer = String.new(encoding: Encoding::BINARY)
+ @closed = false
+ end
+
+ def <<(data)
+ @buffer << data.b
+ self
+ end
+
+ def close
+ @closed = true
+ end
+
+ def bytes
+ @buffer
+ end
+ end
+
+ describe Datastar::Compressor::Gzip::CompressedSocket do
+ subject(:socket) { described_class.new(raw_socket) }
+
+ it 'compresses data and decompresses to original' do
+ socket << sse_data
+ socket.close
+
+ decompressed = Zlib::Inflate.new(31).inflate(raw_socket.bytes)
+ expect(decompressed).to eq(sse_data)
+ end
+
+ it 'flushes data after each write (data available before close)' do
+ socket << sse_data
+ # Data should be in raw_socket before close
+ expect(raw_socket.bytes).not_to be_empty
+
+ partial = Zlib::Inflate.new(31).inflate(raw_socket.bytes)
+ expect(partial).to eq(sse_data)
+ end
+
+ it 'handles multiple writes' do
+ data1 = "event: datastar-patch-signals\ndata: signals {\"a\":1}\n\n"
+ data2 = "event: datastar-patch-signals\ndata: signals {\"b\":2}\n\n"
+
+ socket << data1
+ socket << data2
+ socket.close
+
+ decompressed = Zlib::Inflate.new(31).inflate(raw_socket.bytes)
+ expect(decompressed).to eq(data1 + data2)
+ end
+
+ it 'closes the underlying socket' do
+ socket << sse_data
+ socket.close
+ expect(raw_socket.closed).to be(true)
+ end
+
+ it 'accepts compression level option' do
+ socket = described_class.new(raw_socket, level: Zlib::BEST_SPEED)
+ socket << sse_data
+ socket.close
+
+ decompressed = Zlib::Inflate.new(31).inflate(raw_socket.bytes)
+ expect(decompressed).to eq(sse_data)
+ end
+ end
+
+ describe Datastar::Compressor::Brotli::CompressedSocket do
+ subject(:socket) { described_class.new(raw_socket) }
+
+ it 'compresses data and decompresses to original' do
+ socket << sse_data
+ socket.close
+
+ decompressed = ::Brotli.inflate(raw_socket.bytes)
+ expect(decompressed).to eq(sse_data)
+ end
+
+ it 'flushes data after each write (data available before close)' do
+ socket << sse_data
+ expect(raw_socket.bytes).not_to be_empty
+ end
+
+ it 'handles multiple writes' do
+ data1 = "event: datastar-patch-signals\ndata: signals {\"a\":1}\n\n"
+ data2 = "event: datastar-patch-signals\ndata: signals {\"b\":2}\n\n"
+
+ socket << data1
+ socket << data2
+ socket.close
+
+ decompressed = ::Brotli.inflate(raw_socket.bytes)
+ expect(decompressed).to eq(data1 + data2)
+ end
+
+ it 'closes the underlying socket' do
+ socket << sse_data
+ socket.close
+ expect(raw_socket.closed).to be(true)
+ end
+ end
+
+end
diff --git a/spec/compression_config_spec.rb b/spec/compression_config_spec.rb
new file mode 100644
index 0000000..a0e715d
--- /dev/null
+++ b/spec/compression_config_spec.rb
@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'datastar'
+require 'rack'
+
+RSpec.describe Datastar::CompressionConfig do
+ describe '.build' do
+ it 'returns a disabled config for false' do
+ config = described_class.build(false)
+ expect(config.enabled?).to be(false)
+ end
+
+ it 'returns a disabled config for nil' do
+ config = described_class.build(nil)
+ expect(config.enabled?).to be(false)
+ end
+
+ it 'returns an enabled config with br and gzip for true' do
+ config = described_class.build(true)
+ expect(config.enabled?).to be(true)
+ end
+
+ it 'builds compressors from an array of symbols' do
+ config = described_class.build([:gzip])
+ expect(config.enabled?).to be(true)
+
+ request = build_request('Accept-Encoding' => 'gzip')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:gzip)
+ end
+
+ it 'builds compressors from nested array with options' do
+ config = described_class.build([[:gzip, { level: 1 }]])
+ expect(config.enabled?).to be(true)
+
+ request = build_request('Accept-Encoding' => 'gzip')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:gzip)
+ end
+
+ it 'builds mixed array of symbols and [symbol, hash] pairs' do
+ config = described_class.build([[:br, { quality: 5 }], :gzip])
+ expect(config.enabled?).to be(true)
+ end
+
+ it 'returns the input if already a CompressionConfig' do
+ original = described_class.build(true)
+ expect(described_class.build(original)).to equal(original)
+ end
+
+ it 'raises ArgumentError for invalid input' do
+ expect { described_class.build('invalid') }.to raise_error(ArgumentError)
+ end
+
+ it 'raises ArgumentError for unknown compressor symbol' do
+ expect { described_class.build([:deflate]) }.to raise_error(ArgumentError, /Unknown compressor/)
+ end
+
+ it 'raises LoadError at build time if brotli compressor file cannot be loaded' do
+ allow(described_class).to receive(:build_compressor).and_call_original
+ allow(described_class).to receive(:build_compressor).with(:br).and_raise(LoadError)
+ expect { described_class.build([:br]) }.to raise_error(LoadError)
+ end
+ end
+
+ describe '#negotiate' do
+ it 'returns Null compressor when disabled' do
+ config = described_class.build(false)
+ request = build_request('Accept-Encoding' => 'br, gzip')
+ compressor = config.negotiate(request)
+ expect(compressor).to be_a(Datastar::Compressor::Null)
+ expect(compressor.encoding).to be_nil
+ end
+
+ it 'returns Null compressor when no Accept-Encoding header' do
+ config = described_class.build(true)
+ request = build_request
+ compressor = config.negotiate(request)
+ expect(compressor).to be_a(Datastar::Compressor::Null)
+ end
+
+ it 'returns gzip compressor when client accepts gzip' do
+ config = described_class.build([:gzip])
+ request = build_request('Accept-Encoding' => 'gzip')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:gzip)
+ end
+
+ it 'returns first compressor (preferred) when client supports both' do
+ config = described_class.build([:br, :gzip])
+ request = build_request('Accept-Encoding' => 'br, gzip')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:br)
+ end
+
+ it 'respects list order for preference' do
+ config = described_class.build([:gzip, :br])
+ request = build_request('Accept-Encoding' => 'br, gzip')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:gzip)
+ end
+
+ it 'falls back to second compressor if client does not accept first' do
+ config = described_class.build([:gzip])
+ request = build_request('Accept-Encoding' => 'gzip')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:gzip)
+ end
+
+ it 'returns Null when client encoding not in configured list' do
+ config = described_class.build([:gzip])
+ request = build_request('Accept-Encoding' => 'br')
+ compressor = config.negotiate(request)
+ expect(compressor).to be_a(Datastar::Compressor::Null)
+ end
+
+ it 'returns Null when Accept-Encoding has q=0 for all' do
+ config = described_class.build(true)
+ request = build_request('Accept-Encoding' => 'gzip;q=0, br;q=0')
+ compressor = config.negotiate(request)
+ expect(compressor).to be_a(Datastar::Compressor::Null)
+ end
+
+ it 'handles Accept-Encoding with quality values' do
+ config = described_class.build([:gzip])
+ request = build_request('Accept-Encoding' => 'gzip;q=1.0, br;q=0.5')
+ compressor = config.negotiate(request)
+ expect(compressor.encoding).to eq(:gzip)
+ end
+ end
+
+ describe 'Compressor::NONE' do
+ subject(:null) { Datastar::Compressor::NONE }
+
+ it 'is a frozen constant' do
+ expect(null).to be_frozen
+ expect(null).to equal(Datastar::Compressor::NONE)
+ end
+
+ it 'returns nil encoding' do
+ expect(null.encoding).to be_nil
+ end
+
+ it 'returns the socket unchanged from wrap_socket' do
+ socket = Object.new
+ expect(null.wrap_socket(socket)).to equal(socket)
+ end
+
+ it 'prepare_response is a no-op' do
+ response = double('response')
+ expect(null.prepare_response(response)).to be_nil
+ end
+ end
+
+ describe 'Compressor::Gzip' do
+ subject(:compressor) { Datastar::Compressor::Gzip.new({}) }
+
+ it 'has :gzip encoding' do
+ expect(compressor.encoding).to eq(:gzip)
+ end
+
+ it 'sets response headers' do
+ headers = {}
+ response = double('response', headers: headers)
+ compressor.prepare_response(response)
+ expect(headers['Content-Encoding']).to eq('gzip')
+ expect(headers['Vary']).to eq('Accept-Encoding')
+ end
+
+ it 'wraps socket in Gzip::CompressedSocket' do
+ socket = Object.new
+ wrapped = compressor.wrap_socket(socket)
+ expect(wrapped).to be_a(Datastar::Compressor::Gzip::CompressedSocket)
+ end
+ end
+
+ describe 'Compressor::Brotli' do
+ subject(:compressor) { Datastar::Compressor::Brotli.new({}) }
+
+ it 'has :br encoding' do
+ expect(compressor.encoding).to eq(:br)
+ end
+
+ it 'sets response headers' do
+ headers = {}
+ response = double('response', headers: headers)
+ compressor.prepare_response(response)
+ expect(headers['Content-Encoding']).to eq('br')
+ expect(headers['Vary']).to eq('Accept-Encoding')
+ end
+
+ it 'wraps socket in Brotli::CompressedSocket' do
+ socket = Object.new
+ wrapped = compressor.wrap_socket(socket)
+ expect(wrapped).to be_a(Datastar::Compressor::Brotli::CompressedSocket)
+ end
+ end
+
+ private
+
+ def build_request(headers = {})
+ env = Rack::MockRequest.env_for('/', headers.transform_keys { |k| "HTTP_#{k.upcase.tr('-', '_')}" })
+ Rack::Request.new(env)
+ end
+end
diff --git a/spec/dispatcher_spec.rb b/spec/dispatcher_spec.rb
index 8c3b36b..09b6157 100644
--- a/spec/dispatcher_spec.rb
+++ b/spec/dispatcher_spec.rb
@@ -610,8 +610,106 @@ def self.render_in(view_context) = %(\n#{view_context} 'br, gzip' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: true)
+
+ expect(dispatcher.response['Content-Encoding']).to eq('br')
+ expect(dispatcher.response['Vary']).to eq('Accept-Encoding')
+ end
+
+ it 'sets Content-Encoding: gzip when compression enabled and client accepts gzip only' do
+ request = build_request('/events', headers: { 'HTTP_ACCEPT_ENCODING' => 'gzip' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: true)
+
+ expect(dispatcher.response['Content-Encoding']).to eq('gzip')
+ expect(dispatcher.response['Vary']).to eq('Accept-Encoding')
+ end
+
+ it 'does not set Content-Encoding when compression enabled but no Accept-Encoding' do
+ request = build_request('/events')
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: true)
+
+ expect(dispatcher.response['Content-Encoding']).to be_nil
+ expect(dispatcher.response['Vary']).to be_nil
+ end
+
+ it 'does not set Content-Encoding when compression disabled' do
+ request = build_request('/events', headers: { 'HTTP_ACCEPT_ENCODING' => 'br, gzip' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: false)
+
+ expect(dispatcher.response['Content-Encoding']).to be_nil
+ end
+
+ it 'streams gzip-compressed data that decompresses correctly' do
+ request = build_request('/events', headers: { 'HTTP_ACCEPT_ENCODING' => 'gzip' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: true, heartbeat: false)
+
+ dispatcher.patch_signals(foo: 'bar')
+
+ raw_socket = BinarySocket.new
+ dispatcher.response.body.call(raw_socket)
+
+ decompressed = Zlib::Inflate.new(31).inflate(raw_socket.bytes)
+ expect(decompressed).to include('datastar-patch-signals')
+ expect(decompressed).to include('"foo":"bar"')
+ end
+
+ it 'streams brotli-compressed data that decompresses correctly' do
+ request = build_request('/events', headers: { 'HTTP_ACCEPT_ENCODING' => 'br' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: true, heartbeat: false)
+
+ dispatcher.patch_signals(foo: 'bar')
+
+ raw_socket = BinarySocket.new
+ dispatcher.response.body.call(raw_socket)
+
+ decompressed = Brotli.inflate(raw_socket.bytes)
+ expect(decompressed).to include('datastar-patch-signals')
+ expect(decompressed).to include('"foo":"bar"')
+ end
+
+ it 'respects compression order as preference (gzip first)' do
+ request = build_request('/events', headers: { 'HTTP_ACCEPT_ENCODING' => 'br, gzip' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: [:gzip, :br])
+
+ expect(dispatcher.response['Content-Encoding']).to eq('gzip')
+ end
+
+ it 'respects compression as array of enabled encodings' do
+ request = build_request('/events', headers: { 'HTTP_ACCEPT_ENCODING' => 'br, gzip' })
+ dispatcher = Datastar.new(request:, response:, view_context:, compression: [:gzip])
+
+ expect(dispatcher.response['Content-Encoding']).to eq('gzip')
+ end
+ end
+
private
+ # Binary socket for compression tests
+ class BinarySocket
+ attr_reader :closed
+
+ def initialize
+ @buffer = String.new(encoding: Encoding::BINARY)
+ @closed = false
+ end
+
+ def <<(data)
+ @buffer << data.b
+ self
+ end
+
+ def close
+ @closed = true
+ end
+
+ def bytes
+ @buffer
+ end
+ end
+
def build_request(path, method: 'GET', body: nil, content_type: 'application/json', accept: 'text/event-stream', headers: {})
headers = {
'HTTP_ACCEPT' => accept,