dboard 3.0.1 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b007fa0f768847e5a5155f08205ca9b8bc3ec1afbe60dfbc21d0e0ba7fb279
-  data.tar.gz: 665d3e307f3af7c5192e30b2864b195e2f842d4165acd9f7f5ad062439191ace
+  metadata.gz: 2ca84c9c7461e1f0aefa5463e6796774e3fcb41d909430f0447bf9c240609753
+  data.tar.gz: e0f59d7466411b2dcfff3799f521271950dfab15e1322b5d15aaaca66b621ea7
 SHA512:
-  metadata.gz: 166b2aa677c0234e1de2574df03f17072adab4e09c7bd68e26a8be03640f1b4ac50ccd3246657c383cd741611823c3efbd8fdd299a582a17d534a3c40164e5cf
-  data.tar.gz: aa99aae44e6a0a968150f42438dca61893f45960df655a06722a93d0ff52a2e3daa6abb56ed9f827b8647f6a718b0f5c230cb117c83e696fd22868852d5402e4
+  metadata.gz: a32643a51fbdd0acb92d4b7e3c7f88db9f2749316918867e700e6582ac0956814a0789a6df1934f71017623716b55b69c8510886d3b5156f2be9183b474ddfc5
+  data.tar.gz: e222ceed0499f6bac7622f690cc71815d095252dc6158c7db48007e595ba57b8e617bcc7e033030910ae7088071ee555f699ba93ab701753db053c0c01728f13

data/.github/workflows/ci.yml

@@ -14,12 +14,12 @@ jobs:
     strategy:
       matrix:
         ruby-version:
-          - 3.1
-          - "3.0"
-          - 2.7
+          - "3.4"
+          - "3.3"
+          - "3.2"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
       - name: Set up Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:
@@ -27,3 +27,27 @@ jobs:
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
       - name: Run tests
         run: bundle exec rake
+
+  release:
+    if: github.ref_name == github.event.repository.default_branch
+    needs: test
+    environment: Rubygems
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Publish gem
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- '---\n:rubygems_api_key: %s\n' "$RUBYGEMS_API_KEY" > "$HOME/.gem/credentials"
+          sed -i -E "s/(VERSION = \"[0-9.]+)\"/\1.${GITHUB_RUN_NUMBER}\"/" lib/version.rb # Add build number to version
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          RUBYGEMS_API_KEY: "${{secrets.RUBYGEMS_API_KEY}}"

data/README.md

