utopia 2.30.2 → 2.31.0

data/lib/utopia/controller.rb

@@ -3,134 +3,12 @@
 # Released under the MIT License.
 # Copyright, 2009-2025, by Samuel Williams.
 
-require_relative "path"
-
-require_relative "middleware"
-require_relative "controller/variables"
-require_relative "controller/base"
-
-require_relative "controller/rewrite"
-require_relative "controller/respond"
-require_relative "controller/actions"
-
-require "concurrent/map"
+require_relative "controller/middleware"
 
 module Utopia
-	# A middleware which loads controller classes and invokes functionality based on the requested path.
-	class Controller
-		# The controller filename.
-		CONTROLLER_RB = "controller.rb".freeze
-		
-		def self.[] request
-			request.env[VARIABLES_KEY]
-		end
-		
-		# @param root [String] The content root where controllers will be loaded from.
-		# @param base [Class] The base class for controllers.
-		def initialize(app, root: Utopia::default_root, base: Controller::Base)
-			@app = app
-			@root = root
-			
-			@controller_cache = Concurrent::Map.new
-			
-			@base = base
-		end
-		
-		attr :app
-		
-		def freeze
-			return self if frozen?
-			
-			@root.freeze
-			@base.freeze
-			
-			super
-		end
-		
-		# Fetch the controller for the given relative path. May be cached.
-		def lookup_controller(path)
-			@controller_cache.fetch_or_store(path.to_s) do
-				load_controller_file(path)
-			end
-		end
-		
-		# Loads the controller file for the given relative url_path.
-		def load_controller_file(uri_path)
-			base_path = File.join(@root, uri_path.components)
-			
-			controller_path = File.join(base_path, CONTROLLER_RB)
-			# puts "load_controller_file(#{path.inspect}) => #{controller_path}"
-			
-			if File.exist?(controller_path)
-				klass = Class.new(@base)
-				
-				# base_path is expected to be a string representing a filesystem path:
-				klass.const_set(:BASE_PATH, base_path.freeze)
-				
-				# uri_path is expected to be an instance of Path:
-				klass.const_set(:URI_PATH, uri_path.dup.freeze)
-				
-				klass.const_set(:CONTROLLER, self)
-				
-				klass.class_eval(File.read(controller_path), controller_path)
-				
-				# We lock down the controller class to prevent unsafe modifications:
-				klass.freeze
-				
-				# Create an instance of the controller:
-				return klass.new
-			else
-				return nil
-			end
-		end
-		
-		# Invoke the controller layer for a given request. The request path may be rewritten.
-		def invoke_controllers(request)
-			request_path = Path.from_string(request.path_info)
-			
-			# The request path must be absolute. We could handle this internally but it is probably better for this to be an error:
-			raise ArgumentError.new("Invalid request path #{request_path}") unless request_path.absolute?
-			
-			# The controller path contains the current complete path being evaluated:
-			controller_path = Path.new
-			
-			# Controller instance variables which eventually get processed by the view:
-			variables = request.env[VARIABLES_KEY]
-			
-			while request_path.components.any?
-				# We copy one path component from the relative path to the controller path at a time. The controller, when invoked, can modify the relative path (by assigning to relative_path.components). This allows for controller-relative rewrites, but only the remaining path postfix can be modified.
-				controller_path.components << request_path.components.shift
-				
-				if controller = lookup_controller(controller_path)
-					# Don't modify the original controller:
-					controller = controller.clone
-					
-					# Append the controller to the set of controller variables, updates the controller with all current instance variables.
-					variables << controller
-					
-					if result = controller.process!(request, request_path)
-						return result
-					end
-				end
-			end
-			
-			# Controllers can directly modify relative_path, which is copied into controller_path. The controllers may have rewriten the path so we update the path info:
-			request.env[Rack::PATH_INFO] = controller_path.to_s
-			
-			# No controller gave a useful result:
-			return nil
-		end
-		
-		def call(env)
-			env[VARIABLES_KEY] ||= Variables.new
-			
-			request = Rack::Request.new(env)
-			
-			if result = invoke_controllers(request)
-				return result
-			end
-			
-			return @app.call(env)
+	module Controller
+		def self.new(...)
+			Middleware.new(...)
 		end
 	end
 end

