Document Utopia fiber state APIs

Assisted-By: devx/166ed168-1c4d-4c63-a5f6-8d0d9cbff13f

Author: samuel-williams-shopify

lib/utopia/context.rb

@@ -6,6 +6,7 @@
 module Utopia
 	# Accessors for request-scoped Utopia state stored directly in fiber storage.
 	module Context
+		# The fiber storage keys used by Utopia.
 		KEYS = {
 			request: :utopia_request,
 			request_path: :utopia_request_path,
@@ -16,14 +17,17 @@ module Context
 			exception: :utopia_exception
 		}.freeze
 
+		# Fetch a Utopia fiber state value.
 		def self.[] key
 			Fiber[KEYS.fetch(key)]
 		end
 
+		# Assign a Utopia fiber state value.
 		def self.[]= key, value
 			Fiber[KEYS.fetch(key)] = value
 		end
 
+		# Temporarily assign Utopia fiber state values for the duration of the block.
 		def self.with(**values)
 			previous = {}
 
@@ -39,21 +43,25 @@ def self.with(**values)
 			end
 		end
 
+		# Clear all Utopia fiber state values from the current fiber.
 		def self.clear
 			KEYS.each_value do |key|
 				Fiber[key] = nil
 			end
 		end
 
+		# Convert the current Utopia fiber state to a hash.
 		def self.to_hash
 			KEYS.transform_values{|key| Fiber[key]}
 		end
 
 		KEYS.each_key do |name|
+			# Fetch a named Utopia fiber state value.
 			define_singleton_method(name) do
 				self[name]
 			end
 
+			# Assign a named Utopia fiber state value.
 			define_singleton_method("#{name}=") do |value|
 				self[name] = value
 			end

lib/utopia/request.rb

@@ -10,43 +10,56 @@
 
 require_relative "context"
 
+# Protocol namespaces extended with Utopia request helpers.
 module Protocol
+	# HTTP protocol types extended with Utopia request helpers.
 	module HTTP
+		# Convenience methods used by Utopia middleware.
 		class Request
+			# The HTTP request method.
 			alias request_method method
 
+			# Whether the request method is GET.
 			def get?
 				self.method == "GET"
 			end
 
+			# Whether the request method is HEAD.
 			def head?
 				self.method == "HEAD"
 			end
 
+			# Whether the request method is POST.
 			def post?
 				self.method == "POST"
 			end
 
+			# Whether the request method is PUT.
 			def put?
 				self.method == "PUT"
 			end
 
+			# Whether the request method is PATCH.
 			def patch?
 				self.method == "PATCH"
 			end
 
+			# Whether the request method is DELETE.
 			def delete?
 				self.method == "DELETE"
 			end
 
+			# Whether the request method is OPTIONS.
 			def options?
 				self.method == "OPTIONS"
 			end
 
+			# The request path without the query string.
 			def path_info
 				self.path&.split("?", 2)&.first
 			end
 
+			# Set the request path while preserving the query string.
 			def path_info=(value)
 				if query = self.query
 					self.path = "#{value}?#{query}"
@@ -57,28 +70,34 @@ def path_info=(value)
 				@utopia_arguments = nil
 			end
 
+			# The query string without the leading question mark.
 			def query
 				self.path&.split("?", 2)&.last if self.path&.include?("?")
 			end
 
+			# Decoded query arguments.
 			def arguments
 				@utopia_arguments ||= decode_arguments(self.query)
 			end
 			alias params arguments
 
+			# Decoded request cookies.
 			def cookies
 				@utopia_cookies ||= parse_cookies(self.headers["cookie"])
 			end
 
+			# The request host with optional port.
 			def host
 				self.authority || self.headers["host"]
 			end
 			alias host_with_port host
 
+			# Whether the request uses HTTPS.
 			def ssl?
 				self.scheme == "https"
 			end
 
+			# The base URL for the request.
 			def base_url
 				if self.scheme && self.host
 					"#{self.scheme}://#{self.host}"
@@ -87,23 +106,28 @@ def base_url
 				end
 			end
 
+			# The request user agent.
 			def user_agent
 				self.headers["user-agent"]
 			end
 
