broadcaster 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ceb2fcd033b6405112a208cc1feed602dce814168f445235e07a1274848b66ff
-  data.tar.gz: 767ecb5b8008dcd2d4de5d7da5a194535212005acab53f29e70211658041dc36
+  metadata.gz: 8db15deb65dc4589963f402e1db172de1fd5cc31c8e46f99e34897a5dc1f3409
+  data.tar.gz: 57fb1bf72218bbfe631fd8547488b4408921ccec0cce2d09d389eb1cc5996f6b
 SHA512:
-  metadata.gz: 61c646e1eef1b4a3ae2a393b53c0432ae5607497799280b8f99aaa8a63206d868874082665aa5c070fff674d51816cd9445377aeed36553968421ca97ad5df78
-  data.tar.gz: 312d25d807de4f462f6c87cfe63ffac69de515db14be52c18603781051557d99ea3e94d2d0cb509c974e9e1558d2f1f7faa18cc604d6b6a6916b99deb7cc9378
+  metadata.gz: 581d6bcc885ee1366c70e73bd70fad9ba4072b525046e6dde9bb0e0d7091c47edaacc643ee31b06658591c53b41d2a212be04ca7479f77b948f0da8b423e3bed
+  data.tar.gz: 012557be64bfdcda584ac04cea11f456cbc2c0f3f5eab7e83659260288259be837c8bf76e5dc548da1b5fe4d31aa5f11f2afae410651d20815358dfe77b99920

data/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['2.3', '2.4', '2.5', '2.6', '2.7', '3.0', '3.1', '3.2', '3.3', '3.4']
+        include:
+          - ruby-version: '4.0'
+            allow-failure: true
+          - ruby-version: ruby-head
+            allow-failure: true
+          - ruby-version: jruby-head
+            allow-failure: true
+
+    continue-on-error: ${{ matrix.allow-failure || false }}
+
+    services:
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake spec
+
+      - name: Upload coverage to Codecov
+        if: matrix.ruby-version == '3.4'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage/.resultset.json
+          token: ${{ secrets.CODECOV_TOKEN }}

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/README.md

