html2rss 0.23.0 → 0.24.0

data/lib/html2rss/feed_pipeline/auto_fallback.rb

@@ -5,9 +5,10 @@ module Html2rss
     # Retries feed extraction across concrete request strategies for the :auto plan.
     #
     # Owned by {FeedPipeline}; invoked only after {StrategyPlan} resolves +:auto+.
+    # Hosted by the pipeline instance: session + extract call back into FeedPipeline.
     class AutoFallback
       # Ordered list of concrete request strategies attempted by the :auto plan.
-      CHAIN = %i[faraday botasaurus browserless].freeze
+      CHAIN = %i[faraday botasaurus].freeze
 
       # Error classes that should abort auto fallback immediately.
       NON_FALLBACK_ERRORS = [
@@ -44,34 +45,49 @@ module Html2rss
 
         # @param strategy [Symbol] strategy that returned a response
         # @param items_count [Integer] extracted article count
+        # @param transport_meta [Hash, nil] optional allowlisted upstream telemetry
         # @return [void]
-        def record_items(strategy:, items_count:)
-          @attempts << { strategy:, items_count:, error_class: nil }
+        def record_items(strategy:, items_count:, transport_meta: nil)
+          attempt = { strategy:, items_count:, error_class: nil }
+          attempt[:transport_meta] = transport_meta if transport_meta && !transport_meta.empty?
+          @attempts << attempt
         end
 
         # @param response [RequestService::Response] successful response
         # @param articles [Array] extracted articles
+        # @param dedup_dropped [Integer] articles removed by deduplication
+        # @param selected_strategy [Symbol] concrete strategy that produced items
+        # @param attempt_count [Integer] number of attempts recorded for this chain
         # @return [void]
-        def succeed!(response:, articles:)
-          @result = { response:, articles: }
+        def succeed!(response:, articles:, dedup_dropped:, selected_strategy:, attempt_count:)
+          @result = PipelineOutcome.new(
+            response:,
+            articles:,
+            dedup_dropped:,
+            selected_strategy:,
+            attempt_count:,
+            strategy_attempts: attempts
+          )
         end
       end
 
       ##
       # @param strategies [Array<Symbol>] ordered concrete strategies for fallback
       # @param budget [RequestService::Budget] shared request budget across retries
-      # @param session_for [Proc] request session factory proc
-      # @param articles_for [Proc] article extraction proc
+      # @param pipeline [Html2rss::FeedPipeline] host for session + article extraction
+      # @param config [Html2rss::Config] validated feed config
+      # @param resources [Html2rss::FeedPipeline::RuntimePolicy::Resources] budget + policy
       # @return [void]
-      def initialize(strategies:, budget:, session_for:, articles_for:)
+      def initialize(strategies:, budget:, pipeline:, config:, resources:)
         @strategies = strategies
         @budget = budget
-        @session_for = session_for
-        @articles_for = articles_for
+        @pipeline = pipeline
+        @config = config
+        @resources = resources
       end
 
       ##
-      # @return [Hash{Symbol => Object}] pipeline state containing :response and :articles
+      # @return [Html2rss::FeedPipeline::PipelineOutcome] scrape-finished state for materialization
       def call
         state = run_attempts
         return state.result if state.succeeded?
@@ -81,7 +97,7 @@ module Html2rss
 
       private
 
-      attr_reader :strategies, :budget, :session_for, :articles_for
+      attr_reader :strategies, :budget, :pipeline, :config, :resources
 
       def run_attempts
         AttemptState.new.tap do |state|
@@ -93,7 +109,7 @@ module Html2rss
       end
 
       def attempt(strategy:, next_strategy:, state:)
-        request_session = session_for.call(strategy:, budget:)
+        request_session = pipeline.request_session_for(config, strategy:, resources:)
         response = fetch_response(request_session:, strategy:, next_strategy:, state:)
         return unless response
 
@@ -106,38 +122,65 @@ module Html2rss
         raise
       rescue StandardError => error
         state.record_error(strategy:, error:)
-        log_warn_fallback_error(strategy:, next_strategy:, error:) if next_strategy
-        Log.debug("#{self.class}: strategy=#{strategy} error=#{error.class}: #{error.message}")
+        log_fallback_error(strategy:, next_strategy:, error:, request_session:) if next_strategy
         nil
       end
 
       def process_response(response:, strategy:, next_strategy:, request_session:, state:)
-        articles = articles_for.call(response:, request_session:)
+        articles, dedup_dropped = articles_for(response:, request_session:)
         items_count = articles.size
-        state.record_items(strategy:, items_count:)
-        Log.debug("#{self.class}: strategy=#{strategy} items=#{items_count}")
-        return record_success(response:, strategy:, articles:, state:) if items_count.positive?
+        state.record_items(strategy:, items_count:, transport_meta: response.transport_meta)
+        Log.debug("#{self.class}: strategy=#{strategy} items=#{items_count} " \
+                  "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
+                  "budget_remaining=#{budget_remaining_label}")
+        return record_success(response:, strategy:, articles:, dedup_dropped:, state:) if items_count.positive?
 
-        log_info_fallback_zero_items(strategy:, next_strategy:) if next_strategy
+        log_info_fallback_zero_items(strategy:, next_strategy:, response:) if next_strategy
       end
 
-      def record_success(response:, strategy:, articles:, state:)
-        state.succeed!(response:, articles:)
-        return unless state.attempts.size > 1
+      def articles_for(response:, request_session:)
+        pipeline.deduplicated_articles(config:, response:, request_session:)
+      end
+
+      def record_success(response:, strategy:, articles:, dedup_dropped:, state:)
+        attempt_count = state.attempts.size
+        state.succeed!(response:, articles:, dedup_dropped:, selected_strategy: strategy, attempt_count:)
+        return unless attempt_count > 1
 
-        Log.info("#{self.class}: auto selected strategy=#{strategy} after attempts=#{state.attempts.size}")
+        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}")
       end
 
       def finalize_failure(attempts:)
         raise NoFeedItemsExtracted.new(attempts:)
       end
 
