whoisonline 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94f2c31318e63780cdee77f18a8aaad0ff39133c1334205a50016713d9aa2de6
+  data.tar.gz: b52a4bc959ffdfc54449cbee0cd27c74d2a5930d47487fb4f024d62e2a9c4e85
+SHA512:
+  metadata.gz: 1fb7d27b02f1c7d897b412387cc8fd3236f3ad2851f0e3d164b521b54f8f51357ee0fde5cac5e0a87ace9a12776fab2c20d35ce904fc6924dc5bf1195e534444
+  data.tar.gz: 38d09284b895047ca3107c22bfc3c7407781a2f6fe8bfd30ed48eb5e56ae0c8ba2fc9b18cbd09c20acea8ed1ab41029be8280eaa458dfa320a748771188df407

data/README.md

@@ -0,0 +1,91 @@
+# WhoIsOnline
+
+Track “who is online right now?” in Rails 7/8 using Redis TTL. No database writes, production-safe, and auto-hooks into controllers via a Rails Engine.
+
+## Features
+- Rails Engine auto-includes a controller concern to mark users online.
+- Works with `current_user` from any auth system (Devise, custom, etc.).
+- TTL-based presence in Redis, no tables required.
+- Throttled Redis writes to reduce load (configurable).
+- Safe SCAN-based counting; no `KEYS`.
+- Configurable Redis client, TTL, throttle duration, user id method, controller accessor, and namespace.
+
+## Installation
+Add to your Gemfile:
+
+```ruby
+gem "whoisonline", github: "rails-to-rescue/whoisonline"
+```
+
+Or install directly:
+
+```bash
+bundle add whoisonline
+```
+
+## Quick Start
+Create an initializer `config/initializers/whoisonline.rb`:
+
+```ruby
+WhoIsOnline.configure do |config|
+  config.redis = -> { Redis.new(url: ENV.fetch("REDIS_URL")) }
+  config.ttl = 5.minutes
+  config.throttle = 60.seconds
+  config.user_id_method = :id
+end
+```
+
+The engine auto-adds a concern that runs after each controller action to mark the `current_user` as online. Nothing else is required.
+
+## Public API
+- `WhoIsOnline.track(user)` – mark a user online (auto-called by the controller concern).
+- `WhoIsOnline.online?(user)` – boolean.
+- `WhoIsOnline.count` – number of online users (via SCAN).
+- `WhoIsOnline.user_ids` – array of ids (strings by default).
+- `WhoIsOnline.users(User)` – ActiveRecord relation for convenience.
+
+## Configuration
+```ruby
+WhoIsOnline.configure do |config|
+  config.redis = -> { Redis.new(url: ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0")) }
+  config.ttl = 5.minutes           # how long a user stays online without activity
+  config.throttle = 60.seconds     # minimum time between Redis writes per user
+  config.user_id_method = :id      # how to pull an ID from the user object
+  config.current_user_method = :current_user # method on controllers
+  config.namespace = "whoisonline:user"
+  config.auto_hook = true          # disable if you prefer manual tracking
+  config.logger = Rails.logger if defined?(Rails)
+end
+```
+
+## Performance Notes
+- Uses `SET key value EX ttl` for O(1) writes.
+- Throttling prevents hot users from spamming Redis.
+- Counting and user listing use `SCAN` to avoid blocking Redis (`KEYS` is not used).
+- Namespace keeps presence keys isolated; use a dedicated Redis db/cluster for large scale.
+
+## Example Usage in Rails
+```ruby
+# Somewhere in your controller you can also call manually:
+WhoIsOnline.track(current_user)
+
+# In a background job
+if WhoIsOnline.online?(user)
+  # notify
+end
+
+# In a dashboard
+@online_users = WhoIsOnline.users(User).order(last_sign_in_at: :desc)
+@online_count = WhoIsOnline.count
+```
+
+## Extensibility
+- Engine-based hook is easy to extend (e.g., add ActionCable broadcast).
+- Tracker service is isolated and unit-testable.
+- Configuration is thread-safe and lazy-instantiated.
+
+## Author
+- Kapil Dev Pal – dev.kapildevpal@gmail.com / @rails_to_rescue
+- Project: rails_to_rescue
+
+

data/lib/whoisonline/configuration.rb