@@ -21,6 +21,22 @@ Things dboard do for you:
 * Provides a javascript client that knows how to talk to the API (for now it's only included in the [example app](https://github.com/joakimk/dboard_example))
 * Only calls your javascript widgets when there is new data.
 
+Refreshing sources:
+
+Each source defines `update_interval` (seconds), and the collector polls it on that cadence.
+
+You can also trigger an out-of-band refresh (e.g. from an inbound webhook) with `Dboard::Collector.request_update(:key)`, where `:key` is the key the source was registered under. This is throttled: the first trigger refreshes immediately, and further triggers inside the floor window are coalesced into a single trailing refresh, so a flood of triggers never causes more than one refresh per floor. The poll and manual triggers share one clock, so a manual refresh lets the next poll cycle skip its fetch.
+
+The floor defaults to 30 seconds. A source may override it by defining `min_update_interval` (seconds). The effective floor is capped at the source's `update_interval`, so it can never exceed the poll interval.
+
+Targeted refreshes:
+
+`request_update` also takes an optional argument for a targeted refresh: `Dboard::Collector.request_update(:key, arg)`. The argument is opaque; the framework forwards it verbatim to the source and never inspects it. Omitting it (or passing `nil`) means a full refresh of the whole source.
+
+A source opts in by defining `fetch(args = nil)`. It receives `nil` for a full refresh (a scheduled poll or a no-arg `request_update`) and an array of the accumulated arguments for a targeted refresh. Arguments are batched the same way triggers are coalesced: the leading refresh carries the first argument, and any arguments that arrive during the active window are delivered together in the one trailing refresh. A no-arg (full) request queued during a burst wins over pending arguments, since a full refresh already covers them. The poll shares the same clock and floor as targeted refreshes, so both together still fetch at most once per floor.
+
+Publishing stays wholesale: the collector always replaces the stored blob for the key. A source doing a targeted refresh must therefore read its current state (e.g. from the cache) and return the full merged blob, not only the refreshed part.
+
 Data flow:
 
     +-----------------+              +--------------------+

data/lib/collector.rb

@@ -5,6 +5,12 @@ module Dboard
   class Collector
     include Singleton
 
+    DEFAULT_MIN_INTERVAL = 30 # seconds
+
+    FULL = Object.new.freeze # a no-arg request; compared by identity so a caller-supplied value never collides
+    SKIP = Object.new.freeze # a throttled/empty attempt that must not fetch
+    private_constant :FULL, :SKIP
+
     attr_reader :sources
 
     def self.register_source(key, source_instance)
@@ -19,6 +25,10 @@ module Dboard
       instance.register_error_callback(callback)
     end
 
+    def self.request_update(key, arg = nil)
+      instance.request_update(key, arg)
+    end
+
     def self.start
       instance.start
     end
@@ -27,6 +37,11 @@ module Dboard
       @sources = {}
       @after_update_callback = lambda {}
       @error_callback = lambda { |exception| }
+      @mutex = Mutex.new
+      @last_update_at = {}
+      @active = {}
+      @pending = {}
+      @refresh_locks = {}
     end
 
     def start
@@ -44,6 +59,7 @@ module Dboard
 
     def register_source(key, instance)
       @sources.merge!({ key => instance })
+      @refresh_locks[key] = Mutex.new
     end
 
     def register_after_update_callback(callback)
@@ -54,10 +70,33 @@ module Dboard
       @error_callback = callback
     end
 
-    # Public because the old tests depend on it
-    def update_source(source, instance)
+    def request_update(key, arg = nil)
+      instance = @sources.fetch(key)
+      floor = min_interval_for(instance)
+      entry = arg.nil? ? FULL : arg
+      leading = nil
+      delay = @mutex.synchronize {
+        now = monotonic_now
+        (@pending[key] ||= []) << entry
+        case decide_request(@active[key], @last_update_at[key], floor, now)
+        when :coalesce
+          return
+        when :refresh_now
+          @active[key] = true
+          leading = @pending[key]
+          @pending[key] = []
+          0
+        when :schedule
+          @active[key] = true
+          floor - (now - @last_update_at[key])
+        end
+      }
+      spawn { run_worker(key, instance, floor, delay, leading) }
+    end
+
+    def update_source(source, instance, batch = nil)
       begin
-        data = instance.fetch
+        data = fetch_source(instance, batch)
         publish_data(source, data)
       ensure
         @after_update_callback.call
@@ -70,20 +109,111 @@ module Dboard
 
     private
 
+    def fetch_source(instance, batch)
+      if batch.nil? || batch.any? { |entry| entry.equal?(FULL) }
+        instance.fetch
+      else
+        instance.fetch(batch)
+      end
+    end
+
+    def decide_request(active, last_update_at, floor, now)
+      return :coalesce if active
+      return :refresh_now if last_update_at.nil? || (now - last_update_at) >= floor
+
+      :schedule
+    end
+
+    def run_worker(key, instance, floor, delay, leading)
+      cleared = false
+      loop do
+        sleep delay if delay && delay > 0
+        fired = perform_refresh(key, instance, floor, leading: leading, drain: leading.nil?)
+        delay = @mutex.synchronize {
+          remaining = floor - (monotonic_now - @last_update_at[key])
+          remaining = 0 if remaining < 0
+          pending = @pending[key]
+          if fired
+            leading = nil
+            if pending && !pending.empty?
+              remaining # trailing: drain the burst that arrived while we were active
+            else
+              @active[key] = false
+              cleared = true
+              nil
+            end
+          elsif leading || (pending && !pending.empty?)
+            remaining # throttled; retry the retained leading snapshot or the queued args after the floor
+          else
+            @active[key] = false
+            cleared = true
+            nil
+          end
+        }
+        break if cleared
+      end
+    rescue Exception => ex
+      puts "Something failed in the update worker for #{key}: #{ex.message}"
+      puts ex.backtrace
+    ensure
+      @mutex.synchronize { @active[key] = false } unless cleared
+    end
+
+    def perform_refresh(source, instance, min_interval, leading: nil, drain: false)
+      @refresh_locks.fetch(source).synchronize {
+        batch = @mutex.synchronize {
+          now = monotonic_now
+          last = @last_update_at[source]
+          next SKIP unless last.nil? || (now - last) >= min_interval
+
+          if leading
+            resolved = leading
+          elsif drain
+            queued = (@pending[source] ||= [])
+            next SKIP if queued.empty?
+
+            resolved = queued
+            @pending[source] = []
+          else
+            resolved = nil
+          end
+          @last_update_at[source] = now
+          resolved
+        }
+        return false if batch.equal?(SKIP)
+
+        update_source(source, instance, batch)
+        true
+      }
+    end
+
     def update_in_thread(source, instance)
-      time = Time.now
-      puts "#{source} updating..."
-      update_source(source, instance)
-      elapsed_time = Time.now - time
-      time_until_next_update = instance.update_interval - elapsed_time
-      time_until_next_update = 0 if time_until_next_update < 0
-      puts "#{source} done in #{elapsed_time} seconds, will update again in #{time_until_next_update} seconds (interval: #{instance.update_interval})."
+      puts "#{source} polling..."
+      fired = perform_refresh(source, instance, instance.update_interval)
+      time_until_next_update = @mutex.synchronize {
+        remaining = instance.update_interval - (monotonic_now - @last_update_at[source])
+        remaining < 0 ? 0 : remaining
+      }
+      puts "#{source} #{fired ? "updated" : "still fresh"}, will poll again in #{time_until_next_update} seconds (interval: #{instance.update_interval})."
       sleep time_until_next_update
     rescue Exception => ex
       puts "Something failed outside the update_source method. #{ex.message}"
       puts ex.backtrace
     end
 
+    def min_interval_for(instance)
+      override = instance.respond_to?(:min_update_interval) ? instance.min_update_interval : DEFAULT_MIN_INTERVAL
+      [ override, instance.update_interval ].min
+    end
+
+    def spawn(&block)
+      Thread.new(&block)
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
     def publish_data(source, data)
       Publisher.publish(source, data)
     end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module Dboard
-  VERSION = "3.0.1"
+  VERSION = "3.2.0"
 end

data/spec/collector_spec.rb

@@ -1,63 +1,517 @@
 require File.expand_path(File.join(File.dirname(__FILE__), "spec_helper"))
 
-describe Dboard::Collector, ".register_source" do
-  before do
-    Dboard::Collector.instance.sources.clear
+class FakeClock
+  attr_reader :now
+
+  def initialize
+    @now = 0.0
+  end
+
+  def advance(seconds)
+    @now += seconds
   end
+end
 
-  let(:new_relic) { double(:new_relic) }
-  let(:callback) { double(:callback) }
+class LatchSource
+  attr_reader :update_interval
 
-  it "can register a source" do
-    allow(new_relic).to receive(:update_interval).and_return(5)
-    Dboard::Collector.register_source :new_relic, new_relic
-    expect(Dboard::Collector.instance.sources).to eq({ new_relic: new_relic })
+  def initialize(update_interval:)
+    @update_interval = update_interval
+    @lock = Mutex.new
+    @started = Queue.new
+    @release = Queue.new
+    @block_next = false
+    @value = nil
+    @fetch_values = []
+    @fetch_times = []
   end
 
-  it "can register an after update callback" do
-    allow(new_relic).to receive(:fetch).and_return({ db: "100%" })
-    Dboard::Collector.register_after_update_callback callback
+  def set_value(value)
+    @lock.synchronize { @value = value }
+  end
 
-    expect(callback).to receive(:call)
-    allow(Dboard::Publisher).to receive(:publish)
-    Dboard::Collector.instance.update_source(:new_relic, new_relic)
+  def block_next_fetch!
+    @lock.synchronize { @block_next = true }
+  end
 
-    # since it is a singleton, and this callbacks leaks into the other tests
-    Dboard::Collector.register_after_update_callback(lambda {})
+  def wait_until_started
+    @started.pop
   end
 
-  it "can register an error callback" do
-    error = RuntimeError.new("error")
-    allow(new_relic).to receive(:fetch).and_raise(error)
+  def release!
+    @release << true
+  end
 
-    Dboard::Collector.register_error_callback callback
+  def fetch_count
+    @lock.synchronize { @fetch_values.size }
+  end
+
+  def fetch_values
+    @lock.synchronize { @fetch_values.dup }
+  end
 
-    expect(callback).to receive(:call).with(error)
-    allow(Dboard::Publisher).to receive(:publish)
-    allow_any_instance_of(Dboard::Collector).to receive(:puts)
-    Dboard::Collector.instance.update_source(:new_relic, new_relic)
+  def fetch_times
+    @lock.synchronize { @fetch_times.dup }
+  end
 
-    # since it is a singleton, and this callbacks leaks into the other tests
-    Dboard::Collector.register_error_callback(lambda { |_| })
+  def fetch
+    now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    block_here = @lock.synchronize {
+      @fetch_values << @value
+      @fetch_times << now
+      blocking = @block_next
+      @block_next = false
+      blocking
+    }
+    if block_here
+      @started << true
+      @release.pop
+    end
+    { value: fetch_values.last }
   end
 end
 
-describe Dboard::Collector, "update_source" do
-  before do
-    Dboard::Collector.instance.sources.clear
+RSpec.describe Dboard::Collector do
+  describe ".register_source" do
+    before do
+      Dboard::Collector.instance.sources.clear
+    end
+
+    let(:new_relic) { double(:new_relic) }
+    let(:callback) { double(:callback) }
+
+    it "can register a source" do
+      allow(new_relic).to receive(:update_interval).and_return(5)
+      Dboard::Collector.register_source :new_relic, new_relic
+      expect(Dboard::Collector.instance.sources).to eq({ new_relic: new_relic })
+    end
+
+    it "can register an after update callback" do
+      allow(new_relic).to receive(:fetch).and_return({ db: "100%" })
+      allow(callback).to receive(:call)
+      allow(Dboard::Publisher).to receive(:publish)
+      Dboard::Collector.register_after_update_callback callback
+
+      Dboard::Collector.instance.update_source(:new_relic, new_relic)
+
+      expect(callback).to have_received(:call)
+
+      # since it is a singleton, and this callbacks leaks into the other tests
+      Dboard::Collector.register_after_update_callback(lambda {})
+    end
+
+    it "can register an error callback" do
+      error = RuntimeError.new("error")
+      allow(new_relic).to receive(:fetch).and_raise(error)
+      allow(callback).to receive(:call)
+      allow(Dboard::Publisher).to receive(:publish)
+      allow_any_instance_of(Dboard::Collector).to receive(:puts)
+      Dboard::Collector.register_error_callback callback
+
+      Dboard::Collector.instance.update_source(:new_relic, new_relic)
+
+      expect(callback).to have_received(:call).with(error)
+
+      # since it is a singleton, and this callbacks leaks into the other tests
+      Dboard::Collector.register_error_callback(lambda { |_| })
+    end
   end
 
-  let(:new_relic) { double(:new_relic) }
+  describe "update_source" do
+    before do
+      Dboard::Collector.instance.sources.clear
+    end
+
+    let(:new_relic) { double(:new_relic) }
+
+    it "collects and publishes data from sources" do
+      allow(new_relic).to receive(:fetch).and_return({ db: "100%" })
+      allow(Dboard::Publisher).to receive(:publish)
+
+      Dboard::Collector.instance.update_source(:new_relic, new_relic)
+
+      expect(Dboard::Publisher).to have_received(:publish).with(:new_relic, { db: "100%" })
+    end
+
+    it "prints out debugging info" do
+      allow(new_relic).to receive(:fetch).and_raise(Exception.new("some error"))
+      allow(Dboard::Collector.instance).to receive(:puts)
 
-  it "collects and publishes data from sources" do
-    allow(new_relic).to receive(:fetch).and_return({ db: "100%" })
-    expect(Dboard::Publisher).to receive(:publish).with(:new_relic, { db: "100%" })
-    Dboard::Collector.instance.update_source(:new_relic, new_relic)
+      Dboard::Collector.instance.update_source(:new_relic, new_relic)
+
+      expect(Dboard::Collector.instance).to have_received(:puts).twice
+    end
   end
 
-  it "prints out debugging info" do
-    allow(new_relic).to receive(:fetch).and_raise(Exception.new("some error"))
-    expect(Dboard::Collector.instance).to receive(:puts).twice
-    Dboard::Collector.instance.update_source(:new_relic, new_relic)
+  describe "throttled on-demand refresh" do
+    let(:collector) { Dboard::Collector.instance }
+
+    before do
+      reset_collector!
+      allow(collector).to receive(:puts)
+      allow(Dboard::Publisher).to receive(:publish)
+    end
+
+    after do
+      join_threads
+      reset_collector!
+    end
+
+    describe "the refresh decision" do
+      it "refreshes immediately on the first trigger" do
+        expect(collector.send(:decide_request, false, nil, 30, 100)).to eq(:refresh_now)
+      end
+
+      it "refreshes again once the floor has elapsed" do
+        expect(collector.send(:decide_request, false, 100, 30, 130)).to eq(:refresh_now)
+      end
+
+      it "schedules a trailing when triggered within the floor" do
+        expect(collector.send(:decide_request, false, 100, 30, 110)).to eq(:schedule)
+      end
+
+      it "coalesces a trigger that arrives while a refresh is active or scheduled" do
+        expect(collector.send(:decide_request, true, 100, 30, 110)).to eq(:coalesce)
+      end
+    end
+
+    describe "the effective floor" do
+      it "defaults to DEFAULT_MIN_INTERVAL" do
+        source = double(:source, update_interval: 100)
+        expect(collector.send(:min_interval_for, source)).to eq(Dboard::Collector::DEFAULT_MIN_INTERVAL)
+      end
+
+      it "uses a source's min_update_interval override" do
+        source = double(:source, update_interval: 100, min_update_interval: 10)
+        expect(collector.send(:min_interval_for, source)).to eq(10)
+      end
+
+      it "never exceeds the update_interval" do
+        too_short = double(:source, update_interval: 5)
+        big_override = double(:source, update_interval: 5, min_update_interval: 30)
+        expect(collector.send(:min_interval_for, too_short)).to eq(5)
+        expect(collector.send(:min_interval_for, big_override)).to eq(5)
+      end
+    end
+
+    describe "coalescing (deterministic clock)" do
+      it "turns a burst into exactly one leading and one trailing refresh" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        workers = capture_worker_blocks
+
+        10.times { collector.request_update(:src) }
+        workers.each(&:call)
+
+        expect(source).to have_received(:fetch).twice
+      end
+
+      it "still fires the trailing when the floor is clamped to a fast update_interval" do
+        source = double(:source, update_interval: 5)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        workers = capture_worker_blocks
+
+        3.times { collector.request_update(:src) }
+        workers.each(&:call)
+
+        expect(source).to have_received(:fetch).twice
+      end
+
+      it "resets in-flight state when a fetch raises, so a later trigger still refreshes" do
+        source = double(:source, update_interval: 100)
+        calls = 0
+        allow(source).to receive(:fetch) do
+          calls += 1
+          raise "boom" if calls == 1
+
+          { ok: true }
+        end
+        collector.register_source(:src, source)
+        clock = use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src)
+        expect(collector.instance_variable_get(:@active)[:src]).to be_falsey
+
+        clock.advance(30)
+        collector.request_update(:src)
+
+        expect(source).to have_received(:fetch).twice
+      end
+    end
+
+    describe "the shared clock" do
+      it "lets a manual refresh make the next poll cycle skip its fetch" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src)
+        collector.send(:update_in_thread, :src, source)
+
+        expect(source).to have_received(:fetch).once
+      end
+
+      it "re-evaluates a scheduled trailing when a poll refreshes during its sleep" do
+        source = double(:source, update_interval: 100, min_update_interval: 10)
+        clock = FakeClock.new
+        fetch_times = []
+        allow(source).to receive(:fetch) { fetch_times << clock.now; { ok: true } }
+        collector.register_source(:src, source)
+        allow(collector).to receive(:monotonic_now) { clock.now }
+
+        polled = false
+        allow(collector).to receive(:sleep) do |seconds|
+          if polled
+            clock.advance(seconds)
+          else
+            polled = true
+            clock.advance(4)
+            collector.instance_variable_get(:@last_update_at)[:src] = clock.now
+          end
+        end
+
+        workers = capture_worker_blocks
+        2.times { collector.request_update(:src) }
+        workers.each(&:call)
+
+        expect(fetch_times.length).to eq(2)
+        expect(fetch_times.last).to be >= 4 + 10
+      end
+    end
+
+    describe "with arguments" do
+      it "passes the argument to fetch as a one-element batch and publishes the result" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: "x" })
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src, "x")
+
+        expect(source).to have_received(:fetch).with([ "x" ])
+        expect(Dboard::Publisher).to have_received(:publish).with(:src, { ok: "x" })
+      end
+
+      it "forwards the argument through the class-level request_update" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        Dboard::Collector.request_update(:src, "x")
+
+        expect(source).to have_received(:fetch).with([ "x" ])
+      end
+
+      it "splits a burst of arguments into a leading batch and a trailing batch" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        workers = capture_worker_blocks
+
+        collector.request_update(:src, "x")
+        collector.request_update(:src, "y")
+        collector.request_update(:src, "z")
+        workers.each(&:call)
+
+        expect(source).to have_received(:fetch).with([ "x" ]).once
+        expect(source).to have_received(:fetch).with([ "y", "z" ]).once
+      end
+
+      it "refreshes the whole source when no argument is given" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src)
+
+        expect(source).to have_received(:fetch).with(no_args)
+      end
+
+      it "does a full refresh when a no-arg request is coalesced with pending arguments" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        workers = capture_worker_blocks
+
+        collector.request_update(:src, "a")
+        collector.request_update(:src, "b")
+        collector.request_update(:src)
+        workers.each(&:call)
+
+        expect(source).to have_received(:fetch).with([ "a" ]).once
+        expect(source).to have_received(:fetch).with(no_args).once
+      end
+
+      it "treats a caller-supplied :full argument as an ordinary partial arg" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src, :full)
+
+        expect(source).to have_received(:fetch).with([ :full ])
+      end
+
+      it "refreshes a source whose fetch takes no arguments" do
+        source = Class.new do
+          def update_interval
+            100
+          end
+
+          def fetch
+            { ok: true }
+          end
+        end.new
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src)
+
+        expect(Dboard::Publisher).to have_received(:publish).with(:src, { ok: true })
+      end
+
+      it "leaves pending args untouched when a poll wins and delivers them on the next on-demand refresh" do
+        source = double(:source, update_interval: 100)
+        fetch_args = []
+        allow(source).to receive(:fetch) { |*args| fetch_args << args.first; { ok: true } }
+        collector.register_source(:src, source)
+        use_fake_clock
+        workers = capture_worker_blocks
+
+        collector.request_update(:src, "a")
+        collector.request_update(:src, "p")
+        expect(collector.instance_variable_get(:@pending)[:src]).to eq([ "p" ])
+
+        collector.send(:update_in_thread, :src, source)
+        expect(collector.instance_variable_get(:@pending)[:src]).to eq([ "p" ])
+
+        workers.each(&:call)
+
+        expect(fetch_args).to eq([ nil, [ "a" ], [ "p" ] ])
+      end
+
+      it "retries the retained leading snapshot when a poll refreshes before it runs" do
+        source = double(:source, update_interval: 100)
+        fetch_args = []
+        allow(source).to receive(:fetch) { |*args| fetch_args << args.first; { ok: true } }
+        collector.register_source(:src, source)
+        clock = use_fake_clock
+        workers = capture_worker_blocks
+
+        collector.request_update(:src, "p")
+        collector.instance_variable_get(:@last_update_at)[:src] = clock.now
+        workers.each(&:call)
+
+        expect(fetch_args).to eq([ [ "p" ] ])
+      end
+
+      it "shares one clock between a partial refresh and the poll" do
+        source = double(:source, update_interval: 100)
+        allow(source).to receive(:fetch).and_return({ ok: true })
+        collector.register_source(:src, source)
+        use_fake_clock
+        run_workers_inline
+
+        collector.request_update(:src, "p")
+        collector.send(:update_in_thread, :src, source)
+
+        expect(source).to have_received(:fetch).with([ "p" ]).once
+        expect(source).to have_received(:fetch).with(no_args).exactly(0).times
+      end
+    end
+
+    describe "under real threads" do
+      it "coalesces a burst arriving during the leading fetch into one trailing that captures the final state" do
+        source = LatchSource.new(update_interval: 0.15)
+        source.set_value("v1")
+        source.block_next_fetch!
+        collector.register_source(:src, source)
+        capture_real_threads
+
+        collector.request_update(:src)
+        source.wait_until_started
+
+        source.set_value("v2")
+        10.times { collector.request_update(:src) }
+
+        source.release!
+        join_threads
+
+        expect(source.fetch_count).to eq(2)
+        expect(source.fetch_values.last).to eq("v2")
+        expect(source.fetch_times[1] - source.fetch_times[0]).to be >= 0.15 - 0.02
+      end
+
+      it "throttles a sustained stream of triggers to roughly one refresh per floor" do
+        source = LatchSource.new(update_interval: 0.1)
+        collector.register_source(:src, source)
+        capture_real_threads
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 0.5
+        while Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+          collector.request_update(:src)
+          sleep 0.01
+        end
+        join_threads
+
+        expect(source.fetch_count).to be_between(2, 8)
+      end
+    end
+
+    private
+
+    def reset_collector!
+      collector.sources.clear
+      %i[@last_update_at @active @pending @refresh_locks].each { |ivar| collector.instance_variable_get(ivar).clear }
+      collector.register_after_update_callback(lambda {})
+      collector.register_error_callback(lambda { |_| })
+    end
+
+    def use_fake_clock
+      clock = FakeClock.new
+      allow(collector).to receive(:monotonic_now) { clock.now }
+      allow(collector).to receive(:sleep) { |seconds| clock.advance(seconds) }
+      clock
+    end
+
+    def run_workers_inline
+      allow(collector).to receive(:spawn) { |&block| block.call }
+    end
+
+    def capture_worker_blocks
+      blocks = []
+      allow(collector).to receive(:spawn) { |&block| blocks << block }
+      blocks
+    end
+
+    def capture_real_threads
+      @threads = []
+      allow(collector).to receive(:spawn) do |&block|
+        thread = Thread.new(&block)
+        @threads << thread
+        thread
+      end
+    end
+
+    def join_threads
+      (@threads || []).each { |thread| thread.join(3) }
+    end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dboard
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.2.0
 platform: ruby
 authors:
 - Joakim Kolsjö
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-06-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dalli
@@ -124,7 +123,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -139,8 +137,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Dashboard framework
 test_files: []