newshound 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: decd51fd02b481edd644a56bd700575010ae0b3d747fc2880803c68c32e50bfa
-  data.tar.gz: f44304b8a0f6621296ff13900a2e59ea702b62c08ed6491ad0a60b4839b76b6d
+  metadata.gz: ed2c9eae65ac8681fc1c72890cbd421ca9dd73130c37fa86c04643cb74c03856
+  data.tar.gz: 7ccb875f08607e1478245384376a621243fdd44e40443fb191064210cff94ba6
 SHA512:
-  metadata.gz: 813c1c7d310854f34722819c8321d24438cafd543bf9c4dcf164e90bcf716423953ae0583656fe97476d454342fb8c4dabdfa48b66d886d6adb21abc6466521b
-  data.tar.gz: 6c60ed849cd31e6e08066dc9893c2dcd3d3a82450923d97383717f2c5e21f2ea4943880b73ccce9926cbed83ead51b9cea0b2c08c91ba1fb8b63a6a8fb66e983
+  metadata.gz: a78bd31f883c89116c83b7c77b680faba172b41e0bc3f375e4a81a075503d33860ebd4778e71f11d868a794fe04effd815e240ebd3d5c6135b0ed80599c87469
+  data.tar.gz: 4985d3d128688284f4734391b12e7f6e34d1c69857d713d3995d2078cc4df210b64ca5f84d889841e52b1b3a9086bcf0f19e7d35bef646b60e08020379527ad6

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.3

data/Gemfile

@@ -4,6 +4,12 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
-gem "rubocop", "~> 1.0"
+group :development, :test do
+  gem "bundler", "~> 2.0"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.0"
+  gem "rubocop", "~> 1.0"
+  gem "pg"
+  gem "pry"
+  gem "simplecov", require: false
+end

data/README.md

@@ -1,115 +1,192 @@
 # Newshound 🐕
 
-A Ruby gem that sniffs out exceptions and job statuses in your Rails app and reports them daily to Slack.
+A Ruby gem that displays real-time exceptions and job statuses in a collapsible banner for authorized users in your Rails application.
 
 ## Features
 
-- 📊 Daily Que job status reports (counts by job type, queue health)
-- 🚨 Last 4 exceptions from exception-track
-- 💬 Slack integration via webhook or Web API
-- ⏰ Automatic daily scheduling with que-scheduler
-- 🔧 Configurable report times and limits
+- 🎯 **Real-time Web UI Banner** - Shows exceptions and job statuses at the top of every page
+- 🔐 **Role-Based Access** - Only visible to authorized users (developers, admins, etc.)
+- 📊 **Que Job Monitoring** - Real-time queue health and job status
+- 🚨 **Exception Tracking** - Recent exceptions from exception-track
+- 🎨 **Collapsible UI** - Clean, non-intrusive banner that expands on click
+- ⚡ **Zero Configuration** - Automatically injects into HTML responses
+- 🔧 **Highly Customizable** - Configure roles and authorization logic
 
 ## Installation
 
 Add to your Gemfile:
 
 ```ruby
-gem 'newshound', path: 'path/to/newshound'  # or from git/rubygems when published
+gem 'newshound'
 ```
 
 Then:
 
 ```bash
 bundle install
+rails generate newshound:install
 ```
 
+The generator will create `config/initializers/newshound.rb` with default configuration.
+
 ## Configuration
 
