Add page finder service

Add a new service which find the page by urlname or should try to find the correct wildcard url for a given parent_page. It will traverse the page tree and will try to match all page_layouts with a wildcard_url. The first match wins and will be returned.
The page and params are stored in the service itself and can be received later in the controller.

Author: kulturbande

app/services/alchemy/page_finder.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Alchemy
+  class PageFinder
+    attr_reader :params
+
+    def initialize(params: ActionController::Parameters.new)
+      @params = params
+    end
+
+    def call(urlname)
+      return if urlname.blank?
+
+      find_by_urlname(urlname) || find_by_wildcard_url(urlname)
+    end
+
+    private
+
+    # Finds a page by exact urlname match within the current language.
+    #
+    # @return [Alchemy::Page]
+    def find_by_urlname(urlname)
+      Current.language.pages.contentpages.find_by(urlname: urlname)
+    end
+
+    # Walks the page tree level by level, matching URL segments against page slugs or wildcard URLs.
+    #
+    # @return [Alchemy::Page] the matched page or nil if no match
+    def find_by_wildcard_url(urlname)
+      root_page = Current.language.root_page
+      return if root_page.nil? || wildcard_layout_names.empty?
+
+      segments = urlname.split("/")
+      current_parent = root_page
+      path_prefix = nil
+      page = nil
+
+      until segments.empty?
+        children = current_parent.children.contentpages
+        expected_urlname = [path_prefix, segments.first].compact.join("/")
+
+        # use only one database query to extract the exact child or children with wildcard_url
+        possible_pages = children.where(urlname: expected_urlname)
+          .or(children.where(page_layout: wildcard_layout_names))
+          .to_a
+
+        # Try an exact slug match first
+        page = possible_pages.find { _1.urlname == expected_urlname }
+        if page
+          segments = segments.drop(1)
+          current_parent = page
+          path_prefix = expected_urlname
+          next
+        end
+
+        # Try children with wildcard_url attributes (it is not necessary to select for wildcard urls
+        # because the urlname did not match before)
+        possible_pages.each do |child|
+          pattern = child.wildcard_url.pattern
+
+          # a wildcard url pattern can have multiple segments, e.g. ":year/:slug"
+          segment_count = pattern.count("/") + 1
+          candidate_url = segments.first(segment_count).join("/")
+
+          extracted_params = extract_matching_params(candidate_url, pattern, child.wildcard_url.params)
+          next unless extracted_params
+
+          @params.merge!(ActionController::Parameters.new(extracted_params).permit(*extracted_params.keys))
+
+          # prepare the data for the next segment loop
+          path_prefix = [path_prefix, child.slug].compact.join("/")
+          segments = segments.drop(segment_count)
+          current_parent = child
+          page = child
+          break
+        end
+        return unless page
+      end
+
+      page
+    end
+
+    # Extracts named parameters from a URL matching a wildcard pattern.
+    # Returns nil if the URL does not match or constraints are not satisfied.
+    #
+    # @param url [String] the URL segment(s) to check, e.g. "2024/my-post"
+    # @param pattern [String] the wildcard pattern, e.g. ":year/:slug"
+    # @param constraints [String, Hash, nil] param definitions
+    # @return [Hash<Symbol, String>, nil] extracted params or nil
+    def extract_matching_params(url, pattern, constraints)
+      url_segments = url.split("/")
+      pattern_segments = pattern.split("/")
+      return unless url_segments.size == pattern_segments.size
+
+      extracted = {}
+      matched = pattern_segments.each_with_index.all? do |pattern_segment, index|
+        url_segment = url_segments[index]
+        if pattern_segment.start_with?(":")
+          key = pattern_segment[1..].to_sym
+          extracted[key] = url_segment if matches_constraint?(url_segment, key, constraints)
+        else
+          pattern_segment == url_segment
+        end
+      end
+
+      extracted if matched
+    end
+
+    # Checks if a param value satisfies its constraint.
+    #
+    # @param value [String] the param value
+    # @param key [Symbol] the param name
+    # @param constraints [String, Hash, nil] param definitions
+    # @return [Boolean]
+    def matches_constraint?(value, key, constraints)
+      return true if constraints.blank?
+
+      type = constraints.is_a?(String) ? constraints : constraints[key.to_s] || constraints[key]
+      return true if type.nil?
+      return value.match?(type) if type.is_a?(Regexp)
+
+      format_matchers = Alchemy.config.format_matchers
+      !format_matchers.respond_to?(type.to_sym) || value.match?(format_matchers.public_send(type.to_sym))
+    end
+
+    # Returns the names of all page layouts that have a wildcard_url defined.
+    #
+    # @return [Array<String>] layout names with wildcard URLs
+    def wildcard_layout_names
+      @_wildcard_layout_names ||= PageDefinition.all.select { |d| d.wildcard_url&.present? }.map(&:name)
+    end
+  end
+end

