tg_error_notifier 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb51823201c7e9fef5a9a3d3f1ddb9ca52390d75cf256c1488f3b3f72ebc6d2b
-  data.tar.gz: d778ac6a5c07212e617729878ad8dc9d05d338377d9788f57a44577b9d739804
+  metadata.gz: 03b6d8e79dd258e7487a99925017dc62d9fd7d66255af5e80c62aecff7b6638b
+  data.tar.gz: 062f6f0253004feb248c55e9cf2962244a7683c6d6771dac55f9a762a1c97bec
 SHA512:
-  metadata.gz: c943e6433257b3d68fb0d4630156e3073084dfa82d90ef51c38d5db4b518f840abd2e211d0aacf893ed8734d70e893cb8872969ffbe284324893b54946882610
-  data.tar.gz: 3f05a5989f3d5731eef6114b2e8acb3247ea97af1ee43d7ccc98d163f6496b5f22c55b6fed9fac1e31c5c3431dfe82919bb42c715f342c3b610552a4f6ed7849
+  metadata.gz: 8caa97214339f4f0af2683a40f7d3a705a80fd0ecb9dd65f7a242d97efb38b2cab5e284b5b4f2d2cff3bb0121034190b09f8ad87793529937e89a2624bf1bc3c
+  data.tar.gz: 8e546d58081bd0e50abae5bf375a7d9adac0ada19032fb44fbfe089fedb62fbaf55e0abe4b35489857716fa21352466c90224d36592faa43926d6fd578330b5b

data/README.md