-Create an initializer `config/initializers/newshound.rb`:
+### Basic Configuration
 
 ```ruby
+# config/initializers/newshound.rb
 Newshound.configure do |config|
-  # Slack configuration (choose one method)
-  config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']  # Option 1: Webhook
-  # OR set ENV['SLACK_API_TOKEN'] for Web API          # Option 2: Web API
-  
-  config.slack_channel = "#ops-alerts"     # Default: "#general"
-  config.report_time = "09:00"            # Default: "09:00" (24-hour format)
-  config.exception_limit = 4              # Default: 4 (last N exceptions)
-  config.time_zone = "America/New_York"   # Default: "America/New_York"
-  config.enabled = true                   # Default: true
+  # Enable or disable the banner
+  config.enabled = true
+
+  # Maximum number of exceptions to show in banner
+  config.exception_limit = 10
+
+  # User roles that can view the banner
+  config.authorized_roles = [:developer, :super_user]
+
+  # Method to call to get current user (most apps use :current_user)
+  config.current_user_method = :current_user
+end
+```
+
+### Advanced: Custom Authorization
+
+If the default role-based authorization doesn't fit your needs, you can provide custom logic:
+
+```ruby
+# config/initializers/newshound.rb
+Newshound.authorize_with do |controller|
+  # Your custom authorization logic
+  # Return true to show banner, false to hide
+  user = controller.current_user
+  user&.admin? || user&.developer?
+end
+```
+
+### Example Authorization Scenarios
+
+```ruby
+# Only show in development
+Newshound.authorize_with do |controller|
+  Rails.env.development?
+end
+
+# Check multiple conditions
+Newshound.authorize_with do |controller|
+  user = controller.current_user
+  user.present? &&
+    (user.has_role?(:admin) || user.email.ends_with?('@yourcompany.com'))
+end
+
+# Use your existing authorization system
+Newshound.authorize_with do |controller|
+  controller.current_user&.can?(:view_newshound)
 end
 ```
 
-### Slack Setup
+## How It Works
+
+Newshound uses Rails middleware to automatically inject a banner into HTML responses for authorized users. The banner:
+
+1. ✅ Appears automatically on all HTML pages
+2. 🔒 Only visible to users with authorized roles
+3. 📊 Shows real-time data from your exception and job queues
+4. 🎨 Collapses to save space, expands on click
+5. 🚀 No JavaScript dependencies, pure CSS animations
 
-#### Option 1: Webhook URL (Simpler)
-1. Go to https://api.slack.com/apps
-2. Create a new app or select existing
-3. Enable "Incoming Webhooks"
-4. Add a new webhook for your channel
-5. Copy the webhook URL to your config
+## Banner Content
 
-#### Option 2: Web API Token (More features)
-1. Create a Slack app at https://api.slack.com/apps
-2. Add OAuth scopes: `chat:write`, `chat:write.public`
-3. Install to workspace
-4. Copy the Bot User OAuth Token
-5. Set as `ENV['SLACK_API_TOKEN']`
+The banner displays:
 
-## Usage
+### Exception Section
+- Recent exceptions from exception-track
+- Exception class and message
+- Controller/action where it occurred
+- Timestamp
+- Visual indicators (🟢 all clear / 🔴 errors)
 
-### Automatic Daily Reports
+### Job Queue Section
+- **Ready to Run**: Jobs waiting to execute
+- **Scheduled**: Jobs scheduled for future execution
+- **Failed**: Jobs in retry queue
+- **Completed Today**: Successfully finished jobs
+- Color-coded health status
 
-If you have `que-scheduler` configured, Newshound will automatically schedule daily reports at your configured time.
+## User Requirements
 
-### Manual Reports
+Your User model should have a `role` attribute that matches one of the configured `authorized_roles`. Common patterns:
 
 ```ruby
-# Send report immediately
-Newshound.report!
+# String enum
+class User < ApplicationRecord
+  enum role: { user: 'user', developer: 'developer', admin: 'admin' }
+end
 
-# Or via rake task
-rake newshound:report_now
+# Symbol enum
+class User < ApplicationRecord
+  enum role: { user: 0, developer: 1, super_user: 2 }
+end
+
+# String column
+class User < ApplicationRecord
+  def role
+    @role ||= read_attribute(:role)&.to_sym
+  end
+end
+```
+
+If your User model uses different attribute names, you can customize the authorization logic using `Newshound.authorize_with`.
+
+## Testing
 
-# Enqueue for background processing
-rake newshound:schedule
+### Test Reporters
 
-# Check configuration
+```bash
+# Test exception reporter
+rake newshound:test_exceptions
+
+# Test job queue reporter
+rake newshound:test_jobs
+
+# Show current configuration
 rake newshound:config
 ```
 
