feat!: add namespaced feed pipeline primitives

Author: gildesmarais

app.rb

@@ -6,33 +6,7 @@
 require 'base64'
 
 require 'html2rss'
-require_relative 'app/environment_validator'
-require_relative 'app/auth'
-require_relative 'app/auto_source'
-require_relative 'app/feeds'
-require_relative 'app/local_config'
-require_relative 'app/flags'
-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'
-require_relative 'app/app_context'
-require_relative 'app/request_context_middleware'
-require_relative 'app/api/v1/feeds'
-require_relative 'app/api/v1/health'
-require_relative 'app/api/v1/strategies'
-require_relative 'app/ssrf_filter_strategy'
-require_relative 'app/http_cache'
-require_relative 'app/feed_request_handler'
-require_relative 'app/feed_route_handler'
-require_relative 'app/routes/api_v1'
-require_relative 'app/routes/static'
+Dir[File.join(__dir__, 'app/**/*.rb')].each { |file| require file }
 
 module Html2rss
   module Web

app/feeds/cache.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'time'
+
+require_relative '../cache_ttl'
+require_relative '../security_logger'
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Small synchronous cache for canonical feed results.
+      module Cache
+        Entry = Data.define(:result, :expires_at)
+
+        class << self
+          # @param key [String]
+          # @param ttl_seconds [Integer]
+          # @yieldreturn [Html2rss::Web::Feeds::Result]
+          # @return [Html2rss::Web::Feeds::Result]
+          def fetch(key, ttl_seconds:)
+            entry = read_entry(key)
+            return entry.result if fresh?(entry)
+
+            result = yield
+            write_entry(key, ttl_seconds, result)
+            result
+          end
+
+          # @param reason [String]
+          # @return [nil]
+          def clear!(reason: 'manual')
+            @entries = {} # rubocop:disable ThreadSafety/ClassInstanceVariable
+            SecurityLogger.log_cache_lifecycle('feeds_cache', 'clear', reason: reason)
+            nil
+          end
+
+          private
+
+          # @param key [String]
+          # @return [Entry, nil]
+          def read_entry(key)
+            entries[key]
+          end
+
+          # @param entry [Entry, nil]
+          # @return [Boolean]
+          def fresh?(entry)
+            entry && Time.now.utc < entry.expires_at
+          end
+
+          # @param key [String]
+          # @param ttl_seconds [Integer]
+          # @param result [Html2rss::Web::Feeds::Result]
+          # @return [void]
+          def write_entry(key, ttl_seconds, result)
+            entries[key] = Entry.new(result: result, expires_at: Time.now.utc + normalize_ttl(ttl_seconds))
+            SecurityLogger.log_cache_lifecycle('feeds_cache', 'write', key_hash: key_hash(key))
+          end
+
+          # @return [Hash{String=>Entry}]
+          def entries
+            @entries ||= {} # rubocop:disable ThreadSafety/ClassInstanceVariable
+          end
+
+          # @param ttl_seconds [Integer]
+          # @return [Integer]
+          def normalize_ttl(ttl_seconds)
+            ttl_seconds.to_i.positive? ? ttl_seconds.to_i : CacheTtl::DEFAULT_SECONDS
+          end
+
+          # @param key [String]
+          # @return [String]
+          def key_hash(key)
+            Digest::SHA256.hexdigest(key)[0..11]
+          end
+        end
+      end
+    end
+  end
+end

