utopia 2.32.0 → 3.0.0

data/lib/utopia/session/middleware.rb

@@ -1,21 +1,26 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2025, by Samuel Williams.
-# Copyright, 2019, by Huba Nagy.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "openssl"
 require "digest/sha2"
 require "console"
 require "json"
 
+require "protocol/http/cookie"
+
 require_relative "lazy_hash"
 require_relative "serialization"
+require_relative "../middleware"
+require_relative "../request"
+require_relative "../response"
 
 module Utopia
 	module Session
 		# A middleware which provides a secure client-side session storage using a private symmetric encrpytion key.
-		class Middleware
+		class Middleware < Protocol::HTTP::Middleware
+			# Raised when payload processing fails.
 			class PayloadError < StandardError
 			end
 			
@@ -23,7 +28,7 @@ module Utopia
 			
 			SECRET_KEY = "UTOPIA_SESSION_SECRET".freeze
 			
-			RACK_SESSION = "rack.session".freeze
+			SESSION_KEY = "utopia.session".freeze
 			CIPHER_ALGORITHM = "aes-256-cbc"
 			
 			# The session will expire if no requests were made within 24 hours:
@@ -33,12 +38,19 @@ module Utopia
 			DEFAULT_UPDATE_TIMEOUT = 3600
 			
 			# @param session_name [String] The name of the session cookie.
-			# @param secret [Array] The secret text used to generate a symetric encryption key for the coookie data.
-			# @param same_site [Symbol, String] Controls how the cookie is provided to the site.
-			# @param expires_after [String] The cache-control header to set for static content.
-			# @param options [Hash<Symbol,Object>] Additional defaults used for generating the cookie by `Rack::Utils.set_cookie_header!`.
-			def initialize(app, session_name: RACK_SESSION, secret: nil, expires_after: DEFAULT_EXPIRES_AFTER, update_timeout: DEFAULT_UPDATE_TIMEOUT, secure: false, same_site: :lax, maximum_size: MAXIMUM_SIZE, **options)
-				@app = app
+			# @param secret [String] The secret text used to generate a symmetric encryption key for the cookie data.
+			# @param expires_after [Numeric | Nil] The maximum session inactivity in seconds.
+			# @param update_timeout [Numeric | Nil] The maximum interval between session cookie updates.
+			# @param domain [String | Nil] The domain for which the cookie is valid.
+			# @param path [String | Nil] The path for which the cookie is valid.
+			# @param max_age [Integer | Nil] The browser cookie lifetime in seconds.
+			# @param secure [Boolean] Whether the cookie requires a secure connection.
+			# @param http_only [Boolean] Whether client-side scripts may access the cookie.
+			# @param same_site [Symbol | String | Boolean | Nil] Controls whether the cookie is sent with cross-site requests.
+			# @param partitioned [Boolean] Whether the cookie uses partitioned storage.
+			# @param maximum_size [Integer | Nil] The maximum encoded session payload size.
+			def initialize(app, session_name: SESSION_KEY, secret: nil, expires_after: DEFAULT_EXPIRES_AFTER, update_timeout: DEFAULT_UPDATE_TIMEOUT, domain: nil, path: "/", max_age: nil, secure: false, http_only: true, same_site: :lax, partitioned: false, maximum_size: MAXIMUM_SIZE)
+				super(app)
 				
 				@session_name = session_name
 				@cookie_name = @session_name + ".encrypted"
@@ -54,18 +66,20 @@ module Utopia
 				@update_timeout = update_timeout
 				
 				@cookie_defaults = {
-					domain: nil,
-					path: "/",
+					domain: domain,
+					path: path,
+					max_age: max_age,
 					
 					# The SameSite attribute controls when the cookie is sent to the server, from 3rd parties (None), from requests with external referrers (Lax) or from within the site itself (Strict).
-					same_site: same_site,
+					same_site: normalize_same_site(same_site),
 					
 					# The Secure attribute is meant to keep cookie communication limited to encrypted transmission, directing browsers to use cookies only via secure/encrypted connections. However, if a web server sets a cookie with a secure attribute from a non-secure connection, the cookie can still be intercepted when it is sent to the user by man-in-the-middle attacks. Therefore, for maximum security, cookies with the Secure attribute should only be set over a secure connection.
 					secure: secure,
 					
 					# The HttpOnly attribute directs browsers not to expose cookies through channels other than HTTP (and HTTPS) requests. This means that the cookie cannot be accessed via client-side scripting languages (notably JavaScript), and therefore cannot be stolen easily via cross-site scripting (a pervasive attack technique).
-					http_only: true,
-				}.merge(options)
+					http_only: http_only,
+					partitioned: partitioned,
+				}
 				
 				@serialization = Serialization.new
 				@maximum_size = maximum_size
