datastar 1.0.0.beta.1 → 1.0.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07c2774d8c0274b50336a6163a1e22b4451bfd2ec271601d0a5a9f21c0e14fba
-  data.tar.gz: bebe0a2d43cf8ab1e03a1693bbd2bfc206e8f1e650bf24333d39a8cfa59a4ebb
+  metadata.gz: 55282db68817596fd27726daa87179e08fcddb3b8deaea5826161d54f7a850cb
+  data.tar.gz: '0864d609f3afa0c950d357f396973b7882c6f834f56c112e4765e3dfc7add400'
 SHA512:
-  metadata.gz: f98e8f6b5de65c9250b2ab678970f9ecdac84edfbc5088951570bd8b1f5f08d134180216d8b92d272628cd392bdb0ce1b71bb80f7263451a18de7308c7bf24d7
-  data.tar.gz: d179c5dd59e5a5de18d2688a721e10dc7d62042c40b59cd1bd707f7a147e942ba234ebf6c2ca101b3cbce2d8c6288e6809d77fe3c7282569786c59e21b81282d
+  metadata.gz: 1712f02ea8b4d5def9d04381062f35135eb3213863b63536a35d8322b3880efb917acfb5dde900be7181ea2576b825791b301bd392a649bd799784aa93fbf28d
+  data.tar.gz: 4e268347627b41ec8c7506891adbf7c95f32d10d16c4ed3f5e33192f624660456d9a1712dee71921af18390c7998f1755a48a2cc73701a298036fce8ab1a48de

data/README.md

