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,113 @@
+# frozen_string_literal: true
+
+module Alchemy
+  class PageFinder
+    attr_reader :urlname
+
+    Result = Data.define(:page, :extracted_params)
+
+    def initialize(urlname)
+      @urlname = urlname
+    end
+
+    # @return [PageFinder::Result, nil]
+    def call
+      return if urlname.blank?
+
+      find_by_urlname || find_by_wildcard_url
+    end
+
+    private
+
+    # Finds a page by exact urlname match within the current language.
+    def find_by_urlname
+      page = Current.language.pages.contentpages.find_by(urlname: urlname)
+      Result.new(page: page, extracted_params: permitted_params({})) if page
+    end
+
+    # Finds a page whose urlname pattern matches the given URL.
+    # Uses a single SQL query to load all candidate pages with wildcard patterns
+    # in their urlname, then matches and validates constraints in Ruby.
+    def find_by_wildcard_url
+      return if wildcard_definitions.empty?
+
+      wildcard_pages = Current.language.pages.contentpages
+        .where("urlname LIKE ?", "%:%")
+        .to_a
+
+      url_depth = urlname.count("/")
+
+      matches = wildcard_pages.filter_map do |wildcard_page|
+        next if wildcard_page.urlname.count("/") != url_depth
+
+        matched_params = match_url_pattern(wildcard_page)
+        [wildcard_page, matched_params] if matched_params
+      end
+
+      return if matches.empty?
+
+      # take the first page that matched the url
+      page, params = matches.min_by { |page, _| [page.depth, page.lft] }
+      Result.new(page: page, extracted_params: permitted_params(params))
+    end
+
+    # Matches the urlname against a page's wildcard pattern.
+    # Builds a regex from the pattern with constraints baked into capture groups,
+    # then extracts and validates params in one step.
+    #
+    # @param wildcard_page [Alchemy::Page] a page with wildcard segments in its urlname
+    # @return [Hash<Symbol, String>, nil] matched params or nil
+    def match_url_pattern(wildcard_page)
+      regex_parts = wildcard_page.urlname.split("/").map do |segment|
+        segment_to_pattern(segment)
+      end
+
+      return if regex_parts.include?(nil)
+
+      match = Regexp.new("\\A#{regex_parts.join("/")}\\z").match(urlname)
+      return unless match
+
+      match.named_captures.transform_keys(&:to_sym)
+    end
+
+    # Converts a single URL segment into a regex pattern string.
+    # Static segments are escaped, dynamic segments (e.g. ":id") are resolved
+    # to a capture group with the constraint from the matching wildcard definition.
+    #
+    # @param segment [String] a single URL segment, e.g. "products" or ":id"
+    # @return [String, nil] regex pattern string or nil if no matching definition found
+    def segment_to_pattern(segment)
+      unless segment.start_with?(":")
+        return Regexp.escape(segment)
+      end
+
+      key = segment[1..] # remove leading colon
+      wildcard_url = wildcard_urls_by_param_key[key.to_sym]
+      wildcard_url ? "(?<#{key}>#{wildcard_url.constraint_pattern(key)})" : nil
+    end
+
+    # Cache the wildcard_url definition and store it in a hash
+    #
+    # @return [Hash<Symbol, WildcardUrlType::Value>] param key to wildcard_url lookup
+    def wildcard_urls_by_param_key
+      @_wildcard_urls_by_param_key ||= wildcard_definitions.each_with_object({}) do |definition, hash|
+        definition.wildcard_url.param_keys.each do |key|
+          hash[key] = definition.wildcard_url
+        end
+      end
+    end
+
+    # @param hash [Hash] raw extracted params
+    # @return [ActionController::Parameters] permitted params
+    def permitted_params(hash)
+      ActionController::Parameters.new(hash).permit(*hash.keys)
+    end
+
+    # Returns all page definitions that have a wildcard_url defined.
+    #
+    # @return [Array<PageDefinition>]
+    def wildcard_definitions
+      @_wildcard_definitions ||= PageDefinition.all.select { |d| d.wildcard_url&.present? }
+    end
+  end
+end