@@ -79,6 +93,8 @@ module Utopia
 			
 			attr :cookie_defaults
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -91,25 +107,44 @@ module Utopia
 				super
 			end
 			
-			def call(env)
-				session_hash = prepare_session(env)
+			# Attach a lazily loaded session to the request, then persist it.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The wrapped application response.
+			def call(request)
+				request.session = prepare_session(request)
 				
-				status, headers, body = @app.call(env)
+				response = Response.wrap(@delegate.call(request))
 				
-				update_session(env, session_hash, headers)
+				update_session(request.session, response.headers)
 				
-				return [status, headers, body]
+				return response
 			end
 			
 			protected
 			
-			def prepare_session(env)
-				env[RACK_SESSION] = LazyHash.new do
-					self.load_session_values(env)
+			# Normalize a SameSite option to its cookie directive value:
+			def normalize_same_site(same_site)
+				case same_site
+				when false, nil
+					return nil
+				when :none, "None", :None
+					return "None"
+				when :lax, "Lax", :Lax
+					return "Lax"
+				when true, :strict, "Strict", :Strict
+					return "Strict"
+				else
+					raise ArgumentError, "Invalid same_site value: #{same_site.inspect}!"
 				end
 			end
 			
-			def update_session(env, session_hash, headers)
+			def prepare_session(request)
+				LazyHash.new do
+					self.load_session_values(request)
+				end
+			end
+			
+			def update_session(session_hash, headers)
 				if session_hash.needs_update?(@update_timeout)
 					values = session_hash.values
 					
@@ -132,9 +167,7 @@ module Utopia
 			
 			# Load session from user supplied cookie. If the data is invalid or otherwise fails validation, `build_iniital_session` is invoked.
 			# @return hash of values.
-			def load_session_values(env)
-				request = Rack::Request.new(env)
-				
+			def load_session_values(request)
 				# Decrypt the data from the user if possible:
 				if data = request.cookies[@cookie_name]
 					begin
@@ -178,7 +211,45 @@ module Utopia
 					expires: expires(updated_at)
 				}.merge(@cookie_defaults)
 				
-				Rack::Utils.set_cookie_header!(headers, @cookie_name, cookie)
+				headers.add("set-cookie", cookie_header(@cookie_name, cookie))
+			end
+			
+			def cookie_header(name, cookie)
+				directives = {}
+				
+				if domain = cookie[:domain]
+					directives["Domain"] = domain
+				end
+				
+				if path = cookie[:path]
+					directives["Path"] = path
+				end
+				
+				if max_age = cookie[:max_age]
+					directives["Max-Age"] = max_age
+				end
+				
+				if expires = cookie[:expires]
+					directives["Expires"] = expires.httpdate
+				end
+				
+				if cookie[:secure]
+					directives["Secure"] = true
+				end
+				
+				if cookie[:http_only]
+					directives["HttpOnly"] = true
+				end
+				
+				if same_site = cookie[:same_site]
+					directives["SameSite"] = same_site
+				end
+				
+				if cookie[:partitioned]
+					directives["Partitioned"] = true
+				end
+				
+				return Protocol::HTTP::Cookie.new(name, cookie.fetch(:value), directives).to_s
 			end
 			
 			def encrypt(hash)
@@ -192,7 +263,7 @@ module Utopia
 				e = c.update(@serialization.dump(hash))
 				e << c.final
 				
-				return [iv, e].pack("m16m*")
+				return [iv + e].pack("m0")
 			end
 			
 			def decrypt(data)