@@ -138,3 +138,50 @@ TgErrorNotifier.capture_message(
 ```
 
 `capture_message` returns the same diagnostic hash format as `capture_exception`.
+
+## Named topics for messages
+
+Send messages to a dedicated Forum topic by name. The topic is created on first use (blue icon) and reused afterwards:
+
+```ruby
+TgErrorNotifier.capture_message("New account: #{account.name}", topic: "Registrations")
+```
+
+Since the topic → thread_id mapping is cached in memory per process, configure a persistent store so restarts and multiple processes (Puma workers, Sidekiq) don't create duplicate topics:
+
+```ruby
+TgErrorNotifier.configure do |config|
+  config.topic_store_read  = ->(name) { MyKeyValueStore.get("tg_topic:#{name}") }
+  config.topic_store_write = ->(name, thread_id) { MyKeyValueStore.set("tg_topic:#{name}", thread_id) }
+end
+```
+
+Without a store everything still works, but each process creates its own topic. Named topics work independently of `topics_enabled` (which controls per-exception topics). Requirements are the same: forum supergroup + `can_manage_topics` bot permission.
+
+## Buttons under the message
+
+Attach an inline keyboard to error notifications — e.g. a link that files the error as a task on your board. The gem does not interpret the buttons: whatever the callable returns is passed to Telegram as is, so `url`, `callback_data` and `web_app` buttons all work.
+
+```ruby
+TgErrorNotifier.configure do |config|
+  config.buttons = lambda do |kind:, source:, context:, fingerprint:, exception: nil, message: nil|
+    next nil unless kind == :exception
+
+    token = ErrorTaskLink.issue(exception: exception, source: source, fingerprint: fingerprint)
+    [[{ text: "\u2795 To the board", url: "https://example.com/e/#{token}" }]]
+  end
+end
+```
+
+Arguments:
+
+| key | value |
+| --- | --- |
+| `kind` | `:exception` for `capture_exception`/rescued errors, `:message` for `capture_message` |
+| `exception` | the exception (nil for `:message`) |
+| `message` | the message text (nil for `:exception`) |
+| `source` | where it came from (`"Sidekiq: MyWorker"`, `"manual"`, ...) |
+| `context` | the context hash passed to the notifier |
+| `fingerprint` | grouping key of the exception — stable across repeats, use it to deduplicate whatever the button creates (nil for `:message`) |
+
+Return an array of rows (`[[button, button], [button]]`); a flat array becomes a single row; `nil` or `[]` means no keyboard. Exceptions raised inside the callable are logged and the notification is still delivered — without the keyboard.

data/lib/tg_error_notifier/configuration.rb

@@ -23,7 +23,10 @@ module TgErrorNotifier
       :grouping_enabled,
       :grouping_window,
       :topics_enabled,
-      :topic_icon_color
+      :topic_icon_color,
+      :topic_store_read,
+      :topic_store_write,
+      :buttons
 
     def initialize
       @enabled = true
@@ -52,6 +55,25 @@ module TgErrorNotifier
       @grouping_window = 60
       @topics_enabled = false
       @topic_icon_color = nil
+      # Persistent storage for named topics (created via capture_message topic:).
+      # Without a store each process/restart would create a duplicate forum topic.
+      #   topic_store_read  = ->(name) { ... }        # returns thread_id or nil
+      #   topic_store_write = ->(name, thread_id) { ... }
+      @topic_store_read = nil
+      @topic_store_write = nil
+      # Inline keyboard attached under the message. The gem does not interpret
+      # the buttons: whatever the host returns goes to Telegram as is, so the
+      # host is free to use url buttons, callback_data or web_app.
+      #
+      #   config.buttons = lambda do |kind:, source:, context:, fingerprint:, exception: nil, message: nil|
+      #     [[{ text: "To the board", url: "https://example.com/e/#{token}" }]]
+      #   end
+      #
+      # Return value: array of rows, each row an array of button hashes.
+      # A flat array of buttons is accepted too and becomes a single row.
+      # Return nil or [] for no keyboard. Errors raised inside are logged and
+      # the message is still delivered, without the keyboard.
+      @buttons = nil
     end
 
     def proxy?

data/lib/tg_error_notifier/grouper.rb

@@ -46,6 +46,12 @@ module TgErrorNotifier
       end
     end
 
+    def rollback(key)
+      @mutex.synchronize do
+        @entries.delete(key)
+      end
+    end
+
     def grouping_key(exception)
       "#{exception.class.name}:#{normalize_message(exception.message)}"
     end

data/lib/tg_error_notifier/notifier.rb

@@ -7,6 +7,10 @@ require "cgi"
 module TgErrorNotifier
   class Notifier
     MAX_MESSAGE_LENGTH = 3800
+    # Отдельные поля (сообщение исключения, значения контекста) режем заранее,
+    # чтобы гарантированно осталось место под бэктрейс и закрывающие теги
+    MAX_FIELD_LENGTH = 900
+    HTML_TAGS = %w[pre code b i u s].freeze
 
     def initialize(config)
       @config = config
@@ -27,7 +31,7 @@ module TgErrorNotifier
       thread_id = nil
       suppressed_count = 0
 
-      if config.topics_enabled || config.grouping_enabled
+      if config.topics_enabled || config.grouping_enabled || config.buttons
         key = grouper.grouping_key(exception)
       end
 
@@ -49,21 +53,30 @@ module TgErrorNotifier
         source: source,
         context: context,
         thread_id: thread_id,
-        suppressed_count: suppressed_count
+        suppressed_count: suppressed_count,
+        fingerprint: key
       )
-      send_payload(payload)
+      response = send_payload(payload)
+
+      if !response[:sent] && config.grouping_enabled && key
+        grouper.rollback(key)
+      end
+
+      response
     rescue StandardError => e
       log("notify failed: #{e.class}: #{e.message}")
       { sent: false, status: :failed, reason: e.class.name, error: e.message }
     end
 
-    def notify_message(message:, level:, source:, context: {}, thread_id: nil)
+    def notify_message(message:, level:, source:, context: {}, topic: nil, thread_id: nil)
       enabled_check = enabled_status
       unless enabled_check[:enabled]
         log("skipped: #{enabled_check[:reason]}")
         return { sent: false, status: :skipped, reason: enabled_check[:reason] }
       end
 
+      thread_id ||= topic_manager.thread_id_for_name(topic) if topic
+
       payload = build_message_payload(
         message: message,
         level: level,
@@ -108,7 +121,7 @@ module TgErrorNotifier
       ignored.include?(exception.class.name)
     end
 
-    def send_payload(payload)
+    def send_payload(payload, retry_plain: true)
       token = resolve(config.bot_token)
       uri = URI("#{resolve(config.api_base)}/bot#{token}/sendMessage")
 
@@ -131,15 +144,29 @@ module TgErrorNotifier
       end
 
       log("telegram api error: HTTP #{response.code} #{response.body}")
+
+      # Последний рубеж: разметка не распарсилась — шлём то же самое
+      # обычным текстом, чтобы тело сообщения дошло в любом случае
+      if retry_plain && parse_entities_error?(response)
+        plain = payload.dup
+        plain.delete(:parse_mode)
+        plain[:text] = truncate(strip_html(payload[:text]))
+        return send_payload(plain, retry_plain: false)
+      end
+
       { 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: {}, thread_id: nil, suppressed_count: 0)
+    def parse_entities_error?(response)
+      response.code.to_i == 400 && response.body.to_s.include?("can't parse entities")
+    end
+
+    def build_payload(exception:, source:, context: {}, thread_id: nil, suppressed_count: 0, fingerprint: nil)
       parts = [
         "<b>🚨 #{escape(resolve(config.app_name).to_s)}: #{escape(resolve(config.environment).to_s)}</b>",
-        "<b>Source:</b> #{escape(source.to_s)}",
+        "<b>Source:</b> #{escape(clamp(source, MAX_FIELD_LENGTH))}",
         "<b>Exception:</b> <code>#{escape(exception.class.name)}</code>",
-        "<b>Message:</b> #{escape(exception.message.to_s)}"
+        "<b>Message:</b> #{escape(clamp(exception.message, MAX_FIELD_LENGTH))}"
       ]
 
       if suppressed_count > 0
@@ -148,12 +175,19 @@ module TgErrorNotifier
 
       parts << context_block(context)
 
-      text = parts.compact.join("\n")
+      text = truncate(parts.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>"
+        header = "\n<b>Backtrace:</b>\n"
+        # Бэктрейс режем по остатку бюджета ДО оборачивания в <pre>,
+        # иначе финальный truncate обрезал бы текст внутри тега и Telegram
+        # отвечал 400 "can't find end tag corresponding to start tag pre"
+        budget = MAX_MESSAGE_LENGTH - text.length - header.length - "<pre></pre>".length
+        if budget > 100
+          bt = cut_escaped(escape(lines.join("\n")), budget)
+          text = "#{text}#{header}<pre>#{bt}</pre>"
+        end
       end
 
       payload = {
@@ -163,13 +197,46 @@ module TgErrorNotifier
         disable_web_page_preview: true
       }
       payload[:message_thread_id] = thread_id if thread_id
+      keyboard = build_keyboard(
+        kind: :exception,
+        exception: exception,
+        source: source,
+        context: context,
+        fingerprint: fingerprint
+      )
+      payload[:reply_markup] = keyboard if keyboard
       payload
     end
 
+    # Кнопки строит хост (config.buttons) — гем не знает, куда они ведут.
+    # Сбой в колбэке не должен отменять доставку самого уведомления: об ошибке
+    # надо узнать в любом случае, кнопка — дополнение.
+    def build_keyboard(kind:, source:, context:, fingerprint:, exception: nil, message: nil)
+      return nil if config.buttons.nil?
+
+      rows = config.buttons.call(
+        kind: kind,
+        exception: exception,
+        message: message,
+        source: source,
+        context: context,
+        fingerprint: fingerprint
+      )
+      return nil if rows.nil? || rows.empty?
+
+      # Плоский список кнопок принимаем как одну строку клавиатуры.
+      rows = [rows] unless rows.first.is_a?(Array)
+
+      { inline_keyboard: rows }
+    rescue StandardError => e
+      log("buttons failed: #{e.class}: #{e.message}")
+      nil
+    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 = context.map { |k, v| "<b>#{escape(k.to_s)}:</b> #{escape(clamp(v, MAX_FIELD_LENGTH))}" }
       formatted.join("\n")
     end
 
@@ -189,13 +256,50 @@ module TgErrorNotifier
         disable_web_page_preview: true
       }
       payload[:message_thread_id] = thread_id if thread_id
+      keyboard = build_keyboard(
+        kind: :message,
+        message: message,
+        source: source,
+        context: context,
+        fingerprint: nil
+      )
+      payload[:reply_markup] = keyboard if keyboard
       payload
     end
 
+    def clamp(value, limit)
+      text = value.to_s
+      text.length > limit ? "#{text[0...limit]}…" : text
+    end
+
+    # Обрезка уже экранированного текста: не оставляем хвост от «&amp;»
+    def cut_escaped(text, limit)
+      return text if text.length <= limit
+
+      text[0...limit].sub(/&[#a-zA-Z0-9]*\z/, "")
+    end
+
     def truncate(text)
       return text if text.length <= MAX_MESSAGE_LENGTH
 
-      text[0...MAX_MESSAGE_LENGTH] + "\n...truncated"
+      close_tags(cut_escaped(text, MAX_MESSAGE_LENGTH - 20)) + "\n...truncated"
+    end
+
+    # Обрезка могла оставить незакрытый тег или его половину — Telegram
+    # на таком отвечает 400 и сообщение не доходит вовсе
+    def close_tags(text)
+      text = text.sub(/<[^>]*\z/, "")
+
+      HTML_TAGS.each do |tag|
+        unclosed = text.scan("<#{tag}>").size - text.scan("</#{tag}>").size
+        unclosed.times { text += "</#{tag}>" }
+      end
+
+      text
+    end
+
+    def strip_html(text)
+      CGI.unescapeHTML(text.to_s.gsub(/<[^>]*>/, ""))
     end
 
     def resolve(value)

data/lib/tg_error_notifier/topic_manager.rb

@@ -2,27 +2,92 @@
 
 require "net/http"
 require "json"
+require "set"
 
 module TgErrorNotifier
   class TopicManager
     ICON_COLOR_RED = 0xFB6F5F
+    ICON_COLOR_BLUE = 0x6FB9F0
     MAX_TOPIC_NAME = 128
+    MAX_STORE_KEY = 200
 
     def initialize(config)
       @config = config
       @mutex = Mutex.new
+      @condition = ConditionVariable.new
       @topics = {} # grouping_key => message_thread_id
+      @creating = Set.new
     end
 
     def thread_id_for(key, exception)
+      name = nil
+      store_key = "exception:#{key}"[0...MAX_STORE_KEY]
+
       @mutex.synchronize do
+        # Wait if another thread is already creating this topic
+        while @creating.include?(key)
+          @condition.wait(@mutex, 10)
+        end
+
         return @topics[key] if @topics.key?(key)
+
+        # Тема ошибки должна пережить рестарт и быть общей для всех
+        # процессов: иначе каждый puma/sidekiq-воркер заводит свой дубль
+        stored = store_read(store_key)
+        if stored
+          @topics[key] = stored
+          return stored
+        end
+
+        @creating.add(key)
+        name = topic_name(exception)
       end
 
-      thread_id = create_topic(topic_name(exception))
+      thread_id = create_topic(name)
 
-      if thread_id
-        @mutex.synchronize { @topics[key] = thread_id }
+      @mutex.synchronize do
+        if thread_id
+          @topics[key] = thread_id
+          store_write(store_key, thread_id)
+        end
+        @creating.delete(key)
+        @condition.broadcast
+      end
+
+      thread_id
+    end
+
+    # Resolve thread_id for an explicitly named topic (capture_message topic: "...").
+    # Unlike exception topics, named topics survive restarts via the configured
+    # topic_store_read/topic_store_write callbacks.
+    def thread_id_for_name(name)
+      key = "topic:#{name}"
+
+      @mutex.synchronize do
+        while @creating.include?(key)
+          @condition.wait(@mutex, 10)
+        end
+
+        return @topics[key] if @topics.key?(key)
+
+        stored = store_read(name)
+        if stored
+          @topics[key] = stored
+          return stored
+        end
+
+        @creating.add(key)
+      end
+
+      thread_id = create_topic(truncate_name(name), icon_color: @config.topic_icon_color || ICON_COLOR_BLUE)
+
+      @mutex.synchronize do
+        if thread_id
+          @topics[key] = thread_id
+          store_write(name, thread_id)
+        end
+        @creating.delete(key)
+        @condition.broadcast
       end
 
       thread_id
@@ -30,13 +95,36 @@ module TgErrorNotifier
 
     private
 
-    def topic_name(exception)
-      name = "#{exception.class.name}: #{exception.message}"
-      name = name.gsub(/\s+/, " ").strip
+    def store_read(name)
+      reader = @config.topic_store_read
+      return nil unless reader
+
+      value = reader.call(name)
+      value.to_s.empty? ? nil : value.to_i
+    rescue StandardError => e
+      log("topic_store_read failed: #{e.class}: #{e.message}")
+      nil
+    end
+
+    def store_write(name, thread_id)
+      writer = @config.topic_store_write
+      return unless writer
+
+      writer.call(name, thread_id)
+    rescue StandardError => e
+      log("topic_store_write failed: #{e.class}: #{e.message}")
+    end
+
+    def truncate_name(name)
+      name = name.to_s.gsub(/\s+/, " ").strip
       name.length > MAX_TOPIC_NAME ? "#{name[0...MAX_TOPIC_NAME - 1]}…" : name
     end
 
-    def create_topic(name)
+    def topic_name(exception)
+      truncate_name("#{exception.class.name}: #{exception.message}")
+    end
+
+    def create_topic(name, icon_color: nil)
       token = resolve(@config.bot_token)
       chat_id = resolve(@config.chat_id)
       uri = URI("#{resolve(@config.api_base)}/bot#{token}/createForumTopic")
@@ -44,7 +132,7 @@ module TgErrorNotifier
       payload = {
         chat_id: chat_id,
         name: name,
-        icon_color: @config.topic_icon_color || ICON_COLOR_RED
+        icon_color: icon_color || @config.topic_icon_color || ICON_COLOR_RED
       }
 
       request = Net::HTTP::Post.new(uri)

data/lib/tg_error_notifier/version.rb

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

data/lib/tg_error_notifier.rb

@@ -30,8 +30,10 @@ module TgErrorNotifier
     end
 
     # API similar to Sentry.capture_message("text")
-    def capture_message(message, level: :info, source: "manual", context: {})
-      notifier.notify_message(message: message, level: level, source: source, context: context)
+    # topic: имя форум-топика — сообщение уйдёт в отдельную тему группы
+    # (топик создаётся один раз и переиспользуется через topic_store_read/write)
+    def capture_message(message, level: :info, source: "manual", context: {}, topic: nil)
+      notifier.notify_message(message: message, level: level, source: source, context: context, topic: topic)
     end
 
     def reset!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tg_error_notifier
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Sergei Ustinov