+			# The request referrer.
 			def referrer
 				self.headers["referer"]
 			end
 			alias referer referrer
 
+			# The current Utopia session, if installed.
 			def session
 				Utopia::Context.session
 			end
 
+			# The remote peer IP address, if available.
 			def ip
 				self.peer&.ip_address
 			end
 
+			# The full request URL, if scheme and host are available.
 			def url
 				base_url = self.base_url
 
@@ -114,6 +138,7 @@ def url
 				end
 			end
 
+			# Build a derived request with updated protocol fields.
 			def with(method: self.method, path: self.path, path_info: nil)
 				request = self.dup
 				request.method = method
@@ -134,6 +159,7 @@ def with(method: self.method, path: self.path, path_info: nil)
 				return request
 			end
 
+			# Fetch a Rack-style compatibility value or query argument.
 			def [] key
 				case key
 				when "REQUEST_METHOD"

lib/utopia/session.rb

@@ -7,10 +7,13 @@
 require_relative "context"
 
 module Utopia
+	# Session access helpers and middleware constructor.
 	module Session
+		# Base class for Utopia session errors.
 		class Error < StandardError
 		end
 
+		# Raised when session access requires installed session middleware.
 		class MissingError < Error
 		end
 	end
@@ -20,27 +23,32 @@ class MissingError < Error
 
 module Utopia
 	module Session
-		
+		# Build a session middleware instance.
 		def self.new(...)
 			Middleware.new(...)
 		end
 
+		# The current session, if session middleware is installed.
 		def self.current
 			Context.session
 		end
 
+		# The current session, or raise a clear error if sessions are unavailable.
 		def self.required
 			self.current or raise MissingError, "No current Utopia session!"
 		end
 
+		# Fetch a value from the current session.
 		def self.[] key
 			self.required[key]
 		end
 
+		# Assign a value in the current session.
 		def self.[]= key, value
 			self.required[key] = value
 		end
 
+		# Delete a value from the current session.
 		def self.delete(key)
 			self.required.delete(key)
 		end

lib/utopia/session/lazy_hash.rb

@@ -7,15 +7,19 @@ module Utopia
 	module Session
 		# A simple hash table which fetches it's values only when required.
 		class LazyHash
+			# Base class for session mutation errors.
 			class MutationError < Session::Error
 			end
 
+			# Raised when mutating a session after it has been committed.
 			class AlreadyCommittedError < MutationError
 			end
 
+			# Raised when mutating a session from a non-owning fiber.
 			class WrongFiberError < MutationError
 			end
 
+			# Initialize a lazy hash with a block for loading values.
 			def initialize(&block)
 				@changed = false
 				@values = nil
@@ -25,13 +29,18 @@ def initialize(&block)
 				@loader = block
 			end
 
+			# The loaded session values, if already loaded.
 			attr :values
+			
+			# The fiber which owns session mutation.
 			attr :owner
 
+			# Fetch a session value.
 			def [] key
 				load![key]
 			end
 
+			# Assign a session value.
 			def []= key, value
 				check_mutable!
 
@@ -45,10 +54,12 @@ def []= key, value
 				return value
 			end
 
+			# Check whether the session includes the specified key.
 			def include?(key)
 				load!.include?(key)
 			end
 
+			# Delete a session value.
 			def delete(key)
 				check_mutable!
 				load!
@@ -58,27 +69,33 @@ def delete(key)
 				@values.delete(key)
 			end
 
+			# Whether the session has changed since it was loaded.
 			def changed?
 				@changed
 			end
 
+			# Whether the session has already been committed.
 			def committed?
 				@committed
 			end
 
+			# Mark the session as committed.
 			def commit!
 				check_owner!
 				@committed = true
 			end
 
+			# Load the session values if they have not been loaded yet.
 			def load!
 				@values ||= @loader.call
 			end
 
+			# Whether the session values have been loaded.
 			def loaded?
 				!@values.nil?
 			end
 
+			# Whether the session should be committed to the response.
 			def needs_update?(timeout = nil)
 				# If data has changed, we need update:
 				return true if @changed