html2rss 0.32.0 → 0.32.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4841672d87f3828928fa35646176d878469ade0afce9f9e6a119ccd1cf3251ae
-  data.tar.gz: 618382810f59ff95713064d91a2ccb6df4c0dd2cf6287f31127cddd5848e8dbd
+  metadata.gz: e095abe52bc258d262e3a24909e0feb480b2eb1d537e57580fc271203b0c6dbc
+  data.tar.gz: 8fdabe7ed5afee08c46ab94c2b6f80c1f8c66df9ffec9439e40e80fa897bfa96
 SHA512:
-  metadata.gz: 7abf8800a5943fca86ed9fa19058a1957ed101d52db70fd75042bda91abc2a9070d3bb5e6b0129e18103ebf407de2ea97a5e1a826cec3b5a7c0f21c12d0dfd61
-  data.tar.gz: 7831958f9d9b2af2db632b341cd8c902b45ed78feaf12dc21ee4f9c80c72237d56acba58e1b2aa7b0c842fc6dd3626beb48fd0e08ef932730920e33c23eb2f4b
+  metadata.gz: fdcce48a2a4fb3a8c3ea02fd8f4bb799bd8ed7acb4e66e74da3cde693f6a51cc3aa72d363670b13f077d1521d97321e0676d14b59c6b61f1c685fdc4db64cb67
+  data.tar.gz: ce1c1cac4c38f4660e61cb7c9506991d8c0d847c8bdfbb583c678680854b7327a16b9aa637af641aaae42bed9f15b9330cc344ee922252da16863a517569fad4

data/lib/html2rss/auto_source/scraper/meta_oembed.rb

@@ -116,6 +116,7 @@ module Html2rss
         end
 
         # @return [Hash{Symbol => Object}] oEmbed fields hash
+        # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- structured warn keeps fields local
         def fetch_oembed_data
           return {} unless request_session && (link_node = oembed_link_node)
           return {} unless (oembed_url = resolve_url(link_node['href']))
@@ -123,7 +124,12 @@ module Html2rss
           response = request_session.follow_up(url: oembed_url, relation: :auto_source, origin_url: url)
           parse_oembed_response(response)
         rescue Html2rss::Error, RequestService::UnsupportedResponseContentType, JSON::ParserError => error
-          Log.warn("#{self.class}: failed to fetch oEmbed payload (#{error.class}: #{error.message})")
+          Log.warn({
+            event_name: 'meta_oembed.fetch_failed',
+            host: url.host,
+            error_class: error.class.name,
+            message: "#{self.class}: failed to fetch oEmbed payload (#{error.class}: #{error.message})"
+          }.to_json)
           {}
         end
 

data/lib/html2rss/auto_source/scraper/native_feed.rb

@@ -57,16 +57,25 @@ module Html2rss
         ##
         # @yieldparam article [Hash{Symbol => Object}]
         # @return [Enumerator, void]
+        # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- structured empty/items logs
         def each(&)
           return enum_for(:each) unless block_given?
 
           articles = fetch_articles
           if articles.empty?
-            Log.info("#{self.class}: host=#{url.host} item_count=0 fallback=true")
+            Log.info({
+              event_name: 'auto_source.native_feed.empty',
+              host: url.host,
+              message: "#{self.class}: host=#{url.host} item_count=0 fallback=true"
+            }.to_json)
             return
           end
 
-          Log.info("#{self.class}: host=#{url.host} item_count=#{articles.size} fallback=false")
+          Log.info({
+            event_name: 'auto_source.native_feed.items',
+            host: url.host,
+            message: "#{self.class}: host=#{url.host} item_count=#{articles.size} fallback=false"
+          }.to_json)
           articles.each(&)
         end
 
@@ -74,7 +83,8 @@ module Html2rss
 
         attr_reader :parsed_body, :url, :request_session
 