data/lib/utopia/exceptions/mailer.rb

@@ -154,7 +154,7 @@ module Utopia
 				
 				mail.text_part = Mail::Part.new
 				mail.text_part.body = generate_body(exception, env)
-			
+				
 				if body = extract_body(env) and body.size > 0
 					mail.attachments["body.bin"] = body
 				end
@@ -162,10 +162,10 @@ module Utopia
 				if @dump_environment
 					mail.attachments["environment.yaml"] = YAML.dump(env)
 				end
-
+				
 				return mail
 			end
-
+			
 			def send_notification(exception, env)
 				mail = generate_mail(exception, env)
 				
@@ -176,7 +176,7 @@ module Utopia
 				$stderr.puts mail_exception.to_s
 				$stderr.puts mail_exception.backtrace
 			end
-
+			
 			def extract_body(env)
 				if io = env["rack.input"]
 					io.rewind if io.respond_to?(:rewind)

data/lib/utopia/extensions/array_split.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2024, by Samuel Williams.
+# Copyright, 2009-2025, by Samuel Williams.
 
 module Utopia
 	module Extensions
@@ -14,7 +14,7 @@ module Utopia
 				end
 			end
 		end
-
+		
 		::Array.prepend(ArraySplit)
 	end
 end

data/lib/utopia/extensions/date_comparisons.rb

@@ -17,9 +17,9 @@ module Utopia
 				end
 			end
 		end
-
+		
 		::Time.prepend(TimeDateComparison)
-
+		
 		# Provides comparison operator extensions.
 		module DateTimeComparison
 			def <=>(other)
@@ -30,7 +30,7 @@ module Utopia
 				end
 			end
 		end
-
+		
 		::Date.prepend(DateTimeComparison)
 	end
 end

