datastar 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc94dbbe291bd86a1aaae4302cd8fdaa0262f06bcbf0bb81ce201099a92de0b7
-  data.tar.gz: 804810f5e0633c690d329f79e3eb220734cb558767f951be18b383bfdd97fcd9
+  metadata.gz: 568e2026e9657b4042957c360641bc3c1b51bfdfe7dcf1710a78b75e07a71ccf
+  data.tar.gz: 25851c3fc4b6bb74c8db43d6ecfbbd8fa796be259fe9b0b4bc4653e3077c0e41
 SHA512:
-  metadata.gz: 22716ea763849a6f6aae0a762809b29662e8dfb279dd2bcd0165b2af3a53cb8cbed31f57c8c4af8db55e1f9e54764243741265b01c6d9772eb28b2197790977b
-  data.tar.gz: 88efa4fb0a989d5d05548a8264650b89a08f1af6cb6bdcbb848da36e6aa09cc8c37729233ed867fbfdb2a9cfeb3fd8944f27a7b8c618259a569b451d8f0b3a92
+  metadata.gz: 880721f4912523484e4c79c8faeba5241e371007d5a6d81cbf45f1979ef4d25a6a1c32c25afe24165c4e646bf1523355ae9bea9a13310da2a05287fab71acb82
+  data.tar.gz: 9b594d6249a5a923d8da9d693e495d8f1622835bd8b698c5e8ff8396bbf00f5ac6f5c6302591ac9ae4690f06c7b6e9dc1c9e752d9d9f3757e74648349472ba3d

data/README.md

@@ -1,6 +1,6 @@
 # Datastar Ruby SDK
 
