errmine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8cb0080b9e4a44a6e2003052e2363ffff60518821efa97420ab16b5dd53083bc
+  data.tar.gz: d5db59abdf0c8d23b1aaa2e7b009ff21efaaf21bea63c702b535e45e000c7ca2
+SHA512:
+  metadata.gz: 10d3e4c4db4f7559fe0971f81cab347aec5f867eea1b39efdb98816fc0c0a595d8c6a774b3f1c20accb073e24b7c6bbbc9c5cede8362231fd627f3e907ef97c6
+  data.tar.gz: ff53f1241f18c703a647bb9dc3e1fc8cb7a82f5b652bbb08b4573d5376dc85271f3f280eddee7e057c44ae1512a633025fb117b2b13e3b6427b83705d1c03a85

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Errmine changelog
+
+## 0.1.0 (2025-12-23)
+
+Initial release of Errmine - dead simple exception tracking for Redmine.
+
+- [Feature] Automatic exception tracking to Redmine via REST API.
+- [Feature] Issue deduplication using 8-character MD5 checksums based on exception class, message, and first application backtrace line.
+- [Feature] Occurrence counter in issue subject (`[checksum][count] ExceptionClass: message`).
+- [Feature] Rate limiting with configurable cooldown to prevent Redmine flooding.
+- [Feature] Rails 7+ Error Reporting API integration via Railtie.
+- [Feature] Rack middleware for exception handling in all Ruby web applications.
+- [Feature] Manual notification API with custom context support.
+- [Feature] Environment variable configuration (`ERRMINE_REDMINE_URL`, `ERRMINE_API_KEY`, `ERRMINE_PROJECT`, `ERRMINE_APP_NAME`).
+- [Feature] Thread-safe in-memory cache with automatic cleanup.
+- [Feature] Fail-safe error handling - never crashes your application.
+- [Feature] Zero runtime dependencies - uses only Ruby stdlib.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Maciej Mensfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,252 @@
+<p align="center">
+  <img src="misc/logo.png" alt="Errmine" width="600"/>
+</p>
+
+# Errmine
+
+[![Build Status](https://github.com/mensfeld/errmine/workflows/ci/badge.svg)](https://github.com/mensfeld/errmine/actions?query=workflow%3Aci)
+[![Gem Version](https://badge.fury.io/rb/errmine.svg)](http://badge.fury.io/rb/errmine)
+
+Dead simple, zero-dependency exception tracking for Redmine.
+
+Errmine automatically creates and updates Redmine issues from Ruby/Rails exceptions. When an error occurs, it creates a new issue. When the same error occurs again, it increments a counter and adds a journal note instead of creating duplicates.
+
+```
+[a1b2c3d4][47] NoMethodError: undefined method 'foo' for nil...
+```
+
+## Why Errmine?
+
+If you already use Redmine for project management, Errmine lets you track production errors without adding another service to your stack.
+
+**vs. Sentry, Honeybadger, Airbrake, etc.**
+- No external service, no monthly fees, no data leaving your infrastructure
+- Errors live alongside your tasks and documentation in Redmine
+- No new UI to learn - just Redmine issues
+
+**vs. Exception Notification gem**
+- Automatic deduplication - same error updates existing issue instead of creating duplicates
+- Rate limiting prevents inbox/Redmine flooding during error storms
+- Occurrence counting shows error frequency at a glance
+
+**vs. Rolling your own**
+- Zero dependencies - uses only Ruby stdlib
+- Handles edge cases: rate limiting, timeouts, thread safety, fail-safe error handling
+- Works out of the box with Rails 7+ Error Reporting API
+
+## Features
+
+- **Zero dependencies** - Uses only Ruby stdlib (net/http, json, digest, uri)
+- **Automatic deduplication** - Same errors update existing issues instead of creating duplicates
+- **Rate limiting** - Prevents flooding Redmine during error loops
+- **Rails integration** - Works with Rails 7+ Error Reporting API or as Rack middleware
+- **Thread-safe** - Safe to use in multi-threaded environments
+- **Fail-safe** - Never crashes your application, logs errors to stderr
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'errmine'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+### Environment Variables
+
+Errmine reads these environment variables as defaults:
+
+- `ERRMINE_REDMINE_URL` - Redmine server URL
+- `ERRMINE_API_KEY` - API key for authentication
+- `ERRMINE_PROJECT` - Project identifier (default: `'bug-tracker'`)
+- `ERRMINE_APP_NAME` - Application name (default: `'unknown'`)
+
+### Rails
+
+Create an initializer:
+
+```ruby
+# config/initializers/errmine.rb
+Errmine.configure do |config|
+  config.redmine_url = ENV.fetch('REDMINE_URL')
+  config.api_key     = ENV.fetch('REDMINE_API_KEY')
+  config.project_id  = 'my-project'
+  config.tracker_id  = 1                    # Default: 1 (Bug)
+  config.app_name    = Rails.application.class.module_parent_name
+  config.cooldown    = 300                  # Default: 300 seconds
+end
+```
+
+### Plain Ruby
+
+```ruby
+require 'errmine'
+
+Errmine.configure do |config|
+  config.redmine_url = 'https://redmine.example.com'
+  config.api_key     = 'your-redmine-api-key'
+  config.project_id  = 'my-project'
+end
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `redmine_url` | `ENV['ERRMINE_REDMINE_URL']` | Redmine server URL (required) |
+| `api_key` | `ENV['ERRMINE_API_KEY']` | API key for authentication (required) |
+| `project_id` | `ENV['ERRMINE_PROJECT']` or `'bug-tracker'` | Redmine project identifier |
+| `tracker_id` | `1` | Tracker ID (usually 1 = Bug) |
+| `app_name` | `ENV['ERRMINE_APP_NAME']` or `'unknown'` | Application name shown in issues |
+| `enabled` | `true` | Enable/disable notifications |
+| `cooldown` | `300` | Seconds between same-error notifications |
+
+## Usage
+
+### Rails 7+ (Automatic)
+
+Errmine automatically subscribes to Rails' error reporting API via a Railtie. Unhandled exceptions are reported automatically. No additional setup required.
+
+### Rack Middleware
+
+For all Rails versions or any Rack-based application:
+
+```ruby
+# config/application.rb (Rails)
+config.middleware.use Errmine::Middleware
+
+# or config.ru (Sinatra, etc.)
+use Errmine::Middleware
+```
+
+The middleware captures request context (URL, HTTP method, user via Warden).
+
+### Manual Notification
+
+Report exceptions manually with custom context:
+
+```ruby
+begin
+  risky_operation
+rescue => e
+  Errmine.notify(e, {
+    url: request.url,
+    user: current_user&.email,
+    custom_field: 'any value'
+  })
+  raise
+end
+```
+
+### rescue_from in Controllers
+
+```ruby
+class ApplicationController < ActionController::Base
+  rescue_from StandardError do |e|
+    Errmine.notify(e, {
+      url: request.url,
+      user: current_user&.email
+    })
+    raise e
+  end
+end
+```
+
+### Disabling Notifications
+
+```ruby
+Errmine.configure do |config|
+  config.enabled = Rails.env.production?
+end
+```
+
+## How It Works
+
+### Checksum Generation
+
+Each exception gets an 8-character MD5 checksum based on:
+- Exception class name
+- Exception message
+- First application backtrace line (containing `/app/`)
+
+```
+MD5("NoMethodError:undefined method 'foo':app/controllers/users_controller.rb:45")[0..7]
+# => "a1b2c3d4"
+```
+
+### Deduplication
+
+1. Search Redmine for open issues containing `[{checksum}]` in the subject
+2. If found: increment counter, add journal note with timestamp and backtrace
+3. If not found: create new issue
+
+### Rate Limiting
+
+To prevent flooding Redmine during error loops:
+
+- Each checksum is cached with its last occurrence time
+- Same error won't hit Redmine more than once per cooldown period (default: 5 minutes)
+- Cache is automatically cleaned when it exceeds 500 entries
+
+## Redmine Setup
+
+1. **Enable REST API**: Administration > Settings > API > Enable REST web service
+2. **Create an API key**: My Account > API access key > Show/Reset
+3. **Create a project** for error tracking (or use existing one)
+4. **Permissions**: The API user needs:
+   - View issues
+   - Add issues
+   - Edit issues
+   - Add notes
+
+## Issue Format
+
+### Subject
+
+```
+[{checksum}][{count}] {ExceptionClass}: {truncated message}
+```
+
+Example: `[a1b2c3d4][47] NoMethodError: undefined method 'foo' for nil...`
+
+### Description (Textile format)
+
+```textile
+**Exception:** @NoMethodError@
+**Message:** undefined method 'foo' for nil:NilClass
+**App:** my-app
+**First seen:** 2025-01-15 10:30:00
+
+**URL:** /users/123
+**User:** user@example.com
+
+h3. Backtrace
+
+<pre>
+app/controllers/users_controller.rb:45:in `show'
+app/controllers/application_controller.rb:12:in `authenticate'
+</pre>
+```
+
+### Journal Note (on subsequent occurrences)
+
+```textile
+Occurred again (*47x*) at 2025-01-15 10:35:00
+
+URL: /users/456
+
+<pre>
+app/controllers/users_controller.rb:45:in `show'
+</pre>
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/errmine/middleware.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# @see Errmine
+module Errmine
+  # Rack middleware that catches exceptions and reports them to Redmine.
+  # Re-raises the exception after reporting to allow normal error handling.
+  class Middleware
+    # Creates a new middleware instance
+    #
+    # @param app [#call] the Rack application
+    def initialize(app)
+      @app = app
+    end
+
+    # Processes the request and catches any exceptions
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Array] the Rack response
+    # @raise [Exception] re-raises any caught exception after reporting
+    def call(env)
+      @app.call(env)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      notify_exception(e, env)
+      raise
+    end
+
+    private
+
+    # Sends exception notification to Redmine
+    #
+    # @param exception [Exception] the caught exception
+    # @param env [Hash] the Rack environment
+    def notify_exception(exception, env)
+      context = build_context(env)
+      Errmine.notify(exception, context)
+    rescue StandardError => e
+      warn "[Errmine] Middleware error: #{e.message}"
+    end
+
+    # Builds context hash from Rack environment
+    #
+    # @param env [Hash] the Rack environment
+    # @return [Hash] context with url, method, and user info
+    def build_context(env)
+      context = {}
+
+      request_uri = env['REQUEST_URI'] || env['PATH_INFO']
+      context[:url] = request_uri if request_uri
+
+      request_method = env['REQUEST_METHOD']
+      context[:method] = request_method if request_method
+
+      if defined?(env['warden']) && env['warden']&.user
+        user = env['warden'].user
+        context[:user] = user.respond_to?(:email) ? user.email : user.to_s
+      end
+
+      context
+    end
+  end
+end

data/lib/errmine/notifier.rb

@@ -0,0 +1,395 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'digest'
+require 'singleton'
+
+# @see Errmine
+module Errmine
+  # Core notifier that handles exception reporting to Redmine.
+  # Manages checksum generation, rate limiting, and API communication.
+  class Notifier
+    include Singleton
+
+    # HTTP connection timeout in seconds
+    CONNECT_TIMEOUT = 5
+
+    # HTTP read timeout in seconds
+    READ_TIMEOUT = 10
+
+    # Maximum number of entries in the rate limit cache
+    MAX_CACHE_SIZE = 500
+
+    # Maximum length of exception message in issue subject
+    SUBJECT_MESSAGE_LENGTH = 60
+
+    # Initializes the notifier with empty cache
+    def initialize
+      @cache = {}
+      @mutex = Mutex.new
+    end
+
+    # Notifies Redmine about an exception
+    #
+    # @param exception [Exception] the exception to report
+    # @param context [Hash] additional context (url, user, etc.)
+    # @return [Hash, nil] the created/updated issue or nil on failure
+    def notify(exception, context = {})
+      checksum = generate_checksum(exception)
+
+      return nil if rate_limited?(checksum)
+
+      record_occurrence(checksum)
+
+      result = find_existing_issue(checksum)
+
+      case result
+      when :error
+        nil
+      when nil
+        create_issue(exception, context, checksum)
+      else
+        update_issue(result, exception, context)
+      end
+    end
+
+    # Clears the rate limit cache
+    #
+    # @return [void]
+    def reset_cache!
+      @mutex.synchronize { @cache.clear }
+    end
+
+    private
+
+    # Returns the Errmine configuration
+    #
+    # @return [Errmine::Configuration]
+    def config
+      Errmine.configuration
+    end
+
+    # Generates an 8-character checksum for the exception
+    #
+    # @param exception [Exception]
+    # @return [String]
+    def generate_checksum(exception)
+      first_app_line = first_app_backtrace_line(exception)
+      data = "#{exception.class}:#{exception.message}:#{first_app_line}"
+      Digest::MD5.hexdigest(data)[0, 8]
+    end
+
+    # Finds the first backtrace line from the application
+    #
+    # @param exception [Exception]
+    # @return [String]
+    def first_app_backtrace_line(exception)
+      return '' unless exception.backtrace
+
+      exception.backtrace.find { |line| line.include?('/app/') } ||
+        exception.backtrace.first ||
+        ''
+    end
+
+    # Checks if the checksum is rate limited
+    #
+    # @param checksum [String]
+    # @return [Boolean]
+    def rate_limited?(checksum)
+      @mutex.synchronize do
+        last_seen = @cache[checksum]
+        return false unless last_seen
+
+        Time.now - last_seen < config.cooldown
+      end
+    end
+
+    # Records the occurrence of a checksum
+    #
+    # @param checksum [String]
+    # @return [void]
+    def record_occurrence(checksum)
+      @mutex.synchronize do
+        cleanup_cache if @cache.size >= MAX_CACHE_SIZE
+        @cache[checksum] = Time.now
+      end
+    end
+
+    # Cleans up old entries from the cache
+    #
+    # @return [void]
+    def cleanup_cache
+      cutoff = Time.now - config.cooldown
+      @cache.delete_if { |_, time| time < cutoff }
+
+      return unless @cache.size >= MAX_CACHE_SIZE
+
+      sorted = @cache.sort_by { |_, time| time }
+      to_remove = sorted.first(@cache.size - (MAX_CACHE_SIZE / 2))
+      to_remove.each_key { |key| @cache.delete(key) }
+    end
+
+    # Finds an existing open issue with the given checksum
+    #
+    # @param checksum [String]
+    # @return [Hash, Symbol, nil] the issue hash, :error on failure, or nil if not found
+    def find_existing_issue(checksum)
+      uri = build_uri('/issues.json')
+      uri.query = URI.encode_www_form(
+        project_id: config.project_id,
+        'subject' => "~[#{checksum}]",
+        status_id: 'open'
+      )
+
+      response = http_get(uri)
+      return :error unless response
+
+      data = JSON.parse(response.body)
+      issues = data['issues'] || []
+
+      issues.find { |issue| issue['subject']&.include?("[#{checksum}]") }
+    rescue JSON::ParserError => e
+      warn "[Errmine] Failed to parse response: #{e.message}"
+      :error
+    end
+
+    # Creates a new issue in Redmine
+    #
+    # @param exception [Exception]
+    # @param context [Hash]
+    # @param checksum [String]
+    # @return [Hash, nil]
+    def create_issue(exception, context, checksum)
+      uri = build_uri('/issues.json')
+
+      subject = build_subject(checksum, 1, exception)
+      description = build_description(exception, context)
+
+      payload = {
+        issue: {
+          project_id: config.project_id,
+          tracker_id: config.tracker_id,
+          subject: subject,
+          description: description
+        }
+      }
+
+      response = http_post(uri, payload)
+      return nil unless response
+
+      data = JSON.parse(response.body)
+      data['issue']
+    rescue JSON::ParserError => e
+      warn "[Errmine] Failed to parse response: #{e.message}"
+      nil
+    end
+
+    # Updates an existing issue with new occurrence
+    #
+    # @param issue [Hash]
+    # @param exception [Exception]
+    # @param context [Hash]
+    # @return [Net::HTTPResponse, nil]
+    def update_issue(issue, exception, context)
+      issue_id = issue['id']
+      current_subject = issue['subject']
+
+      new_count = extract_count(current_subject) + 1
+      checksum = extract_checksum(current_subject)
+
+      new_subject = build_subject(checksum, new_count, exception)
+      notes = build_journal_note(new_count, context, exception)
+
+      uri = build_uri("/issues/#{issue_id}.json")
+
+      payload = {
+        issue: {
+          subject: new_subject,
+          notes: notes
+        }
+      }
+
+      http_put(uri, payload)
+    end
+
+    # Builds the issue subject line
+    #
+    # @param checksum [String]
+    # @param count [Integer]
+    # @param exception [Exception]
+    # @return [String]
+    def build_subject(checksum, count, exception)
+      message = exception.message.to_s
+      truncated = message.length > SUBJECT_MESSAGE_LENGTH ? "#{message[0, SUBJECT_MESSAGE_LENGTH]}..." : message
+      truncated = truncated.gsub(/[\r\n]+/, ' ').strip
+
+      "[#{checksum}][#{count}] #{exception.class}: #{truncated}"
+    end
+
+    # Builds the issue description in Textile format
+    #
+    # @param exception [Exception]
+    # @param context [Hash]
+    # @return [String]
+    def build_description(exception, context)
+      lines = []
+      lines << "**Exception:** @#{exception.class}@"
+      lines << "**Message:** #{exception.message}"
+      lines << "**App:** #{config.app_name}"
+      lines << "**First seen:** #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+      lines << ''
+
+      lines << "**URL:** #{context[:url]}" if context[:url]
+
+      lines << "**User:** #{context[:user]}" if context[:user]
+
+      context.each do |key, value|
+        next if %i[url user].include?(key)
+
+        lines << "**#{key.to_s.capitalize}:** #{value}"
+      end
+
+      lines << ''
+      lines << 'h3. Backtrace'
+      lines << ''
+      lines << '<pre>'
+      lines << format_backtrace(exception)
+      lines << '</pre>'
+
+      lines.join("\n")
+    end
+
+    # Builds a journal note for issue updates
+    #
+    # @param count [Integer]
+    # @param context [Hash]
+    # @param exception [Exception]
+    # @return [String]
+    def build_journal_note(count, context, exception)
+      lines = []
+      lines << "Occurred again (*#{count}x*) at #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}"
+      lines << ''
+
+      lines << "URL: #{context[:url]}" if context[:url]
+      lines << "User: #{context[:user]}" if context[:user]
+
+      lines << ''
+      lines << '<pre>'
+      lines << format_backtrace(exception, limit: 10)
+      lines << '</pre>'
+
+      lines.join("\n")
+    end
+
+    # Formats the exception backtrace
+    #
+    # @param exception [Exception]
+    # @param limit [Integer]
+    # @return [String]
+    def format_backtrace(exception, limit: 20)
+      return 'No backtrace available' unless exception.backtrace
+
+      exception.backtrace.first(limit).join("\n")
+    end
+
+    # Extracts the occurrence count from issue subject
+    #
+    # @param subject [String, nil]
+    # @return [Integer]
+    def extract_count(subject)
+      match = subject&.match(/\]\[(\d+)\]/)
+      match ? match[1].to_i : 0
+    end
+
+    # Extracts the checksum from issue subject
+    #
+    # @param subject [String, nil]
+    # @return [String]
+    def extract_checksum(subject)
+      match = subject&.match(/\[([a-f0-9]{8})\]/)
+      match ? match[1] : ''
+    end
+
+    # Builds a URI for the Redmine API
+    #
+    # @param path [String]
+    # @return [URI]
+    def build_uri(path)
+      base = config.redmine_url.chomp('/')
+      URI.parse("#{base}#{path}")
+    end
+
+    # Performs an HTTP GET request
+    #
+    # @param uri [URI]
+    # @return [Net::HTTPResponse, nil]
+    def http_get(uri)
+      http_request(uri) do |http|
+        request = Net::HTTP::Get.new(uri)
+        request['X-Redmine-API-Key'] = config.api_key
+        http.request(request)
+      end
+    end
+
+    # Performs an HTTP POST request
+    #
+    # @param uri [URI]
+    # @param payload [Hash]
+    # @return [Net::HTTPResponse, nil]
+    def http_post(uri, payload)
+      http_request(uri) do |http|
+        request = Net::HTTP::Post.new(uri)
+        request['X-Redmine-API-Key'] = config.api_key
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+        http.request(request)
+      end
+    end
+
+    # Performs an HTTP PUT request
+    #
+    # @param uri [URI]
+    # @param payload [Hash]
+    # @return [Net::HTTPResponse, nil]
+    def http_put(uri, payload)
+      http_request(uri) do |http|
+        request = Net::HTTP::Put.new(uri)
+        request['X-Redmine-API-Key'] = config.api_key
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate(payload)
+        http.request(request)
+      end
+    end
+
+    # Executes an HTTP request with error handling
+    #
+    # @param uri [URI]
+    # @return [Net::HTTPResponse, nil]
+    def http_request(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = CONNECT_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+
+      response = yield(http)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        warn "[Errmine] HTTP #{response.code}: #{response.message}"
+        return nil
+      end
+
+      response
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      warn "[Errmine] Timeout: #{e.message}"
+      nil
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+      warn "[Errmine] Connection error: #{e.message}"
+      nil
+    rescue StandardError => e
+      warn "[Errmine] HTTP error: #{e.message}"
+      nil
+    end
+  end
+end

data/lib/errmine/railtie.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'middleware'
+
+# @see Errmine
+module Errmine
+  # Rails integration via Railtie.
+  # Automatically subscribes to Rails 7+ Error Reporting API when available.
+  class Railtie < Rails::Railtie
+    initializer 'errmine.configure_rails_initialization' do |_app|
+      Rails.error.subscribe(ErrorSubscriber.new) if Rails.version >= '7.0'
+    end
+
+    # Error subscriber for Rails 7+ Error Reporting API
+    class ErrorSubscriber
+      # Called by Rails when an error is reported
+      #
+      # @param error [Exception] the reported error
+      # @param handled [Boolean] whether the error was handled
+      # @param severity [Symbol] the error severity
+      # @param context [Hash]
+      # @param source [String, nil] the error source
+      # @return [void]
+      def report(error, handled:, severity:, context: {}, source: nil)
+        return if handled
+
+        errmine_context = {}
+        errmine_context[:url] = context[:url] if context[:url]
+        errmine_context[:user] = context[:user]&.to_s if context[:user]
+        errmine_context[:source] = source if source
+        errmine_context[:severity] = severity if severity
+
+        Errmine.notify(error, errmine_context)
+      rescue StandardError => e
+        warn "[Errmine] Error subscriber failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/errmine/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Errmine
+  # Current version of the errmine gem
+  VERSION = '0.1.0'
+end

data/lib/errmine.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'errmine/version'
+require_relative 'errmine/notifier'
+
+# Dead simple exception tracking for Redmine.
+# Automatically creates and updates Redmine issues from Ruby/Rails exceptions.
+module Errmine
+  # Base error class for Errmine-specific errors
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid
+  class ConfigurationError < Error; end
+
+  # Configuration class for Errmine settings
+  class Configuration
+    # @return [String, nil] Redmine server URL
+    attr_accessor :redmine_url
+
+    # @return [String, nil] Redmine API key
+    attr_accessor :api_key
+
+    # @return [String] Redmine project identifier
+    attr_accessor :project_id
+
+    # @return [Integer] Redmine tracker ID (default: 1 for Bug)
+    attr_accessor :tracker_id
+
+    # @return [String] Application name shown in issues
+    attr_accessor :app_name
+
+    # @return [Boolean] Whether notifications are enabled
+    attr_accessor :enabled
+
+    # @return [Integer] Cooldown period in seconds between same-error notifications
+    attr_accessor :cooldown
+
+    # Initializes configuration with defaults from environment variables
+    def initialize
+      @redmine_url = ENV.fetch('ERRMINE_REDMINE_URL', nil)
+      @api_key     = ENV.fetch('ERRMINE_API_KEY', nil)
+      @project_id  = ENV['ERRMINE_PROJECT'] || 'bug-tracker'
+      @tracker_id  = 1
+      @app_name    = ENV['ERRMINE_APP_NAME'] || 'unknown'
+      @enabled     = true
+      @cooldown    = 300
+    end
+
+    # Checks if the configuration has required values
+    #
+    # @return [Boolean] true if redmine_url and api_key are present
+    def valid?
+      !redmine_url.nil? && !redmine_url.empty? &&
+        !api_key.nil? && !api_key.empty?
+    end
+  end
+
+  class << self
+    # Returns the current configuration instance
+    #
+    # @return [Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for modification
+    #
+    # @yield [Configuration] the configuration instance
+    # @return [Configuration] the configuration instance
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Resets the configuration to default values
+    #
+    # @return [Configuration] the new configuration instance
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Notifies Redmine about an exception
+    #
+    # @param exception [Exception] the exception to report
+    # @param context [Hash] additional context (url, user, etc.)
+    # @return [Hash, nil] the created/updated issue or nil on failure
+    def notify(exception, context = {})
+      return unless configuration.enabled
+      return unless configuration.valid?
+
+      Notifier.instance.notify(exception, context)
+    rescue StandardError => e
+      warn "[Errmine] Failed to notify: #{e.message}"
+      nil
+    end
+  end
+end
+
+require_relative 'errmine/railtie' if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: errmine
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maciej Mensfeld
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Automatically create and update Redmine issues from Ruby/Rails exceptions.
+  Zero dependencies.
+email:
+- maciej@mensfeld.pl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/errmine.rb
+- lib/errmine/middleware.rb
+- lib/errmine/notifier.rb
+- lib/errmine/railtie.rb
+- lib/errmine/version.rb
+homepage: https://github.com/mensfeld/errmine
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mensfeld/errmine
+  changelog_uri: https://github.com/mensfeld/errmine/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.0.beta2
+specification_version: 4
+summary: Dead simple exception tracking for Redmine
+test_files: []