html2rss 0.32.0 → 0.32.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4841672d87f3828928fa35646176d878469ade0afce9f9e6a119ccd1cf3251ae
-  data.tar.gz: 618382810f59ff95713064d91a2ccb6df4c0dd2cf6287f31127cddd5848e8dbd
+  metadata.gz: d1d74d19e935fcf05c7bd0893f2113dfac1e6639de926ef8844159118ad13ff5
+  data.tar.gz: 3999a5e55251f993b6721d9d3f8c03b8c7588fa0834499a53c808789bb7a3ded
 SHA512:
-  metadata.gz: 7abf8800a5943fca86ed9fa19058a1957ed101d52db70fd75042bda91abc2a9070d3bb5e6b0129e18103ebf407de2ea97a5e1a826cec3b5a7c0f21c12d0dfd61
-  data.tar.gz: 7831958f9d9b2af2db632b341cd8c902b45ed78feaf12dc21ee4f9c80c72237d56acba58e1b2aa7b0c842fc6dd3626beb48fd0e08ef932730920e33c23eb2f4b
+  metadata.gz: 1c7bea03d8553b2e8ec76c8216b57e0f07b20157cb1c1710c31b4730281b410c95b61541fae56bc4d3853cedf5e62854e0255b920607e28cfa902e941e779953
+  data.tar.gz: 6911fdce7df3238bbe27b28b6a8f747077b12a5cd949b12e4cc0bddadff1433f0ef56662cc361f7d80c90924fe38813ac6584ef0ec08a6b39b0859bc4067d2d4

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
@@ -230,9 +236,24 @@ module Html2rss
                  "budget_remaining=#{budget_remaining_label}")
       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)

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.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/version.rb

@@ -2,6 +2,6 @@
 
 module Html2rss
   # Current application version.
-  VERSION = '0.32.0'
+  VERSION = '0.32.1'
   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.1
 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.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: