Add custom 404 page support for sites

Allow sites to configure a custom entry to display when visitors
access non-existent pages. Custom 404 entries must be published
and not password-protected to be used. Falls back to default
404 behavior when no custom entry is configured or when the
custom entry is not publicly accessible.

REDMINE-21049

Author: tf

app/controllers/concerns/pageflow/controller_delegation.rb

@@ -8,7 +8,7 @@ module ControllerDelegation
     # the response.
     def delegate_to_rack_app!(app)
       result = app.call(request.env)
-      yield(*result) if block_given?
+      result = yield(result) if block_given?
 
       throw(:delegate, result)
     end

app/controllers/pageflow/application_controller.rb

@@ -22,15 +22,9 @@ class ApplicationController < ActionController::Base
 
     rescue_from ActiveRecord::RecordNotFound do |exception|
       debug_log_with_backtrace(exception)
+
       respond_to do |format|
-        format.html do
-          begin
-            render file: Rails.public_path.join('pageflow', 'error_pages', '404.html'), status: :not_found
-          rescue ActionView::MissingTemplate => exception
-            debug_log_with_backtrace(exception)
-            head :not_found
-          end
-        end
+        format.html { render_static_404_error_page }
         format.any { head :not_found }
       end
     end
@@ -61,6 +55,14 @@ def locale_from_accept_language_header
       http_accept_language.compatible_language_from(I18n.available_locales)
     end
 
+    def render_static_404_error_page
+      render file: Rails.public_path.join('pageflow', 'error_pages', '404.html'),
+             status: :not_found
+    rescue ActionView::MissingTemplate => e
+      debug_log_with_backtrace(e)
+      head :not_found
+    end
+
     def debug_log_with_backtrace(exception)
       Rails.logger.debug exception
       backtrace = ''

app/controllers/pageflow/entries_controller.rb

@@ -25,6 +25,8 @@ def show
           return unless check_entry_password_protection(entry)
 
           delegate_to_entry_type_frontend_app!(entry)
+        rescue ActiveRecord::RecordNotFound
+          render_custom_or_static_404_error_page
         end
       end
     end
@@ -100,15 +102,18 @@ def entry_redirect(entry)
       Pageflow.config.public_entry_redirect.call(entry, request)
     end
 
-    def delegate_to_entry_type_frontend_app!(entry)
+    def delegate_to_entry_type_frontend_app!(entry, override_status: nil)
       EntriesControllerEnvHelper.add_entry_info_to_env(request.env, entry: entry, mode: :published)
 
-      delegate_to_rack_app!(entry.entry_type.frontend_app) do |_status, headers, _body|
+      delegate_to_rack_app!(entry.entry_type.frontend_app) do |result|
+        status, headers, body = result
         config = Pageflow.config_for(entry)
 
         allow_iframe_for_embed(headers)
         apply_additional_headers(entry, config, headers)
         apply_cache_control(entry, config, headers)
+
+        [override_status || status, headers, body]
       end
     end
 
@@ -128,5 +133,17 @@ def apply_additional_headers(entry, config, headers)
         config.additional_public_entry_headers.for(entry, request)
       )
     end
+
+    def render_custom_or_static_404_error_page
+      site = Site.for_request(request).first
+
+      if site&.custom_404_entry&.published_without_password_protection?
+        entry = PublishedEntry.new(site.custom_404_entry)
+        delegate_to_entry_type_frontend_app!(entry, override_status: 404)
+      else
+        # Fallback to ApplicationController's handler method
+        render_static_404_error_page
+      end
+    end
   end
 end

app/models/concerns/pageflow/entry_publication_states.rb

@@ -38,6 +38,10 @@ def published_with_password_protection?
       published? && published_revision.password_protected?
     end
 
+    def published_without_password_protection?
+      published? && !published_revision.password_protected?
+    end
+
     def published?
       published_revision.present?
     end

app/models/pageflow/site.rb

@@ -1,6 +1,7 @@
 module Pageflow
   class Site < ApplicationRecord
     belongs_to :account
+    belongs_to :custom_404_entry, class_name: 'Entry', optional: true
 
     has_many :entry_templates, dependent: :destroy
     has_many :entries
@@ -11,6 +12,7 @@ class Site < ApplicationRecord
 
     validates :account, presence: true
     validates_inclusion_of :cutoff_mode_name, in: :available_cutoff_mode_names, allow_blank: true
+    validate :custom_404_entry_belongs_to_same_site
 
     delegate :enabled_feature_names, to: :account
 
@@ -74,5 +76,11 @@ def self.ransackable_associations(_auth_object = nil)
     def available_cutoff_mode_names
       Pageflow.config_for(account).cutoff_modes.names
     end
+
+    def custom_404_entry_belongs_to_same_site
+      return unless custom_404_entry.present?
+
+      errors.add(:custom_404_entry, :must_belong_to_same_site) if custom_404_entry.site_id != id
+    end
   end
 end

db/migrate/20250617090048_add_custom404_entry_to_sites.rb

@@ -0,0 +1,5 @@
+class AddCustom404EntryToSites < ActiveRecord::Migration[7.1]
+  def change
+    add_reference :pageflow_sites, :custom_404_entry, null: true
+  end
+end

