whoisonline 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d9ca4af0f12891b59ecbceb8666fbbb49d05043bc29bce86caeb85f1fa5d92d
-  data.tar.gz: d87b7d98171a1b83793d6291c5ccaaf452a372d18554b532435522938486b5b2
+  metadata.gz: dcd954e1560a78b4047064f6b1359d22f159b08fd86f3c8cea97283f8a7f2210
+  data.tar.gz: '06558961aad1873ceb47cf7799049603a9994376a9a2a9ed0b54eeb43b688207'
 SHA512:
-  metadata.gz: 889ddb36bc48126bac9d70df40140381cef90c66a083bc89c533e60b29d44bc117ff9bb1f4637a2f0b60fb6dd04b399fce74db9b232b32362e4a23bf88a0ff98
-  data.tar.gz: 102ad2155cee722972f09558454f57abc61a652453ac70a05ace23833948ced1f0191b999eb313199a6f2c17be097fd53e7b2339d74e68364199dbffcc0e259e
+  metadata.gz: 139becc8c6d5cdd18578023ba4a9c751a6f9803ec2396d73a229e6421d4b21543d3de4327b37513cc9075c3c5f9deb21d1f4e0900a03e84ac24db374d219af71
+  data.tar.gz: a2bd79ab7b77f9524865030f2af74cc011187191d1403968e094a26ed663866fa83d6e2a9a1a41512e3bfb805e2c7f61afa43a46e76dc98e2b7a6aede6b8096c

data/README.md

@@ -1,125 +1,356 @@
-# WhoIsOnline
+# WhoIsOnline 💚
 
-Track "who is online right now?" in Rails 7+ using Redis TTL. No database writes, production-safe, and auto-hooks into controllers via a Rails Engine.
+<div align="center">
 