-      def log_warn_fallback_error(strategy:, next_strategy:, error:)
-        Log.warn("#{self.class}: auto fallback #{strategy} -> #{next_strategy} after error=#{error.class}")
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def log_fallback_error(strategy:, next_strategy:, error:, request_session:)
+        host = request_session.url.host
+        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}")
+        else
+          Log.warn("#{self.class}: auto fallback #{strategy} -> #{next_strategy} " \
+                   "after error=#{error.class} #{detail}")
+        end
+        Log.debug("#{self.class}: strategy=#{strategy} error=#{error.class}: #{error.message} #{detail}")
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+      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}")
       end
 
-      def log_info_fallback_zero_items(strategy:, next_strategy:)
-        Log.info("#{self.class}: auto fallback #{strategy} -> #{next_strategy} after zero extracted items")
+      def budget_remaining_label
+        remaining = budget.remaining_timeout_seconds
+        remaining.nil? ? 'untracked' : format('%.3f', remaining)
       end
     end
   end

data/lib/html2rss/feed_pipeline.rb

@@ -4,8 +4,13 @@ module Html2rss
   ##
   # Builds feeds from validated config through request, extraction, and rendering stages.
   class FeedPipeline
-    # Bundle of inputs shared by selector and auto-source article collection.
-    ExtractionContext = Data.define(:config, :response, :request_session)
+    # Scrape-finished facts after request + extraction + dedup (before Channel/Status materialize).
+    # selected_strategy: set on :auto success; nil otherwise.
+    # attempt_count: auto attempts attempted; 0 outside :auto.
+    # strategy_attempts: auto attempt hashes (with optional transport_meta); empty outside :auto.
+    PipelineOutcome = Data.define(
+      :response, :articles, :dedup_dropped, :selected_strategy, :attempt_count, :strategy_attempts
+    )
 
     ##
     # @param raw_config [Hash{Symbol => Object}] user-provided feed config
@@ -14,34 +19,55 @@ module Html2rss
     end
 
     ##
