.

Author: gildesmarais

.github/copilot-instructions.md

@@ -35,8 +35,8 @@ Fix rubocop `RSpec/MultipleExpectations` adding rspec tag `:aggregate_failures`.
 
 ## Core Rules
 
-- ✅ Use **Roda routing with `hash_branch`**. Keep routes small.
-- ✅ Put logic into `helpers/` or `app/`, not inline in routes.
+- ✅ Organise Roda routes via dedicated modules (e.g. `Html2rss::Web::Routes::*`), keeping the main app class thin.
+- ✅ Keep helper modules minimal: define entrypoints with `class << self` and push implementation helpers under `private`; avoid `module_function` unless mirroring existing conventions.
 - ✅ Validate all inputs. Pass outbound requests through **SSRF filter**.
 - ✅ Add caching headers where appropriate (`Rack::Cache`).
 - ✅ Errors: friendly messages for users, detailed logging internally.
@@ -50,7 +50,7 @@ Fix rubocop `RSpec/MultipleExpectations` adding rspec tag `:aggregate_failures`.
 - ❌ Don't bypass SSRF filter or weaken CSP.
 - ❌ Don't add databases, ORMs, or background jobs.
 - ❌ Don't leak stack traces or secrets in responses.
-- ❌ Don't test private methods using `send(...)`
+- ❌ Don't reach into private API with `send(...)`; expose what you need at the module level instead.
 - ❌ Don't modify `frontend/dist/` - it's generated by build process.
 - ❌ NEVER expose the auth token a user provides.
 

app.rb

@@ -19,6 +19,8 @@
 require_relative 'app/api/v1/strategies'
 require_relative 'app/ssrf_filter_strategy'
 require_relative 'app/http_cache'
+require_relative 'app/routes/api_v1'
+require_relative 'app/routes/static'
 
 module Html2rss
   module Web
@@ -115,60 +117,10 @@ def development? = self.class.development?
       route do |r|
         r.public
 
-        r.on 'api', 'v1' do # rubocop:disable Metrics/BlockLength
-          r.response['Content-Type'] = 'application/json'
-
-          r.on 'health' do
-            r.get do
-              JSON.generate(Api::V1::Health.show(r))
-            end
-          end
-
-          r.on 'strategies' do
-            r.get do
-              JSON.generate(Api::V1::Strategies.index(r))
-            end
-          end
-
-          r.on 'feeds' do
-            r.get String do |token|
-              result = Api::V1::Feeds.show(r, token)
-              result.is_a?(Hash) ? JSON.generate(result) : result
-            end
-            r.post do
-              JSON.generate(Api::V1::Feeds.create(r))
-            end
-          end
-
-          r.get 'docs' do
-            docs_path = 'docs/api/v1/openapi.yaml'
-            if File.exist?(docs_path)
-              r.response['Content-Type'] = 'text/yaml'
-              File.read(docs_path)
-            else
-              r.response.status = 404
-              JSON.generate({ success: false, error: { message: 'Documentation not found' } })
-            end
-          end
-
-          r.get do
-            JSON.generate({ success: true,
-                            data: { api: { name: 'html2rss-web API',
-                                           description: 'RESTful API for converting websites to RSS feeds' } } })
-          end
-        end
-
-        r.get String do |feed_name|
-          next if feed_name.include?('.') && !feed_name.end_with?('.xml', '.rss')
-
-          handle_feed_generation(r, feed_name)
-        end
-
-        r.root do
-          index_path = 'public/frontend/index.html'
-          response['Content-Type'] = 'text/html'
-          File.exist?(index_path) ? File.read(index_path) : fallback_html
-        end
+        Routes::ApiV1.call(r)
+        Routes::Static.call(r,
+                            feed_handler: ->(router_ctx, feed_name) { handle_feed_generation(router_ctx, feed_name) },
+                            index_renderer: ->(router_ctx) { render_index_page(router_ctx) })
       end
 
       private
@@ -181,6 +133,12 @@ def handle_feed_generation(router, feed_name)
         rss_content
       end
 
+      def render_index_page(router)
+        index_path = 'public/frontend/index.html'
+        router.response['Content-Type'] = 'text/html'
+        File.exist?(index_path) ? File.read(index_path) : fallback_html
+      end
+
       def fallback_html
         <<~HTML
           <!DOCTYPE html>

