feat(feeds): negotiate rss or json feed output by extension and Accept

Author: gildesmarais

app.rb

@@ -15,6 +15,10 @@
 require_relative 'app/cache_ttl'
 require_relative 'app/exceptions'
 require_relative 'app/xml_builder'
+require_relative 'app/json_feed_builder'
+require_relative 'app/feed_response_format'
+require_relative 'app/request_target'
+require_relative 'app/feed_render_result'
 require_relative 'app/error_responder'
 require_relative 'app/security_logger'
 require_relative 'app/observability'

app/api/v1/feeds.rb

@@ -17,7 +17,7 @@ module Feeds
           class << self
             # @param request [Rack::Request]
             # @param token [String]
-            # @return [String] XML feed body.
+            # @return [String] serialized feed body.
             def show(request, token)
               ShowFeed.call(request, token)
             end

app/api/v1/feeds/show_feed.rb

@@ -3,8 +3,8 @@
 require_relative '../../../account_manager'
 require_relative '../../../auth'
 require_relative '../../../auto_source'
-require_relative '../../../cache_ttl'
 require_relative '../../../exceptions'
+require_relative '../../../feed_response_format'
 require_relative '../../../feed_generator'
 require_relative '../../../http_cache'
 require_relative '../../../observability'
@@ -21,17 +21,17 @@ module Feeds
           # This module stays narrow by handling only edge validation and
           # orchestration, then delegating generation to existing services.
           module ShowFeed
-            DEFAULT_TTL_SECONDS = 3600
-
             class << self
               # Resolves and renders XML feed output for a token request.
               #
               # @param request [Rack::Request]
               # @param token [String] signed public feed token.
-              # @return [String] XML feed response body.
+              # @return [String] serialized feed response body.
               def call(request, token)
-                feed_token, strategy = resolve_authorized_feed(token)
-                rendered = render_generated_feed(request, feed_token.url, strategy)
+                format = FeedResponseFormat.for_request(request)
+                normalized_token = FeedResponseFormat.strip_known_extension(token)
+                feed_token, strategy = resolve_authorized_feed(normalized_token)
+                rendered = render_generated_feed(request, feed_token.url, strategy, format)
                 emit_render_success(strategy, feed_token.url)
                 rendered
               rescue StandardError => error
@@ -97,22 +97,16 @@ def default_strategy
               # @param request [Rack::Request]
               # @param url [String]
               # @param strategy [String]
-              # @return [String] rendered XML.
-              def render_generated_feed(request, url, strategy)
-                feed_object = AutoSource.generate_feed_object(url, strategy)
-                rendered_feed = FeedGenerator.process_feed_content(url, strategy, feed_object)
-
-                request.response['Content-Type'] = 'application/xml'
-                HttpCache.expires(request.response, ttl_from_feed(feed_object), cache_control: 'public')
+              # @param format [Symbol]
+              # @return [String] rendered feed body.
+              def render_generated_feed(request, url, strategy, format)
+                rendered_feed = AutoSource.generate_feed_result(url, strategy, format:)
 
-                rendered_feed.to_s
-              end
+                request.response['Content-Type'] = FeedResponseFormat.content_type(format)
+                HttpCache.expires(request.response, rendered_feed.ttl_seconds, cache_control: 'public')
+                HttpCache.vary(request.response, 'Accept')
 
-              # @param feed_object [Object] object exposing channel ttl when available.
-              # @return [Integer] cache TTL in seconds.
-              def ttl_from_feed(feed_object)
-                ttl_value = feed_object.respond_to?(:channel) ? feed_object.channel&.ttl : nil
-                CacheTtl.seconds_from_minutes(ttl_value, default: DEFAULT_TTL_SECONDS)
+                rendered_feed.body
               end
 
               # @param token [String]

app/auto_source.rb

@@ -4,6 +4,7 @@
 require_relative 'account_manager'
 require_relative 'auth'
 require_relative 'boundary_models'
+require_relative 'feed_response_format'
 require_relative 'feed_generator'
 require_relative 'url_validator'
 
@@ -64,17 +65,26 @@ def generate_feed_from_stable_id(feed_id, token_data)
 
         # @param url [String]
         # @param strategy [String]
+        # @param format [Symbol]
+        # @return [Html2rss::Web::FeedRenderResult]
+        def generate_feed_result(url, strategy = 'ssrf_filter', format: FeedResponseFormat::RSS)
+          FeedGenerator.generate_feed_result(url, strategy, format:)
+        end
+
+        # @param url [String]
+        # @param strategy [String]
+        # @param format [Symbol]
         # @return [Object] raw feed object from selected strategy.
-        def generate_feed_object(url, strategy = 'ssrf_filter')
-          FeedGenerator.call_strategy(url, strategy)
+        def generate_feed_object(url, strategy = 'ssrf_filter', format: FeedResponseFormat::RSS)
+          FeedGenerator.call_strategy(url, strategy, format:)
         end
 
         # @param url [String]
         # @param strategy [String]
+        # @param format [Symbol]
         # @return [String] rendered RSS/XML content.