-### Integration with que-scheduler
+### Test in Rails Console
 
-Add to your `config/que_schedule.yml`:
-
-```yaml
-newshound_daily_report:
-  class: "Newshound::DailyReportJob"
-  cron: "0 9 * * *"  # 9:00 AM daily
-  queue: default
+```ruby
+# Check if banner would show for a specific user
+user = User.find(123)
+controller = ApplicationController.new
+controller.instance_variable_set(:@current_user, user)
+Newshound::Authorization.authorized?(controller)
+# => true or false
 ```
 
-Or let Newshound auto-configure based on your settings.
+## Troubleshooting
 
-## Report Format
+### Banner not appearing
 
-The daily report includes:
+1. **Check if enabled**: `rake newshound:config`
+2. **Verify user role**: Make sure your user has an authorized role
+3. **Check current_user method**: Ensure your app provides the configured method
+4. **Restart server**: Changes to initializers require a restart
 
-### Exception Section
-- Last 4 exceptions (configurable)
-- Exception class, message, controller/action
-- Count of same exception type in last 24 hours
-- Timestamp
+### No exceptions showing
+
+- Ensure `exception-track` gem is installed and logging exceptions
+- Check that exceptions exist: `rake newshound:test_exceptions`
+
+### No job data
+
+- Verify Que is configured and `que_jobs` table exists
+- Check job data: `rake newshound:test_jobs`
+
+### Banner appears for wrong users
 
-### Que Jobs Section
-- Job counts by type (success/failed/total)
-- Queue health status
-- Ready to run count
-- Scheduled jobs count
-- Failed jobs in retry queue
-- Jobs completed today
+- Review `authorized_roles` configuration
+- Consider using custom authorization with `Newshound.authorize_with`
 
 ## Development
 
@@ -124,20 +201,22 @@ bundle exec rubocop
 bin/console
 ```
 
-## Testing in Your App
+## Dependencies
 
-```ruby
-# In rails console
-Newshound.configuration.slack_webhook_url = "your-webhook"
-Newshound.report!  # Should post to Slack immediately
-```
+- **Rails** >= 6.0
+- **que** >= 1.0 (for job monitoring)
+- **exception-track** >= 0.1 (for exception tracking)
 
-## Troubleshooting
+## Upgrading from 0.1.x
+
+If you were using the previous Slack-based version:
+
+1. Remove Slack/SNS configuration from your initializer
+2. Remove `que-scheduler` if only used for Newshound
+3. Update to new configuration format (see above)
+4. Restart your Rails server
 
-- **No reports sent**: Check `rake newshound:config` to verify configuration
-- **No exceptions showing**: Ensure `exception-track` gem is installed and logging
-- **No job data**: Verify Que is configured and `que_jobs` table exists
-- **Slack not receiving**: Verify webhook URL or API token is correct
+The banner will now appear automatically for authorized users instead of sending Slack notifications.
 
 ## License
 

data/TRANSPORT_USAGE.md