-        def fetch_articles # rubocop:disable Metrics/MethodLength -- discovery + parse path
+        # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- discovery + parse + structured warn
+        def fetch_articles
           return [] unless request_session
 
           response = Syndication::Discovery.best_feed_response(
@@ -87,7 +97,12 @@ module Html2rss
 
           Syndication::Parser.parse_response(response)
         rescue Html2rss::Error, ArgumentError => error
-          Log.warn("#{self.class}: host=#{url.host} failed (#{error.class}: #{error.message})")
+          Log.warn({
+            event_name: 'auto_source.native_feed.failed',
+            host: url.host,
+            error_class: error.class.name,
+            message: "#{self.class}: host=#{url.host} failed (#{error.class}: #{error.message})"
+          }.to_json)
           []
         end
       end

data/lib/html2rss/auto_source/scraper/schema.rb

@@ -12,7 +12,7 @@ module Html2rss
       #
       # @see https://schema.org/docs/full.html
       # @see https://developers.google.com/search/docs/appearance/structured-data/article#microdata
-      class Schema
+      class Schema # rubocop:disable Metrics/ClassLength -- scraper + structured warn paths
         include Enumerable
 
         # Matches a leading schema.org URL prefix on @type values (http or https).
@@ -156,7 +156,11 @@ module Html2rss
           def parse_script_tag(script_tag)
             JSON.parse(script_tag.text, symbolize_names: true)
           rescue JSON::ParserError => error
-            Log.warn("#{name}: failed to parse JSON", error: error.message)
+            Log.warn({
+              event_name: 'schema.parse_failed',
+              error_class: error.class.name,
+              message: "#{name}: failed to parse JSON (#{error.message})"
+            }.to_json)
             []
           end
         end

data/lib/html2rss/auto_source/scraper/sitemap.rb

@@ -7,7 +7,7 @@ module Html2rss
     module Scraper
       ##
       # Scrapes articles from XML sitemaps explicitly linked in HTML or discovered via standard sitemap paths.
-      class Sitemap
+      class Sitemap # rubocop:disable Metrics/ClassLength -- scraper + structured warn paths
         include Enumerable
 
         # Selector for sitemap link tags in HTML head
@@ -78,6 +78,7 @@ module Html2rss
 
         attr_reader :parsed_body, :body, :url, :request_session, :min_priority, :max_age_days
 
+        # rubocop:disable-next Metrics/MethodLength -- structured budget-exhausted warn
         def fetch_and_parse_entries
           entries = parse_direct_sitemap
           return entries unless entries.empty?
@@ -87,7 +88,11 @@ module Html2rss
 
           parse_sitemap_xml(xml_body)
         rescue Html2rss::RequestService::RequestBudgetExceeded
-          Log.warn("#{self.class}: sitemap fetch stopped — request budget exhausted")
+          Log.warn({
+            event_name: 'sitemap.budget_exhausted',
+            host: url.host,
+            message: "#{self.class}: sitemap fetch stopped — request budget exhausted"
+          }.to_json)
           []
         end
 
@@ -122,10 +127,15 @@ module Html2rss
 
           Scraper::Sitemap::Parser.call(xml, min_priority:, max_age_days:).entries
         rescue Html2rss::RequestService::RequestBudgetExceeded
-          Log.warn("#{self.class}: sitemap fan-out stopped — request budget exhausted")
+          Log.warn({
+            event_name: 'sitemap.fanout_budget_exhausted',
+            host: url.host,
+            message: "#{self.class}: sitemap fan-out stopped — request budget exhausted"
+          }.to_json)
           nil
         end
 
+        # rubocop:disable-next Metrics/MethodLength -- structured fetch-failed warn
         def fetch_xml(target_url)
           return unless request_session && target_url
 
@@ -134,7 +144,12 @@ module Html2rss
         rescue Html2rss::RequestService::RequestBudgetExceeded
           raise
         rescue Html2rss::Error => error
-          Log.warn("#{self.class}: failed to fetch sitemap (#{error.class}: #{error.message})")
+          Log.warn({
+            event_name: 'sitemap.fetch_failed',
+            host: url.host,
+            error_class: error.class.name,
+            message: "#{self.class}: failed to fetch sitemap (#{error.class}: #{error.message})"
+          }.to_json)
           nil
         end
 

data/lib/html2rss/auto_source/scraper/wordpress_api/posts_endpoint.rb

@@ -59,7 +59,7 @@ module Html2rss
             nil
           end
 
-          def fetchable_page_scope?
+          def fetchable_page_scope? # rubocop:disable Metrics/MethodLength -- scope checks + structured warn
             return true if page_scope.fetchable?
 
             if page_scope.reason == :non_archive
@@ -70,7 +70,11 @@ module Html2rss
               return false
             end
 
-            logger.warn("#{WordpressApi}: unable to derive safe WordPress archive scope for #{page_url}")
+            logger.warn({
+              event_name: 'wordpress_api.unsafe_archive_scope',
+              host: page_url.host,
+              message: "#{WordpressApi}: unable to derive safe WordPress archive scope for #{page_url}"
+            }.to_json)
             false
           end
 

data/lib/html2rss/auto_source/scraper/wordpress_api.rb

@@ -75,19 +75,31 @@ module Html2rss
 
         attr_reader :parsed_body, :url, :request_session, :page_scope
 
+        # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- structured rescue logs
         def fetch_posts
           response = posts_response
           return unless response
 
           Array(response.parsed_body)
         rescue RequestService::UnsupportedResponseContentType => error
-          Log.warn("#{self.class}: unsupported WordPress API posts content type (#{error.message})")
+          Log.warn({
+            event_name: 'wordpress_api.unsupported_content_type',
+            host: url.host,
+            error_class: error.class.name,
+            message: "#{self.class}: unsupported WordPress API posts content type (#{error.message})"
+          }.to_json)
           nil
         rescue JSON::ParserError => error
-          Log.warn("#{self.class}: failed to parse WordPress API posts JSON (#{error.message})")
+          Log.warn({
+            event_name: 'wordpress_api.parse_failed',
+            host: url.host,
+            error_class: error.class.name,
+            message: "#{self.class}: failed to parse WordPress API posts JSON (#{error.message})"
+          }.to_json)
           nil
         end
 
+        # rubocop:disable-next Metrics/MethodLength -- structured fetch-failed warn
         def posts_response
           return unless request_session
           return unless (resolved_posts_url = posts_endpoint_url)
@@ -98,7 +110,12 @@ module Html2rss
             origin_url: url
           )
         rescue Html2rss::Error => error