-## 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.
-- **Automatic offline detection** when users close their browser/tab.
-- **Visible-only heartbeats**: only ping while the tab is visible/active (configurable interval).
-- Throttled Redis writes to reduce load (configurable).
-- Safe SCAN-based counting; no `KEYS`.
-- Configurable Redis client, TTL, throttle duration, user id method, controller accessor, namespace, and heartbeat interval.
+![WhoIsOnline](https://img.shields.io/badge/WhoIsOnline-v0.1.3-brightgreen)
+![Rails](https://img.shields.io/badge/Rails-7%2B-red)
+![Ruby](https://img.shields.io/badge/Ruby-3.1%2B-red)
+![License](https://img.shields.io/badge/License-MIT-blue)
+![Gem](https://img.shields.io/gem/v/whoisonline?color=blue)
 
-## Installation
-Add to your Gemfile:
+**Track "who is online right now?" in Rails using Redis TTL. Zero database writes, production-ready, and auto-hooks into controllers.**
+
+[Installation](#-installation) • [Quick Start](#-quick-start) • [Configuration](#-configuration) • [API](#-public-api) • [Examples](#-examples)
+
+</div>
+
+---
+
+## ✨ Features
+
+- 🚀 **Zero Setup** - Rails Engine auto-includes controller concern
+- 🔌 **Works with Any Auth** - Devise, custom, or any `current_user` method
+- ⚡ **Redis TTL-Based** - No database tables required
+- 👁️ **Smart Tracking** - Only tracks when tab is visible/active
+- 🔄 **Automatic Offline Detection** - Marks users offline when browser closes
+- ⏱️ **Throttled Writes** - Configurable to reduce Redis load
+- 🔍 **SCAN-Based** - Safe counting without blocking Redis (`KEYS` not used)
+- 🎛️ **Highly Configurable** - Redis client, TTL, throttle, heartbeat interval, and more
+
+---
+
+## 📦 Installation
+
+### From RubyGems (Recommended)
+
+Add to your `Gemfile`:
 
 ```ruby
-gem "whoisonline", github: "KapilDevPal/WhoIsOnline"
+gem "whoisonline"
 ```
 
-Or install directly:
+Then run:
 
 ```bash
-bundle add whoisonline
+bundle install
 ```
 
-## Quick Start
-Create an initializer `config/initializers/whoisonline.rb`:
+### From GitHub (Development)
+
+```ruby
+gem "whoisonline", github: "KapilDevPal/WhoIsOnline"
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Create Initializer
+
+Create `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
-  config.heartbeat_interval = 60.seconds # client heartbeat when tab visible
+  config.heartbeat_interval = 60.seconds # Heartbeat when tab is visible
 end
 ```
 
-The engine auto-adds a concern that runs after each controller action to mark the `current_user` as online.
+### 2. Add to Layout (Optional but Recommended)
 
-**To enable offline detection when users close their browser**, add this to your main layout (e.g., `app/views/layouts/application.html.erb`):
+Add to your main layout (`app/views/layouts/application.html.erb`):
 
 ```erb
-<%= whoisonline_offline_script %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>My App</title>
+    <%= csrf_meta_tags %>
+  </head>
+  <body>
+    <%= yield %>
+    <%= whoisonline_offline_script %>
+  </body>
+</html>
 ```
 
-This will automatically mark users offline when they close the browser/tab.
-Heartbeats run only when the tab is visible/active (interval: `heartbeat_interval`, default 60s), keeping the user online without constant polling.
+**That's it!** The engine automatically tracks users online after each controller action.
+
+---
 
-## Public API
-- `WhoIsOnline.track(user)` – mark a user online (auto-called by the controller concern).
-- `WhoIsOnline.offline(user)` – mark a user offline immediately.
-- `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.
+## 📖 Public API
+
+```ruby
+# Mark user online (auto-called by controller concern)
+WhoIsOnline.track(user)
+
+# Mark user offline immediately
+WhoIsOnline.offline(user)
+
+# Check if user is online
+WhoIsOnline.online?(user)  # => true/false
+
+# Get count of online users
+WhoIsOnline.count  # => 42
+
+# Get array of online user IDs
+WhoIsOnline.user_ids  # => ["1", "2", "3"]
+
+# Get ActiveRecord relation of online users
+WhoIsOnline.users(User)  # => User.where(id: [...])
+```
+
+---
+
+## ⚙️ Configuration
 
-## Configuration
 ```ruby
 WhoIsOnline.configure do |config|
+  # Redis connection (required)
   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.heartbeat_interval = 60.seconds # heartbeat frequency while tab visible
-  config.namespace = "whoisonline:user"
-  config.auto_hook = true          # disable if you prefer manual tracking
-  config.logger = Rails.logger if defined?(Rails)
+  
+  # TTL settings
+  config.ttl = 5.minutes                    # How long user stays online without activity
+  config.throttle = 60.seconds              # Minimum time between Redis writes per user
+  
+  # User identification
+  config.user_id_method = :id               # Method to get user ID
+  config.current_user_method = :current_user # Method on controllers to get user
+  
+  # Heartbeat (for visible tab tracking)
+  config.heartbeat_interval = 60.seconds    # Heartbeat frequency when tab is visible
+  
+  # Advanced
+  config.namespace = "whoisonline:user"     # Redis key namespace
+  config.auto_hook = true                   # Auto-include controller concern
+  config.logger = Rails.logger             # Logger instance
+end
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `ttl` | `5.minutes` | How long a user stays online without activity |
+| `throttle` | `60.seconds` | Minimum time between Redis writes per user |
+| `heartbeat_interval` | `60.seconds` | Heartbeat frequency when tab is visible |
+| `user_id_method` | `:id` | Method to extract ID from user object |
+| `current_user_method` | `:current_user` | Method name on controllers |
+| `namespace` | `"whoisonline:user"` | Redis key namespace prefix |
+| `auto_hook` | `true` | Auto-include controller concern |
+| `logger` | `Rails.logger` | Logger for errors/warnings |
+
+---
+
+## 💡 Examples
+
+### Basic Usage
+
+```ruby
+# In a controller (automatic via engine)
+# Users are tracked after each action
+
+# Check if user is online
+if WhoIsOnline.online?(current_user)
+  # User is currently online
 end
+
+# Get online users count
+@online_count = WhoIsOnline.count
+
+# Get online users
+@online_users = WhoIsOnline.users(User)
 ```
 
-## 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.
+### Manual Tracking
 
-## Example Usage in Rails
 ```ruby
-# Somewhere in your controller you can also call manually:
+# Manually mark user online
 WhoIsOnline.track(current_user)
 
-# Mark user offline (e.g., on logout)
+# Manually mark user offline (e.g., on logout)
 WhoIsOnline.offline(current_user)
+```
 
-# In a background job
-if WhoIsOnline.online?(user)
-  # notify
-end
+### In Background Jobs
 
-# In a dashboard
-@online_users = WhoIsOnline.users(User).order(last_sign_in_at: :desc)
-@online_count = WhoIsOnline.count
+```ruby
+class NotificationJob < ApplicationJob
+  def perform(user_id)
+    user = User.find(user_id)
+    
+    if WhoIsOnline.online?(user)
+      # Only notify if user is online
+      NotificationService.deliver(user)
+    end
+  end
+end
 ```
 
-### Layout Example
-In your main layout (`app/views/layouts/application.html.erb`):
+### Dashboard View
+
+```ruby
+# In your controller
+class DashboardController < ApplicationController
+  def index
+    @online_count = WhoIsOnline.count
+    @online_users = WhoIsOnline.users(User)
+                              .order(last_sign_in_at: :desc)
+                              .limit(50)
+  end
+end
+```
 
 ```erb
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>My App</title>
-    <%= csrf_meta_tags %>
-  </head>
-  <body>
-    <%= yield %>
-    <%= whoisonline_offline_script %>
-  </body>
-</html>
+<!-- In your view -->
+<div class="online-users">
+  <h2>Online Now (<%= @online_count %>)</h2>
+  <ul>
+    <% @online_users.each do |user| %>
+      <li><%= user.name %> <span class="badge">●</span></li>
+    <% end %>
+  </ul>
+</div>
+```
+
+---
+
+## 🎯 How It Works
+
+1. **Controller Action** - After each action, the engine automatically calls `WhoIsOnline.track(current_user)`
+2. **Redis Write** - User presence is stored in Redis with TTL: `SET whoisonline:user:123 <timestamp> EX 300`
+3. **Throttling** - Writes are throttled per user to prevent Redis spam
+4. **Heartbeat** - When tab is visible, JavaScript sends periodic heartbeats to keep user online
+5. **Offline Detection** - When browser closes, JavaScript sends offline request
+6. **TTL Expiry** - If no activity, Redis key expires automatically
+
+---
+
+## ⚡ Performance
+
+- **O(1) Writes** - Uses `SET key value EX ttl` for constant-time operations
+- **Throttled** - Prevents hot users from spamming Redis
+- **SCAN-Based** - Counting uses `SCAN` instead of `KEYS` (non-blocking)
+- **Namespace Isolation** - Keys are namespaced for easy management
+- **No Database** - Zero database writes, all in Redis
+
+### Recommended Settings
+
+For **high-traffic** applications:
+
+```ruby
+config.ttl = 2.minutes              # Shorter TTL = more accurate
+config.throttle = 30.seconds         # More frequent updates
+config.heartbeat_interval = 30.seconds # More frequent heartbeats
+```
+
+For **low-traffic** applications:
+
+```ruby
+config.ttl = 10.minutes              # Longer TTL = less Redis activity
+config.throttle = 120.seconds        # Less frequent updates
+config.heartbeat_interval = 120.seconds # Less frequent heartbeats
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Users Not Showing as Online
+
+1. Check Redis connection: `redis-cli ping`
+2. Verify `current_user` method exists in your controllers
+3. Check logs for errors: `tail -f log/development.log`
+4. Verify TTL hasn't expired: `redis-cli TTL whoisonline:user:1`
+
+### Helper Not Available
+
+If `whoisonline_offline_script` is not available:
+
+1. Restart Rails server
+2. Check that gem is loaded: `bundle list | grep whoisonline`
+3. Verify engine is loaded: Check `config/application.rb` for engine loading
+
+### Heartbeat Not Working
+
+1. Check browser console for JavaScript errors
+2. Verify CSRF token is present: `<%= csrf_meta_tags %>`
+3. Check network tab for heartbeat requests
+4. Verify `heartbeat_interval` is configured
+
+---
+
+## 🛠️ Extensibility
+
+The gem is designed to be extensible:
+
+- **ActionCable Integration** - Broadcast presence changes
+- **Custom Events** - Hook into track/offline events
+- **Multiple Redis Instances** - Use different Redis for presence
+- **Custom User Models** - Works with any user model structure
+
+Example: ActionCable Integration
+
+```ruby
+# In an initializer
+WhoIsOnline.tracker.define_singleton_method(:track) do |user|
+  super(user)
+  ActionCable.server.broadcast("presence", { user_id: user.id, status: "online" })
+end
 ```
 
-## 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.
+---
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 👤 Author
+
+**Kapil Dev Pal**
+
+- 📧 Email: dev.kapildevpal@gmail.com
+- 🐦 Twitter: [@rails_to_rescue](https://twitter.com/rails_to_rescue)
+- 🚀 Project: [rails_to_rescue](https://github.com/rails-to-rescue)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## ⭐ Show Your Support
+
+If you find this gem useful, please give it a ⭐ on GitHub!
+
+---
+
+<div align="center">
 
-## Author
-- Kapil Dev Pal – dev.kapildevpal@gmail.com / @rails_to_rescue
-- Project: rails_to_rescue
+**Made with ❤️ for the Rails community**
 
+[Report Bug](https://github.com/KapilDevPal/WhoIsOnline/issues) • [Request Feature](https://github.com/KapilDevPal/WhoIsOnline/issues) • [View on GitHub](https://github.com/KapilDevPal/WhoIsOnline)
 
+</div>

data/lib/whoisonline/engine.rb

@@ -21,6 +21,9 @@ module WhoIsOnline
 
     initializer "whoisonline.helpers" do
       ActiveSupport.on_load(:action_view) do
+        # Explicitly require the helper module from app directory
+        helper_path = File.join(Engine.root, "app", "helpers", "whoisonline", "application_helper.rb")
+        require helper_path if File.exist?(helper_path)
         include WhoIsOnline::ApplicationHelper
       end
     end

data/lib/whoisonline/version.rb

@@ -1,5 +1,5 @@
 module WhoIsOnline
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whoisonline
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Kapil Dev Pal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-27 00:00:00.000000000 Z
+date: 2025-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport