findbug 0.3.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b51dae70712a19753e3c702d669ad052997bdbd92fdbb5a1906dfe7a4739eb3d
-  data.tar.gz: ece16e26f2e64f87262172768cb577a7d9344c85039992acc7809f372c146173
+  metadata.gz: bc983a190a0ac08221e7bbaf108e52d55ecc20a28712f5bdf380acf61a27e43d
+  data.tar.gz: 77bc4565c0686c4d60646b4e7d9dc65f4faae482c83d8df6b98a4c02f540c162
 SHA512:
-  metadata.gz: 8637ab43bfd03606bceee3fc7eb955af65f2db8300b39b07848beed6106677efc82fb8bc3931c12368c525d502d7c708a5e006b31fdcc4f2816ba644a546f8df
-  data.tar.gz: 8a24d784569793cdbabe425af6ca3c7b1740e7b64a30ec2f59f059adfce927faccc52bdc40e3f9f6c5037136987c1ff9d7f9bba9b585f506da63ede93fa7b63a
+  metadata.gz: c6d0d26042c62b4ea65bd5f574e6c43d588fdfa83914b416a44638dae85c97d3fa12d74d4ffa6bb08b8575d96daa11ed87aeaefc314ee319353cb4acf961a0d6
+  data.tar.gz: 3d8ef1a2aece7c33efb7b629aa5b19013fe96da2b6ec3ec741eba8447b2fa80b36a5c3b6f1be926c4f19cda0ff44388eebc0a6eede1ce42d4e5fe199b448a5b2

data/README.md

@@ -8,16 +8,20 @@
 
 FindBug provides Sentry-like functionality with all data stored on your own infrastructure using Redis and your database. Zero external dependencies, full data ownership.
 
+📚 **Full documentation:** [findbug.dev/docs](https://findbug.dev/docs)
+
 ## Features
 
 - **Error Tracking** - Capture exceptions with full context, stack traces, and request data
 - **Performance Monitoring** - Track request timing, SQL queries, and automatic N+1 detection
-- **Self-Hosted** - All data stays on your infrastructure (Redis + PostgreSQL/MySQL)
+- **Self-Hosted** - All data stays on your infrastructure (Redis + your existing database)
+- **Database-Agnostic** - Works on PostgreSQL, MySQL, and SQLite — adapter detected automatically
 - **Zero Performance Impact** - Async writes via Redis buffer, never blocks your requests
 - **Built-in Dashboard** - Beautiful web UI for viewing errors and performance metrics
 - **Multi-channel Alerts** - Email, Slack, Discord, and custom webhooks
 - **Works Out of the Box** - Built-in background persister, no job scheduler required
 - **Rails 7+ Native** - Designed for modern Rails applications
+- **Tested** - Comprehensive RSpec suite covering every adapter path
 
 ## Why FindBug?
 
@@ -34,7 +38,7 @@ FindBug provides Sentry-like functionality with all data stored on your own infr
 - Ruby 3.1+
 - Rails 7.0+
 - Redis 4.0+
-- PostgreSQL or MySQL
+- A relational database — PostgreSQL, MySQL, or SQLite
 
 ## Installation
 
@@ -142,34 +146,11 @@ Findbug.configure do |config|
   # ===================
   # Alerts (Optional)
   # ===================
+  # Alert channels (Email, Slack, Discord, Webhook) are configured via the
+  # dashboard UI at /findbug/alerts — no code changes needed.
+
   config.alerts do |alerts|
     alerts.throttle_period = 5.minutes
-
-    # Slack
-    # alerts.slack(
-    #   enabled: true,
-    #   webhook_url: ENV["SLACK_WEBHOOK_URL"],
-    #   channel: "#errors"
-    # )
-
-    # Email
-    # alerts.email(
-    #   enabled: true,
-    #   recipients: ["team@example.com"]
-    # )
-
-    # Discord
-    # alerts.discord(
-    #   enabled: true,
-    #   webhook_url: ENV["DISCORD_WEBHOOK_URL"]
-    # )
-
-    # Custom Webhook
-    # alerts.webhook(
-    #   enabled: true,
-    #   url: "https://your-service.com/webhook",
-    #   headers: { "Authorization" => "Bearer token" }
-    # )
   end
 end
 ```
@@ -263,7 +244,7 @@ end
 │                                         └────────┬─────────┘   │
 │                                                  │              │
 │                                                  ▼              │
-│  Dashboard ◄──────────────────── Database (PostgreSQL/MySQL)   │
+│  Dashboard ◄──────────────────── Database (PostgreSQL/MySQL/SQLite) │
 │  (/findbug)                                                     │
 │                                                                 │
 └─────────────────────────────────────────────────────────────────┘
@@ -297,11 +278,44 @@ rails findbug:clear_buffers
 rails findbug:db:stats
 ```
 
-## Multi-Tenant Applications (Apartment/ros-apartment)
+## Database Support
+
+As of v0.5.0 FindBug is database-agnostic. The install generator's migrations and the model layer detect your `ActiveRecord::Base.connection.adapter_name` at runtime and pick the right column types and SQL functions automatically.
+
+| Adapter            | JSON column | Time bucketing SQL                 |
+|--------------------|-------------|------------------------------------|
+| PostgreSQL/PostGIS | `jsonb`     | `date_trunc(...)`                  |
+| MySQL/Mysql2       | `json`      | `DATE_FORMAT(...)` / `DATE(...)`   |
+| SQLite             | `text` (with JSON serialisation in the model) | `strftime(...)` / `DATE(...)` |
+
+The JSON accessors on the models normalise reads to a native Ruby `Hash` / `Array` regardless of the underlying column type, so your application code is identical across adapters.
+
+If you're writing your own migrations against the same multi-DB strategy, the `Findbug::AdapterHelper` module is part of the public API:
+
+```ruby
+Findbug::AdapterHelper.json_column_type      # :jsonb / :json / :text
+Findbug::AdapterHelper.json_default({})      # adapter-appropriate default
+Findbug::AdapterHelper.date_trunc_sql("hour", "captured_at")
+```
+
+## Multi-Tenant Applications
+
+Multi-tenant Rails apps are supported, but the setup depends on *how* your app isolates tenants. The matrix below shows what's possible per adapter:
+
+| Adapter                  | Tenancy model                                                | FindBug support                                                                  |
+|--------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------|
+| PostgreSQL               | Schema-per-tenant (Apartment's default)                      | ✅ First-class — keep FindBug tables in the `public` schema (see below).         |
+| PostgreSQL/MySQL/SQLite  | Row-level (`tenant_id` column)                               | ✅ Nothing special — FindBug's tables aren't tenant-scoped.                      |
+| MySQL                    | Database-per-tenant (Apartment with `use_schemas = false`)   | ⚠️ Doable but awkward — point FindBug at a separate connection via `connects_to`. |
+| SQLite                   | File-per-tenant                                              | ❌ Not practical — use row-level scoping instead.                                |
+
+For the full discussion (including MySQL setup options), see the [Multi-tenant section in the docs](https://findbug.dev/docs#multi-tenant).
+
+### PostgreSQL + Apartment (schema-per-tenant)
 
-If you're using [ros-apartment](https://github.com/rails-on-services/apartment) or similar multi-tenant gems with PostgreSQL schemas, FindBug's tables need to stay in the public schema and the dashboard path should be excluded from tenant switching.
+If you're using [ros-apartment](https://github.com/rails-on-services/apartment) with PostgreSQL schemas, FindBug's tables need to stay in the public schema and the dashboard path should be excluded from tenant switching.
 
-### 1. Exclude FindBug Models
+#### 1. Exclude FindBug Models
 
 Add FindBug models to the `excluded_models` list in `config/initializers/apartment.rb`:
 
@@ -311,11 +325,12 @@ Apartment.configure do |config|
     # Your existing excluded models...
     Findbug::ErrorEvent
     Findbug::PerformanceEvent
+    Findbug::AlertChannel
   ]
 end
 ```
 
-### 2. Exclude FindBug Dashboard Path
+#### 2. Exclude FindBug Dashboard Path
 
 Add `/findbug` to your tenant switching middleware's excluded paths:
 
@@ -339,7 +354,7 @@ class SwitchTenantMiddleware < Apartment::Elevators::Generic
 end
 ```
 
-### 3. Run Migrations in Public Schema
+#### 3. Run Migrations in Public Schema
 
 Ensure FindBug migrations run in the public schema:
 

data/app/controllers/findbug/alerts_controller.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module Findbug
+  # AlertsController manages alert channel configuration via the dashboard.
+  #
+  # Users can create, edit, enable/disable, delete, and test alert channels
+  # directly from the UI instead of editing the Rails initializer.
+  #
+  class AlertsController < ApplicationController
+    before_action :set_alert_channel, only: [:edit, :update, :destroy, :toggle, :test]
+
+    # GET /findbug/alerts
+    #
+    # List all configured alert channels.
+    #
+    def index
+      @channels = Findbug::AlertChannel.order(created_at: :asc)
+      @enabled_count = @channels.count(&:enabled?)
+
+      render template: "findbug/alerts/index", layout: "findbug/application"
+    end
+
+    # GET /findbug/alerts/new
+    #
+    # Form to create a new alert channel.
+    #
+    def new
+      @channel = Findbug::AlertChannel.new
+      render template: "findbug/alerts/new", layout: "findbug/application"
+    end
+
+    # POST /findbug/alerts
+    #
+    # Save a new alert channel.
+    #
+    def create
+      @channel = Findbug::AlertChannel.new(channel_params)
+      @channel.config = build_config_from_params
+
+      if @channel.save
+        flash_success "#{@channel.display_type} alert channel created"
+        redirect_to findbug.alerts_path
+      else
+        flash_error @channel.errors.full_messages.join(", ")
+        render template: "findbug/alerts/new", layout: "findbug/application", status: :unprocessable_entity
+      end
+    end
+
+    # GET /findbug/alerts/:id/edit
+    #
+    # Form to edit an existing alert channel.
+    #
+    def edit
+      render template: "findbug/alerts/edit", layout: "findbug/application"
+    end
+
+    # PATCH /findbug/alerts/:id
+    #
+    # Update an existing alert channel.
+    #
+    def update
+      @channel.assign_attributes(channel_params)
+      @channel.config = build_config_from_params
+
+      if @channel.save
+        flash_success "#{@channel.display_type} alert channel updated"
+        redirect_to findbug.alerts_path
+      else
+        flash_error @channel.errors.full_messages.join(", ")
+        render template: "findbug/alerts/edit", layout: "findbug/application", status: :unprocessable_entity
+      end
+    end
+
+    # DELETE /findbug/alerts/:id
+    #
+    # Delete an alert channel.
+    #
+    def destroy
+      name = @channel.name
+      @channel.destroy
+      flash_success "Alert channel \"#{name}\" deleted"
+      redirect_to findbug.alerts_path
+    end
+
+    # POST /findbug/alerts/:id/toggle
+    #
+    # Toggle enable/disable for an alert channel.
+    #
+    def toggle
+      @channel.enabled = !@channel.enabled?
+
+      if @channel.save
+        status = @channel.enabled? ? "enabled" : "disabled"
+        flash_success "#{@channel.name} #{status}"
+      else
+        flash_error @channel.errors.full_messages.join(", ")
+      end
+
+      redirect_to findbug.alerts_path
+    end
+
+    # POST /findbug/alerts/:id/test
+    #
+    # Send a test alert to this channel.
+    #
+    # Creates a synthetic error event (not persisted to DB) and sends it
+    # directly to the channel, bypassing throttling.
+    #
+    def test
+      unless @channel.enabled?
+        flash_error "Cannot test a disabled channel. Enable it first."
+        redirect_to findbug.alerts_path and return
+      end
+
+      error_event = build_test_error_event
+      channel_instance = @channel.channel_class.new(@channel.config.symbolize_keys)
+
+      begin
+        channel_instance.send_alert(error_event)
+        flash_success "Test alert sent to #{@channel.name} successfully!"
+      rescue StandardError => e
+        flash_error "Failed to send test alert: #{e.message}"
+      end
+
+      redirect_to findbug.alerts_path
+    end
+
+    private
+
+    def set_alert_channel
+      @channel = Findbug::AlertChannel.find(params[:id])
+    end
+
+    def channel_params
+      params.require(:alert_channel).permit(:name, :channel_type, :enabled)
+    end
+
+    # Build the config hash from channel-type-specific form params
+    #
+    # Each channel type has different fields. We extract them from
+    # params[:config] and build a clean hash.
+    #
+    def build_config_from_params
+      config_params = params[:config] || {}
+      channel_type = params.dig(:alert_channel, :channel_type) || @channel&.channel_type
+
+      case channel_type
+      when "email"
+        recipients = (config_params[:recipients] || "").split(/[\n,]/).map(&:strip).compact_blank
+        {
+          "recipients" => recipients,
+          "from" => config_params[:from].presence
+        }.compact
+      when "slack"
+        {
+          "webhook_url" => config_params[:webhook_url],
+          "channel" => config_params[:channel].presence,
+          "username" => config_params[:username].presence,
+          "icon_emoji" => config_params[:icon_emoji].presence
+        }.compact
+      when "discord"
+        {
+          "webhook_url" => config_params[:webhook_url],
+          "username" => config_params[:username].presence,
+          "avatar_url" => config_params[:avatar_url].presence
+        }.compact
+      when "webhook"
+        headers = parse_headers(config_params[:headers])
+        {
+          "url" => config_params[:url],
+          "method" => config_params[:method].presence || "POST",
+          "headers" => headers.presence
+        }.compact
+      else
+        {}
+      end
+    end
+
+    # Parse headers from textarea format ("Key: Value" per line) into a hash
+    def parse_headers(raw)
+      return {} if raw.blank?
+
+      raw.split("\n").each_with_object({}) do |line, hash|
+        key, value = line.split(":", 2).map(&:strip)
+        hash[key] = value if key.present? && value.present?
+      end
+    end
+
+    # Build a synthetic error event for testing alerts
+    #
+    # Uses OpenStruct to duck-type ErrorEvent without touching the database.
+    # Includes all attributes that channel implementations access.
+    #
+    def build_test_error_event
+      now = Time.current
+
+      OpenStruct.new(
+        id: 0,
+        fingerprint: "findbug-test-alert-#{now.to_i}",
+        exception_class: "Findbug::TestAlert",
+        message: "This is a test alert from the Findbug dashboard. If you see this, your alert channel is working correctly!",
+        severity: "error",
+        status: "unresolved",
+        handled: false,
+        occurrence_count: 1,
+        first_seen_at: now,
+        last_seen_at: now,
+        environment: Findbug.config.environment || "production",
+        release_version: Findbug::VERSION,
+        backtrace_lines: [
+          "app/controllers/findbug/alerts_controller.rb:42:in `test'",
+          "lib/findbug/alerts/dispatcher.rb:57:in `send_alerts'",
+          "lib/findbug/alerts/channels/base.rb:34:in `send_alert'"
+        ],
+        context: {},
+        user: nil,
+        request: { "method" => "POST", "path" => "/findbug/alerts/test" },
+        tags: { "source" => "test_alert" }
+      )
+    end
+  end
+end

data/app/models/findbug/alert_channel.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "../../../lib/findbug/alerts/channels/base"
+require_relative "../../../lib/findbug/alerts/channels/email"
+require_relative "../../../lib/findbug/alerts/channels/slack"
+require_relative "../../../lib/findbug/alerts/channels/discord"
+require_relative "../../../lib/findbug/alerts/channels/webhook"
+
+module Findbug
+  # AlertChannel stores alert channel configurations in the database.
+  #
+  # DATABASE SCHEMA
+  # ===============
+  #
+  # This model expects a table created by the install generator:
+  #
+  #   create_table :findbug_alert_channels do |t|
+  #     t.string :channel_type, null: false
+  #     t.string :name, null: false
+  #     t.boolean :enabled, default: false
+  #     t.text :config_data
+  #     t.timestamps
+  #   end
+  #
+  # WHY DB INSTEAD OF INITIALIZER?
+  # ==============================
+  #
+  # Storing alert config in the database lets users create, edit, and
+  # manage alert channels from the dashboard UI without code changes
+  # or redeployment.
+  #
+  # WHY TEXT + SERIALIZE INSTEAD OF JSONB?
+  # ======================================
+  #
+  # ActiveRecord::Encryption works on text columns. We serialize the
+  # config hash as JSON and encrypt the entire blob at rest, so webhook
+  # URLs and tokens are never stored in plain text.
+  #
+  class AlertChannel < ActiveRecord::Base
+    self.table_name = "findbug_alert_channels"
+
+    # Channel types
+    CHANNEL_TYPES = %w[email slack discord webhook].freeze
+
+    # Check if Rails encryption is configured
+    def self.encryption_available?
+      return false unless defined?(ActiveRecord::Encryption)
+
+      ActiveRecord::Encryption.config.primary_key.present?
+    rescue StandardError
+      false
+    end
+
+    # Serialize config as JSON
+    serialize :config_data, coder: JSON
+
+    # Encrypt config at rest if Rails encryption is configured
+    encrypts :config_data if encryption_available?
+
+    # Validations
+    validates :name, presence: true
+    validates :channel_type, presence: true, inclusion: { in: CHANNEL_TYPES }
+    validate :validate_required_config
+
+    # Scopes
+    scope :enabled, -> { where(enabled: true) }
+    scope :by_type, ->(type) { where(channel_type: type) }
+
+    # Convenience accessor for config
+    def config
+      config_data || {}
+    end
+
+    def config=(value)
+      self.config_data = value
+    end
+
+    # Returns the channel class for sending alerts
+    #
+    # Maps channel_type to the corresponding Alerts::Channels class.
+    #
+    def channel_class
+      case channel_type
+      when "email"   then Findbug::Alerts::Channels::Email
+      when "slack"   then Findbug::Alerts::Channels::Slack
+      when "discord" then Findbug::Alerts::Channels::Discord
+      when "webhook" then Findbug::Alerts::Channels::Webhook
+      end
+    end
+
+    # Human-readable channel type
+    def display_type
+      channel_type&.titleize
+    end
+
+    # Returns config with sensitive values masked for display
+    #
+    # Shows scheme + host for URLs, masks everything else.
+    # Email recipients are shown in full (not sensitive).
+    #
+    def masked_config
+      masked = {}
+
+      case channel_type
+      when "email"
+        masked["Recipients"] = Array(config["recipients"]).join(", ").presence || "None"
+        masked["From"] = config["from"] || "findbug@localhost"
+      when "slack"
+        masked["Webhook URL"] = mask_url(config["webhook_url"])
+        masked["Channel"] = config["channel"] || "Default"
+        masked["Username"] = config["username"] || "Findbug"
+      when "discord"
+        masked["Webhook URL"] = mask_url(config["webhook_url"])
+        masked["Username"] = config["username"] || "Findbug"
+      when "webhook"
+        masked["URL"] = mask_url(config["url"])
+        masked["Method"] = (config["method"] || "POST").upcase
+        headers_count = (config["headers"] || {}).size
+        masked["Custom Headers"] = "#{headers_count} configured" if headers_count > 0
+      end
+
+      masked
+    end
+
+    private
+
+    # Mask a URL for safe display
+    #
+    # Shows scheme + host but masks the path (which typically contains
+    # secret tokens in webhook URLs).
+    #
+    def mask_url(url)
+      return "Not configured" if url.blank?
+
+      uri = URI.parse(url)
+      path = uri.path.to_s
+      masked_path = path.length > 8 ? "#{path[0..7]}********" : "********"
+      "#{uri.scheme}://#{uri.host}#{masked_path}"
+    rescue URI::InvalidURIError
+      "#{url[0..15]}********"
+    end
+
+    # Validate that required config fields are present for each channel type
+    def validate_required_config
+      return if config.blank? && !enabled?
+
+      case channel_type
+      when "email"
+        if enabled? && Array(config["recipients"]).compact_blank.empty?
+          errors.add(:base, "Email channel requires at least one recipient")
+        end
+      when "slack"
+        if enabled? && config["webhook_url"].blank?
+          errors.add(:base, "Slack channel requires a webhook URL")
+        end
+      when "discord"
+        if enabled? && config["webhook_url"].blank?
+          errors.add(:base, "Discord channel requires a webhook URL")
+        end
+      when "webhook"
+        if enabled? && config["url"].blank?
+          errors.add(:base, "Webhook channel requires a URL")
+        end
+      end
+    end
+  end
+end

data/app/models/findbug/error_event.rb

@@ -27,14 +27,15 @@ module Findbug
   #     t.timestamps
   #   end
   #
-  # WHY JSONB FOR CONTEXT?
-  # ======================
+  # WHY OVERRIDE JSON ACCESSORS?
+  # =============================
   #
-  # Context is semi-structured - different errors have different context.
-  # JSONB (in PostgreSQL) or JSON (in other DBs) lets us store any shape
-  # of data without schema migrations.
+  # The column type for context/request_data varies by adapter:
+  #   PostgreSQL → jsonb  (AR returns Hash natively)
+  #   MySQL      → json   (AR returns Hash natively)
+  #   SQLite     → text   (AR returns raw JSON String)
   #
-  # For querying, we create GIN indexes on commonly queried paths.
+  # The overrides below normalise both cases so callers always get a Hash.
   #
   class ErrorEvent < ActiveRecord::Base
     self.table_name = "findbug_error_events"
@@ -55,6 +56,33 @@ module Findbug
     validates :status, inclusion: { in: [STATUS_UNRESOLVED, STATUS_RESOLVED, STATUS_IGNORED] }
     validates :severity, inclusion: { in: [SEVERITY_ERROR, SEVERITY_WARNING, SEVERITY_INFO] }
 
+    # JSON field accessors — normalise across adapters (jsonb/json/text).
+    # Reader always returns a Hash; writer stores a JSON string on text columns
+    # and the native object on json/jsonb columns.
+    %i[context request_data].each do |field|
+      define_method(field) do
+        val = read_attribute(field)
+        return {} if val.nil?
+        val.is_a?(String) ? JSON.parse(val) : val
+      rescue JSON::ParserError
+        {}
+      end
+
+      define_method(:"#{field}=") do |val|
+        col_type = self.class.columns_hash[field.to_s]&.type
+        if col_type == :text
+          serialized = case val
+                       when nil    then nil
+                       when String then val
+                       else             val.to_json
+                       end
+          write_attribute(field, serialized)
+        else
+          write_attribute(field, val)
+        end
+      end
+    end
+
     # Scopes
     scope :unresolved, -> { where(status: STATUS_UNRESOLVED) }
     scope :resolved, -> { where(status: STATUS_RESOLVED) }