-          Log.warn("#{self.class}: failed to fetch WordPress API posts (#{error.class}: #{error.message})")
+          Log.warn({
+            event_name: 'wordpress_api.fetch_failed',
+            host: url.host,
+            error_class: error.class.name,
+            message: "#{self.class}: failed to fetch WordPress API posts (#{error.class}: #{error.message})"
+          }.to_json)
           nil
         end
 

data/lib/html2rss/auto_source.rb

@@ -277,7 +277,12 @@ module Html2rss
     def run_scraper(instance)
       instance.map { |item| article_from_scraper_item(item, instance) }
     rescue *OPERATIONAL_ERRORS => error
-      Log.warn("#{self.class}: #{instance.class} quarantined #{error.class}: #{error.message}")
+      Log.warn({
+        event_name: 'auto_source.quarantined',
+        host: url.host,
+        error_class: error.class.name,
+        message: "#{self.class}: #{instance.class} quarantined #{error.class}: #{error.message}"
+      }.to_json)
       []
     end
 

data/lib/html2rss/error.rb

@@ -2,7 +2,13 @@
 
 module Html2rss
   # The Html2rss::Error base class.
-  class Error < StandardError; end
+  class Error < StandardError
+    # @return [Array<Hash{Symbol => Object}>, nil] tier attempt diagnostics when set by AutoFallback
+    attr_accessor :attempts
+
+    # @return [Hash{String => Object}, nil] allowlisted upstream transport telemetry when attached
+    attr_accessor :transport_meta
+  end
 
   # Raised when auto fallback exhausts all concrete tiers and extractors find no feed items.
   class NoFeedItemsExtracted < Error

data/lib/html2rss/feed_pipeline/auto_fallback.rb

@@ -30,12 +30,13 @@ module Html2rss
       ##
       # Mutable run state for one auto-fallback chain: attempts plus selected result.
       class AttemptState
-        attr_reader :attempts, :result, :last_response, :entry_resolution
+        attr_reader :attempts, :result, :last_response, :last_error, :entry_resolution
 
         def initialize
           @attempts = []
           @result = nil
           @last_response = nil