app/api/v1/feeds.rb

@@ -17,151 +17,135 @@ module Api
       module V1
         # RESTful API v1 for feeds
         module Feeds
-          module_function
+          class << self
+            def show(request, token)
+              ensure_auto_source_enabled!
 
-          def show(request, token)
-            handle_token_based_feed(request, token)
-          end
+              feed_token = validated_token_for(token)
+              account = account_for(feed_token)
+              ensure_access!(account, feed_token.url)
 
-          def create(request)
-            raise ForbiddenError, 'Auto source feature is disabled' unless AutoSource.enabled?
+              render_generated_feed(request, feed_token.url)
+            end
 
-            account = authenticate_request(request)
-            params = extract_create_params(request)
-            validate_create_params(params, account)
+            def create(request)
+              ensure_auto_source_enabled!
 
-            feed_data = AutoSource.create_stable_feed(params[:name], params[:url], account, params[:strategy])
-            raise InternalServerError, 'Failed to create feed' unless feed_data
+              account = require_account(request)
+              params = build_create_params(request, account)
 
-            build_create_response(request, feed_data)
-          end
+              feed_data = AutoSource.create_stable_feed(params[:name], params[:url], account, params[:strategy])
+              raise InternalServerError, 'Failed to create feed' unless feed_data
 
-          def handle_token_based_feed(request, token)
-            raise ForbiddenError, 'Auto source feature is disabled' unless AutoSource.enabled?
+              json_response(request, feed_response_payload(feed_data), status: 201)
+            end
 
-            feed_token = validate_feed_token(token)
-            account = get_account_for_token(feed_token)
-            validate_account_access(account, feed_token.url)
+            private
 
-            generate_feed_response(request, feed_token.url)
-          end
+            def ensure_auto_source_enabled!
+              raise ForbiddenError, 'Auto source feature is disabled' unless AutoSource.enabled?
+            end
 
-          def validate_feed_token(token)
-            feed_token = FeedToken.decode(token)
-            raise UnauthorizedError, 'Invalid token' unless feed_token
+            def json_response(request, payload, status: 200)
+              request.response['Content-Type'] = 'application/json'
+              request.response.status = status
+              payload
+            end
 
-            validated_token = FeedToken.validate_and_decode(token, feed_token.url, Auth.secret_key)
-            raise UnauthorizedError, 'Invalid token' unless validated_token
+            def build_create_params(request, account)
+              url = request.params['url'].to_s.strip
+              raise BadRequestError, 'URL parameter is required' if url.empty?
+              raise BadRequestError, 'Invalid URL format' unless UrlValidator.valid_url?(url)
+              raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account, url)
 
-            validated_token
-          end
+              {
+                url: url,
+                name: extract_site_title(url),
+                strategy: normalize_strategy(request.params['strategy'])
+              }
+            end
 
-          def get_account_for_token(feed_token)
-            account = AccountManager.get_account_by_username(feed_token.username)
-            raise UnauthorizedError, 'Account not found' unless account
+            def normalize_strategy(raw_strategy)
+              strategy = raw_strategy.to_s.strip
+              strategy = default_strategy if strategy.empty?
 
-            account
-          end
+              raise BadRequestError, 'Unsupported strategy' unless supported_strategies.include?(strategy)
 
-          def validate_account_access(account, url)
-            raise ForbiddenError, 'Access Denied' unless UrlValidator.url_allowed?(account, url)
-          end
-
-          def generate_feed_response(request, url)
-            strategy = select_strategy(request.params['strategy'])
-            rss_content = AutoSource.generate_feed_content(url, strategy)
+              strategy
+            end
 
-            request.response['Content-Type'] = 'application/xml'
+            def validated_token_for(token)
+              feed_token = Auth.validate_and_decode_feed_token(token)
+              raise UnauthorizedError, 'Invalid token' unless feed_token
 
-            # TODO: get ttl from feed
-            HttpCache.expires(request.response, 600, cache_control: 'public')
+              feed_token
+            end
 
-            rss_content.to_s
-          end
+            def account_for(feed_token)
+              account = AccountManager.get_account_by_username(feed_token.username)
+              raise UnauthorizedError, 'Account not found' unless account
 