@@ -200,7 +271,9 @@ module Utopia
 					raise PayloadError, "Session payload size #{data.bytesize}bytes exceeds maximum allowed size #{@maximum_size}bytes!"
 				end
 				
-				iv, e = data.unpack("m16m*")
+				payload = data.unpack1("m0")
+				iv = payload.byteslice(0, 16)
+				e = payload.byteslice(16..)
 				
 				c = OpenSSL::Cipher.new(CIPHER_ALGORITHM)
 				c.decrypt

data/lib/utopia/session/serialization.rb

@@ -10,7 +10,9 @@ require "date"
 
 module Utopia
 	module Session
+		# Encodes and decodes session values using MessagePack.
 		class Serialization
+			# Initialize a MessagePack factory with session-specific scalar types.
 			def initialize
 				@factory = MessagePack::Factory.new
 				
@@ -23,10 +25,16 @@ module Utopia
 			
 			attr :factory
 			
+			# Decode a MessagePack session value.
+			# @parameter data [String] The serialized data.
+			# @returns [Object] The decoded value.
 			def load(data)
 				@factory.unpack(data)
 			end
 			
+			# Encode a session value using MessagePack.
+			# @parameter object [Object] The value to encode.
+			# @returns [String] The encoded value.
 			def dump(object)
 				@factory.pack(object)
 			end

data/lib/utopia/session.rb

@@ -7,7 +7,12 @@
 require_relative "session/middleware"
 
 module Utopia
+	# Provides cookie-backed session middleware.
 	module Session
+		# Build session middleware around an application.
+		# @parameter arguments [Array] Positional arguments forwarded to {Middleware#initialize}.
+		# @parameter options [Hash] Keyword arguments forwarded to {Middleware#initialize}.
+		# @returns [Middleware] The session middleware.
 		def self.new(...)
 			Middleware.new(...)
 		end

data/lib/utopia/setup.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2010-2025, by Samuel Williams.
+# Copyright, 2010-2026, by Samuel Williams.
 
 require "yaml"
 require "securerandom"
@@ -13,36 +13,54 @@ require "console"
 module Utopia
 	# Used for setting up a Utopia web application, typically via `config/environment.rb`
 	class Setup
+		# Initialize application setup for the given root.
+		# @parameter root [String] The root directory.
+		# @parameter options [Hash] Reserved setup options.
 		def initialize(root, **options)
 			@root = root
 		end
 		
 		attr :root
 		
+		# Resolve the application's configuration directory.
+		# @returns [String] The absolute configuration path.
 		def config_root
 			File.expand_path("config", @root)
 		end
 		
+		# Return the application root.
+		# @returns [String] The application root path.
 		def site_root
 			@root
 		end
 		
+		# Check whether the application is running in production.
+		# @returns [Boolean] Whether the active Utopia variant is `production`.
 		def production?
 			Variant.for(:utopia) == :production
 		end
 		
+		# Check whether the application is running in staging.
+		# @returns [Boolean] Whether the active Utopia variant is `staging`.
 		def staging?
 			Variant.for(:utopia) == :staging
 		end
 		
+		# Check whether the application is running in development.
+		# @returns [Boolean] Whether the active Utopia variant is `development`.
 		def development?
 			Variant.for(:utopia) == :development
 		end
 		
+		# Check whether the application is running in testing.
+		# @returns [Boolean] Whether the active Utopia variant is `testing`.
 		def testing?
 			Variant.for(:utopia) == :testing
 		end
 		
+		# Fetch the configured secret for the given key.
+		# @parameter key [String | Symbol] The lookup key.
+		# @returns [String] The configured secret, or a newly generated transient secret when none is configured.
 		def secret_for(key)
 			secret = ENV["UTOPIA_#{key.upcase}_SECRET"]
 			
@@ -57,6 +75,8 @@ module Utopia
 			return secret
 		end
 		
+		# Apply.
+		# @returns [self] This object.
 		def apply!
 			add_load_path("lib")
 			
@@ -93,7 +113,7 @@ module Utopia
 			path = environment_path(variant)
 			
 			if File.exist?(path)
-				Console.debug(self) {"Loading environment at path: #{path.inspect}"}
+				Console.debug(self){"Loading environment at path: #{path.inspect}"}
 				
 				# Load the YAML environment file:
 				if environment = YAML.load_file(path)