+          @last_error = nil
           @entry_resolution = nil
           @resolution_tried = false
           @aborted = false
@@ -70,7 +71,11 @@ module Html2rss
         # @param error [Exception] caught error
         # @return [void]
         def record_error(strategy:, error:)
-          @attempts << { strategy:, items_count: nil, error_class: error.class.name }
+          attempt = { strategy:, items_count: nil, error_class: error.class.name }
+          meta = error.is_a?(Html2rss::Error) ? error.transport_meta : nil
+          attempt[:transport_meta] = meta if meta&.any?
+          @attempts << attempt
+          @last_error = error
         end
 
         # @param strategy [Symbol] strategy that returned a response
@@ -78,6 +83,7 @@ module Html2rss
         # @param transport_meta [Hash, nil] optional allowlisted upstream telemetry
         # @return [void]
         def record_items(strategy:, items_count:, transport_meta: nil)
+          @last_error = nil
           attempt = { strategy:, items_count:, error_class: nil }
           attempt[:transport_meta] = transport_meta if transport_meta && !transport_meta.empty?
           @attempts << attempt
@@ -136,7 +142,7 @@ module Html2rss
         state = run_attempts
         return state.result if state.succeeded?
 
-        finalize_failure(attempts: state.attempts, response: state.last_response)
+        finalize_failure(state)
       end
 
       private
@@ -215,7 +221,7 @@ module Html2rss
         pipeline.deduplicated_articles(config:, response:, request_session:)
       end
 
-      # rubocop:disable-next Metrics/ParameterLists -- success kwargs match PipelineOutcome
+      # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- success kwargs + structured selected log
       def record_success(response:, strategy:, articles:, dedup_dropped:, admission_drops:, state:)
         attempt_count = state.attempts.size
         state.succeed!(
@@ -225,14 +231,35 @@ module Html2rss
         )
         return unless attempt_count > 1
 
-        Log.info("#{self.class}: auto selected strategy=#{strategy} after attempts=#{attempt_count} " \
-                 "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
-                 "budget_remaining=#{budget_remaining_label}")
+        Log.info({
+          event_name: 'auto_fallback.selected',
+          host: response.url.host,
+          strategy: strategy.to_s,
+          attempt_count:,
+          message: "#{self.class}: auto selected strategy=#{strategy} after attempts=#{attempt_count} " \
+                   "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
+                   "budget_remaining=#{budget_remaining_label}"
+        }.to_json)
       end
 
-      def finalize_failure(attempts:, response:)
-        surface_category = surface_category_for(response)
-        raise NoFeedItemsExtracted.new(attempts:, surface_category:)
+      def finalize_failure(state)
+        if raise_last_error?(state)
+          error = state.last_error
+          error.attempts = state.attempts if error.is_a?(Html2rss::Error)
+          raise error
+        end
+
+        raise NoFeedItemsExtracted.new(
+          attempts: state.attempts,
+          surface_category: surface_category_for(state.last_response)
+        )
+      end
+
+      def raise_last_error?(state)
+        error = state.last_error
+        return false if error.nil? || error.is_a?(RequestService::BotasaurusConfigurationError)
+
+        true
       end
 
       def surface_category_for(response)
@@ -247,8 +274,15 @@ module Html2rss
         detail = "host=#{host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
                  "budget_remaining=#{budget_remaining_label}"
         if error.is_a?(RequestService::RequestTimedOut)