@@ -4,10 +4,10 @@ Implement the [Datastart SSE procotocol](https://data-star.dev/reference/sse_eve
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add this gem to your `Gemfile`
 
 ```bash
-bundle add datastar
+gem 'datastar'
 ```
 
 Or point your `Gemfile` to the source
@@ -165,17 +165,20 @@ end
 Register server-side code to run when the connection is closed by the client
 
 ```ruby
-datastar.on_client_connect do
+datastar.on_client_disconnect do
   puts 'A user has disconnected connected'
 end
 ```
 
+This callback's behaviour depends on the configured [heartbeat](#heartbeat)
+
 #### `on_server_disconnect`
+
 Register server-side code to run when the connection is closed by the server.
 Ie when the served is done streaming without errors.
 
 ```ruby
-datastar.on_server_connect do
+datastar.on_server_disconnect do
   puts 'Server is done streaming'
 end
 ```
@@ -188,15 +191,64 @@ datastar.on_error do |exception|
   Sentry.notify(exception)
 end
 ```
-Note that this callback can be registered globally, too.
+Note that this callback can be [configured globally](#global-configuration), too.
+
+### heartbeat
+
+By default, streaming responses (using the `#stream` block) launch a background thread/fiber to periodically check the connection.
+
+This is because the browser could have disconnected during a long-lived, idle connection (for example waiting on an event bus).
+
+The default heartbeat is 3 seconds, and it will close the connection and trigger [on_client_disconnect](#on_client_disconnect) callbacks if the client has disconnected.
+
+In cases where a streaming block doesn't need a heartbeat and you want to save precious threads (for example a regular ticker update, ie non-idle), you can disable the heartbeat:
+
+```ruby
+datastar = Datastar.new(request:, response:, view_context:, heartbeat: false)
+
+datastar.stream do |sse|
+  100.times do |i|
+    sleep 1
+    sse.merge_signals count: i
+  end
+end
+```
+
+You can also set it to a different number (in seconds)
+
+```ruby
+heartbeat: 0.5
+```
+
+#### 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.
+
+```ruby
+datastar = Datastar.new(request:, response:, view_context:, heartbeat: false)
+
+datastar.stream do |sse|
+  # The event bus implementaton will check connection status when idle
+  # by calling #check_connection! on it
+  EventBus.subscribe('channel', sse) do |event|
+    sse.merge_signals eventName: event.name
+  end
+end
+```
 
 ### Global configuration
 
 ```ruby
 Datastar.configure do |config|
+  # Global on_error callback
+  # Can be overriden on specific instances
   config.on_error do |exception|
     Sentry.notify(exception)
   end
+  
+  # Global heartbeat interval (or false, to disable)
+  # Can be overriden on specific instances
+  config.heartbeat = 0.3
 end
 ```
 
@@ -274,7 +326,7 @@ From this library's root, run the bundled-in test Rack app:
 bundle puma examples/test.ru
 ```
 
-Now run the test bash scripts in the `test` directory in this repo.
+Now run the test bash scripts in the `sdk/test` directory in this repo.
 
 ```bash
 ./test-all.sh http://localhost:9292

data/lib/datastar/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'thread'
+require 'logger'
 
 module Datastar
   # The default executor based on Ruby threads
@@ -30,15 +31,19 @@ module Datastar
   # You'd normally do this on app initialization 
   # For example in a Rails initializer
   class Configuration
-    NOOP_CALLBACK = ->(_error) {}
     RACK_FINALIZE = ->(_view_context, response) { response.finish }
+    DEFAULT_HEARTBEAT = 3
 
-    attr_accessor :executor, :error_callback, :finalize
+    attr_accessor :executor, :error_callback, :finalize, :heartbeat, :logger
 
     def initialize
       @executor = ThreadExecutor.new
-      @error_callback = NOOP_CALLBACK
       @finalize = RACK_FINALIZE
+      @heartbeat = DEFAULT_HEARTBEAT
+      @logger = Logger.new(STDOUT)
+      @error_callback = proc do |e|
+        @logger.error("#{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}")
+      end
     end
 
     def on_error(callable = nil, &block)

data/lib/datastar/consts.rb

@@ -4,10 +4,7 @@
 module Datastar
   module Consts
     DATASTAR_KEY = 'datastar'
-    VERSION = '1.0.0-beta.5'
-
-    # The default duration for settling during fragment merges. Allows for CSS transitions to complete.
-    DEFAULT_FRAGMENTS_SETTLE_DURATION = 300
+    VERSION = '1.0.0-beta.11'
 
     # The default duration for retrying SSE on connection reset. This is part of the underlying retry mechanism of SSE.
     DEFAULT_SSE_RETRY_DURATION = 1000
@@ -57,7 +54,6 @@ module Datastar
     # Dataline literals.
     SELECTOR_DATALINE_LITERAL = 'selector'
     MERGE_MODE_DATALINE_LITERAL = 'mergeMode'
-    SETTLE_DURATION_DATALINE_LITERAL = 'settleDuration'
     FRAGMENTS_DATALINE_LITERAL = 'fragments'
     USE_VIEW_TRANSITION_DATALINE_LITERAL = 'useViewTransition'
     SIGNALS_DATALINE_LITERAL = 'signals'

data/lib/datastar/dispatcher.rb

@@ -35,13 +35,15 @@ module Datastar
     # @option executor [Object] the executor object to use for managing threads and queues
     # @option error_callback [Proc] the callback to call when an error occurs
     # @option finalize [Proc] the callback to call when the response is finalized
+    # @option heartbeat [Integer, nil, FalseClass] the heartbeat interval in seconds
     def initialize(
       request:,
       response: nil,
       view_context: nil,
       executor: Datastar.config.executor,
       error_callback: Datastar.config.error_callback,
-      finalize: Datastar.config.finalize
+      finalize: Datastar.config.finalize,
+      heartbeat: Datastar.config.heartbeat
     )
       @on_connect = []
       @on_client_disconnect = []
@@ -61,6 +63,10 @@ module Datastar
       @response.headers['X-Accel-Buffering'] = 'no'
       @response.delete_header 'Content-Length'
       @executor.prepare(@response)
+      raise ArgumentError, ':heartbeat must be a number' if heartbeat && !heartbeat.is_a?(Numeric)
+
+      @heartbeat = heartbeat
+      @heartbeat_on = false
     end
 
     # Check if the request accepts SSE responses
@@ -124,7 +130,7 @@ module Datastar
     # @param fragments [String, #call(view_context: Object) => Object] the HTML fragment or object
     # @param options [Hash] the options to send with the message
     def merge_fragments(fragments, options = BLANK_OPTIONS)
-      stream do |sse|
+      stream_no_heartbeat do |sse|
         sse.merge_fragments(fragments, options)
       end
     end
@@ -138,7 +144,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_fragments(selector, options = BLANK_OPTIONS)
-      stream do |sse|
+      stream_no_heartbeat do |sse|
         sse.remove_fragments(selector, options)
       end
     end
@@ -152,7 +158,7 @@ module Datastar
     # @param signals [Hash] signals to merge
     # @param options [Hash] the options to send with the message
     def merge_signals(signals, options = BLANK_OPTIONS)
-      stream do |sse|
+      stream_no_heartbeat do |sse|
         sse.merge_signals(signals, options)
       end
     end
@@ -166,7 +172,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 do |sse|
+      stream_no_heartbeat do |sse|
         sse.remove_signals(paths, options)
       end
     end
@@ -180,7 +186,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 do |sse|
+      stream_no_heartbeat do |sse|
         sse.execute_script(script, options)
       end
     end
@@ -190,7 +196,7 @@ module Datastar
     #
     # @param url [String] the URL or path to redirect to
     def redirect(url)
-      stream do |sse|
+      stream_no_heartbeat do |sse|
         sse.redirect(url)
       end
     end
@@ -237,6 +243,15 @@ module Datastar
     def stream(streamer = nil, &block)
       streamer ||= block
       @streamers << streamer
+      if @heartbeat && !@heartbeat_on
+        @heartbeat_on = true
+        @streamers << proc do |sse|
+          while true
+            sleep @heartbeat
+            sse.check_connection!
+          end
+        end
+      end
 
       body = if @streamers.size == 1
         stream_one(streamer) 
@@ -250,6 +265,14 @@ module Datastar
 
     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
     #
@@ -300,11 +323,12 @@ module Datastar
 
         handling_errors(conn_generator, socket) do
           done_count = 0
+          threads_size = @heartbeat_on ? threads.size - 1 : threads.size
 
           while (data = @queue.pop)
             if data == :done
               done_count += 1
-              @queue << nil if done_count == threads.size
+              @queue << nil if done_count == threads_size
             elsif data.is_a?(Exception)
               raise data
             else

data/lib/datastar/railtie.rb

@@ -14,6 +14,8 @@ module Datastar
     initializer 'datastar' do |_app|
       Datastar.config.finalize = FINALIZE
 
+      Datastar.config.logger = Rails.logger
+
       Datastar.config.executor = if config.active_support.isolation_level == :fiber
                                    require 'datastar/rails_async_executor'
                                    RailsAsyncExecutor.new

data/lib/datastar/server_sent_event_generator.rb

@@ -17,7 +17,6 @@ module Datastar
       'retry' => Consts::DEFAULT_SSE_RETRY_DURATION,
       Consts::AUTO_REMOVE_DATALINE_LITERAL => Consts::DEFAULT_EXECUTE_SCRIPT_AUTO_REMOVE,
       Consts::MERGE_MODE_DATALINE_LITERAL => Consts::DEFAULT_FRAGMENT_MERGE_MODE,
-      Consts::SETTLE_DURATION_DATALINE_LITERAL => Consts::DEFAULT_FRAGMENTS_SETTLE_DURATION,
       Consts::USE_VIEW_TRANSITION_DATALINE_LITERAL => Consts::DEFAULT_FRAGMENTS_USE_VIEW_TRANSITIONS,
       Consts::ONLY_IF_MISSING_DATALINE_LITERAL => Consts::DEFAULT_MERGE_SIGNALS_ONLY_IF_MISSING,
     }.freeze
@@ -39,6 +38,13 @@ module Datastar
       @view_context = view_context
     end
 
+    # Sometimes we'll want to run periodic checks to ensure the connection is still alive
+    # ie. the browser hasn't disconnected
+    # For example when idle listening on an event bus.
+    def check_connection!
+      @stream << MSG_END
+    end
+
     def merge_fragments(fragments, options = BLANK_OPTIONS)
       # Support Phlex components
       # And Rails' #render_in interface

data/lib/datastar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Datastar
-  VERSION = '1.0.0.beta.1'
+  VERSION = '1.0.0.beta.3'
 end

metadata

@@ -1,28 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: datastar
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta.1
+  version: 1.0.0.beta.3
 platform: ruby
 authors:
 - Ismael Celis
 bindir: exe
 cert_chain: []
-date: 2025-02-11 00:00:00.000000000 Z
+date: 2025-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 3.1.14
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: 3.1.14
 email:
 - ismaelct@gmail.com
 executables: []