@@ -105,7 +125,7 @@ module Utopia
 				
 				return true
 			else
-				Console.debug(self) {"Ignoring environment at path: #{path.inspect} (file not found)"}
+				Console.debug(self){"Ignoring environment at path: #{path.inspect} (file not found)"}
 				
 				return false
 			end

data/lib/utopia/shell.rb

@@ -3,30 +3,51 @@
 # Released under the MIT License.
 # Copyright, 2020-2025, by Samuel Williams.
 
-require "rack/builder"
-require "rack/test"
+require "protocol/http/request"
+require_relative "application"
 require "irb"
 
 module Utopia
 	# This is designed to be used with the corresponding bake task.
 	class Shell
-		include Rack::Test::Methods
-		
+		# Initialize a shell for a Bake context.
+		# @parameter context [Bake::Context] The context that provides the application root.
 		def initialize(context)
 			@context = context
 			@app = nil
 		end
 		
+		# Load the configured application on first access.
+		# @returns [Application] The application middleware.
 		def app
-			@app ||= Rack::Builder.parse_file(
-				File.expand_path("config.ru", @context.root)
-			).first
+			@app ||= Application.load(File.expand_path(Application::PATH, @context.root))
+		end
+		
+		# Perform a GET request.
+		# @parameter path [Utopia::Path | String] The path.
+		# @parameter headers [Hash] The headers.
+		# @returns [Protocol::HTTP::Response] The application response.
+		def get(path, headers = nil)
+			app.call(Protocol::HTTP::Request["GET", path, headers])
+		end
+		
+		# Perform a POST request.
+		# @parameter path [Utopia::Path | String] The path.
+		# @parameter headers [Hash] The headers.
+		# @parameter body [Protocol::HTTP::Body::Readable | Nil] The request body.
+		# @returns [Protocol::HTTP::Response] The application response.
+		def post(path, headers = nil, body = nil)
+			app.call(Protocol::HTTP::Request["POST", path, headers, body])
 		end
 		
+		# Convert this object to a string.
+		# @returns [String] The resulting string.
 		def to_s
 			self.class.name
 		end
 		
+		# Expose this shell's binding to IRB.
+		# @returns [Binding] The shell binding.
 		def binding
 			super
 		end

data/lib/utopia/static/local_file.rb

@@ -1,107 +1,130 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
 require "time"
 require "digest/sha1"
 
+require "protocol/http/body/file"
+require "protocol/http/body/head"
+require "protocol/http/header/range"
+
+require_relative "../response"
+
 module Utopia
 	# A middleware which serves static files from the specified root directory.
 	module Static
-		# Represents a local file on disk which can be served directly, or passed upstream to sendfile.
+		# Represents a local static resource and constructs responses for it.
 		class LocalFile
-			def initialize(root, path)
-				@root = root
+			# Initialize metadata for a local file.
+			# @parameter path [String] The resolved filesystem path.
+			def initialize(path)
 				@path = path
-				@etag = Digest::SHA1.hexdigest("#{File.size(full_path)}#{mtime_date}")
+				@stat = File.stat(@path)
+				@mtime_date = @stat.mtime.httpdate
 				
-				@range = nil
+				fingerprint = Digest::SHA1.hexdigest("#{@stat.size}:#{@stat.mtime.to_i}:#{@stat.mtime.nsec}")
+				@etag = %Q{W/"#{fingerprint}"}
 			end
 			
-			attr :root
 			attr :path
 			attr :etag
-			attr :range
-			
-			# Fit in with Rack::Sendfile
-			def to_path
-				full_path
-			end
-			
-			def full_path
-				File.join(@root, @path.components)
-			end
 			
+			# Format the file's modification time for an HTTP header.
+			# @returns [String] The HTTP-date modification time.
 			def mtime_date
-				File.mtime(full_path).httpdate
+				@mtime_date
 			end
 			
+			# Measure the file's content length.
+			# @returns [Integer] The file size in bytes.
 			def bytesize
-				File.size(full_path)
-			end
-			
-			# This reflects whether calling each would yield anything.
-			def empty?
-				bytesize == 0
+				@stat.size
 			end
 			