-    # @return [RSS::Rss] generated RSS feed
-    def to_rss
-      run do |response:, config:, articles:|
-        channel = Html2rss::Channel.new(response, overrides: config.channel)
-        FeedBuilder.build(:rss, channel:, articles:, stylesheets: config.stylesheets)
-      end
+    # Runs the pipeline once and returns an opaque, Marshal-cacheable result.
+    #
+    # @return [Html2rss::FeedResult]
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- Status kwargs stay co-located with Channel
+    def to_result
+      config = Config.from_hash(raw_config, params: raw_config[:params])
+      outcome = pipeline_outcome_for(config)
+      channel = Channel.from_response(outcome.response, overrides: config.channel)
+      status = Status.build(
+        articles: outcome.articles,
+        dedup_dropped: outcome.dedup_dropped,
+        selected_strategy: outcome.selected_strategy,
+        attempt_count: outcome.attempt_count,
+        strategy_attempts: outcome.strategy_attempts
+      )
+      FeedResult.new(channel:, articles: outcome.articles, status:, stylesheets: config.stylesheets)
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
-    ##
-    # @return [Hash] generated JSONFeed 1.1 payload
-    def to_json_feed
-      run do |response:, config:, articles:|
-        channel = Html2rss::Channel.new(response, overrides: config.channel)
-        FeedBuilder.build(:json_feed, channel:, articles:)
-      end
+    # @api private Host seam for {AutoFallback} (and single-strategy path).
+    # @param config [Html2rss::Config]
+    # @param strategy [Symbol]
+    # @param resources [Html2rss::FeedPipeline::RuntimePolicy::Resources]
+    # @return [Html2rss::RequestSession]
+    def request_session_for(config, strategy:, resources:)
+      RequestSession.build(
+        config:,
+        strategy:,
+        budget: resources.budget,
+        policy: resources.policy
+      )
+    end
+
+    # @api private Host seam for {AutoFallback} (and single-strategy path).
+    # @param config [Html2rss::Config]
+    # @param response [Html2rss::RequestService::Response]
+    # @param request_session [Html2rss::RequestSession]
+    # @return [Array(Array<Html2rss::Article>, Integer)] unique articles and drop count
+    def deduplicated_articles(config:, response:, request_session:)
+      collected = collect_articles(config:, response:, request_session:)
+      unique = Article::Deduplicator.new(collected).call
+      [unique, collected.size - unique.size]
     end
 
     private
 
     attr_reader :raw_config
 
-    def run
-      config = Config.from_hash(raw_config, params: raw_config[:params])
-      state = pipeline_state_for(config)
-      yield response: state.fetch(:response), config:, articles: state.fetch(:articles)
-    end
-
-    def pipeline_state_for(config)
+    def pipeline_outcome_for(config)
       plan = StrategyPlan.resolve(config.strategy)
       resources = RuntimePolicy.resources_for(config)
       if plan.is_a?(StrategyPlan::Auto)
@@ -54,52 +80,33 @@ module Html2rss
     def run_pipeline_for_strategy(config, strategy:, resources:)
       request_session = request_session_for(config, strategy:, resources:)
       response = request_session.fetch_initial_response
