tg_error_notifier 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d8c70bb799ac75d0ec7db9e1f15d089bb493d1a76e905f6a88a33e2ecbf26ad8
+  data.tar.gz: 01c6e5de7fc99ad1f7603627f9c9db23d6c9a817e35b2d659288ff6bdbf6abd0
+SHA512:
+  metadata.gz: a7a076c6107c81900dfb8f189b63f0bc4c4c0265ce26f587114fb548b39aca5e54c75ae80e400a38e1dc759d7f5034d56a6e1c9bb88f66aae89d53baecbc6e68
+  data.tar.gz: 0c9a3ecc60610f7a53a82fa1d86da36908e78c45232ec66edcdc96c56dd0b9538b18e87323b8a5fb0af70353a1c3354f4c6879ebc7fd19091b835070dc2e39ba

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,92 @@
+# tg_error_notifier
+
+Gem for Rails error notifications to Telegram.
+
+## What it catches
+- Unhandled errors in Rack/Rails request cycle.
+- Failed ActiveJob executions.
+
+## Quick usage
+```ruby
+# Gemfile
+gem "tg_error_notifier"
+```
+
+```ruby
+# config/initializers/telegram_error_notifier.rb
+Rails.application.configure do
+  config.telegram_error_notifier.bot_token = ENV["TELEGRAM_BOT_TOKEN"]
+  config.telegram_error_notifier.chat_id = ENV["TELEGRAM_ERRORS_CHAT_ID"]
+  config.telegram_error_notifier.app_name = "my_app"
+end
+```
+
+## Environment variables
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_ERRORS_CHAT_ID`
+- `TELEGRAM_ERRORS_APP_NAME` (optional)
+
+## Telegram setup (bot, private channel/group, chat_id)
+
+### 1. Create a bot and get token
+1. Open Telegram and start chat with `@BotFather`.
+2. Send `/newbot` and follow prompts (bot name + username ending with `bot`).
+3. Copy the HTTP API token (looks like `123456:ABC...`) and save it as `TELEGRAM_BOT_TOKEN`.
+
+### 2. Create a private channel or private group
+
+#### Private channel
+1. Telegram -> New Channel -> set as **Private**.
+2. Open channel settings -> Administrators -> add your bot as admin.
+3. Grant at least permission to post messages.
+
+#### Private group (or supergroup)
+1. Telegram -> New Group -> add at least one member.
+2. Add your bot to the group.
+3. Promote bot to admin if needed (recommended for reliability).
+4. Keep group private (no public username).
+
+### 3. Get `chat_id`
+
+#### Method A (easy): `@userinfobot` / `@RawDataBot`
+- Add bot `@userinfobot` (or `@RawDataBot`) into your target channel/group.
+- Send any message there.
+- Open the helper bot dialog and read chat id.
+- For channels/supergroups it is usually negative and starts with `-100...`.
+- Delete this bot from your channel.
+
+#### Method B (official API): `getUpdates`
+1. Send at least one message in target chat after adding your bot.
+2. Open in browser:
+   `https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getUpdates`
+3. Find `chat` object and copy `chat.id`.
+
+Examples:
+- Private channel/supergroup: `-1001234567890`
+- Private group (old style): `-123456789`
+
+### 4. Validate before using in Rails
+- Ensure bot is present in the target chat.
+- Ensure bot has permission to send messages.
+- Put value into `TELEGRAM_ERRORS_CHAT_ID` and run a smoke test.
+
+## Manual notification
+```ruby
+begin
+  do_work
+rescue => e
+  pp TgErrorNotifier.capture_exception(e)
+  # or with extra context:
+  TgErrorNotifier.capture_exception(
+    e,
+    source: "custom",
+    context: { feature: "sync", user_id: current_user&.id }
+  )
+  raise
+end
+```
+
+`capture_exception` returns a diagnostic hash, e.g.:
+- `{ sent: true, status: :sent, code: 200 }`
+- `{ sent: false, status: :skipped, reason: "missing_chat_id" }`
+- `{ sent: false, status: :failed, reason: "telegram_api_error", code: 400, body: "..." }`

data/lib/tg_error_notifier/configuration.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TgErrorNotifier
+  class Configuration
+    attr_accessor :enabled,
+      :bot_token,
+      :chat_id,
+      :api_base,
+      :environment,
+      :app_name,
+      :max_backtrace_lines,
+      :ignored_exceptions,
+      :ignored_environments,
+      :open_timeout,
+      :read_timeout,
+      :logger,
+      :include_backtrace,
+      :active_job_enabled
+
+    def initialize
+      @enabled = true
+      @bot_token = ENV["TELEGRAM_BOT_TOKEN"]
+      @chat_id = ENV["TELEGRAM_ERRORS_CHAT_ID"]
+      @api_base = "https://api.telegram.org"
+      @environment = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      @app_name = ENV["TELEGRAM_ERRORS_APP_NAME"] || "Rails App"
+      @max_backtrace_lines = 20
+      @ignored_exceptions = [
+        "ActionController::RoutingError",
+        "ActiveRecord::RecordNotFound",
+        "ActionController::UnknownFormat"
+      ]
+      @ignored_environments = ["test"]
+      @open_timeout = 2
+      @read_timeout = 5
+      @logger = nil
+      @include_backtrace = true
+      @active_job_enabled = true
+    end
+  end
+end

data/lib/tg_error_notifier/middleware.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TgErrorNotifier
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env)
+    rescue StandardError => e
+      TgErrorNotifier.notify(
+        exception: e,
+        source: "rack",
+        context: {
+          method: env["REQUEST_METHOD"],
+          path: env["PATH_INFO"],
+          query: env["QUERY_STRING"],
+          request_id: env["action_dispatch.request_id"]
+        }
+      )
+      raise
+    end
+  end
+end

data/lib/tg_error_notifier/notifier.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "cgi"
+
+module TgErrorNotifier
+  class Notifier
+    MAX_MESSAGE_LENGTH = 3800
+
+    def initialize(config)
+      @config = config
+    end
+
+    def notify(exception:, source:, context: {})
+      enabled_check = enabled_status
+      unless enabled_check[:enabled]
+        log("skipped: #{enabled_check[:reason]}")
+        return { sent: false, status: :skipped, reason: enabled_check[:reason] }
+      end
+
+      if ignored_exception?(exception)
+        return { sent: false, status: :skipped, reason: "ignored_exception" }
+      end
+
+      payload = build_payload(exception: exception, source: source, context: context)
+      send_payload(payload)
+    rescue StandardError => e
+      log("notify failed: #{e.class}: #{e.message}")
+      { sent: false, status: :failed, reason: e.class.name, error: e.message }
+    end
+
+    private
+
+    attr_reader :config
+
+    def enabled_status
+      return { enabled: false, reason: "disabled" } unless resolve(config.enabled)
+      if config.ignored_environments.include?(resolve(config.environment).to_s)
+        return { enabled: false, reason: "ignored_environment" }
+      end
+
+      token_present = resolve(config.bot_token).to_s != ""
+      chat_present = resolve(config.chat_id).to_s != ""
+      return { enabled: false, reason: "missing_bot_token" } unless token_present
+      return { enabled: false, reason: "missing_chat_id" } unless chat_present
+
+      { enabled: true }
+    end
+
+    def ignored_exception?(exception)
+      ignored = config.ignored_exceptions.map(&:to_s)
+      ignored.include?(exception.class.name)
+    end
+
+    def send_payload(payload)
+      token = resolve(config.bot_token)
+      uri = URI("#{resolve(config.api_base)}/bot#{token}/sendMessage")
+
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = payload.to_json
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = config.open_timeout
+      http.read_timeout = config.read_timeout
+
+      response = http.request(request)
+      if response.is_a?(Net::HTTPSuccess)
+        return { sent: true, status: :sent, code: response.code.to_i }
+      end
+
+      log("telegram api error: HTTP #{response.code} #{response.body}")
+      { sent: false, status: :failed, reason: "telegram_api_error", code: response.code.to_i, body: response.body.to_s }
+    end
+
+    def build_payload(exception:, source:, context: {})
+      text = [
+        "<b>🚨 #{escape(resolve(config.app_name).to_s)}: #{escape(resolve(config.environment).to_s)}</b>",
+        "<b>Source:</b> #{escape(source.to_s)}",
+        "<b>Exception:</b> <code>#{escape(exception.class.name)}</code>",
+        "<b>Message:</b> #{escape(exception.message.to_s)}",
+        context_block(context)
+      ].compact.join("\n")
+
+      if config.include_backtrace && exception.backtrace
+        lines = exception.backtrace.first(config.max_backtrace_lines)
+        bt = escape(lines.join("\n"))
+        text = "#{text}\n<b>Backtrace:</b>\n<pre>#{bt}</pre>"
+      end
+
+      {
+        chat_id: resolve(config.chat_id),
+        text: truncate(text),
+        parse_mode: "HTML",
+        disable_web_page_preview: true
+      }
+    end
+
+    def context_block(context)
+      return nil if context.nil? || context.empty?
+
+      formatted = context.map { |k, v| "<b>#{escape(k.to_s)}:</b> #{escape(v.to_s)}" }
+      formatted.join("\n")
+    end
+
+    def truncate(text)
+      return text if text.length <= MAX_MESSAGE_LENGTH
+
+      text[0...MAX_MESSAGE_LENGTH] + "\n...truncated"
+    end
+
+    def resolve(value)
+      value.respond_to?(:call) ? value.call : value
+    end
+
+    def escape(text)
+      CGI.escapeHTML(text.to_s)
+    end
+
+    def log(message)
+      return unless config.logger
+
+      config.logger.error("[TgErrorNotifier] #{message}")
+    end
+  end
+end

data/lib/tg_error_notifier/railtie.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TgErrorNotifier
+  class Railtie < Rails::Railtie
+    config.telegram_error_notifier = ActiveSupport::OrderedOptions.new
+
+    initializer "tg_error_notifier.configure", after: :load_config_initializers do |app|
+      options = app.config.telegram_error_notifier
+
+      TgErrorNotifier.configure do |config|
+        config.enabled = options.enabled unless options.enabled.nil?
+        config.bot_token = options.bot_token unless options.bot_token.nil?
+        config.chat_id = options.chat_id unless options.chat_id.nil?
+        config.api_base = options.api_base unless options.api_base.nil?
+        config.environment = options.environment unless options.environment.nil?
+        config.app_name = options.app_name unless options.app_name.nil?
+        config.max_backtrace_lines = options.max_backtrace_lines unless options.max_backtrace_lines.nil?
+        config.ignored_exceptions = options.ignored_exceptions unless options.ignored_exceptions.nil?
+        config.ignored_environments = options.ignored_environments unless options.ignored_environments.nil?
+        config.open_timeout = options.open_timeout unless options.open_timeout.nil?
+        config.read_timeout = options.read_timeout unless options.read_timeout.nil?
+        config.logger = options.logger unless options.logger.nil?
+        config.include_backtrace = options.include_backtrace unless options.include_backtrace.nil?
+        config.active_job_enabled = options.active_job_enabled unless options.active_job_enabled.nil?
+      end
+    end
+
+    initializer "tg_error_notifier.middleware" do |app|
+      app.middleware.use TgErrorNotifier::Middleware
+    end
+
+    initializer "tg_error_notifier.subscriber", after: :load_config_initializers do
+      TgErrorNotifier::Subscriber.attach! if TgErrorNotifier.configuration.active_job_enabled
+    end
+  end
+end

data/lib/tg_error_notifier/subscriber.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TgErrorNotifier
+  class Subscriber
+    def self.attach!
+      return if @attached
+
+      ActiveSupport::Notifications.subscribe("perform.active_job") do |_name, _start, _finish, _id, payload|
+        exception = payload[:exception_object]
+        next unless exception
+
+        job = payload[:job]
+        TgErrorNotifier.notify(
+          exception: exception,
+          source: "active_job",
+          context: {
+            job_class: job&.class&.name,
+            job_id: job&.job_id,
+            queue: job&.queue_name,
+            executions: job&.executions
+          }
+        )
+      end
+
+      @attached = true
+    end
+  end
+end

data/lib/tg_error_notifier/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TgErrorNotifier
+  VERSION = "0.1.0"
+end

data/lib/tg_error_notifier.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails"
+require_relative "tg_error_notifier/version"
+require_relative "tg_error_notifier/configuration"
+require_relative "tg_error_notifier/notifier"
+require_relative "tg_error_notifier/middleware"
+require_relative "tg_error_notifier/subscriber"
+require_relative "tg_error_notifier/railtie"
+
+module TgErrorNotifier
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def notify(exception:, source:, context: {})
+      notifier.notify(exception: exception, source: source, context: context)
+    end
+
+    # API similar to Sentry.capture_exception(error)
+    def capture_exception(exception, source: "manual", context: {})
+      notify(exception: exception, source: source, context: context)
+    end
+
+    private
+
+    def notifier
+      @notifier ||= Notifier.new(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: tg_error_notifier
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergei Ustinov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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'
+description: Catches Rails request and ActiveJob exceptions and sends detailed alerts
+  to Telegram.
+email:
+- se.ustinov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/tg_error_notifier.rb
+- lib/tg_error_notifier/configuration.rb
+- lib/tg_error_notifier/middleware.rb
+- lib/tg_error_notifier/notifier.rb
+- lib/tg_error_notifier/railtie.rb
+- lib/tg_error_notifier/subscriber.rb
+- lib/tg_error_notifier/version.rb
+homepage: https://github.com/sergeyustinov/TgErrorNotifier
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sergeyustinov/TgErrorNotifier
+  source_code_uri: https://github.com/sergeyustinov/TgErrorNotifier
+  changelog_uri: https://github.com/sergeyustinov/TgErrorNotifier/releases
+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: 4.0.5
+specification_version: 4
+summary: Rails error notifications to Telegram
+test_files: []