app/feeds/json_renderer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+require_relative '../exceptions'
+require_relative '../json_feed_builder'
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Renders JSON Feed output from shared feed results.
+      module JsonRenderer
+        VERSION = 'https://jsonfeed.org/version/1.1'
+
+        class << self
+          # @param result [Html2rss::Web::Feeds::Result]
+          # @return [String]
+          def call(result)
+            case result.status
+            when :ok
+              JSON.generate(payload_for(result.payload.fetch(:feed)))
+            when :empty
+              empty_feed(result)
+            else
+              error_feed(result)
+            end
+          end
+
+          private
+
+          # @param result [Html2rss::Web::Feeds::Result]
+          # @return [String]
+          def empty_feed(result)
+            JsonFeedBuilder.build_empty_feed_warning(
+              url: result.payload.fetch(:url),
+              strategy: result.payload.fetch(:strategy),
+              site_title: result.payload.fetch(:feed).channel.title
+            )
+          end
+
+          # @param result [Html2rss::Web::Feeds::Result]
+          # @return [String]
+          def error_feed(result)
+            JsonFeedBuilder.build_error_feed(message: result.message || HttpError::DEFAULT_MESSAGE)
+          end
+
+          # @param feed [RSS::Rss]
+          # @return [Hash{Symbol=>Object}]
+          def payload_for(feed)
+            {
+              version: VERSION,
+              title: feed.channel.title,
+              home_page_url: feed.channel.link,
+              description: feed.channel.description,
+              items: feed.items.map { |item| item_payload(item) }
+            }.compact
+          end
+
+          # @param item [Object]
+          # @return [Hash{Symbol=>Object}]
+          def item_payload(item)
+            {
+              id: item.respond_to?(:guid) && item.guid ? item.guid.content : (item.link || item.title),
+              url: item.link,
+              title: item.title,
+              content_text: item.description,
+              date_published: published_at(item)
+            }.compact
+          end
+
+          # @param item [Object]
+          # @return [String, nil]
+          def published_at(item)
+            value = item.respond_to?(:pubDate) ? item.pubDate : nil
+            return value.iso8601 if value.respond_to?(:iso8601)
+
+            Time.parse(value.to_s).utc.iso8601 if value
+          rescue ArgumentError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

app/feeds/request.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Request-edge contract for feed rendering.
+      Request = Data.define(:target_kind, :representation, :feed_name, :token, :params)
+    end
+  end
+end

app/feeds/request_parser.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'request'
+require_relative 'response_format'
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Parses route inputs into shared feed request contracts.
+      module RequestParser
+        class << self
+          # @param request [Rack::Request]
+          # @param target_kind [Symbol]
+          # @param identifier [String]
+          # @return [Html2rss::Web::Feeds::Request]
+          def call(request:, target_kind:, identifier:)
+            representation = ResponseFormat.for_request(request)
+            normalized_identifier = ResponseFormat.strip_known_extension(identifier)
+
+            Request.new(
+              target_kind: target_kind,
+              representation: representation,
+              feed_name: target_kind == :static ? normalized_identifier : nil,
+              token: target_kind == :token ? normalized_identifier : nil,
+              params: request.params.to_h
+            )
+          end
+        end
+      end
+    end
+  end
+end

app/feeds/resolved_source.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Normalized source inputs for shared feed generation.
+      ResolvedSource = Data.define(:source_kind, :cache_identity, :generator_input, :ttl_seconds)
+    end
+  end
+end