-      articles = deduplicated_articles(
-        ExtractionContext.new(config:, response:, request_session:)
+      articles, dedup_dropped = deduplicated_articles(config:, response:, request_session:)
+      PipelineOutcome.new(
+        response:, articles:, dedup_dropped:, selected_strategy: nil, attempt_count: 0, strategy_attempts: []
       )
-      { response:, articles: }
     end
 
-    def request_session_for(config, strategy:, resources:)
-      RequestSession.build(
-        config:,
-        strategy:,
-        budget: resources.budget,
-        policy: resources.policy
-      )
-    end
-
-    def deduplicated_articles(extraction)
-      Article::Deduplicator.new(collect_articles(extraction)).call
-    end
-
-    # rubocop:disable Metrics/MethodLength
     def run_auto_pipeline(config, resources:)
       AutoFallback.new(
         strategies: AutoFallback::CHAIN,
         budget: resources.budget,
-        session_for: lambda do |strategy:, budget:|
-          budget.effective_timeout_seconds(fallback: resources.policy.total_timeout_seconds)
-          request_session_for(config, strategy:, resources:)
-        end,
-        articles_for: lambda do |response:, request_session:|
-          deduplicated_articles(ExtractionContext.new(config:, response:, request_session:))
-        end
+        pipeline: self,
+        config:,
+        resources:
       ).call
     end
-    # rubocop:enable Metrics/MethodLength
 
-    def collect_articles(extraction)
-      selector_articles(extraction) + auto_source_articles(extraction)
+    def collect_articles(config:, response:, request_session:)
+      selector_articles(config:, response:, request_session:) +
+        auto_source_articles(config:, response:, request_session:)
     end
 
     # rubocop:disable Metrics/MethodLength
-    def selector_articles(extraction)
-      config = extraction.config
+    def selector_articles(config:, response:, request_session:)
       return [] unless (selectors = config.selectors)
 
-      page_responses = extraction.request_session.page_responses(
-        extraction.response,
+      page_responses = request_session.page_responses(
+        response,
         pagination_config: selectors.dig(:items, :pagination)
       )
 
@@ -114,10 +121,10 @@ module Html2rss
     end
     # rubocop:enable Metrics/MethodLength
 
-    def auto_source_articles(extraction)
-      return [] unless (auto_source = extraction.config.auto_source)
+    def auto_source_articles(config:, response:, request_session:)
+      return [] unless (auto_source = config.auto_source)
 
-      AutoSource.new(extraction.response, auto_source, request_session: extraction.request_session).articles
+      AutoSource.new(response, auto_source, request_session:).articles
     end
   end
 end

data/lib/html2rss/feed_result.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Closed Marshal-cacheable handle for one scrape.
+  #
+  # Frozen consumer query/render set (do not grow without an explicit contract change):
+  # {#empty?}, {#channel_title}, {#to_rss}, {#to_json_feed}, and {#status}.
+  #
+  # Non-goals: no Channel reader, no Articles reader, no peephole into scrape internals.
+  # html2rss-web and other consumers must use only this surface.
+  #
+  # @note Gem contract: instances must round-trip through +Marshal.dump+ / +Marshal.load+
+  #   so web can cache one scrape and render RSS or JSON Feed on read. Loaded results
+  #   are re-frozen via private {#marshal_load}. For trusted cache reads only,
+  #   +Marshal.load(payload, freeze: true)+ is also safe.
+  class FeedResult
+    ##
+    # @param channel [Html2rss::Channel] channel metadata (internal; not exposed on the public API)
+    # @param articles [Array<Html2rss::Article>] extracted articles (deduplicated; not exposed)
+    # @param status [Html2rss::Status] pipeline telemetry
+    # @param stylesheets [Array<Hash>] optional RSS stylesheet configs
+    def initialize(channel:, articles:, status:, stylesheets: [])
+      raise ArgumentError, 'channel must be a Html2rss::Channel' unless channel.is_a?(Channel)
+      raise ArgumentError, 'status must be a Html2rss::Status' unless status.is_a?(Status)
+
+      articles = Array(articles)
+      raise ArgumentError, 'articles must all be Html2rss::Article' unless articles.all?(Article)
+
+      @channel = channel
+      @articles = articles.dup.freeze
+      @status = status
+      @stylesheets = freeze_stylesheets(stylesheets)
+      freeze
+    end
+
+    ##
+    # @return [Boolean] true when the scrape produced no items
+    def empty? = @articles.empty?
+
+    ##
+    # Channel title string only — does not expose the channel object.
+    #
+    # @return [String] title from the materialized channel
+    def channel_title = @channel.title
+
+    ##
+    # @return [RSS::Rss] RSS 2.0 document
+    def to_rss
+      FeedBuilder::Rss.new(
+        channel: @channel,
+        articles: @articles,
+        stylesheets: @stylesheets,
+        generator: status.to_generator_comment
+      ).call
+    end
+
+    ##
+    # @param feed_url [String, nil] optional self URL for JSON Feed (+feed_url+)
+    # @return [Hash] JSON Feed 1.1 hash
+    def to_json_feed(feed_url: nil)
+      FeedBuilder::JsonFeed.new(
+        channel: @channel,
+        articles: @articles,
+        feed_url:,
+        user_comment: status.to_generator_comment
+      ).call
+    end
+
+    ##
+    # @return [Html2rss::Status] frozen scraper tallies, dedup count, and generator formatter.
+    #   {#to_h} on +status+ is a stable consumer contract for observability payloads.
+    attr_reader :status
+
+    private
+
+    # Constructor payload for Marshal (avoids default ivar thaw). Rebuilds via {#initialize}.
+    def marshal_dump = [@channel, @articles, @status, @stylesheets]
+
+    def marshal_load((channel, articles, status, stylesheets))
+      initialize(channel:, articles:, status:, stylesheets:)
+    end
+
+    def freeze_stylesheets(stylesheets)
+      Array(stylesheets).map do |sheet|
+        sheet.to_h.transform_keys(&:to_sym).transform_values do |value|
+          value.is_a?(String) ? value.dup.freeze : value
+        end.freeze
+      end.freeze
+    end
+  end
+end

data/lib/html2rss/request_service/botasaurus_contract.rb

@@ -10,7 +10,7 @@ module Html2rss
       # Default Botasaurus scrape options when no explicit config is provided.
       DEFAULT_OPTIONS = {
         navigation_mode: 'auto',
-        max_retries: 2,
+        max_retries: 1,
         headless: false
       }.freeze
 
@@ -30,6 +30,17 @@ module Html2rss
         lang
       ].freeze
 
+      # Allowlisted upstream response keys exposed as Response#transport_meta.
+      META_KEYS = %w[
+        request_id strategy_used render_ms challenge_detected blocked_detected attempts error_category
+      ].freeze
+
+      # Remaining seconds at or below which Botasaurus retries are disabled.
+      TIGHT_BUDGET_SECONDS = 12
+
+      # Seconds reserved from remaining budget before setting wait_timeout_seconds.
+      BUDGET_WAIT_RESERVE_SECONDS = 2
+
       # Parsed Botasaurus response wrapper.
       class ParsedResponse
         # Fallback headers when upstream omits response headers.
@@ -90,6 +101,9 @@ module Html2rss
         # @return [String, nil] final URL reported by upstream
         def final_url = payload['final_url']
 
+        # @return [Hash{String => Object}] allowlisted upstream telemetry (frozen)
+        def transport_meta = payload.slice(*META_KEYS).compact.freeze
+
         private
 
         attr_reader :payload, :transport_status
@@ -109,6 +123,7 @@ module Html2rss
       ##
       # @param url [Html2rss::Url] canonical URL to scrape
       # @param options [Hash] validated request.botasaurus options
+      # @param remaining_timeout_seconds [Numeric, nil] shared request budget remainder for clamps
       # @option options [String] :navigation_mode
       # @option options [Integer] :max_retries
       # @option options [String] :wait_for_selector
@@ -121,14 +136,15 @@ module Html2rss
       # @option options [String] :user_agent
       # @option options [Array<Integer>] :window_size
       # @option options [String] :lang
-      def initialize(url:, options: {})
+      def initialize(url:, options: {}, remaining_timeout_seconds: nil)
         @url = url
         @options = options
+        @remaining_timeout_seconds = remaining_timeout_seconds
       end
 
-      # @return [Hash] payload for POST /scrape
+      # @return [Hash] payload for POST /scrape (budget-clamped when remaining is known)
       def request_payload
-        DEFAULT_OPTIONS.merge(filtered_options).merge(url: url.to_s)
+        DEFAULT_OPTIONS.merge(filtered_options).merge(url: url.to_s).then { clamp_for_budget(_1) }
       end
 
       # @param transport_response [Faraday::Response] upstream HTTP response
@@ -145,13 +161,25 @@ module Html2rss
 
       private
 
-      attr_reader :url, :options
+      attr_reader :url, :options, :remaining_timeout_seconds
 
       def filtered_options
         OPTION_KEYS.each_with_object({}) do |key, normalized|
           normalized[key] = options[key] if options.key?(key)
         end
       end
+
+      def clamp_for_budget(payload)
+        remaining = remaining_timeout_seconds
+        return payload if remaining.nil?
+
+        clamped = payload.dup
+        clamped[:max_retries] = 0 if remaining <= TIGHT_BUDGET_SECONDS
+        budget_wait = [1, (remaining - BUDGET_WAIT_RESERVE_SECONDS).floor].max
+        configured = clamped[:wait_timeout_seconds]
+        clamped[:wait_timeout_seconds] = configured ? [configured, budget_wait].min : budget_wait
+        clamped
+      end
     end
   end
 end

data/lib/html2rss/request_service/botasaurus_strategy.rb

@@ -27,7 +27,8 @@ module Html2rss
           body: parsed_response.html,
           headers: parsed_response.headers,
           url: response_url(parsed_response.final_url),
-          status: parsed_response.status
+          status: parsed_response.status,
+          transport_meta: parsed_response.transport_meta
         )
       end
 