spec/services/alchemy/page_finder_spec.rb

@@ -0,0 +1,195 @@
+# 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/:product_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) }
+
+    it "finds a wildcard page and extracts params" do
+      result = described_class.new("products/123").call
+      expect(result.page).to eq(product_detail_page)
+      expect(result.extracted_params[:id]).to eq("123")
+    end
+
+    it "finds a page by exact urlname" do
+      result = described_class.new("products").call
+      expect(result.page).to eq(products_page)
+    end
+
+    it "finds a nested page by its full urlname" do
+      result = described_class.new(comments_page.urlname).call
+      expect(result.page).to eq(comments_page)
+    end
+
+    it "returns nil for a blank path" do
+      expect(described_class.new("").call).to be_nil
+    end
+
+    it "returns nil for a path with no matching prefix" do
+      expect(described_class.new("other/123").call).to be_nil
+    end
+
+    context "single-segment pattern with integer constraint" do
+      it "matches /products/123 and prefers the constrained sibling" do
+        result = described_class.new("products/123").call
+        expect(result.page).to eq(product_detail_page)
+        expect(result.extracted_params[:id]).to eq("123")
+        expect(result.extracted_params).not_to have_key(:slug)
+      end
+
+      it "rejects non-integer and falls through to unconstrained sibling" do
+        result = described_class.new("products/some-slug").call
+        expect(result.page).to eq(product_by_slug_page)
+        expect(result.extracted_params[:product_slug]).to eq("some-slug")
+        expect(result.extracted_params).not_to have_key(:id)
+      end
+    end
+
+    context "multi-segment pattern" do
+      it "matches /blog/2024/my-post and extracts both params" do
+        result = described_class.new("blog/2024/my-post").call
+        expect(result.page).to eq(blog_post_page)
+        expect(result.extracted_params[:year]).to eq("2024")
+        expect(result.extracted_params[:slug]).to eq("my-post")
+      end
+
+      it "does not match with wrong segment count" do
+        expect(described_class.new("blog/2024").call).to be_nil
+      end
+    end
+
+    context "pattern with static segments" do
+      let(:uuid) { "550e8400-e29b-41d4-a716-446655440000" }
+
+      it "matches /users/:uuid/profile" do
+        result = described_class.new("users/#{uuid}/profile").call
+        expect(result.page).to eq(user_profile_page)
+        expect(result.extracted_params[:uuid]).to eq(uuid)
+      end
+
+      it "does not match without the trailing static segment" do
+        expect(described_class.new("users/#{uuid}").call).to be_nil
+      end
+    end
+
+    context "hierarchical patterns (grandchild under pattern page)" do
+      it "matches /products/42/comments through the pattern parent" do
+        result = described_class.new("products/42/comments").call
+        expect(result.page).to eq(comments_page)
+        expect(result.extracted_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 product_slug and id" do
+        result = described_class.new("category/electronics/42").call
+        expect(result.page).to eq(category_detail)
+        expect(result.extracted_params[:product_slug]).to eq("electronics")
+        expect(result.extracted_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
+        result = described_class.new("shared/2024/my-post").call
+        expect(result.page).to eq(multi_segment_page)
+        expect(result.extracted_params[:year]).to eq("2024")
+        expect(result.extracted_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
+        result = described_class.new("static-parent/foo/bar").call
+        expect(result.page).to eq(static_page)
+        expect(result.extracted_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
+        result = described_class.new("warehouse/AB-1234").call
+        expect(result.page).to eq(sku_page)
+        expect(result.extracted_params[:sku]).to eq("AB-1234")
+      end
+
+      it "does not match when the value violates the regex" do
+        expect(described_class.new("warehouse/invalid").call).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("anything").call).to be_nil
+    end
+  end
+end