@@ -0,0 +1,44 @@
+require "logger"
+
+module WhoIsOnline
+  class Configuration
+    DEFAULT_NAMESPACE = "whoisonline:user".freeze
+
+    attr_accessor :ttl, :throttle, :user_id_method, :namespace, :auto_hook,
+                  :logger, :current_user_method
+    attr_writer :redis
+
+    def initialize
+      @ttl = 5.minutes
+      @throttle = 60.seconds
+      @user_id_method = :id
+      @current_user_method = :current_user
+      @namespace = DEFAULT_NAMESPACE
+      @auto_hook = true
+      @logger = default_logger
+    end
+
+    def redis
+      @redis ||= lambda do
+        Redis.new(url: ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0"))
+      end
+    end
+
+    def redis_connection
+      client = redis.respond_to?(:call) ? redis.call : redis
+      raise ArgumentError, "config.redis must return a Redis-compatible client" unless client.respond_to?(:set)
+
+      client
+    end
+
+    private
+
+    def default_logger
+      return Rails.logger if defined?(Rails)
+
+      Logger.new($stdout, progname: "WhoIsOnline")
+    end
+  end
+end
+
+

data/lib/whoisonline/controller.rb

@@ -0,0 +1,32 @@
+require "active_support/concern"
+
+module WhoIsOnline
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      after_action :who_is_online_track_user
+    end
+
+    private
+
+    def who_is_online_track_user
+      return unless WhoIsOnline.configuration.auto_hook
+
+      user = resolve_whoisonline_user
+      return unless user
+
+      WhoIsOnline.track(user)
+    rescue StandardError => e
+      WhoIsOnline.configuration.logger&.warn("whoisonline track failed: #{e.class} #{e.message}")
+      true
+    end
+
+    def resolve_whoisonline_user
+      method = WhoIsOnline.configuration.current_user_method
+      return public_send(method) if respond_to?(method, true)
+
+      nil
+    end
+  end
+end

data/lib/whoisonline/engine.rb

@@ -0,0 +1,16 @@
+require "rails/engine"
+require_relative "controller"
+
+module WhoIsOnline
+  class Engine < ::Rails::Engine
+    isolate_namespace WhoIsOnline
+
+    initializer "whoisonline.controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include WhoIsOnline::Controller
+      end
+    end
+  end
+end
+
+

data/lib/whoisonline/redis_store.rb

@@ -0,0 +1,47 @@
+require "redis"
+
+module WhoIsOnline
+  class RedisStore
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def connection
+      @connection ||= @configuration.redis_connection
+    end
+
+    def write_presence(key, value, ttl_seconds)
+      connection.set(key, value, ex: ttl_seconds)
+    rescue StandardError => e
+      log(:warn, "whoisonline write failed: #{e.class} #{e.message}")
+      nil
+    end
+
+    def exists?(key)
+      connection.exists?(key)
+    rescue StandardError => e
+      log(:warn, "whoisonline exists? failed: #{e.class} #{e.message}")
+      false
+    end
+
+    def scan_keys(match:)
+      return enum_for(:scan_keys, match: match) unless block_given?
+
+      connection.scan_each(match: match) { |key| yield key }
+    rescue StandardError => e
+      log(:warn, "whoisonline scan failed: #{e.class} #{e.message}")
+      []
+    end
+
+    private
+
+    def log(level, message)
+      logger = @configuration.logger
+      return unless logger
+
+      logger.public_send(level, message)
+    end
+  end
+end
+
+

data/lib/whoisonline/tracker.rb

@@ -0,0 +1,70 @@
+require "concurrent/hash"
+
+module WhoIsOnline
+  class Tracker
+    def initialize(configuration, redis_store)
+      @configuration = configuration
+      @redis_store = redis_store
+      @last_write_by_user = Concurrent::Hash.new
+    end
+
+    def track(user)
+      uid = extract_id(user)
+      return unless uid
+      return if throttled?(uid)
+
+      key = presence_key(uid)
+      now = Time.now.to_i
+      result = @redis_store.write_presence(key, now, ttl_seconds)
+      @last_write_by_user[uid] = Time.now if result
+    end
+
+    def online?(user)
+      uid = extract_id(user)
+      return false unless uid
+
+      @redis_store.exists?(presence_key(uid))
+    end
+
+    def count
+      user_ids.size
+    end
+
+    def user_ids
+      keys = @redis_store.scan_keys(match: "#{@configuration.namespace}:*")
+      keys.lazy.map { |key| key.split(":").last }.to_a
+    end
+
+    def users(model_class)
+      model_class.where(id: user_ids)
+    end
+
+    private
+
+    def extract_id(user)
+      return nil unless user
+      return user if user.is_a?(String) || user.is_a?(Numeric)
+      return user.public_send(@configuration.user_id_method) if user.respond_to?(@configuration.user_id_method)
+
+      nil
+    end
+
+    def presence_key(uid)
+      "#{@configuration.namespace}:#{uid}"
+    end
+
+    def ttl_seconds
+      @configuration.ttl.to_i
+    end
+
+    def throttled?(uid)
+      return false unless @configuration.throttle
+
+      last = @last_write_by_user[uid]
+      return false unless last
+
+      (Time.now - last) < @configuration.throttle
+    end
+  end
+end
+

data/lib/whoisonline/version.rb

@@ -0,0 +1,5 @@
+module WhoIsOnline
+  VERSION = "0.1.0"
+end
+
+

data/lib/whoisonline.rb

@@ -0,0 +1,33 @@
+require "active_support"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/module/delegation"
+
+require_relative "whoisonline/version"
+require_relative "whoisonline/configuration"
+require_relative "whoisonline/redis_store"
+require_relative "whoisonline/tracker"
+require_relative "whoisonline/engine"
+
+module WhoIsOnline
+  class << self
+    delegate :track, :online?, :count, :user_ids, :users, to: :tracker
+
+    def tracker
+      @_tracker ||= Tracker.new(configuration, redis_store)
+    end
+
+    def redis_store
+      @_redis_store ||= RedisStore.new(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      configuration
+    end
+  end
+end
+

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: whoisonline
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kapil Dev Pal
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-12-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Production-ready Rails 7/8 online presence tracking using Redis TTL and
+  controller auto-hook.
+email:
+- dev.kapildevpal@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/whoisonline.rb
+- lib/whoisonline/configuration.rb
+- lib/whoisonline/controller.rb
+- lib/whoisonline/engine.rb
+- lib/whoisonline/redis_store.rb
+- lib/whoisonline/tracker.rb
+- lib/whoisonline/version.rb
+- logowho.png
+homepage: https://github.com/KapilDevPal/WhoIsOnline
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/KapilDevPal/WhoIsOnline
+  source_code_uri: https://github.com/KapilDevPal/WhoIsOnline
+  changelog_uri: https://github.com/KapilDevPal/WhoIsOnline/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/KapilDevPal/WhoIsOnline/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Redis-backed online presence for Rails without database writes
+test_files: []