@@ -52,7 +53,11 @@ module Html2rss
       end
 
       def contract
-        @contract ||= BotasaurusContract.new(url: ctx.url, options: ctx.request.fetch(:botasaurus, {}))
+        @contract ||= BotasaurusContract.new(
+          url: ctx.url,
+          options: ctx.request.fetch(:botasaurus, {}),
+          remaining_timeout_seconds: attempt_timeout_seconds
+        )
       end
 
       def client
@@ -60,9 +65,13 @@ module Html2rss
       end
 
       def request_options
-        timeout = ctx.budget.effective_timeout_seconds(fallback: ctx.policy.total_timeout_seconds)
+        { timeout: attempt_timeout_seconds.to_i }
+      end
 
-        { timeout: timeout.to_i }
+      def attempt_timeout_seconds
+        @attempt_timeout_seconds ||= ctx.budget.effective_timeout_seconds(
+          fallback: ctx.policy.total_timeout_seconds
+        )
       end
 
       def content_type_header

data/lib/html2rss/request_service/budget.rb

@@ -82,11 +82,16 @@ module Html2rss
       def remaining_timeout_seconds
         return unless @total_timeout_seconds
 
-        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
-        remaining = @total_timeout_seconds - elapsed
+        remaining = @total_timeout_seconds - elapsed_seconds
         [remaining, 0.0].max
       end
 