@@ -0,0 +1,117 @@
+# Transport Layer Usage
+
+The Newshound gem now supports multiple transport adapters for sending notifications. You can choose between Slack (direct) and Amazon SNS based on your environment needs.
+
+## Configuration
+
+### Using Slack Transport (Default)
+
+```ruby
+# config/initializers/newshound.rb
+Newshound.configure do |config|
+  config.transport_adapter = :slack  # This is the default
+  config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
+  config.slack_channel = '#your-channel'
+  # ... other configurations
+end
+```
+
+### Using SNS Transport
+
+```ruby
+# config/initializers/newshound.rb
+Newshound.configure do |config|
+  config.transport_adapter = :sns
+  config.sns_topic_arn = ENV['SNS_TOPIC_ARN']
+  config.aws_region = ENV['AWS_REGION'] || 'us-east-1'
+
+  # Optional: Provide AWS credentials explicitly
+  # If not provided, will use default AWS credential chain
+  config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID']
+  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+
+  # ... other configurations
+end
+```
+
+### Environment-based Configuration
+
+You can switch transport based on environment:
+
+```ruby
+# config/initializers/newshound.rb
+Newshound.configure do |config|
+  if Rails.env.production?
+    # Use SNS in production to route through AWS infrastructure
+    config.transport_adapter = :sns
+    config.sns_topic_arn = ENV['SNS_TOPIC_ARN']
+    config.aws_region = ENV['AWS_REGION']
+  else
+    # Use direct Slack in development/staging
+    config.transport_adapter = :slack
+    config.slack_webhook_url = ENV['SLACK_WEBHOOK_URL']
+    config.slack_channel = '#dev-notifications'
+  end
+
+  # Common configurations
+  config.report_time = "09:00"
+  config.exception_limit = 4
+  config.time_zone = "America/New_York"
+end
+```
+
+## Custom Transport Adapters
+
+You can also create your own transport adapter:
+
+```ruby
+class MyCustomTransport < Newshound::Transport::Base
+  def deliver(message)
+    # Your custom delivery logic here
+    # Return true on success, false on failure
+
+    # Example: Send to custom API endpoint
+    response = HTTParty.post(
+      'https://api.example.com/notifications',
+      body: message.to_json,
+      headers: { 'Content-Type' => 'application/json' }
+    )
+
+    response.success?
+  rescue StandardError => e
+    logger.error "Failed to deliver: #{e.message}"
+    false
+  end
+end
+
+# Use the custom transport
+Newshound.configure do |config|
+  config.transport_adapter = MyCustomTransport
+  # ... other configurations
+end
+```
+
+## AWS SNS Setup
+
+If using SNS transport, ensure you have:
+
+1. Created an SNS topic in AWS
+2. Subscribed your Slack webhook URL to the SNS topic
+3. Configured proper IAM permissions for publishing to the topic
+4. Installed the aws-sdk-sns gem (it's optional):
+
+```ruby
+# Add to your Gemfile if using SNS
+gem 'aws-sdk-sns', '~> 1.0'
+```
+
+## Testing
+
+The transport layer is fully testable. You can inject mock transports in your tests:
+
+```ruby
+# In your tests
+mock_transport = double('Transport', deliver: true)
+notifier = Newshound::SlackNotifier.new(transport: mock_transport)
+notifier.post({ text: "Test message" })
+```

data/lib/generators/newshound/install/install_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Newshound
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Configures Newshound for your Rails application"
+
+      def create_initializer
+        template "newshound.rb", "config/initializers/newshound.rb"
+      end
+
+      def display_post_install_message
+        say ""
+        say "===============================================================================", :green
+        say "  Newshound has been successfully installed!", :green
+        say ""
+        say "  Next steps:", :yellow
+        say "  1. Configure authorized roles in config/initializers/newshound.rb"
+        say "  2. Make sure your User model has a role attribute (or customize authorization)"
+        say "  3. Restart your Rails server"
+        say ""
+        say "  The Newshound banner will automatically appear at the top of pages for"
+        say "  authorized users (developers and super_users by default)."
+        say ""
+        say "  To test the reporters, run:", :cyan
+        say "    rake newshound:test_exceptions"
+        say "    rake newshound:test_jobs"
+        say ""
+        say "  For more information, visit:", :blue
+        say "    https://github.com/salbanez/newshound"
+        say "===============================================================================", :green
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/newshound/install/templates/newshound.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+Newshound.configure do |config|
+  # Enable or disable Newshound completely
+  # When enabled, the banner will be shown to authorized users
+  # Default is true
+  config.enabled = true
+
+  # Maximum number of exceptions to include in banner
+  # Default is 10
+  config.exception_limit = 10
+
+  # User roles that are authorized to view the Newshound banner
+  # These should match the role values in your User model
+  # Default is [:developer, :super_user]
+  config.authorized_roles = [:developer, :super_user]
+
+  # Method name to call to get the current user
+  # Most apps use :current_user (Devise, etc.)
+  # Default is :current_user
+  config.current_user_method = :current_user
+end
+
+# Advanced: Custom authorization logic
+# If the default role-based authorization doesn't fit your needs,
+# you can provide a custom authorization block:
+#
+# Newshound.authorize_with do |controller|
+#   # Your custom logic here
+#   # Return true to show the banner, false to hide it
+#   controller.current_user&.admin?
+# end

data/lib/newshound/authorization.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Newshound
+  module Authorization
+    class << self
+      # Check if the current user/controller is authorized to view Newshound data
+      def authorized?(controller)
+        return false unless Newshound.configuration.enabled
+
+        # Use custom authorization block if provided
+        if Newshound.configuration.authorization_block
+          return Newshound.configuration.authorization_block.call(controller)
+        end
+
+        # Default authorization: check if current_user has an authorized role
+        user = current_user_from(controller)
+        return false unless user
+
+        user_role = user_role_from(user)
+        return false unless user_role
+
+        Newshound.configuration.authorized_roles.include?(user_role.to_sym)
+      end
+
+      private
+
+      def current_user_from(controller)
+        method_name = Newshound.configuration.current_user_method
+        return nil unless controller.respond_to?(method_name)
+
+        controller.send(method_name)
+      end
+
+      def user_role_from(user)
+        return nil unless user
+
+        # Try common role attribute names
+        [:role, :user_role, :type].each do |attr|
+          return user.send(attr) if user.respond_to?(attr)
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/newshound/configuration.rb

@@ -2,23 +2,24 @@
 
 module Newshound
   class Configuration
-    attr_accessor :slack_webhook_url, :slack_channel, :report_time,
-                  :exception_limit, :time_zone, :enabled
+    attr_accessor :exception_limit, :enabled, :authorized_roles,
+                  :current_user_method, :authorization_block
 
     def initialize
-      @slack_webhook_url = nil
-      @slack_channel = "#general"
-      @report_time = "09:00"
-      @exception_limit = 4
-      @time_zone = "America/New_York"
+      @exception_limit = 10
       @enabled = true
+      @authorized_roles = [:developer, :super_user]
+      @current_user_method = :current_user
+      @authorization_block = nil
+    end
+
+    # Allow custom authorization logic
+    def authorize_with(&block)
+      @authorization_block = block
     end
 
     def valid?
-      return false unless enabled
-      return false if slack_webhook_url.nil? || slack_webhook_url.empty?
-      
-      true
+      enabled
     end
   end
 end

data/lib/newshound/exception_reporter.rb

@@ -2,9 +2,17 @@
 
 module Newshound
   class ExceptionReporter
+    attr_reader :exception_source, :configuration, :time_range
+
+    def initialize(exception_source: nil, configuration: nil, time_range: 24.hours)
+      @exception_source = exception_source || (defined?(ExceptionTrack::Log) ? ExceptionTrack::Log : nil)
+      @configuration = configuration || Newshound.configuration
+      @time_range = time_range
+    end
+
     def generate_report
       return no_exceptions_block if recent_exceptions.empty?
-      
+
       [
         {
           type: "section",
@@ -24,12 +32,12 @@ module Newshound
     end
 
     def fetch_recent_exceptions
-      return [] unless defined?(ExceptionTrack::Log)
-      
-      ExceptionTrack::Log
-        .where("created_at >= ?", 24.hours.ago)
+      return [] unless exception_source
+
+      exception_source
+        .where("created_at >= ?", time_range.ago)
         .order(created_at: :desc)
-        .limit(Newshound.configuration.exception_limit)
+        .limit(configuration.exception_limit)
     end
 
     def format_exceptions
@@ -62,9 +70,11 @@ module Newshound
     end
 
     def exception_count(exception)
-      ExceptionTrack::Log
+      return 0 unless exception_source
+
+      exception_source
         .where(exception_class: exception.exception_class)
-        .where("created_at >= ?", 24.hours.ago)
+        .where("created_at >= ?", time_range.ago)
         .count
     end