-        def generate_feed_content(url, strategy = 'ssrf_filter')
-          feed_content = FeedGenerator.call_strategy(url, strategy)
-          FeedGenerator.process_feed_content(url, strategy, feed_content)
+        def generate_feed_content(url, strategy = 'ssrf_filter', format: FeedResponseFormat::RSS)
+          generate_feed_result(url, strategy, format:).body
         end
 
         private

app/error_responder.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
 
 require_relative 'api/v1/contract'
+require_relative 'feed_response_format'
+require_relative 'json_feed_builder'
 require_relative 'observability'
+require_relative 'request_target'
 
 module Html2rss
   module Web
@@ -27,6 +30,7 @@ def respond(request:, response:, error:)
 
           client_message = client_message_for(error)
 
+          return render_feed_error(request, response, client_message) if RequestTarget.feed?(request)
           return render_api_error(response, client_message, error_code) if api_request?(request)
 
           render_xml_error(response, client_message)
@@ -35,8 +39,14 @@ def respond(request:, response:, error:)
         private
 
         # @param request [Rack::Request]
-        # @return [Boolean] true when request path is within API v1.
+        # @return [Boolean]
         def api_request?(request)
+          RequestTarget.api?(request) || api_path?(request)
+        end
+
+        # @param request [Rack::Request]
+        # @return [Boolean]
+        def api_path?(request)
           path = request.path.to_s
           path == API_ROOT_PATH || path.start_with?("#{API_ROOT_PATH}/")
         end
@@ -50,6 +60,17 @@ def render_api_error(response, message, code)
           JSON.generate({ success: false, error: { message: message, code: code } })
         end
 
+        # @param response [Rack::Response]
+        # @param message [String]
+        # @return [String] negotiated feed error payload.
+        def render_feed_error(request, response, message)
+          format = FeedResponseFormat.for_request(request)
+          response['Content-Type'] = FeedResponseFormat.content_type(format)
+          return JsonFeedBuilder.build_error_feed(message: message) if format == FeedResponseFormat::JSON_FEED
+
+          XmlBuilder.build_error_feed(message: message)
+        end
+
         # @param response [Rack::Response]
         # @param message [String]
         # @return [String] XML error feed.

app/feed_accept_header.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Web
+    ##
+    # Parses Accept headers for feed representation negotiation.
+    module FeedAcceptHeader
+      MediaRange = Data.define(:type, :subtype, :quality, :position) do
+        # @return [Integer]
+        def specificity
+          return 0 if type == '*' && subtype == '*'
+          return 1 if subtype == '*'
+
+          2
+        end
+
+        # @param candidate [String]
+        # @return [Boolean]
+        def matches?(candidate)
+          candidate_type, candidate_subtype = candidate.downcase.split('/', 2)
+          return true if type == '*' && subtype == '*'
+          return candidate_type == type if subtype == '*'
+
+          candidate_type == type && candidate_subtype == subtype
+        end
+      end
+
+      class << self
+        # @param accept_header [String, nil]
+        # @param json_media_types [Array<String>]
+        # @param rss_media_types [Array<String>]
+        # @return [Symbol, nil]
+        def preferred_format(accept_header, json_media_types:, rss_media_types:)
+          media_ranges = parse(accept_header)
+          return nil if media_ranges.empty?
+
+          json_score = best_score(media_ranges, json_media_types)
+          rss_score = best_score(media_ranges, rss_media_types)
+
+          return nil unless json_score
+          return FeedResponseFormat::JSON_FEED if rss_score.nil?
+
+          (json_score <=> rss_score)&.positive? ? FeedResponseFormat::JSON_FEED : nil
+        end
+
+        private
+
+        # @param accept_header [String, nil]
+        # @return [Array<MediaRange>]
+        def parse(accept_header)
+          accept_header.to_s.split(',').filter_map.with_index do |raw_range, position|
+            build_media_range(raw_range, position)
+          end
+        end
+
+        # @param raw_range [String]
+        # @param position [Integer]
+        # @return [MediaRange, nil]
+        def build_media_range(raw_range, position)
+          media_type, *parameter_parts = raw_range.strip.downcase.split(';')
+          type, subtype = media_type.to_s.split('/', 2)
+          return if type.to_s.empty? || subtype.to_s.empty?
+
+          MediaRange.new(
+            type:,
+            subtype:,
+            quality: extract_quality(parameter_parts),
+            position:
+          )
+        end
+
+        # @param parameter_parts [Array<String>]
+        # @return [Float]
+        def extract_quality(parameter_parts)
+          raw_value = parameter_parts
+                      .map(&:strip)
+                      .find { |part| part.start_with?('q=') }
+                      &.split('=', 2)
+                      &.last
+          quality = raw_value ? Float(raw_value) : 1.0
+          quality.clamp(0.0, 1.0)
+        rescue ArgumentError
+          1.0
+        end
+
+        # @param media_ranges [Array<MediaRange>]
+        # @param candidates [Array<String>]
+        # @return [Array(Float, Integer, Integer), nil]
+        def best_score(media_ranges, candidates)
+          media_ranges
+            .filter { |range| range.quality.positive? && candidates.any? { |candidate| range.matches?(candidate) } }
+            .map { |range| [range.quality, range.specificity, -range.position] }
+            .max
+        end
+      end
+    end
+  end
+end