+      ##
+      # @return [Float] seconds since this budget was created
+      def elapsed_seconds
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+      end
+
       ##
       # Resolves wall-clock seconds for the next adapter attempt.
       #

data/lib/html2rss/request_service/response.rb

@@ -7,12 +7,16 @@ module Html2rss
     ##
     # To be used by strategies to provide their response.
     class Response
+      # Default when a strategy does not attach transport telemetry.
+      EMPTY_TRANSPORT_META = {}.freeze
+
       ##
       # @param body [String] the body of the response
       # @param url [Html2rss::Url] the final request URL
       # @param headers [Hash] the headers of the response
       # @param status [Integer, nil] the HTTP status code when available
-      def initialize(body:, url:, headers: {}, status: nil)
+      # @param transport_meta [Hash] allowlisted upstream telemetry (frozen when present)
+      def initialize(body:, url:, headers: {}, status: nil, transport_meta: EMPTY_TRANSPORT_META)
         @body = body
 
         headers = headers.dup
@@ -22,6 +26,7 @@ module Html2rss
         @headers = headers
         @status = status
         @url = url
+        @transport_meta = transport_meta.nil? || transport_meta.empty? ? EMPTY_TRANSPORT_META : transport_meta.freeze
       end
 
       # @return [String] the raw body of the response
@@ -36,6 +41,9 @@ module Html2rss
       # @return [Html2rss::Url] the URL of the response
       attr_reader :url
 
+      # @return [Hash] allowlisted upstream transport telemetry
+      attr_reader :transport_meta
+
       # @return [String] normalized content type header value
       def content_type = header('content-type').to_s
 

data/lib/html2rss/request_service/strategy.rb

@@ -86,6 +86,9 @@ module Html2rss
 
       def check_timeout!
         ctx.budget.effective_timeout_seconds(fallback: ctx.policy.total_timeout_seconds)
+      rescue RequestTimedOut
+        log_timeout!(reason: 'budget_exhausted')
+        raise
       end
 
       # @return [ResponseGuard, nil]
@@ -96,6 +99,8 @@ module Html2rss
       # @raise [StandardError]
       def handle_error(error)
         if timeout_error?(error)
+          log_timeout!(reason: 'transport')
+          Log.debug("#{self.class}: transport timeout message=#{error.message}")
           raise RequestTimedOut, error.message
         elsif connection_error?(error)
           translate_connection_error(error)
@@ -104,6 +109,23 @@ module Html2rss
         end
       end
 
+      # @param reason [String] timeout classification (budget_exhausted / transport)
+      # @return [void]
+      # rubocop:disable Metrics/AbcSize -- 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)
+        detail = [
+          "strategy=#{self.class.name}",
+          "host=#{ctx.url.host}",
+          "elapsed=#{format('%.3f', ctx.budget.elapsed_seconds)}s",
+          "budget_remaining=#{remaining_label}",
+          "reason=#{reason}"
+        ]
+        Log.info("#{self.class}: request timeout #{detail.join(' ')}")
+      end
+      # rubocop:enable Metrics/AbcSize
+
       # @param error [StandardError]
       # @return [void]
       # @raise [StandardError]

data/lib/html2rss/request_session.rb

@@ -109,6 +109,10 @@ module Html2rss
       visited_urls.add(normalize_url(url))
     end
 
+    ##
+    # @return [Html2rss::Url] the session's current request URL
+    def url = context.url
+
     private
 
     attr_reader :context, :strategy, :logger, :visited_urls