data/lib/utopia/import_map.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "json"
+require "xrb"
+require "protocol/url"
+
+module Utopia
+	# Represents an import map for JavaScript modules with support for URI and relative path resolution.
+	# Import maps allow you to control how JavaScript imports are resolved, supporting both absolute
+	# URLs and relative paths with proper context-aware resolution.
+	#
+	# The builder pattern supports nested base URIs that are properly resolved relative to parent bases.
+	# All URL resolution follows RFC 3986 via the `protocol-url` gem.
+	#
+	# @example Basic usage with absolute URLs.
+	# 	import_map = Utopia::ImportMap.build do |map|
+	# 		map.import("react", "https://esm.sh/react@18")
+	# 		map.import("@myapp/utils", "./js/utils.js", integrity: "sha384-...")
+	# 	end
+	# 	
+	# 	puts import_map.to_html
+	#
+	# @example Using nested base URIs for different CDNs.
+	# 	import_map = Utopia::ImportMap.build do |map|
+	# 		# Imports without base
+	# 		map.import("app", "/app.js")
+	# 		
+	# 		# CDN imports - base is set to jsdelivr
+	# 		map.with(base: "https://cdn.jsdelivr.net/npm/") do |m|
+	# 			m.import "lit", "lit@2.7.5/index.js"
+	# 			m.import "lit/decorators.js", "lit@2.7.5/decorators.js"
+	# 		end
+	# 		
+	# 		# Nested base combines with parent: "https://cdn.jsdelivr.net/npm/mermaid@10/"
+	# 		map.with(base: "https://cdn.jsdelivr.net/npm/") do |m|
+	# 			m.with(base: "mermaid@10/") do |nested|
+	# 				nested.import "mermaid", "dist/mermaid.esm.min.mjs"
+	# 			end
+	# 		end
+	# 	end
+	#
+	# @example Creating page-specific import maps with relative paths.
+	# 	# Global import map with base: "/_components/"
+	# 	global_map = Utopia::ImportMap.build(base: "/_components/") do |map|
+	# 		map.import("button", "./button.js")
+	# 	end
+	# 	
+	# 	# For a page at /foo/bar/, create a context-specific import map
+	# 	page_map = global_map.relative_to("/foo/bar/")
+	# 	# Base becomes: "../../_components/"
+	# 	# button import resolves to: "../../_components/button.js"
+	# 	
+	# 	puts page_map.to_html
+	class ImportMap
+		# Builder class for constructing import maps with scoped base URIs.
+		#
+		# The builder supports nested `with(base:)` blocks where each base is resolved
+		# relative to its parent base, following RFC 3986 URL resolution rules.
+		#
+		# @example Nested base resolution.
+		# 	ImportMap.build do |map|
+		# 		# No base - imports as-is
+		# 		map.import("app", "/app.js")
+		# 		
+		# 		# Base: "https://cdn.example.com/"
+		# 		map.with(base: "https://cdn.example.com/") do |cdn|
+		# 			cdn.import("lib", "lib.js")  # => "https://cdn.example.com/lib.js"
+		# 			
+		# 			# Nested base: "https://cdn.example.com/" + "v2/" = "https://cdn.example.com/v2/"
+		# 			cdn.with(base: "v2/") do |v2|
+		# 				v2.import("new-lib", "lib.js")  # => "https://cdn.example.com/v2/lib.js"
+		# 			end
+		# 		end
+		# 	end
+		class Builder
+			def self.build(import_map, **options, &block)
+				builder = self.new(import_map, **options)
+				
+				if block.arity == 1
+					yield(builder)
+				else
+					builder.instance_eval(&block)
+				end
+				
+				return builder
+			end
+			
+			def initialize(import_map, base: nil)
+				@import_map = import_map
+				@base = Protocol::URL[base]
+			end
+			
+			# Add an import mapping with the current base URI.
+			#
+			# If a base is set, the value is resolved relative to that base following RFC 3986.
+			# Absolute URLs (scheme://...) are preserved as-is when used as values.
+			#
+			# @parameter specifier [String] The module specifier (e.g., "react", "@myapp/utils").
+			# @parameter value [String] The URL or path to resolve to.
+			# @parameter integrity [String, nil] Optional subresource integrity hash.
+			# @returns [Builder] Self for method chaining.
+			#
+			# @example With base URL.
+			# 	builder = Builder.new(map, base: "https://cdn.com/")
+			# 	builder.import("lib", "lib.js")  # Resolves to: "https://cdn.com/lib.js"
+			# 	builder.import("ext", "https://other.com/ext.js")  # Keeps: "https://other.com/ext.js"
+			def import(specifier, value, integrity: nil)
+				resolved_value = if @base
+					value_url = Protocol::URL[value]
+					
+					# Combine base with value
+					(@base + value_url).to_s
+				else
+					value
+				end
+				
+				@import_map.import(specifier, resolved_value, integrity: integrity)
+				
+				self
+			end
+			
+			# Create a nested scope with a different base URI.
+			#
+			# The new base is resolved relative to the current base. This allows for
+			# hierarchical organization of imports from different sources.
+			#
+			# @parameter base [String] The new base URI, resolved relative to current base.
+			# @yields [Builder] A new builder with the resolved base.
+			# @returns [Builder] The builder instance.
+			#
+			# @example Nested CDN paths.
+			# 	builder.with(base: "https://cdn.com/") do |cdn|
+			# 		cdn.with(base: "libs/v2/") do |v2|
+			# 			# Base is now: "https://cdn.com/libs/v2/"
+			# 			v2.import("util", "util.js")  # => "https://cdn.com/libs/v2/util.js"
+			# 		end
+			# 	end
+			def with(base:, &block)
+				# Resolve the new base relative to the current base
+				resolved_base = if @base
+					@base + Protocol::URL[base]
+				else
+					base
+				end
+				
+				self.class.build(@import_map, base: resolved_base, &block)
+			end
+			
+			# Add a scope mapping.
+			#
+			# Scopes allow different import resolutions for different parts of your application.
+			#
+			# @parameter scope_prefix [String] The scope prefix (e.g., "/pages/").
+			# @parameter imports [Hash] Import mappings specific to this scope.
+			# @returns [Builder] Self for method chaining.
+			#
+			# @example Scope-specific imports.
+			# 	builder.scope("/admin/", {"utils" => "/admin/utils.js"})
+			def scope(scope_prefix, imports)
+				@import_map.scope(scope_prefix, imports)
+				self
+			end
+		end
+		
+		# Create an import map using a builder pattern.
+		#
+		# The builder supports both block parameter and instance_eval styles.
+		# The returned import map is frozen to prevent accidental mutation.
+		#
+		# @parameter base [String, nil] The base URI for resolving relative paths.
+		# @yields {|builder| ...} If a block is given.
+		# 	@parameter builder [Builder] The import map builder, if the block takes an argument.
+		# @returns [ImportMap] A frozen import map instance.
+		#
+		# @example Block parameter style.
+		# 	import_map = ImportMap.build do |map|
+		# 		map.import("react", "https://esm.sh/react")
+		# 	end
+		#
+		# @example Instance eval style.
+		# 	import_map = ImportMap.build do
+		# 		import "react", "https://esm.sh/react"
+		# 	end
+		def self.build(base: nil, &block)
+			instance = self.new(base: base)
+			
+			builder = Builder.build(instance, &block)
+			
+			return instance.freeze
+		end
+		
+		# Initialize a new import map.
+		#
+		# Typically you should use {build} instead of calling this directly.
+		#
+		# @parameter imports [Hash] The imports mapping.
+		# @parameter integrity [Hash] Integrity hashes for imports.
+		# @parameter scopes [Hash] Scoped import mappings.
+		# @parameter base [String, Protocol::URL, nil] The base URI for resolving relative paths.
+		def initialize(imports = {}, integrity = {}, scopes = {}, base: nil)
+			@imports = imports
+			@integrity = integrity
+			@scopes = scopes
+			@base = Protocol::URL[base]
+		end
+		
+		# @attribute [Hash(String, String)] The imports mapping.
+		attr :imports
+		
+		# @attribute [Hash(String, String)] Subresource integrity hashes for imports.
+		attr :integrity
+		
+		# @attribute [Hash(String, Hash)] Scoped import mappings.
+		attr :scopes
+		
+		# @attribute [Protocol::URL::Absolute | Protocol::URL::Relative | nil] The parsed base URL for efficient resolution.
+		attr :base
+		
+		# Add an import mapping.
+		#
+		# @parameter specifier [String] The import specifier (e.g., "react", "@myapp/utils").
+		# @parameter value [String] The URL or path to resolve to.
+		# @parameter integrity [String, nil] Optional subresource integrity hash for the resource.
+		# @returns [ImportMap] Self for method chaining.
+		def import(specifier, value, integrity: nil)
+			@imports[specifier] = value
+			@integrity[specifier] = integrity if integrity
+			
+			self
+		end
+		
+		# Add a scope mapping.
+		#
+		# Scopes allow different import resolutions based on the referrer URL.
+		# See https://github.com/WICG/import-maps#scoping-examples for details.
+		#
+		# @parameter scope_prefix [String] The scope prefix (e.g., "/pages/").
+		# @parameter imports [Hash] Import mappings specific to this scope.
+		# @returns [ImportMap] Self for method chaining.
+		def scope(scope_prefix, imports)
+			@scopes[scope_prefix] = imports
+			
+			self
+		end
+		
+		# Create a new import map with paths relative to the given page path.
+		# This is useful for creating page-specific import maps from a global one.
+		#
+		# @parameter path [String] The absolute page path to make imports relative to.
+		# @returns [ImportMap] A new import map with a relative base.
+		#
+		# @example Creating page-specific import maps.
+		# 	# Global import map with base: "/_components/"
+		# 	import_map = ImportMap.build(base: "/_components/") { ... }
+		# 	
+		# 	# For a page at /foo/bar/, calculate relative path to components
+		# 	page_map = import_map.relative_to("/foo/bar/")
+		# 	# Base becomes: "../../_components/"
+		def relative_to(path)
+			if @base
+				# Calculate the relative path from the page to the base
+				relative_base = Protocol::URL::Path.relative(@base.path, path)
+				resolved_base = Protocol::URL[relative_base]
+			else
+				resolved_base = nil
+			end
+			
+			instance = self.class.new(@imports.dup, @integrity.dup, @scopes.dup, base: resolved_base)
+			
+			return instance.freeze
+		end
+		
+		# Resolve a single import value considering base context.
+		#
+		# @parameter value [String] The import URL or path value.
+		# @parameter base [Protocol::URL, nil] The base URL context for resolving relative paths.
+		# @returns [Protocol::URL, String] The resolved URL object or original string.
+		private def resolve_value(value, base)
+			if base
+				base + Protocol::URL[value]
+			else
+				value
+			end
+		end
+		
+		# Resolve a hash of imports with the given base.
+		#
+		# @parameter imports [Hash] The imports hash to resolve.
+		# @parameter base [Protocol::URL, nil] The base URL context.
+		# @returns [Hash] The resolved imports with string values.
+		private def resolve_imports(imports, base)
+			result = {}
+			
+			imports.each do |specifier, value|
+				result[specifier] = resolve_value(value, base).to_s
+			end
+			
+			result
+		end
+		
+		# Build the import map as a Hash with resolved paths.
+		#
+		# All relative paths are resolved against the base URL if present.
+		# Absolute URLs and protocol-relative URLs are preserved as-is.
+		# This method is compatible with the JSON gem's `as_json` convention.
+		#
+		# @returns [Hash] The resolved import map data structure ready for JSON serialization.
+		def as_json(...)
+			result = {}
+			
+			# Add imports
+			if @imports.any?
+				result["imports"] = resolve_imports(@imports, @base)
+			end
+			
+			# Add scopes
+			if @scopes.any?
+				result["scopes"] = {}
+				@scopes.each do |scope_prefix, scope_imports|
+					# Resolve the scope prefix itself with base
+					scope_url = Protocol::URL[scope_prefix]
+					resolved_prefix = if @base && !scope_url.is_a?(Protocol::URL::Absolute)
+						(@base + scope_url).to_s
+					else
+						scope_prefix
+					end
+					
+					result["scopes"][resolved_prefix] = resolve_imports(scope_imports, @base)
+				end
+			end
+			
+			# Add integrity
+			if @integrity.any?
+				result["integrity"] = @integrity.dup
+			end
+			
+			return result
+		end
+		
+		# Convert the import map to JSON.
+		#
+		# @returns [String] The JSON representation of the import map.
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
+		# Generate the import map as an XRB fragment suitable for embedding in HTML.
+		#
+		# Creates a `<script type="importmap">` tag containing the JSON representation.
+		#
+		# @returns [XRB::Builder::Fragment] The generated HTML fragment.
+		def to_html
+			json_data = to_json
+			
+			XRB::Builder.fragment do |builder|
+				builder.inline("script", type: "importmap") do
+					builder.raw(json_data)
+				end
+			end
+		end
+		
+		# Convenience method for rendering the import map as an HTML string.
+		#
+		# Equivalent to `to_html.to_s`.
+		#
+		# @returns [String] The generated HTML containing the import map script tag.
+		def to_s
+			to_html.to_s
+		end
+	end
+end