@@ -1,12 +1,12 @@
 # Broadcaster
 
 [![Gem Version](https://badge.fury.io/rb/broadcaster.svg)](https://rubygems.org/gems/broadcaster)
-[![Build Status](https://travis-ci.org/gabynaiman/broadcaster.svg?branch=master)](https://travis-ci.org/gabynaiman/broadcaster)
-[![Coverage Status](https://coveralls.io/repos/gabynaiman/broadcaster/badge.svg?branch=master)](https://coveralls.io/r/gabynaiman/broadcaster?branch=master)
-[![Code Climate](https://codeclimate.com/github/gabynaiman/broadcaster.svg)](https://codeclimate.com/github/gabynaiman/broadcaster)
+[![CI](https://github.com/gabynaiman/broadcaster/actions/workflows/ci.yml/badge.svg)](https://github.com/gabynaiman/broadcaster/actions/workflows/ci.yml)
 
 Broadcasting based on Redis PubSub
 
+Requires a running Redis server.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -40,6 +40,46 @@ broadcaster.unsubscribe subscription_id
 broadcaster.unsubscribe_all
 ```
 
+Any callable object can be used instead of a block:
+
+```ruby
+class Receiver
+  def call(message)
+    puts message
+  end
+end
+
+broadcaster.subscribe 'channel_1', Receiver.new
+```
+
+Messages are serialized with `Marshal`, so any serializable Ruby object can be published.
+
+Each subscriber runs isolated from the others: if one raises an error it is logged
+and the message is still delivered to the remaining subscribers.
+
+## Scoping
+
+Channels are scoped by the broadcaster `id`. Without an explicit `id` each instance
+gets a random one, so instances are isolated from each other:
+
+```ruby
+broadcaster_1 = Broadcaster.new
+broadcaster_2 = Broadcaster.new
+
+broadcaster_2.subscribe('channel_1') { |message| puts message }
+broadcaster_1.publish 'channel_1', 'text' # not received by broadcaster_2
+```
+
+Sharing the same `id` makes them see each other's messages, even across processes:
+
+```ruby
+broadcaster_1 = Broadcaster.new id: 'my_app'
+broadcaster_2 = Broadcaster.new id: 'my_app'
+
+broadcaster_2.subscribe('channel_1') { |message| puts message }
+broadcaster_1.publish 'channel_1', 'text' # received by broadcaster_2
+```
+
 ## Global configuration
 
 ```ruby
@@ -52,13 +92,24 @@ Broadcaster.configure do |config|
 end
 ```
 
+| Setting | Default | Description |
+|---|---|---|
+| `redis_client` | `Redic` | Redis client class |
+| `redis_settings` | `'redis://localhost:6379'` | Connection settings passed to the client |
+| `logger` | `Logger.new(STDOUT)` | Logger used by every broadcaster |
+| `reconnection_timeout` | `10` | Seconds to wait before retrying a broken listener connection |
+| `watchdog_interval` | `30` | Seconds between watchdog checks |
+| `watchdog_timeout` | `120` | Seconds without listener activity before restarting it |
+
 ## Options
 
 ```ruby
 options = {
   id: 'my_app',                             # Shared broadcaster for multiple processes
   redis_settings: 'redis://host_name:6379', # Custom redis connection
-  logger: Logger.new('/file.log')           # Custom logger
+  logger: Logger.new('/file.log'),          # Custom logger
+  watchdog_interval: 30,                    # Watchdog tuning for this instance
+  watchdog_timeout: 120
   # or
   redis_client: Redic::Sentinels,
   redis_settings: hosts: [sentinel_1, sentinel_2], master_name: 'mymaster'
@@ -67,6 +118,38 @@ options = {
 Broadcaster.new options
 ```
 
+`reconnection_timeout` can only be set globally.
+
+## Reconnection
+
+The listener runs on its own thread. If the connection to Redis drops, it is
+re-established automatically after `reconnection_timeout` seconds, keeping the
+current subscriptions. Publishing while the connection is down raises an error.
+
+## Watchdog
+
+Reconnection relies on the connection raising an error. A half-open socket never
+does: if the TCP connection is silently dropped, or a Redis Sentinel failover
+promotes a new master, the listener stays blocked reading from a socket that will
+never deliver another message. The process looks healthy while no message is
+received, and nothing recovers on its own.
+
+The watchdog covers that case. It publishes a ping on its own channel every
+`watchdog_interval` seconds, and if no message reaches the listener for
+`watchdog_timeout` seconds it restarts the listener over a new connection —
+which also re-resolves the current master when using `Redic::Sentinels`.
+
+`watchdog_timeout` must be comfortably greater than `watchdog_interval`, so that a
+single lost ping does not trigger a restart.
+
+## Shutdown
+
+Stops the watchdog and the listener, and closes both connections:
+
+```ruby
+broadcaster.shutdown
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/gabynaiman/broadcaster.

data/Rakefile

@@ -3,6 +3,7 @@ require 'rake/testtask'
 
 Rake::TestTask.new(:spec) do |t|
   t.libs << 'spec'
+  t.libs << 'lib'
   t.pattern = 'spec/**/*_spec.rb'
   t.verbose = false
   t.warning = false
@@ -13,11 +14,12 @@ Rake::TestTask.new(:spec) do |t|
   t.options << "-l #{ENV['LINE']} " if ENV['LINE'] && ENV['TEST']
 end
 
+task default: :spec
+
+desc 'IRB console'
 task :console do
-  require 'pry'
+  require 'irb'
   require 'broadcaster'
   ARGV.clear
-  Pry.start
-end
-
-task default: :spec
+  IRB.start
+end

data/broadcaster.gemspec

@@ -1,10 +1,11 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'broadcaster/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'broadcaster'
-  spec.version       = '1.0.2'
+  spec.version       = Broadcaster::VERSION
   spec.authors       = ['Gabriel Naiman']
   spec.email         = ['gabynaiman@gmail.com']
   spec.summary       = 'Broadcasting based on Redis PubSub'
@@ -12,6 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/gabynaiman/broadcaster'
   spec.license       = 'MIT'
 
+  spec.required_ruby_version = '>= 2.3.0'
+
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
@@ -20,11 +23,19 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'redic',        '~> 1.5'
   spec.add_dependency 'class_config', '~> 0.0'
 
+  if RUBY_VERSION >= '4.0'
+    spec.add_dependency 'logger'
+    spec.add_dependency 'securerandom'
+  end
+
   spec.add_development_dependency 'rake', '~> 12.0'
   spec.add_development_dependency 'minitest', '~> 5.0', '< 5.11'
   spec.add_development_dependency 'minitest-colorin', '~> 0.1'
   spec.add_development_dependency 'minitest-line', '~> 0.6'
   spec.add_development_dependency 'simplecov', '~> 0.12'
-  spec.add_development_dependency 'coveralls', '~> 0.8'
-  spec.add_development_dependency 'pry-nav', '~> 0.2'
+
+  if RUBY_VERSION >= '3.3'
+    spec.add_development_dependency 'mutex_m'
+    spec.add_development_dependency 'ostruct'
+  end
 end

data/lib/broadcaster/version.rb

@@ -0,0 +1,3 @@
+class Broadcaster
+  VERSION = '1.1.0'
+end

data/lib/broadcaster/watchdog.rb

@@ -0,0 +1,47 @@
+class Broadcaster
+  class Watchdog
+
+    CHANNEL = '__watchdog__'.freeze
+
+    def initialize(broadcaster, interval:, timeout:, logger:)
+      @broadcaster = broadcaster
+      @interval = interval
+      @timeout = timeout
+      @logger = logger
+    end
+
+    def start
+      @thread = Thread.new do
+        loop do
+          sleep interval
+          check
+        end
+      end
+    end
+
+    def stop
+      thread.kill
+    end
+
+    private
+
+    attr_reader :broadcaster, :interval, :timeout, :logger, :thread
+
+    def check
+      broadcaster.publish CHANNEL, ping: Time.now.to_f
+
+      return unless unresponsive?
+
+      logger.warn(self.class.name) { "No notifications received for #{timeout}s" }
+      broadcaster.restart_listener
+
+    rescue => ex
+      logger.error(self.class.name) { "#{ex.class}: #{ex.message}" }
+    end
+
+    def unresponsive?
+      Time.now - broadcaster.last_notification_at > timeout
+    end
+
+  end
+end

data/lib/broadcaster.rb

@@ -3,6 +3,9 @@ require 'class_config'
 require 'logger'
 require 'securerandom'
 
+require_relative 'broadcaster/version'
+require_relative 'broadcaster/watchdog'
+
 class Broadcaster
 
   extend ClassConfig
@@ -11,8 +14,10 @@ class Broadcaster
   attr_config :redis_settings, 'redis://localhost:6379'
   attr_config :logger, Logger.new(STDOUT)
   attr_config :reconnection_timeout, 10
+  attr_config :watchdog_interval, 30
+  attr_config :watchdog_timeout, 120
 
-  attr_reader :id
+  attr_reader :id, :last_notification_at
 
   def initialize(options={})
     @id = options.fetch(:id, SecureRandom.uuid)
@@ -23,7 +28,12 @@ class Broadcaster
     @publisher = establish_connection
     @subscriptions = {}
     @mutex = Mutex.new
-    listen
+    @watchdog = Watchdog.new self, logger: logger,
+                                   interval: options.fetch(:watchdog_interval, Broadcaster.watchdog_interval),
+                                   timeout: options.fetch(:watchdog_timeout, Broadcaster.watchdog_timeout)
+
+    start_listener
+    watchdog.start
   end
 
   def publish(channel, message)
@@ -60,28 +70,57 @@ class Broadcaster
     end
   end
 
+  def restart_listener
+    logger.warn(logger_name) { 'Restarting listener' }
+
+    listener.kill if listener && listener != Thread.current
+    disconnect subscriber
+
+    start_listener
+  end
+
+  def shutdown
+    watchdog.stop
+    listener.kill
+
+    disconnect subscriber
+    disconnect publisher
+
+    logger.info(logger_name) { 'Shutdown' }
+  end
+
   private
 
-  attr_reader :publisher, :subscriber, :subscriptions, :mutex, :logger, :logger_name, :redis_client, :redis_settings
+  attr_reader :publisher, :subscriber, :listener, :watchdog, :subscriptions, :mutex, :logger, :logger_name,
+              :redis_client, :redis_settings
 
   def establish_connection
     redis_client.new(redis_settings).tap { |redis| redis.call! 'PING' }
   end
 
+  def disconnect(connection)
+    connection.client.disconnect!
+  rescue => ex
+    logger.error(logger_name) { ex }
+  end
+
   def scoped(channel)
     "#{id}:#{channel}"
   end
 
-  def listen
-    subscriber = establish_connection
+  def start_listener
+    @subscriber = establish_connection
     subscriber.call! 'PSUBSCRIBE', scoped('*')
 
     logger.info(logger_name) { 'Listener started' }
 
-    Thread.new do
+    @last_notification_at = Time.now
+
+    @listener = Thread.new do
       loop do
         begin
           notification = subscriber.client.read
+          @last_notification_at = Time.now
 
           channel = notification[2]
           message = Marshal.load notification[3]
@@ -109,15 +148,15 @@ class Broadcaster
       end
 
       logger.warn(logger_name) { 'Listener broken' }
-      listen
+      restart_listener
     end
 
   rescue => ex
     logger.error(logger_name) { ex }
     sleep Broadcaster.reconnection_timeout
 
-    logger.info(logger_name) { 'Listener reconnectig' }
+    logger.info(logger_name) { 'Listener reconnecting' }
     retry
   end
 
-end
+end

data/spec/broadcast_spec.rb

@@ -2,8 +2,8 @@ require 'minitest_helper'
 
 describe Broadcaster do
 
-  def wait_for(&block)
-    Timeout.timeout(1) do
+  def wait_for(timeout=1, &block)
+    Timeout.timeout(timeout) do
       while !block.call
         sleep 0.001
       end
@@ -183,4 +183,55 @@ describe Broadcaster do
     received_messages.must_equal ['message 1', 'message 3']
   end
 
+  describe 'Watchdog' do
+
+    def with_blocked_listener(options={})
+      HangingRedis.reset
+
+      broadcaster = Broadcaster.new options.merge(redis_client: HangingRedis)
+      wait_for { HangingRedis.blocked_reads > 0 }
+      HangingRedis.hanging = false
+
+      yield broadcaster
+
+    ensure
+      broadcaster.shutdown if broadcaster
+      HangingRedis.reset
+    end
+
+    it 'Restarts a listener blocked on a silent connection' do
+      with_blocked_listener watchdog_interval: 0.05, watchdog_timeout: 0.2 do |broadcaster|
+        received_messages = []
+
+        broadcaster.subscribe 'channel_1' do |message|
+          received_messages << message
+        end
+
+        wait_for(10) do
+          broadcaster.publish 'channel_1', 'message 1'
+          sleep 0.1
+          received_messages.any?
+        end
+
+        received_messages.must_include 'message 1'
+      end
+    end
+
+    it 'Does not restart the listener before the timeout elapses' do
+      with_blocked_listener watchdog_interval: 0.05, watchdog_timeout: 60 do |broadcaster|
+        received_messages = []
+
+        broadcaster.subscribe 'channel_1' do |message|
+          received_messages << message
+        end
+
+        broadcaster.publish 'channel_1', 'message 1'
+        sleep 0.5
+
+        received_messages.must_be_empty
+      end
+    end
+
+  end
+
 end

data/spec/minitest_helper.rb

@@ -1,13 +1,10 @@
 require 'simplecov'
-require 'coveralls'
 
-SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new [SimpleCov::Formatter::HTMLFormatter, Coveralls::SimpleCov::Formatter]
 SimpleCov.start
 
 require 'broadcaster'
 require 'minitest/autorun'
 require 'minitest/colorin'
-require 'pry-nav'
 require 'timeout'
 
 Broadcaster.configure do |config|
@@ -61,4 +58,51 @@ class MockRedis
     @redis.client
   end
 
+end
+
+class HangingRedis
+
+  class << self
+
+    attr_writer :hanging
+    attr_accessor :blocked_reads
+
+    def hanging?
+      @hanging.nil? ? true : @hanging
+    end
+
+    def reset
+      @hanging = nil
+      @blocked_reads = 0
+    end
+
+    def blocked_reads
+      @blocked_reads ||= 0
+    end
+
+  end
+
+  def initialize(*args)
+    @redis = Redic.new(*args)
+  end
+
+  def call!(*args)
+    @redis.call!(*args)
+  end
+
+  def client
+    self
+  end
+
+  def read
+    return @redis.client.read unless self.class.hanging?
+
+    self.class.blocked_reads += 1
+    sleep
+  end
+
+  def disconnect!
+    @redis.client.disconnect!
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: broadcaster
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Gabriel Naiman
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-26 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redic
@@ -114,34 +114,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.12'
-- !ruby/object:Gem::Dependency
-  name: coveralls
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-- !ruby/object:Gem::Dependency
-  name: pry-nav
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
 description: Broadcasting based on Redis PubSub
 email:
 - gabynaiman@gmail.com
@@ -149,24 +121,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".coveralls.yml"
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".ruby-gemset"
 - ".ruby-version"
-- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - broadcaster.gemspec
 - lib/broadcaster.rb
+- lib/broadcaster/version.rb
+- lib/broadcaster/watchdog.rb
 - spec/broadcast_spec.rb
 - spec/minitest_helper.rb
 homepage: https://github.com/gabynaiman/broadcaster
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -174,15 +147,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
-signing_key: 
+rubygems_version: 3.0.9
+signing_key:
 specification_version: 4
 summary: Broadcasting based on Redis PubSub
 test_files:

data/.coveralls.yml

@@ -1,2 +0,0 @@
-service_name: travis-ci
-repo_token: DIwiPcMHvmwcB0uOFrsaZ3ftClakHZSCM

data/.travis.yml

@@ -1,23 +0,0 @@
-language: ruby
-
-rvm:
-  - 2.0
-  - 2.1
-  - 2.2
-  - 2.3
-  - 2.4
-  - 2.5
-  - 2.6
-  - 2.7
-  - jruby-9.2.9.0
-  - ruby-head
-  - jruby-head
-
-matrix:
-  fast_finish: true
-  allow_failures:
-    - rvm: ruby-head
-    - rvm: jruby-head
-
-services:
-  - redis-server