spec/models/concerns/pageflow/entry_publication_states_spec.rb

@@ -249,5 +249,45 @@ module Pageflow
         end
       end
     end
+
+    describe '#published_with_password_protection?' do
+      it 'returns true for entry published with password protection' do
+        entry = create(:entry, :published_with_password)
+
+        expect(entry.published_with_password_protection?).to eq(true)
+      end
+
+      it 'returns false for entry published without password protection' do
+        entry = create(:entry, :published)
+
+        expect(entry.published_with_password_protection?).to eq(false)
+      end
+
+      it 'returns false for non-published entry' do
+        entry = create(:entry)
+
+        expect(entry.published_with_password_protection?).to eq(false)
+      end
+    end
+
+    describe '#published_without_password_protection?' do
+      it 'returns true for entry published without password protection' do
+        entry = create(:entry, :published)
+
+        expect(entry.published_without_password_protection?).to eq(true)
+      end
+
+      it 'returns false for entry published with password protection' do
+        entry = create(:entry, :published_with_password)
+
+        expect(entry.published_without_password_protection?).to eq(false)
+      end
+
+      it 'returns false for non-published entry' do
+        entry = create(:entry)
+
+        expect(entry.published_without_password_protection?).to eq(false)
+      end
+    end
   end
 end

spec/models/pageflow/site_spec.rb

@@ -161,5 +161,31 @@ module Pageflow
         expect(result).to eq([matching_site])
       end
     end
+
+    describe 'custom_404_entry validation' do
+      it 'is valid when custom_404_entry belongs to same site' do
+        site = create(:site)
+        entry = create(:entry, site: site)
+        site.custom_404_entry = entry
+
+        expect(site).to be_valid
+      end
+
+      it 'is invalid when custom_404_entry belongs to different site' do
+        site1 = create(:site)
+        site2 = create(:site)
+        entry = create(:entry, site: site2)
+        site1.custom_404_entry = entry
+
+        site1.valid?
+        expect(site1.errors).to include(:custom_404_entry)
+      end
+
+      it 'is valid when custom_404_entry is nil' do
+        site = build(:site)
+
+        expect(site).to be_valid
+      end
+    end
   end
 end

spec/requests/pageflow/entries_show_request_spec.rb

@@ -216,6 +216,79 @@ module Pageflow
         expect(response.body).to include('Not Found')
       end
 
+      it 'renders custom 404 entry when site has custom_404_entry configured' do
+        site = create(:site, cname: 'my.example.com')
+        custom_404_entry = create(:entry, :published,
+                                  type_name: 'test',
+                                  title: 'Custom 404',
+                                  site:)
+        site.update!(custom_404_entry:)
+
+        get('http://my.example.com/non-existent-entry')
+
+        expect(response.status).to eq(404)
+        expect(response.body).to include('Custom 404 published rendered by entry type frontend app')
+      end
+
+      it 'falls back to default 404 when site has no custom_404_entry' do
+        create(:site, cname: 'my.example.com')
+
+        get('http://my.example.com/non-existent-entry')
+
+        expect(response.status).to eq(404)
+        expect(response.body).to include("The page you've requested cannot be found.")
+      end
+
+      it 'renders site-specific custom 404 entry' do
+        site1 = create(:site, cname: 'site1.example.com')
+        site2 = create(:site, cname: 'site2.example.com')
+
+        custom_404_entry1 = create(:entry, :published,
+                                    type_name: 'test',
+                                    title: 'Site 1 Not Found',
+                                    site: site1)
+        custom_404_entry2 = create(:entry, :published,
+                                    type_name: 'test',
+                                    title: 'Site 2 Not Found',
+                                    site: site2)
+
+        site1.update!(custom_404_entry: custom_404_entry1)
+        site2.update!(custom_404_entry: custom_404_entry2)
+
+        get('http://site1.example.com/non-existent')
+        expect(response.status).to eq(404)
+        expect(response.body).to include('Site 1 Not Found')
+
+        get('http://site2.example.com/non-existent')
+        expect(response.status).to eq(404)
+        expect(response.body).to include('Site 2 Not Found')
+      end
+
+      it 'falls back to default 404 when custom_404_entry is not published' do
+        site = create(:site, cname: 'my.example.com')
+        unpublished_404_entry = create(:entry, type_name: 'test', site:)
+        site.update!(custom_404_entry: unpublished_404_entry)
+
+        get('http://my.example.com/non-existent-entry')
+
+        expect(response.status).to eq(404)
+        expect(response.body).to include("The page you've requested cannot be found.")
+      end
+
+      it 'falls back to default 404 when custom_404_entry is password protected' do
+        site = create(:site, cname: 'my.example.com')
+        password_protected_404_entry = create(:entry, :published_with_password,
+                                              type_name: 'test',
+                                              password: 'secret123',
+                                              site:)
+        site.update!(custom_404_entry: password_protected_404_entry)
+
+        get('http://my.example.com/non-existent-entry')
+
+        expect(response.status).to eq(404)
+        expect(response.body).to include("The page you've requested cannot be found.")
+      end
+
       it 'responds with forbidden for entry published with password' do
         entry = create(:entry, :published_with_password,
                        password: 'abc123abc',