spec/services/alchemy/page_finder_spec.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+module Alchemy
+  RSpec.describe PageFinder do
+    let(:language) { create(:alchemy_language) }
+    let!(:language_root) do
+      create(:alchemy_page, :language_root, language: language)
+    end
+
+    before do
+      PageDefinition.reset!
+      Current.language = language
+    end
+
+    def create_page(name:, layout: "standard", parent: language_root)
+      create(
+        :alchemy_page, :public,
+        name: name,
+        page_layout: layout,
+        parent: parent,
+        language: language
+      )
+    end
+
+    # Page tree used by most tests:
+    #
+    #   Products (standard)                      -> /products
+    #   +-- Product Details (product_detail)     -> /products/:id        (integer constraint)
+    #   |   +-- Comments (standard)              -> /products/:id/comments
+    #   +-- Product By Slug (product_by_slug)    -> /products/:slug      (no constraint)
+    #
+    #   Blog (standard)                          -> /blog
+    #   +-- Blog Post (blog_post)                -> /blog/:year/:slug   (integer + string)
+    #
+    #   Users (standard)                         -> /users
+    #   +-- User Profile (user_profile)          -> /users/:uuid/profile (uuid constraint)
+
+    let!(:products_page) { create_page(name: "Products") }
+    let!(:product_detail_page) { create_page(name: "Product Details", layout: "product_detail", parent: products_page) }
+    let!(:comments_page) { create_page(name: "Comments", parent: product_detail_page) }
+    let!(:product_by_slug_page) { create_page(name: "Product By Slug", layout: "product_by_slug", parent: products_page) }
+
+    let!(:blog_page) { create_page(name: "Blog") }
+    let!(:blog_post_page) { create_page(name: "Blog Post", layout: "blog_post", parent: blog_page) }
+
+    let!(:users_page) { create_page(name: "Users") }
+    let!(:user_profile_page) { create_page(name: "User Profile", layout: "user_profile", parent: users_page) }
+
+    let(:params) { ActionController::Parameters.new }
+
+    it "defaults to Current.language.root_page" do
+      page = described_class.new(params: params).call("products/123")
+      expect(page).to eq(product_detail_page)
+      expect(params[:id]).to eq("123")
+    end
+
+    it "finds a page by exact urlname" do
+      page = described_class.new(params: params).call("products")
+      expect(page).to eq(products_page)
+    end
+
+    it "finds a nested page by its full urlname" do
+      page = described_class.new(params: params).call(comments_page.urlname)
+      expect(page).to eq(comments_page)
+    end
+
+    it "returns nil for a blank path" do
+      expect(described_class.new(params: params).call("")).to be_nil
+    end
+
+    it "returns nil for a path with no matching prefix" do
+      expect(described_class.new(params: params).call("other/123")).to be_nil
+    end
+
+    context "single-segment pattern with integer constraint" do
+      it "matches /products/123" do
+        page = described_class.new(params: params).call("products/123")
+        expect(page).to eq(product_detail_page)
+        expect(params[:id]).to eq("123")
+      end
+
+      it "rejects non-integer and falls through to unconstrained sibling" do
+        page = described_class.new(params: params).call("products/some-slug")
+        expect(page).to eq(product_by_slug_page)
+        expect(params[:slug]).to eq("some-slug")
+        # ensures no stale params leak from the failed product_detail match
+        expect(params).not_to have_key(:id)
+      end
+    end
+
+    context "multi-segment pattern" do
+      it "matches /blog/2024/my-post and extracts both params" do
+        page = described_class.new(params: params).call("blog/2024/my-post")
+        expect(page).to eq(blog_post_page)
+        expect(params[:year]).to eq("2024")
+        expect(params[:slug]).to eq("my-post")
+      end
+
+      it "does not match with wrong segment count" do
+        expect(described_class.new(params: params).call("blog/2024")).to be_nil
+      end
+    end
+
+    context "pattern with static segments" do
+      let(:uuid) { "550e8400-e29b-41d4-a716-446655440000" }
+
+      it "matches /users/:uuid/profile" do
+        page = described_class.new(params: params).call("users/#{uuid}/profile")
+        expect(page).to eq(user_profile_page)
+        expect(params[:uuid]).to eq(uuid)
+      end
+
+      it "does not match without the trailing static segment" do
+        expect(described_class.new(params: params).call("users/#{uuid}")).to be_nil
+      end
+    end
+
+    context "hierarchical patterns (grandchild under pattern page)" do
+      it "matches /products/42/comments through the pattern parent" do
+        page = described_class.new(params: params).call("products/42/comments")
+        expect(page).to eq(comments_page)
+        expect(params[:id]).to eq("42")
+      end
+    end
+
+    context "nested wildcard patterns" do
+      let!(:category_page) { create_page(name: "Category") }
+      let!(:category_by_slug) { create_page(name: "Category By Slug", layout: "product_by_slug", parent: category_page) }
+      let!(:category_detail) { create_page(name: "Category Detail", layout: "product_detail", parent: category_by_slug) }
+
+      it "matches /category/electronics/42 and extracts both slug and id" do
+        page = described_class.new(params: params).call("category/electronics/42")
+        expect(page).to eq(category_detail)
+        expect(params[:slug]).to eq("electronics")
+        expect(params[:id]).to eq("42")
+      end
+    end
+
+    context "with competing sibling patterns of different segment counts" do
+      let!(:shared_page) { create_page(name: "Shared") }
+      let!(:multi_segment_page) { create_page(name: "Multi Segment", layout: "blog_post", parent: shared_page) }
+      let!(:single_segment_page) { create_page(name: "Single Segment", layout: "product_by_slug", parent: shared_page) }
+      let!(:child_of_single) { create_page(name: "My Post", parent: single_segment_page) }
+
+      it "matches the first pattern sibling even when the other could also match via its child" do
+        page = described_class.new(params: params).call("shared/2024/my-post")
+        expect(page).to eq(multi_segment_page)
+        expect(params[:year]).to eq("2024")
+        expect(params[:slug]).to eq("my-post")
+      end
+    end
+
+    context "with a static wildcard_url pattern (no dynamic segments)" do
+      let!(:static_parent) { create_page(name: "Static Parent") }
+      let!(:static_page) { create_page(name: "Static Page", layout: "static_wildcard", parent: static_parent) }
+
+      it "matches /static-parent/foo/bar" do
+        page = described_class.new(params: params).call("static-parent/foo/bar")
+        expect(page).to eq(static_page)
+        expect(params.keys).to be_empty
+      end
+    end
+
+    context "with a regex constraint" do
+      let!(:warehouse_page) { create_page(name: "Warehouse") }
+      let!(:sku_page) { create_page(name: "SKU Lookup", layout: "product_by_sku", parent: warehouse_page) }
+
+      it "matches when the value satisfies the regex" do
+        page = described_class.new(params: params).call("warehouse/AB-1234")
+        expect(page).to eq(sku_page)
+        expect(params[:sku]).to eq("AB-1234")
+      end
+
+      it "does not match when the value violates the regex" do
+        expect(described_class.new(params: params).call("warehouse/invalid")).to be_nil
+      end
+    end
+  end
+
+  RSpec.describe PageFinder, "when no content pages exist" do
+    let(:language) { create(:alchemy_language) }
+    let!(:language_root) do
+      create(:alchemy_page, :language_root, language: language)
+    end
+
+    before do
+      PageDefinition.reset!
+      Current.language = language
+    end
+
+    it "returns nil" do
+      expect(described_class.new.call("anything")).to be_nil
+    end
+  end
+end