-			alias size bytesize
-			
-			def each
-				File.open(full_path, "rb") do |file|
-					file.seek(@range.begin)
-					remaining = @range.end - @range.begin+1
-					
-					while remaining > 0
-						break unless part = file.read([8192, remaining].min)
-						
-						remaining -= part.length
-						
-						yield part
-					end
-				end
-			end
-			
-			def modified?(env)
-				if modified_since = env["HTTP_IF_MODIFIED_SINCE"]
-					return false if File.mtime(full_path) <= Time.parse(modified_since)
+			# Check whether the file has changed since the request validators.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Boolean] Whether the file is newer than the request validators.
+			def modified?(request)
+				if etags = request.headers["if-none-match"]
+					return !etags.weak_match?(@etag)
 				end
 				
-				if etags = env["HTTP_IF_NONE_MATCH"]
-					etags = etags.split(/\s*,\s*/)
-					return false if etags.include?(etag) || etags.include?("*")
+				if modified_since = request.headers["if-modified-since"]
+					return @stat.mtime.to_i > modified_since.to_time.to_i
 				end
 				
 				return true
 			end
 			
-			CONTENT_LENGTH = Rack::CONTENT_LENGTH
-			CONTENT_RANGE = "Content-Range".freeze
+			CONTENT_LENGTH = "content-length".freeze
+			CONTENT_RANGE = "content-range".freeze
 			
-			def serve(env, response_headers)
-				ranges = Rack::Utils.get_byte_ranges(env["HTTP_RANGE"], size)
-				response = [200, response_headers, self]
+			# Serve.
+			# @parameter request [Utopia::Request] The request.
+			# @parameter response_headers [Hash] The response headers.
+			# @returns [Protocol::HTTP::Response] The response.
+			def serve(request, response_headers)
+				ranges = byte_ranges(request)
+				size = bytesize
 				
 				# puts "Requesting ranges: #{ranges.inspect} (#{size})"
 				
 				if ranges == nil or ranges.size != 1
 					# No ranges, or multiple ranges (which we don't support).
 					# TODO: Support multiple byte-ranges, for now just send entire file:
-					response[0] = 200
-					response[1][CONTENT_LENGTH] = size.to_s
-					@range = 0...size
+					status = 200
+					response_headers[CONTENT_LENGTH] = size.to_s
+					range = nil
 				else
 					# Partial content:
-					@range = ranges[0]
-					partial_size = @range.size
+					range = ranges[0]
+					partial_size = range.size
 					
-					response[0] = 206
-					response[1][CONTENT_LENGTH] = partial_size.to_s
-					response[1][CONTENT_RANGE] = "bytes #{@range.min}-#{@range.max}/#{size}"
+					status = 206
+					response_headers[CONTENT_LENGTH] = partial_size.to_s
+					response_headers[CONTENT_RANGE] = "bytes #{range.min}-#{range.max}/#{size}"
 				end
 				
-				return response
+				if request.head?
+					body = Protocol::HTTP::Body::Head.new(size)
+				else
+					body = Protocol::HTTP::Body::File.open(@path, range, size: size)
+				end
+				
+				return Response[status, response_headers, body]
+			end
+			
+			# Resolve satisfiable byte ranges from the parsed range header.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Array | Nil] The resulting values, or `nil` if the range is not applicable.
+			def byte_ranges(request)
+				return nil unless request.method == Protocol::HTTP::Methods::GET
+				
+				range = request.headers["range"]
+				return nil unless range&.bytes?
+				
+				if validator = request.headers["if-range"]
+					return nil unless if_range?(validator)
+				end
+				
+				return range.resolve(bytesize)
+			end
+			
+			# Check whether an If-Range validator strongly matches this file.
+			# @parameter validator [String] The If-Range entity tag or HTTP date.
+			# @returns [Boolean] Whether the range can be served safely.
+			private def if_range?(validator)
+				validator = validator.to_s
+				
+				# Date validators cannot be used because this file's modification date is not known to be strong:
+				return false unless validator.start_with?('"')
+				
+				# Weak entity tags cannot authorize a partial response:
+				return false if @etag.start_with?("W/")
+				
+				return @etag == validator
 			end
 		end
 	end