-          Log.info("#{self.class}: auto fallback #{strategy} -> #{next_strategy} " \
-                   "after timeout=#{error.class} #{detail}")
+          Log.info({
+            event_name: 'auto_fallback.timeout',
+            host:,
+            strategy: strategy.to_s,
+            next_strategy: next_strategy.to_s,
+            error_class: error.class.name,
+            message: "#{self.class}: auto fallback #{strategy} -> #{next_strategy} " \
+                     "after timeout=#{error.class} #{detail}"
+          }.to_json)
         else
           Log.warn({
             event_name: 'auto_fallback.error',
@@ -264,9 +298,16 @@ module Html2rss
       end
 
       def log_info_fallback_zero_items(strategy:, next_strategy:, response:)
-        Log.info("#{self.class}: auto fallback #{strategy} -> #{next_strategy} after zero extracted items " \
-                 "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
-                 "budget_remaining=#{budget_remaining_label}")
+        host = response.url.host
+        Log.info({
+          event_name: 'auto_fallback.zero_items',
+          host:,
+          strategy: strategy.to_s,
+          next_strategy: next_strategy.to_s,
+          message: "#{self.class}: auto fallback #{strategy} -> #{next_strategy} after zero extracted items " \
+                   "host=#{host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
+                   "budget_remaining=#{budget_remaining_label}"
+        }.to_json)
       end
 
       def budget_remaining_label

data/lib/html2rss/feed_resolution.rb

@@ -285,10 +285,13 @@ module Html2rss
 
       def result(applied:, reason:, scrape_url:, probe_count:, winner_score:)
         scrape_host = Html2rss::Url.from_absolute(scrape_url).host
-        Log.info(
-          "FeedResolution: entry_host=#{entry_url.host} scrape_host=#{scrape_host} " \
-          "applied=#{applied} probe_count=#{probe_count} winner_score=#{winner_score.inspect} reason=#{reason}"
-        )
+        Log.info({
+          event_name: 'feed_resolution.result',
+          host: entry_url.host,
+          message: "FeedResolution: entry_host=#{entry_url.host} scrape_host=#{scrape_host} " \
+                   "applied=#{applied} probe_count=#{probe_count} winner_score=#{winner_score.inspect} " \
+                   "reason=#{reason}"
+        }.to_json)
         Result.new(entry_url: entry_url.to_s, scrape_url:, applied:, reason:, probe_count:, winner_score:)
       end
     end

data/lib/html2rss/request_service/blocked_surface.rb

@@ -47,6 +47,17 @@ module Html2rss
           message: 'Blocked surface detected: Vercel Security Checkpoint. ' \
                    'This site is a JS-rendered SPA behind Vercel edge protection. ' \
                    'Configure BOTASAURUS_SCRAPER_URL or target a direct listing URL.'
+        },
+        {
+          key: :http_403_forbidden,
+          min_matches: 2,
+          patterns: [
+            %r{<title>\s*403\s+forbidden\s*</title>}i,
+            %r{<h1>\s*403\s+forbidden\s*</h1>}i
+          ],
+          message: 'Blocked surface detected: HTTP 403 Forbidden access block page. ' \
+                   'Target a direct listing URL, configure BOTASAURUS_SCRAPER_URL, ' \
+                   'or run from an environment that is not IP-blocked.'
         }
       ].freeze
 

data/lib/html2rss/request_service/botasaurus_contract.rb

@@ -198,6 +198,11 @@ module Html2rss
           "Botasaurus scrape failed (#{details.join(', ')})."
         end
 
+        # @return [Hash{String => Object}] allowlisted diagnostics plus error_category (frozen)
+        def transport_meta
+          diagnostics.merge('error_category' => error_category).freeze
+        end
+
         private
 
         attr_reader :payload, :transport_status

data/lib/html2rss/request_service/botasaurus_strategy.rb

@@ -49,14 +49,16 @@ module Html2rss
       end
 
       def raise_from_error!(error)
-        raise BlockedSurfaceDetected, "Blocked surface detected: #{error.challenge_message}" if error.challenge_block?
-
-        if error.timeout?
-          log_timeout!(reason: 'botasaurus_upstream')
-          raise RequestTimedOut.new(error.failure_message, timeout_phase: error.timeout_phase)
-        end
-
-        raise BotasaurusServiceError, error.failure_message
+        err = if error.challenge_block?
+                BlockedSurfaceDetected.new("Blocked surface detected: #{error.challenge_message}")
+              elsif error.timeout?
+                log_timeout!(reason: 'botasaurus_upstream')
+                RequestTimedOut.new(error.failure_message, timeout_phase: error.timeout_phase)
+              else
+                BotasaurusServiceError.new(error.failure_message)
+              end
+        err.transport_meta = error.transport_meta
+        raise err
       end
 
       def response_url(final_url)

data/lib/html2rss/request_service/httpx_strategy.rb

@@ -60,8 +60,18 @@ module Html2rss
 
       private
 