app/feeds/resolver.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+require_relative '../account_manager'
+require_relative '../auth'
+require_relative '../auto_source'
+require_relative '../cache_ttl'
+require_relative '../exceptions'
+require_relative '../local_config'
+require_relative '../url_validator'
+require_relative '../api/v1/contract'
+require_relative 'resolved_source'
+
+module Html2rss
+  module Web
+    module Feeds
+      ##
+      # Resolves static and token-backed requests into shared generator inputs.
+      module Resolver
+        class << self
+          # @param feed_request [Html2rss::Web::Feeds::Request]
+          # @return [Html2rss::Web::Feeds::ResolvedSource]
+          def call(feed_request)
+            case feed_request.target_kind
+            when :static
+              resolve_static(feed_request)
+            when :token
+              resolve_token(feed_request)
+            else
+              raise BadRequestError, "Unsupported feed target: #{feed_request.target_kind}"
+            end
+          end
+
+          private
+
+          # @param feed_request [Html2rss::Web::Feeds::Request]
+          # @return [Html2rss::Web::Feeds::ResolvedSource]
+          def resolve_static(feed_request)
+            config = LocalConfig.find(feed_request.feed_name)
+            config[:params] = (config[:params] || {}).merge(feed_request.params) if feed_request.params.any?
+            config[:strategy] ||= Html2rss::RequestService.default_strategy_name
+
+            ResolvedSource.new(
+              source_kind: :static,
+              cache_identity: static_cache_identity(feed_request.feed_name, feed_request.params),
+              generator_input: config,
+              ttl_seconds: CacheTtl.seconds_from_minutes(config.dig(:channel, :ttl))
+            )
+          end
+
+          # @param feed_request [Html2rss::Web::Feeds::Request]
+          # @return [Html2rss::Web::Feeds::ResolvedSource]
+          def resolve_token(feed_request)
+            feed_token = validated_feed_token(feed_request.token)
+            strategy = resolved_strategy(feed_token)
+            generator_input = token_generator_input(feed_token.url, strategy)
+
+            ResolvedSource.new(
+              source_kind: :token,
+              cache_identity: token_cache_identity(feed_request.token),
+              generator_input: generator_input,
+              ttl_seconds: CacheTtl.seconds_from_minutes(generator_input.dig(:channel, :ttl), default: 300)
+            )
+          end
+
+          # @param feed_name [String]
+          # @param params [Hash{Object=>Object}]
+          # @return [String]
+          def static_cache_identity(feed_name, params)
+            normalized_params = params.to_h.sort_by { |key, _| key.to_s }
+            digest = Digest::SHA256.hexdigest(Marshal.dump(normalized_params))
+            "static:#{feed_name}:#{digest}"
+          end
+
+          # @param token [String]
+          # @return [String]
+          def token_cache_identity(token)
+            "token:#{Digest::SHA256.hexdigest(token.to_s)}"
+          end
+
+          # @param token [String]
+          # @return [Html2rss::Web::FeedToken]
+          def validated_feed_token(token)
+            feed_token = Auth.validate_and_decode_feed_token(token)
+            raise UnauthorizedError, 'Invalid token' unless feed_token
+
+            account = AccountManager.get_account_by_username(feed_token.username)
+            raise UnauthorizedError, 'Account not found' unless account
+
+            ensure_token_access!(account, feed_token.url)
+            ensure_auto_source_enabled!
+            feed_token
+          end
+
+          # @param account [Hash{Symbol=>Object}]
+          # @param url [String]
+          # @return [void]
+          def ensure_token_access!(account, url)
+            raise ForbiddenError, 'Access Denied' unless UrlValidator.url_allowed?(account, url)
+          end
+
+          # @return [void]
+          def ensure_auto_source_enabled!
+            raise ForbiddenError, Api::V1::Contract::MESSAGES[:auto_source_disabled] unless AutoSource.enabled?
+          end
+
+          # @param feed_token [Html2rss::Web::FeedToken]
+          # @return [String]
+          def resolved_strategy(feed_token)
+            strategy = feed_token.strategy.to_s.strip
+            strategy = Html2rss::RequestService.default_strategy_name.to_s if strategy.empty?
+            supported = Html2rss::RequestService.strategy_names.map(&:to_s)
+            raise BadRequestError, 'Unsupported strategy' unless supported.include?(strategy)
+
+            strategy
+          end
+
+          # @param url [String]
+          # @param strategy [String]
+          # @return [Hash{Symbol=>Object}]
+          def token_generator_input(url, strategy)
+            LocalConfig.global
+                       .slice(:stylesheets, :headers)
+                       .merge(
+                         strategy: strategy.to_sym,
+                         channel: { url: url },
+                         auto_source: {}
+                       )
+          end
+        end
+      end
+    end
+  end
+end