-Implement the [Datastart SSE procotocol](https://data-star.dev/reference/sse_events) in Ruby. It can be used in any Rack handler, and Rails controllers.
+Implement the [Datastar SSE procotocol](https://data-star.dev/reference/sse_events) in Ruby. It can be used in any Rack handler, and Rails controllers.
 
 ## Installation
 
@@ -13,7 +13,7 @@ gem 'datastar'
 Or point your `Gemfile` to the source
 
 ```bash
-gem 'datastar', git: 'https://github.com/starfederation/datastar', glob: 'sdk/ruby/*.gemspec'
+gem 'datastar', github: 'starfederation/datastar-ruby'
 ```
 
 ## Usage
@@ -245,6 +245,21 @@ You can also set it to a different number (in seconds)
 heartbeat: 0.5
 ```
 
+#### Per-stream override
+
+The `#stream` method also accepts a `heartbeat:` keyword that overrides the constructor-level setting for a single call. This is useful when a dispatcher is generally configured with a heartbeat but a particular response doesn't need one (e.g. a one-shot update). The previous value is restored once the call returns.
+
+```ruby
+datastar = Datastar.new(request:, response:) # default heartbeat
+
+# Disable heartbeat for this single response
+datastar.stream(heartbeat: false) do |sse|
+  sse.patch_elements(html)
+end
+```
+
+The one-shot helpers (`#patch_elements`, `#remove_elements`, `#patch_signals`, `#remove_signals`, `#execute_script`, `#redirect`) use this internally to avoid spawning a heartbeat thread for a single message.
+
 #### Manual connection check
 
 If you want to check connection status on your own, you can disable the heartbeat and use `sse.check_connection!`, which will close the connection and trigger callbacks if the client is disconnected.
@@ -270,13 +285,105 @@ Datastar.configure do |config|
   config.on_error do |exception|
     Sentry.notify(exception)
   end
-  
+
   # Global heartbeat interval (or false, to disable)
-  # Can be overriden on specific instances
+  # Can be overriden on specific instances
   config.heartbeat = 0.3
+
+  # Enable compression for SSE streams (default: false)
+  # See the Compression section below for details
+  config.compression = true
 end
 ```
 
+### Compression
+
+SSE data (JSON + HTML) is highly compressible, and long-lived connections benefit significantly from compression. This SDK supports opt-in Brotli and gzip compression for SSE streams.
+
+#### Enabling compression
+
+Per-instance:
+
+```ruby
+datastar = Datastar.new(request:, response:, view_context:, compression: true)
+```
+
+Or globally:
+
+```ruby
+Datastar.configure do |config|
+  config.compression = true
+end
+```
+
+When enabled, the SDK negotiates compression with the client via the `Accept-Encoding` header and sets the appropriate `Content-Encoding` response header. If the client does not support compression, responses are sent uncompressed.
+
+#### Brotli vs gzip
+
+Brotli (`:br`) is preferred by default as it offers better compression ratios. It requires the host app to require the [`brotli`](https://github.com/miyucy/brotli) gem. Gzip uses Ruby built-in `zlib` and requires no extra dependencies.
+
+To use Brotli, add the gem to your `Gemfile`:
+
+```ruby
+gem 'brotli'
+```
+
+#### Configuration options
+
+```ruby
+Datastar.configure do |config|
+  # Enable compression (default: false)
+  # true enables both :br and :gzip (br preferred)
+  config.compression = true
+
+  # Or pass an array of encodings (first = preferred)
+  config.compression = [:br, :gzip]
+
+  # Per-encoder options via [symbol, options] pairs
+  config.compression = [[:br, { quality: 5 }], :gzip]
+end
+```
+
+You can also set these per-instance:
+
+```ruby
+datastar = Datastar.new(
+  request:, response:, view_context:,
+  compression: [:gzip]              # only gzip, no brotli
+)
+
+# Or with per-encoder options
+datastar = Datastar.new(
+  request:, response:, view_context:,
+  compression: [[:gzip, { level: 1 }]]
+)
+```
+
+#### Per-encoder options
+
+Options are passed directly to the underlying compressor via the array form. Available options depend on the encoder.
+
+**Gzip** (via `Zlib::Deflate`):
+
+| Option       | Default                     | Description                                                  |
+| ------------ | --------------------------- | ------------------------------------------------------------ |
+| `:level`     | `Zlib::DEFAULT_COMPRESSION` | Compression level (0-9). 0 = none, 1 = fastest, 9 = smallest. `Zlib::BEST_SPEED` and `Zlib::BEST_COMPRESSION` also work. |
+| `:mem_level` | `8`                         | Memory usage (1-9). Higher uses more memory for better compression. |
+| `:strategy`  | `Zlib::DEFAULT_STRATEGY`    | Algorithm strategy. Alternatives: `Zlib::FILTERED`, `Zlib::HUFFMAN_ONLY`, `Zlib::RLE`, `Zlib::FIXED`. |
+
+**Brotli** (via `Brotli::Compressor`, requires the `brotli` gem):
+
+| Option     | Default    | Description                                                  |
+| ---------- | ---------- | ------------------------------------------------------------ |
+| `:quality` | `11`       | Compression quality (0-11). Lower is faster, higher compresses better. |
+| `:lgwin`   | `22`       | Base-2 log of sliding window size (10-24).                   |
+| `:lgblock` | `0` (auto) | Base-2 log of max input block size (16-24, or 0 for auto).   |
+| `:mode`    | `:generic` | Compression mode: `:generic`, `:text`, or `:font`. `:text` is a good choice for SSE (UTF-8 HTML/JSON). |
+
+#### Proxy considerations
+
+Even with `X-Accel-Buffering: no` (set by default), some proxies like Nginx may buffer compressed responses. You may need to add `proxy_buffering off` to your Nginx configuration when using compression with SSE.
+
 ### Rendering Rails templates
 
 In Rails, make sure to initialize Datastar with the `view_context` in a controller.
@@ -364,12 +471,6 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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 the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-### Building
-
-To build `consts.rb` file from template, run Docker and run `make task build`
-
-The template is located at `build/consts_ruby.gtpl`.
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/starfederation/datastar.

data/benchmarks/compression.rb

@@ -0,0 +1,251 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Benchmark: SSE compression payload sizes
+#
+# Compares bytes-over-the-wire for no compression, gzip, and brotli
+# when streaming large HTML elements via Datastar's SSE protocol.
+#
+# Usage:
+#   bundle exec ruby benchmarks/compression.rb
+#
+# The benchmark patches realistic HTML payloads of increasing size
+# through the full Datastar SSE pipeline (ServerSentEventGenerator →
+# CompressedSocket → raw socket) and reports the resulting byte sizes
+# and compression ratios.
+
+require 'bundler/setup'
+require 'datastar'
+require 'datastar/compressor/gzip'
+require 'datastar/compressor/brotli'
+
+# --- Payload generators ---------------------------------------------------
+
+# A user-row partial, repeated N times inside a <tbody>.
+# Realistic: IDs, data attributes, mixed text, Tailwind-style classes.
+def html_table(row_count)
+  rows = row_count.times.map do |i|
+    <<~HTML
+      <tr id="user-row-#{i}" class="border-b border-gray-200 hover:bg-gray-50 transition-colors duration-150" data-user-id="#{i}" data-signal-selected="false">
+        <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900">#{i + 1}</td>
+        <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">user-#{i}@example.com</td>
+        <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">#{%w[Admin Editor Viewer].sample}</td>
+        <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">2025-01-#{(i % 28 + 1).to_s.rjust(2, '0')}</td>
+        <td class="px-6 py-4 whitespace-nowrap text-right text-sm font-medium">
+          <button class="text-indigo-600 hover:text-indigo-900 mr-3" data-on-click="$$put('/users/#{i}/edit')">Edit</button>
+          <button class="text-red-600 hover:text-red-900" data-on-click="$$delete('/users/#{i}')">Delete</button>
+        </td>
+      </tr>
+    HTML
+  end
+
+  <<~HTML
+    <tbody id="users-table-body">
+    #{rows.join}
+    </tbody>
+  HTML
+end
+
+# A dashboard card with nested elements — charts placeholder, stats, lists.
+def html_dashboard(card_count)
+  cards = card_count.times.map do |i|
+    <<~HTML
+      <div id="card-#{i}" class="bg-white overflow-hidden shadow-lg rounded-2xl border border-gray-100 p-6 flex flex-col gap-4">
+        <div class="flex items-center justify-between">
+          <h3 class="text-lg font-semibold text-gray-900">Metric #{i + 1}</h3>
+          <span class="inline-flex items-center rounded-full bg-green-50 px-2 py-1 text-xs font-medium text-green-700 ring-1 ring-inset ring-green-600/20">+#{rand(1..99)}%</span>
+        </div>
+        <div class="text-3xl font-bold text-gray-900">#{rand(1_000..99_999).to_s.chars.each_slice(3).map(&:join).join(',')}</div>
+        <div class="h-32 bg-gradient-to-r from-indigo-50 to-indigo-100 rounded-lg flex items-end gap-1 p-2">
+          #{8.times.map { |j| "<div class=\"bg-indigo-#{[400, 500, 600].sample} rounded-t w-full\" style=\"height: #{rand(20..100)}%\"></div>" }.join("\n          ")}
+        </div>
+        <ul class="divide-y divide-gray-100">
+          #{5.times.map { |j| "<li class=\"flex justify-between py-2 text-sm\"><span class=\"text-gray-500\">Region #{j + 1}</span><span class=\"font-medium text-gray-900\">#{rand(100..9_999)}</span></li>" }.join("\n          ")}
+        </ul>
+      </div>
+    HTML
+  end
+
+  <<~HTML
+    <div id="dashboard-grid" class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 p-6">
+    #{cards.join}
+    </div>
+  HTML
+end
+
+# --- Socket that counts bytes --------------------------------------------
+
+class ByteCountingSocket
+  attr_reader :total_bytes
+
+  def initialize
+    @total_bytes = 0
+  end
+
+  def <<(data)
+    @total_bytes += data.bytesize
+    self
+  end
+
+  def close; end
+end
+
+# --- Helpers --------------------------------------------------------------
+
+# Pipe an HTML payload through the full SSE + compression stack
+# and return the byte count that would go over the wire.
+def measure_bytes(html, encoding)
+  socket = ByteCountingSocket.new
+
+  wrapped = case encoding
+            when :none  then socket
+            when :gzip  then Datastar::Compressor::Gzip::CompressedSocket.new(socket)
+            when :br    then Datastar::Compressor::Brotli::CompressedSocket.new(socket, mode: :text)
+            end
+
+  generator = Datastar::ServerSentEventGenerator.new(
+    wrapped,
+    signals: {},
+    view_context: nil
+  )
+
+  generator.patch_elements(html)
+  wrapped.close unless encoding == :none
+
+  socket.total_bytes
+end
+
+def format_bytes(bytes)
+  if bytes >= 1024 * 1024
+    "%.1f MB" % (bytes / (1024.0 * 1024))
+  elsif bytes >= 1024
+    "%.1f KB" % (bytes / 1024.0)
+  else
+    "#{bytes} B"
+  end
+end
+
+def ratio(original, compressed)
+  "%.1f%%" % ((1.0 - compressed.to_f / original) * 100)
+end
+
+# --- Run benchmarks -------------------------------------------------------
+
+SCENARIOS = [
+  ["Table 10 rows",     -> { html_table(10) }],
+  ["Table 50 rows",     -> { html_table(50) }],
+  ["Table 200 rows",    -> { html_table(200) }],
+  ["Table 1000 rows",   -> { html_table(1000) }],
+  ["Dashboard 5 cards", -> { html_dashboard(5) }],
+  ["Dashboard 20 cards",-> { html_dashboard(20) }],
+  ["Dashboard 50 cards",-> { html_dashboard(50) }],
+]
+
+ENCODINGS = %i[none gzip br]
+
+# Header
+puts "Datastar SSE Compression Benchmark"
+puts "=" * 90
+puts
+puts format(
+  "%-22s %12s %12s %8s %12s %8s",
+  "Scenario", "No Compress", "Gzip", "Saved", "Brotli", "Saved"
+)
+puts "-" * 90
+
+SCENARIOS.each do |name, generator|
+  html = generator.call
+  results = ENCODINGS.map { |enc| [enc, measure_bytes(html, enc)] }.to_h
+  none = results[:none]
+
+  puts format(
+    "%-22s %12s %12s %8s %12s %8s",
+    name,
+    format_bytes(none),
+    format_bytes(results[:gzip]),
+    ratio(none, results[:gzip]),
+    format_bytes(results[:br]),
+    ratio(none, results[:br])
+  )
+end
+
+# --- Streaming: multiple SSE events over one connection -------------------
+
+# Simulates a long-lived SSE connection where rows are patched individually
+# (e.g. a live-updating table). The compressor stays open across events,
+# so repeated structure (CSS classes, attribute patterns) compresses
+# increasingly well as the dictionary builds up.
+
+def measure_streaming_bytes(payloads, encoding)
+  socket = ByteCountingSocket.new
+
+  wrapped = case encoding
+            when :none  then socket
+            when :gzip  then Datastar::Compressor::Gzip::CompressedSocket.new(socket)
+            when :br    then Datastar::Compressor::Brotli::CompressedSocket.new(socket, mode: :text)
+            end
+
+  generator = Datastar::ServerSentEventGenerator.new(
+    wrapped,
+    signals: {},
+    view_context: nil
+  )
+
+  payloads.each { |html| generator.patch_elements(html) }
+  wrapped.close unless encoding == :none
+
+  socket.total_bytes
+end
+
+def table_rows(count)
+  count.times.map do |i|
+    <<~HTML
+      <tr id="user-row-#{i}" class="border-b border-gray-200 hover:bg-gray-50 transition-colors duration-150" data-user-id="#{i}" data-signal-selected="false">
+        <td class="px-6 py-4 whitespace-nowrap text-sm font-medium text-gray-900">#{i + 1}</td>
+        <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">user-#{i}@example.com</td>
+        <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">#{%w[Admin Editor Viewer].sample}</td>
+        <td class="px-6 py-4 whitespace-nowrap text-sm text-gray-500">2025-01-#{(i % 28 + 1).to_s.rjust(2, '0')}</td>
+        <td class="px-6 py-4 whitespace-nowrap text-right text-sm font-medium">
+          <button class="text-indigo-600 hover:text-indigo-900 mr-3" data-on-click="$$put('/users/#{i}/edit')">Edit</button>
+          <button class="text-red-600 hover:text-red-900" data-on-click="$$delete('/users/#{i}')">Delete</button>
+        </td>
+      </tr>
+    HTML
+  end
+end
+
+puts
+puts
+puts "Streaming: individual row patches over one SSE connection"
+puts "=" * 90
+puts
+puts format(
+  "%-22s %12s %12s %8s %12s %8s",
+  "Scenario", "No Compress", "Gzip", "Saved", "Brotli", "Saved"
+)
+puts "-" * 90
+
+[10, 50, 200, 1000].each do |count|
+  payloads = table_rows(count)
+  results = ENCODINGS.map { |enc| [enc, measure_streaming_bytes(payloads, enc)] }.to_h
+  none = results[:none]
+
+  puts format(
+    "%-22s %12s %12s %8s %12s %8s",
+    "#{count} row patches",
+    format_bytes(none),
+    format_bytes(results[:gzip]),
+    ratio(none, results[:gzip]),
+    format_bytes(results[:br]),
+    ratio(none, results[:br])
+  )
+end
+
+puts
+puts "Notes:"
+puts "  - Single-event sizes include full SSE framing (event: / data: prefixes)"
+puts "  - Gzip: default compression level, gzip framing (window_bits=31)"
+puts "  - Brotli: default quality (11) with mode: :text"
+puts "  - Streaming rows: each row is a separate patch_elements SSE event"
+puts "    over one persistent compressed connection. The compressor dictionary"
+puts "    builds up across events, improving ratios for repetitive markup."

data/lib/datastar/compression_config.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Datastar
+  module Compressor
+    # Null compressor — no-op, used when compression is disabled or no match.
+    class Null
+      def encoding = nil
+      def wrap_socket(socket) = socket
+      def prepare_response(_response) = nil
+    end
+
+    NONE = Null.new.freeze
+  end
+
+  # Immutable value object that holds an ordered list of pre-built compressors
+  # and negotiates the best one for a given request.
+  #
+  # Use {.build} to create instances from user-facing configuration values.
+  # The first compressor in the list is preferred when the client supports multiple.
+  #
+  # @example Via global configuration
+  #   Datastar.configure do |config|
+  #     config.compression = true                            # [:br, :gzip] with default options
+  #     config.compression = [:br, :gzip]                    # preferred = first in list
+  #     config.compression = [[:br, { quality: 5 }], :gzip]  # per-encoder options
+  #   end
+  #
+  # @example Per-request negotiation (used internally by Dispatcher)
+  #   compressor = Datastar.config.compression.negotiate(request)
+  #   compressor.prepare_response(response)
+  #   socket = compressor.wrap_socket(raw_socket)
+  class CompressionConfig
+    ACCEPT_ENCODING = 'HTTP_ACCEPT_ENCODING'
+    BLANK_HASH = {}.freeze
+
+    # Build a {CompressionConfig} from various user-facing input forms.
+    #
+    # @param input [Boolean, Array<Symbol, Array(Symbol, Hash)>, CompressionConfig]
+    #   - +false+ / +nil+ — compression disabled (empty compressor list)
+    #   - +true+ — enable +:br+ and +:gzip+ with default options
+    #   - +Array<Symbol>+ — enable listed encodings with default options, e.g. +[:gzip]+
+    #   - +Array<Array(Symbol, Hash)>+ — enable with per-encoder options,
+    #     e.g. +[[:br, { quality: 5 }], :gzip]+
+    #   - +CompressionConfig+ — returned as-is
+    # @return [CompressionConfig]
+    # @raise [ArgumentError] if +input+ is not a recognised form
+    # @raise [LoadError] if a requested encoder's gem is not available (e.g. +brotli+)
+    #
+    # @example Disable compression
+    #   CompressionConfig.build(false)
+    #
+    # @example Enable all supported encodings
+    #   CompressionConfig.build(true)
+    #
+    # @example Gzip only, with custom level
+    #   CompressionConfig.build([[:gzip, { level: 1 }]])
+    def self.build(input)
+      case input
+      when CompressionConfig
+        input
+      when false, nil
+        new([])
+      when true
+        new([build_compressor(:br), build_compressor(:gzip)])
+      when Array
+        compressors = input.map do |entry|
+          case entry
+          when Symbol
+            build_compressor(entry)
+          when Array
+            name, options = entry
+            build_compressor(name, options || BLANK_HASH)
+          else
+            raise ArgumentError, "Invalid compression entry: #{entry.inspect}. Expected Symbol or [Symbol, Hash]."
+          end
+        end
+        new(compressors)
+      else
+        raise ArgumentError, "Invalid compression value: #{input.inspect}. Expected true, false, or Array."
+      end
+    end
+
+    def self.build_compressor(name, options = BLANK_HASH)
+      case name
+      when :br
+        require_relative 'compressor/brotli'
+        Compressor::Brotli.new(options)
+      when :gzip
+        require_relative 'compressor/gzip'
+        Compressor::Gzip.new(options)
+      else
+        raise ArgumentError, "Unknown compressor: #{name.inspect}. Expected :br or :gzip."
+      end
+    end
+    private_class_method :build_compressor
+
+    # @param compressors [Array<Compressor::Gzip, Compressor::Brotli>]
+    #   ordered list of pre-built compressor instances. First = preferred.
+    def initialize(compressors)
+      @compressors = compressors.freeze
+      freeze
+    end
+
+    # Whether any compressors are configured.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   CompressionConfig.build(false).enabled? # => false
+    #   CompressionConfig.build(true).enabled?  # => true
+    def enabled?
+      @compressors.any?
+    end
+
+    # Negotiate compression with the client based on the +Accept-Encoding+ header.
+    #
+    # Iterates the configured compressors in order (first = preferred) and returns
+    # the first one whose encoding the client accepts. Returns {Compressor::NONE}
+    # when compression is disabled, the header is absent, or no match is found.
+    #
+    # No objects are created per-request — compressors are pre-built and reused.
+    #
+    # @param request [Rack::Request]
+    # @return [Compressor::Gzip, Compressor::Brotli, Compressor::Null]
+    #
+    # @example
+    #   config = CompressionConfig.build([:gzip, :br])
+    #   compressor = config.negotiate(request)
+    #   compressor.prepare_response(response)
+    #   socket = compressor.wrap_socket(raw_socket)
+    def negotiate(request)
+      return Compressor::NONE unless enabled?
+
+      accepted = parse_accept_encoding(request.get_header(ACCEPT_ENCODING).to_s)
+      return Compressor::NONE if accepted.empty?
+
+      @compressors.each do |compressor|
+        return compressor if accepted.include?(compressor.encoding)
+      end
+
+      Compressor::NONE
+    end
+
+    private
+
+    # Parse Accept-Encoding header into a set of encoding symbols
+    # @param header [String]
+    # @return [Set<Symbol>]
+    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

data/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

data/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

data/lib/datastar/configuration.rb

@@ -35,6 +35,7 @@ module Datastar
     DEFAULT_HEARTBEAT = 3
 
     attr_accessor :executor, :error_callback, :finalize, :heartbeat, :logger
+    attr_reader :compression
 
     def initialize
       @executor = ThreadExecutor.new
@@ -44,6 +45,11 @@ module Datastar
       @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)

data/lib/datastar/dispatcher.rb

@@ -28,7 +28,7 @@ module Datastar
     HTTP_ACCEPT = 'HTTP_ACCEPT'
     HTTP1 = 'HTTP/1.1'
 
-    attr_reader :request, :response
+    attr_reader :request, :response, :heartbeat
 
     # @option request [Rack::Request] the request object
     # @option response [Rack::Response, nil] the response object
@@ -44,7 +44,8 @@ module Datastar
       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 @@ module Datastar
 
       @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
@@ -131,7 +137,7 @@ module Datastar
     # @param elements [String, #call(view_context: Object) => Object] the HTML elements or object
     # @param options [Hash] the options to send with the message
     def patch_elements(elements, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.patch_elements(elements, options)
       end
     end
@@ -146,7 +152,7 @@ module Datastar
     # @param selector [String] a CSS selector for the fragment to remove
     # @param options [Hash] the options to send with the message
     def remove_elements(selector, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.remove_elements(selector, options)
       end
     end
@@ -160,7 +166,7 @@ module Datastar
     # @param signals [Hash, String] signals to merge
     # @param options [Hash] the options to send with the message
     def patch_signals(signals, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.patch_signals(signals, options)
       end
     end
@@ -174,7 +180,7 @@ module Datastar
     # @param paths [Array<String>] object paths to the signals to remove
     # @param options [Hash] the options to send with the message
     def remove_signals(paths, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.remove_signals(paths, options)
       end
     end
@@ -188,7 +194,7 @@ module Datastar
     # @param script [String] the script to execute
     # @param options [Hash] the options to send with the message
     def execute_script(script, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.execute_script(script, options)
       end
     end
@@ -198,7 +204,7 @@ module Datastar
     #
     # @param url [String] the URL or path to redirect to
     def redirect(url)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.redirect(url)
       end
     end
@@ -239,10 +245,24 @@ module Datastar
     # By default, the built-in Rack finalzer just returns the resposne Array which can be used by any Rack handler.
     # On Rails, the Rails controller response is set to this objects streaming response.
     #
+    # A per-call +heartbeat:+ keyword overrides the constructor-level heartbeat
+    # for the duration of this call. Pass +false+ to disable heartbeat for a
+    # one-shot message (e.g. a single +patch_elements+), or a Numeric interval
+    # to enable it. The previous value is restored once the call returns.
+    # @example Disable heartbeat for a single response
+    #
+    #  datastar.stream(heartbeat: false) do |sse|
+    #    sse.patch_elements(html)
+    #  end
+    #
     # @param streamer [#call(ServerSentEventGenerator), nil] a callable to call with the generator
+    # @param heartbeat [Numeric, false] override the heartbeat interval for this call, or +false+ to disable
     # @yieldparam sse [ServerSentEventGenerator] the generator object
     # @return [Object] depends on the finalize callback
-    def stream(streamer = nil, &block)
+    def stream(streamer = nil, heartbeat: @heartbeat, &block)
+      heartbeat_was = @heartbeat
+      @heartbeat = heartbeat
+
       streamer ||= block
       @streamers << streamer
       if @heartbeat && !@heartbeat_on
@@ -263,18 +283,12 @@ module Datastar
 
       @response.body = body
       @finalize.call(@view_context, @response)
+    ensure
+      @heartbeat = heartbeat_was
     end
 
     private
 
-    def stream_no_heartbeat(&block)
-      was = @heartbeat
-      @heartbeat = false
-      stream(&block).tap do
-        @heartbeat = was
-      end
-    end
-
     # Produce a response body for a single stream
     # In this case, the SSE generator can write directly to the socket
     #
@@ -283,6 +297,7 @@ module Datastar
     # @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 +323,7 @@ module Datastar
       @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 +376,13 @@ module Datastar
       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

data/lib/datastar/server_sent_event_generator.rb

@@ -3,9 +3,46 @@
 require 'json'
 
 module Datastar
+  module ElementPatchMode
+    # Morphs the element into the existing element.
+    OUTER = 'outer'
+
+    # Replaces the inner HTML of the existing element.
+    INNER = 'inner'
+
+    # Removes the existing element.
+    REMOVE = 'remove'
+
+    # Replaces the existing element with the new element.
+    REPLACE = 'replace'
+
+    # Prepends the element inside to the existing element.
+    PREPEND = 'prepend'
+
+    # Appends the element inside the existing element.
+    APPEND = 'append'
+
+    # Inserts the element before the existing element.
+    BEFORE = 'before'
+
+    # Inserts the element after the existing element.
+    AFTER = 'after'
+  end
+
   class ServerSentEventGenerator
     MSG_END = "\n"
 
+    DEFAULT_SSE_RETRY_DURATION = 1000
+    DEFAULT_ELEMENTS_USE_VIEW_TRANSITIONS = false
+    DEFAULT_PATCH_SIGNALS_ONLY_IF_MISSING = false
+
+    SELECTOR_DATALINE_LITERAL = 'selector'
+    MODE_DATALINE_LITERAL = 'mode'
+    ELEMENTS_DATALINE_LITERAL = 'elements'
+    USE_VIEW_TRANSITION_DATALINE_LITERAL = 'useViewTransition'
+    SIGNALS_DATALINE_LITERAL = 'signals'
+    ONLY_IF_MISSING_DATALINE_LITERAL = 'onlyIfMissing'
+
     SSE_OPTION_MAPPING = {
       'eventId' => 'id',
       'retryDuration' => 'retry',
@@ -13,11 +50,13 @@ module Datastar
       'retry' => 'retry',
     }.freeze
 
+    DEFAULT_ELEMENT_PATCH_MODE = ElementPatchMode::OUTER
+
     OPTION_DEFAULTS = {
-      'retry' => Consts::DEFAULT_SSE_RETRY_DURATION,
-      Consts::MODE_DATALINE_LITERAL => Consts::DEFAULT_ELEMENT_PATCH_MODE,
-      Consts::USE_VIEW_TRANSITION_DATALINE_LITERAL => Consts::DEFAULT_ELEMENTS_USE_VIEW_TRANSITIONS,
-      Consts::ONLY_IF_MISSING_DATALINE_LITERAL => Consts::DEFAULT_PATCH_SIGNALS_ONLY_IF_MISSING,
+      'retry' => DEFAULT_SSE_RETRY_DURATION,
+      MODE_DATALINE_LITERAL => DEFAULT_ELEMENT_PATCH_MODE,
+      USE_VIEW_TRANSITION_DATALINE_LITERAL => DEFAULT_ELEMENTS_USE_VIEW_TRANSITIONS,
+      ONLY_IF_MISSING_DATALINE_LITERAL => DEFAULT_PATCH_SIGNALS_ONLY_IF_MISSING,
     }.freeze
 
     SIGNAL_SEPARATOR = '.'
@@ -52,7 +91,7 @@ module Datastar
 
       buffer = +"event: datastar-patch-elements\n"
       build_options(options, buffer)
-      element_lines.each { |line| buffer << "data: #{Consts::ELEMENTS_DATALINE_LITERAL} #{line}\n" }
+      element_lines.each { |line| buffer << "data: #{ELEMENTS_DATALINE_LITERAL} #{line}\n" }
 
       write(buffer)
     end
@@ -61,7 +100,7 @@ module Datastar
       patch_elements(
         nil, 
         options.merge(
-          Consts::MODE_DATALINE_LITERAL => Consts::ElementPatchMode::REMOVE,
+          MODE_DATALINE_LITERAL => ElementPatchMode::REMOVE,
           selector:
         )
       )
@@ -75,7 +114,7 @@ module Datastar
         signals = JSON.dump(signals)
         buffer << "data: signals #{signals}\n"
       when String
-        multi_data_lines(signals, buffer, Consts::SIGNALS_DATALINE_LITERAL)
+        multi_data_lines(signals, buffer, SIGNALS_DATALINE_LITERAL)
       end
       write(buffer)
     end
@@ -101,8 +140,8 @@ module Datastar
       script_tag << %( data-effect="el.remove()") if auto_remove
       script_tag << ">#{script}</script>"
 
-      options[Consts::SELECTOR_DATALINE_LITERAL] = 'body'
-      options[Consts::MODE_DATALINE_LITERAL] = Consts::ElementPatchMode::APPEND
+      options[SELECTOR_DATALINE_LITERAL] = 'body'
+      options[MODE_DATALINE_LITERAL] = ElementPatchMode::APPEND
 
       patch_elements(script_tag, options)
     end
@@ -143,7 +182,7 @@ module Datastar
             buffer << "data: #{k} #{kk} #{vv}\n"
           end
         elsif v.is_a?(Array)
-          if k == Consts::SELECTOR_DATALINE_LITERAL
+          if k == SELECTOR_DATALINE_LITERAL
             buffer << "data: #{k} #{v.join(', ')}\n"
           else
             buffer << "data: #{k} #{v.join(' ')}\n"

data/lib/datastar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Datastar
-  VERSION = '1.0.1'
+  VERSION = '1.0.3'
 end

data/lib/datastar.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'datastar/version'
-require_relative 'datastar/consts'
-
 module Datastar
   BLANK_OPTIONS = {}.freeze
 
@@ -27,6 +25,7 @@ module Datastar
 end
 
 require_relative 'datastar/configuration'
+require_relative 'datastar/compression_config'
 require_relative 'datastar/dispatcher'
 require_relative 'datastar/server_sent_event_generator'
 require_relative 'datastar/railtie' if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: datastar
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Ismael Celis
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.14
+        version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.14
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -75,6 +75,7 @@ files:
 - LICENSE.md
 - README.md
 - Rakefile
+- benchmarks/compression.rb
 - examples/hello-world/Gemfile
 - examples/hello-world/Gemfile.lock
 - examples/hello-world/hello-world.html
@@ -86,8 +87,10 @@ files:
 - examples/threads/threads.ru
 - lib/datastar.rb
 - lib/datastar/async_executor.rb
+- lib/datastar/compression_config.rb
+- lib/datastar/compressor/brotli.rb
+- lib/datastar/compressor/gzip.rb
 - lib/datastar/configuration.rb
-- lib/datastar/consts.rb
 - lib/datastar/dispatcher.rb
 - lib/datastar/rails_async_executor.rb
 - lib/datastar/rails_thread_executor.rb
@@ -114,7 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Ruby SDK for Datastar. Rack-compatible.
 test_files: []

data/lib/datastar/consts.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-# This is auto-generated by Datastar. DO NOT EDIT.
-module Datastar
-  module Consts
-    DATASTAR_KEY = 'datastar'
-    VERSION = '1.0.0-RC.1'
-
-    # The default duration for retrying SSE on connection reset. This is part of the underlying retry mechanism of SSE.
-    DEFAULT_SSE_RETRY_DURATION = 1000
-
-    # Should elements be patched using the ViewTransition API?
-    DEFAULT_ELEMENTS_USE_VIEW_TRANSITIONS = false
-
-    # Should a given set of signals patch if they are missing?
-    DEFAULT_PATCH_SIGNALS_ONLY_IF_MISSING = false
-
-    module ElementPatchMode
-
-      # Morphs the element into the existing element.
-      OUTER = 'outer';
-
-      # Replaces the inner HTML of the existing element.
-      INNER = 'inner';
-
-      # Removes the existing element.
-      REMOVE = 'remove';
-
-      # Replaces the existing element with the new element.
-      REPLACE = 'replace';
-
-      # Prepends the element inside to the existing element.
-      PREPEND = 'prepend';
-
-      # Appends the element inside the existing element.
-      APPEND = 'append';
-
-      # Inserts the element before the existing element.
-      BEFORE = 'before';
-
-      # Inserts the element after the existing element.
-      AFTER = 'after';
-    end
-
-
-    # The mode in which an element is patched into the DOM.
-    DEFAULT_ELEMENT_PATCH_MODE = ElementPatchMode::OUTER
-
-    # Dataline literals.
-    SELECTOR_DATALINE_LITERAL = 'selector'
-    MODE_DATALINE_LITERAL = 'mode'
-    ELEMENTS_DATALINE_LITERAL = 'elements'
-    USE_VIEW_TRANSITION_DATALINE_LITERAL = 'useViewTransition'
-    SIGNALS_DATALINE_LITERAL = 'signals'
-    ONLY_IF_MISSING_DATALINE_LITERAL = 'onlyIfMissing'
-  end
-end