+      # Caps one HTTPX execute (including internal MAX_RETRIES) so a hanging
+      # :default tier cannot consume the full shared auto-fallback budget.
+      #
+      # @return [Float] monotonic deadline
       def request_deadline
-        monotonic_now + ctx.budget.effective_timeout_seconds(fallback: ctx.policy.total_timeout_seconds)
+        budget_timeout = ctx.budget.effective_timeout_seconds(fallback: ctx.policy.total_timeout_seconds)
+        monotonic_now + [budget_timeout, attempt_timeout_ceiling].min
+      end
+
+      # @return [Float] connect + read ceiling for a single attempt
+      def attempt_timeout_ceiling
+        (ctx.policy.connect_timeout_seconds + ctx.policy.read_timeout_seconds).to_f
       end
 
       def reset_redirect_tracking!

data/lib/html2rss/request_service/strategy.rb

@@ -111,18 +111,24 @@ module Html2rss
 
       # @param reason [String] timeout classification (budget_exhausted / transport)
       # @return [void]
-      # rubocop:disable-next Metrics/AbcSize -- structured timeout fields stay in one log line
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- structured timeout fields stay in one log line
       def log_timeout!(reason:)
         remaining = ctx.budget.remaining_timeout_seconds
         remaining_label = remaining.nil? ? 'untracked' : format('%.3f', remaining)
+        host = ctx.url.host
         detail = [
           "strategy=#{self.class.name}",
-          "host=#{ctx.url.host}",
+          "host=#{host}",
           "elapsed=#{format('%.3f', ctx.budget.elapsed_seconds)}s",
           "budget_remaining=#{remaining_label}",
           "reason=#{reason}"
         ]
-        Log.info("#{self.class}: request timeout #{detail.join(' ')}")
+        Log.info({
+          event_name: 'request_service.timeout',
+          host:,
+          strategy: self.class.name,
+          message: "#{self.class}: request timeout #{detail.join(' ')}"
+        }.to_json)
       end
 
       # @param error [StandardError]

data/lib/html2rss/request_service.rb

@@ -98,24 +98,49 @@ module Html2rss
       # @return [Response] the response from the executed strategy.
       # @raise [UnknownStrategy] if the strategy is not registered.
       def execute(ctx, strategy: default_strategy_name)
-        strategy_sym = strategy.to_sym
+        strategy_sym = resolve_strategy_name(strategy, relation: ctx.relation, host: ctx.url.host)
         strategy_class = STRATEGIES.fetch(strategy_sym) do
           raise UnknownStrategy,
                 "The strategy '#{strategy}' is not known. Available strategies: #{strategy_names.join(', ')}"
         end
 
-        warn_migration_strategy(strategy_sym) if MIGRATION_REPLACEMENTS.key?(strategy_sym)
         strategy_class.new(ctx).execute
       end
 
       private
 
-      def warn_migration_strategy(strategy)
-        replacement = MIGRATION_REPLACEMENTS.fetch(strategy)
-        message = "RequestService: strategy ':#{strategy}' is deprecated for migration and will be removed " \
-                  "in a future release. Use ':#{replacement}' instead."
-        warn(message, category: :deprecated)
-        Log.warn(message)
+      ##
+      # Resolves deprecated migration aliases to their replacement strategy name.
+      # @param strategy [Symbol, String] requested strategy name
+      # @param relation [Symbol] request relation (+ :initial + or follow-up)
+      # @param host [String, nil] request host for structured deprecation telemetry
+      # @return [Symbol] canonical strategy name after migration remapping
+      def resolve_strategy_name(strategy, relation:, host:)
+        strategy_sym = strategy.to_sym
+        replacement = MIGRATION_REPLACEMENTS[strategy_sym]
+        return strategy_sym unless replacement
+
+        warn_migration_strategy(strategy_sym, replacement, relation:, host:)
+        replacement
+      end
+
+      ##
+      # Emits a structured +strategy_deprecated+ warning once per session (+ :initial + only).
+      # @param strategy [Symbol] deprecated strategy alias
+      # @param replacement [Symbol] preferred strategy name
+      # @param relation [Symbol] request relation
+      # @param host [String, nil] request host
+      # @return [void]
+      def warn_migration_strategy(strategy, replacement, relation:, host:)
+        return unless relation == :initial
+
+        Log.warn({
+          event_name: 'strategy_deprecated',
+          strategy: strategy.to_s,
+          replacement: replacement.to_s,
+          host:,
+          message: "#{name}: strategy=#{strategy.inspect} is deprecated; using #{replacement.inspect} instead."
+        }.to_json)
       end
     end
   end