-          def authenticate_request(request)
-            account = Auth.authenticate(request)
-            raise UnauthorizedError, 'Authentication required' unless account
+              account
+            end
 
-            account
-          end
+            def ensure_access!(account, url)
+              raise ForbiddenError, 'Access Denied' unless UrlValidator.url_allowed?(account, url)
+            end
 
-          private
+            def render_generated_feed(request, url)
+              rss_content = AutoSource.generate_feed_content(url, normalize_strategy(request.params['strategy']))
 
-          def extract_create_params(request)
-            url = request.params['url']
-            strategy = select_strategy(request.params['strategy'])
-            {
-              url: url,
-              name: extract_site_title(url),
-              strategy: strategy
-            }
-          end
+              request.response['Content-Type'] = 'application/xml'
 
-          def validate_create_params(params, account)
-            raise BadRequestError, 'URL parameter is required' if params[:url].nil? || params[:url].empty?
-            raise BadRequestError, 'Invalid URL format' unless UrlValidator.valid_url?(params[:url])
-            raise ForbiddenError, 'URL not allowed for this account' unless UrlValidator.url_allowed?(account,
-                                                                                                      params[:url])
-          end
+              # TODO: get ttl from feed
+              HttpCache.expires(request.response, 600, cache_control: 'public')
 
-          def build_create_response(request, feed_data)
-            request.response['Content-Type'] = 'application/json'
-            request.response.status = 201
-            feed_response_payload(feed_data)
-          end
+              rss_content.to_s
+            end
 
-          def select_strategy(raw_strategy)
-            strategy = raw_strategy.to_s.strip
-            strategy = default_strategy if strategy.empty?
+            def require_account(request)
+              account = Auth.authenticate(request)
+              raise UnauthorizedError, 'Authentication required' unless account
 
-            raise BadRequestError, 'Unsupported strategy' unless supported_strategies.include?(strategy)
+              account
+            end
 
-            strategy
-          end
+            def supported_strategies
+              Html2rss::RequestService.strategy_names.map(&:to_s)
+            end
 
-          def supported_strategies
-            Html2rss::RequestService.strategy_names.map(&:to_s)
-          end
+            def default_strategy
+              Html2rss::RequestService.default_strategy_name.to_s
+            end
 
-          def default_strategy
-            Html2rss::RequestService.default_strategy_name.to_s
-          end
+            def feed_response_payload(feed_data)
+              {
+                success: true,
+                data: { feed: feed_attributes(feed_data) },
+                meta: { created: true }
+              }
+            end
 
-          def feed_response_payload(feed_data)
-            {
-              success: true,
-              data: { feed: feed_attributes(feed_data) },
-              meta: { created: true }
-            }
-          end
+            def feed_attributes(feed_data)
+              timestamp = Time.now.iso8601
 
-          def feed_attributes(feed_data)
-            timestamp = Time.now.iso8601
-
-            {
-              id: feed_data[:id],
-              name: feed_data[:name],
-              url: feed_data[:url],
-              strategy: feed_data[:strategy],
-              public_url: feed_data[:public_url],
-              created_at: timestamp,
-              updated_at: timestamp
-            }
-          end
+              {
+                id: feed_data[:id],
+                name: feed_data[:name],
+                url: feed_data[:url],
+                strategy: feed_data[:strategy],
+                public_url: feed_data[:public_url],
+                created_at: timestamp,
+                updated_at: timestamp
+              }
+            end
 
-          def extract_site_title(url)
-            Html2rss::Url.for_channel(url).channel_titleized
-          rescue StandardError
-            nil
+            def extract_site_title(url)
+              Html2rss::Url.for_channel(url).channel_titleized
+            rescue StandardError
+              nil
+            end
           end
-
-          module_function :extract_create_params, :validate_create_params, :build_create_response,
-                          :authenticate_request, :select_strategy, :supported_strategies, :default_strategy,
-                          :feed_response_payload, :feed_attributes, :extract_site_title
-          private_class_method :extract_create_params, :validate_create_params, :build_create_response,
-                               :authenticate_request, :select_strategy, :supported_strategies, :default_strategy,
-                               :feed_response_payload, :feed_attributes, :extract_site_title
         end
       end
     end