data/lib/html2rss/sst/normalizer.rb

@@ -119,17 +119,29 @@ module Html2rss
 
         body = parsed.at_css('body')
         if body
-          Html2rss::Log.warn('sst.normalizer root fallback: body')
+          Html2rss::Log.warn({
+            event_name: 'sst.normalizer.root_fallback',
+            reason: 'body',
+            message: 'sst.normalizer root fallback: body'
+          }.to_json)
           return body
         end
 
         first = parsed.element_children.find { |child| element_root?(child) }
         if first
-          Html2rss::Log.warn('sst.normalizer root fallback: first element child')
+          Html2rss::Log.warn({
+            event_name: 'sst.normalizer.root_fallback',
+            reason: 'first_element_child',
+            message: 'sst.normalizer root fallback: first element child'
+          }.to_json)
           return first
         end
 
-        Html2rss::Log.warn('sst.normalizer root fallback: self')
+        Html2rss::Log.warn({
+          event_name: 'sst.normalizer.root_fallback',
+          reason: 'self',
+          message: 'sst.normalizer root fallback: self'
+        }.to_json)
         parsed
       end
 
@@ -146,7 +158,11 @@ module Html2rss
 
         if @node_count >= MAX_NODES && !@degraded
           @degraded = true
-          Html2rss::Log.warn("sst.normalizer MAX_NODES=#{MAX_NODES} breached; degrading to semantic-tag-only")
+          Html2rss::Log.warn({
+            event_name: 'sst.normalizer.max_nodes',
+            max_nodes: MAX_NODES,
+            message: "sst.normalizer MAX_NODES=#{MAX_NODES} breached; degrading to semantic-tag-only"
+          }.to_json)
         end
 
         return if @degraded && !SEMANTIC_DEGRADE_TAGS.include?(tag)

data/lib/html2rss/syndication/discovery.rb

@@ -60,7 +60,11 @@ module Html2rss
         ).tap do |response|
           next unless response
 
-          Log.info("Syndication::Discovery: host=#{page.host} selected_feed_url=#{response.url}")
+          Log.info({
+            event_name: 'syndication.discovery.selected',
+            host: page.host,
+            message: "Syndication::Discovery: host=#{page.host} selected_feed_url=#{response.url}"
+          }.to_json)
         end
       end
 

data/lib/html2rss/syndication/parser.rb

@@ -6,7 +6,7 @@ module Html2rss
   module Syndication
     ##
     # Parses RSS 2.0 and Atom documents into AutoSource article hashes.
-    module Parser
+    module Parser # rubocop:disable Metrics/ModuleLength -- feed formats + structured parse warn
       module_function
 
       ##
@@ -29,7 +29,11 @@ module Html2rss
 
         items_from(feed, base_url:).filter_map { |item| article_hash(item, base_url:) }
       rescue RSS::Error => error
-        Log.warn("Syndication::Parser: failed to parse feed (#{error.class}: #{error.message})")
+        Log.warn({
+          event_name: 'syndication.parse_failed',
+          error_class: error.class.name,
+          message: "Syndication::Parser: failed to parse feed (#{error.class}: #{error.message})"
+        }.to_json)
         []
       end
 

data/lib/html2rss/version.rb

@@ -2,6 +2,6 @@
 
 module Html2rss
   # Current application version.
-  VERSION = '0.32.0'
+  VERSION = '0.32.2'
   public_constant :VERSION
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: html2rss
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.32.2
 platform: ruby
 authors:
 - Gil Desmarais
@@ -478,7 +478,7 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  changelog_uri: https://github.com/html2rss/html2rss/releases/tag/v0.32.0
+  changelog_uri: https://github.com/html2rss/html2rss/releases/tag/v0.32.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: