Use protocol media for response negotiation.

Assisted-By: devx/b3414b50-d642-461b-95a8-8f773c4d087b

Author: samuel-williams-shopify

lib/utopia/controller/respond.rb

@@ -20,13 +20,24 @@ def self.prepended(base)
 
 			# Defines response handlers on controller classes.
 			module ClassMethods
-				# Return this controller's responder.
-				# @returns [Responder] The responder.
+				# Return this controller's responder builder.
+				# @returns [Responder::Builder] The responder builder.
 				def responds
-					@responder ||= Responder.new
+					@responder_builder ||= Responder::Builder.new
 				end
 
-				alias respond responds
+				# Compile the response declarations before freezing the controller class.
+				# @returns [self] This controller class.
+				def freeze
+					return self if frozen?
+					
+					if @responder_builder
+						@responder = @responder_builder.build
+						@responder_builder = nil
+					end
+					
+					return super
+				end
 
 				# Serialize a semantic value according to the request's accepted media types.
 				# @parameter context [Controller::Base] The controller context.

lib/utopia/controller/responder.rb

@@ -5,25 +5,23 @@
 
 require_relative "middleware"
 
+require "protocol/http/header/accept"
+require "protocol/media/map"
+require "protocol/media/type"
+require "protocol/media/range"
+
 module Utopia
 	module Controller
 		# @namespace
 		module Handlers
 			# Serializes controller values as JSON responses.
 			module JSON
-				APPLICATION_JSON = HTTP::Accept::ContentType.new("application", "json").freeze
-				
-				# Delegate content-type splitting to the JSON media type.
-				# @parameter arguments [Array] The arguments.
-				# @returns [Array] The resulting values.
-				def self.split(*arguments)
-					APPLICATION_JSON.split(*arguments)
-				end
+				APPLICATION_JSON = Protocol::Media::Type.new("application", "json").freeze
 
 				# Serialize an object as JSON.
 				# @parameter context [Object] The context.
 				# @parameter request [Utopia::Request] The request.
-				# @parameter media_range [HTTP::Accept::MediaTypes::MediaRange] The negotiated media range.
+				# @parameter media_range [Protocol::HTTP::Header::Accept::MediaRange] The negotiated media range.
 				# @parameter object [Object] The object.
 				# @parameter options [Hash] The options.
 				# @returns [String] The serialized JSON body.
@@ -36,27 +34,20 @@ def self.call(context, request, media_range, object, **options)
 				end
 
 				# The media type produced by this handler.
-				# @returns [HTTP::Accept::ContentType] The JSON media type.
+				# @returns [Protocol::Media::Type] The JSON media type.
 				def self.content_type
 					APPLICATION_JSON
 				end
 			end
 
 			# Passes response values through without transformation.
 			module Passthrough
-				WILDCARD = HTTP::Accept::MediaTypes::MediaRange.new("*", "*").freeze
-				
-				# Delegate content-type splitting to the wildcard media range.
-				# @parameter arguments [Array] The arguments.
-				# @returns [Array] The resulting values.
-				def self.split(*arguments)
-					WILDCARD.split(*arguments)
-				end
+				WILDCARD = Protocol::Media::Range.new("*", "*").freeze
 
 				# Pass an object through without transformation.
 				# @parameter context [Object] The context.
 				# @parameter request [Utopia::Request] The request.
-				# @parameter media_range [HTTP::Accept::MediaTypes::MediaRange] The negotiated media range.
+				# @parameter media_range [Protocol::HTTP::Header::Accept::MediaRange] The negotiated media range.
 				# @parameter object [Object] The object.
 				# @parameter options [Hash] The options.
 				# @returns [Object] The original body.
@@ -76,17 +67,10 @@ def self.content_type
 		class Responder
 			# A content-type handler and its response block.
 			Handler = Struct.new(:content_type, :block) do
-				# Delegate content-type splitting to this handler's content type.
-				# @parameter arguments [Array] The arguments.
-				# @returns [Array] The resulting values.
-				def split(*arguments)
-					self.content_type.split(*arguments)
-				end
-				
 				# Invoke this handler's block in the controller context.
 				# @parameter context [Object] The context.
 				# @parameter request [Utopia::Request] The request.
-				# @parameter media_range [HTTP::Accept::MediaTypes::MediaRange] The negotiated media range.
+				# @parameter media_range [Protocol::HTTP::Header::Accept::MediaRange] The negotiated media range.
 				# @parameter arguments [Array] The arguments.
 				# @parameter options [Hash] The options.
 				# @returns [Object] The handler block's result.
@@ -95,66 +79,97 @@ def call(context, request, media_range, *arguments, **options)
 				end
 			end
 
-			# Initialize an empty content-type handler map.
-			def initialize
-				@handlers = HTTP::Accept::MediaTypes::Map.new
+			# Incrementally constructs an immutable responder.
+			class Builder
+				# Initialize an empty responder builder.
+				def initialize
+					@handlers = Protocol::Media::Map::Builder.new
+					@passthrough = nil
+				end
+				
+				# Add a serializer for the specified content type.
+				# @parameter content_type [String | Protocol::Media::Type] The produced media type.
+				# @yields The response handler body.
+				# @returns [self] This builder.
+				def handle(content_type, &block)
+					@handlers[content_type] = Handler.new(content_type, block).freeze
+					return self
+				end
+				
+				# Register the default JSON handler.
+				# @returns [self] This builder.
+				def with_json
+					@handlers[Handlers::JSON::APPLICATION_JSON] = Handlers::JSON
+					return self
+				end
+				
+				# Register the wildcard passthrough handler.
+				# @returns [self] This builder.
+				def with_passthrough
+					@passthrough = Handlers::Passthrough
+					return self
+				end
+				
+				# Add a serializer for the specified content type.
+				# @parameter content_type [String | Protocol::Media::Type] The produced media type.
+				# @yields The response handler body.
+				# @returns [self] This builder.
+				def with(content_type, &block)
+					return handle(content_type, &block)
+				end
+				
+				# Compile the declarations into an immutable responder.
+				# @returns [Responder] The responder.
+				def build
+					return Responder.new(@handlers.build, @passthrough).freeze
+				end
 			end
 
-			attr :handlers
+			# Construct an immutable responder using a builder.
+			# @yields {|builder| ...} The mutable builder.
+			# @returns [Responder] The responder.
+			def self.build
+				builder = Builder.new
+				yield builder
+				return builder.build
+			end
 
-			# Freeze this object and its internal state.
-			# @returns [self] This object.
-			def freeze
-				@handlers.freeze
-				
-				super
+			# Initialize a responder with an immutable handler map.
+			# @parameter handlers [Protocol::Media::Map] The response handlers.
+			# @parameter passthrough [Object | Nil] The fallback response handler.
+			def initialize(handlers, passthrough = nil)
+				@handlers = handlers
+				@passthrough = passthrough
 			end
 
+			attr :handlers
+			
 			# Negotiate the request's accepted media types and invoke the best handler.
 			# @parameter context [Object] The controller context.
 			# @parameter request [Utopia::Request] The request.
 			# @parameter arguments [Array] The arguments.
 			# @parameter options [Hash] The options.
 			# @returns [Array(Object, Object) | Nil] The selected content type and body, or `nil` if none matches.
 			def call(context, request, *arguments, **options)
-				# Parse the list of browser preferred content types and return ordered by priority:
-				media_types = HTTP::Accept::MediaTypes.browser_preferred_media_types(
-					HTTP::Accept::MediaTypes::HTTP_ACCEPT => Array(request.headers["accept"]).join(",")
-				)
+				if accept = request.headers["accept"]
+					media_types = accept.media_ranges.sort
+				else
+					media_types = [Handlers::Passthrough::WILDCARD]
+				end
 
-				handler, media_range = @handlers.for(media_types)
+				if match = @handlers.for(media_types)
+					handler, media_range = match
+				elsif @passthrough
+					handler = @passthrough
+					media_range = media_types.first
+				end
 
 				if handler
 					return handler.content_type, handler.call(context, request, media_range, *arguments, **options)
 				end
 
 				return nil
 			end
-			
-			# Add a serializer for the specified content type.
-			def handle(content_type, &block)
-				@handlers << Handler.new(content_type, block)
-			end
-			
-			# Register the default JSON handler.
-			# @returns [HTTP::Accept::MediaTypes::Map] The updated handler map.
-			def with_json
-				@handlers << Handlers::JSON
-			end
-			
-			# Register the wildcard passthrough handler.
-			# @returns [HTTP::Accept::MediaTypes::Map] The updated handler map.
-			def with_passthrough
-				@handlers << Handlers::Passthrough
-			end
-			
-			# Invoke the responder with the given object.
-			# @parameter content_type [String] The content type.
-			# @yields The response handler body.
-			# @returns [HTTP::Accept::MediaTypes::Map] The updated handler map.
-			def with(content_type, &block)
-				handle(content_type, &block)
-			end
 		end
 	end
 end

test/utopia/.performance/pages/api/controller.rb

@@ -4,7 +4,7 @@
 # Copyright, 2016-2023, by Samuel Williams.
 
 prepend Respond, Actions
-respond.with_json
+responds.with_json
 
 on 'fetch' do
 	succeed! [1, 2, 3]

test/utopia/controller/.respond/api/controller.rb

@@ -4,7 +4,7 @@
 # Copyright, 2016-2023, by Samuel Williams.
 
 prepend Respond, Actions
-respond.with_json
+responds.with_json
 
 class VersionedResponse
 	def to_json(options = {})

test/utopia/controller/.respond/html/controller.rb

@@ -6,7 +6,7 @@
 prepend Respond, Actions
 
 # Respond with json:
-respond.with_json
+responds.with_json
 
 # This method should return HTML, even thought this controller responds with JSON.
 on 'hello-world' do

test/utopia/controller/.respond/rewrite/controller.rb

@@ -5,7 +5,7 @@
 
 prepend Respond, Rewrite, Actions
 
-respond.with_json
+responds.with_json
 
 rewrite.extract_prefix id: Integer do |request|
 	fail! :not_found, message: "Could not find record" if @id == 1

test/utopia/controller/.websocket/server/controller.rb

@@ -5,7 +5,7 @@
 
 prepend Respond, Actions
 
-respond.with_passthrough
+responds.with_passthrough
 
 on 'events' do |request|
 	upgrade = Async::WebSocket::Adapters::HTTP.open(request) do |connection|

test/utopia/controller/respond.rb

@@ -46,6 +46,8 @@ def self.uri_path
 		end
 	end
 
+	TestController.freeze
+	
 	let(:controller) {TestController.new}
 
 	def mock_request(path, headers = {})
@@ -117,6 +119,14 @@ def mock_request(path, headers = {})
 		expect(response.read).to be == "Explicit"
 	end
 
+	it "falls back to the passthrough handler" do
+		responder = Utopia::Controller::Responder.build do |builder|
+			builder.with_passthrough
+		end
+		request = Utopia::Request["GET", "/", {"accept" => "application/xml"}]
+		
+		expect(responder.call(controller, request, "Hello World")).to be == [nil, "Hello World"]
+	end
 end
 
 describe Utopia::Controller do

utopia.gemspec

@@ -36,6 +36,7 @@ Gem::Specification.new do |spec|
 	spec.add_dependency "net-smtp"
 	spec.add_dependency "protocol-content", "~> 0.1"
 	spec.add_dependency "protocol-http", "~> 0.68"
+	spec.add_dependency "protocol-media", "~> 0.2"
 	spec.add_dependency "protocol-url", "~> 0.10"
 	spec.add_dependency "samovar", "~> 2.1"
 	spec.add_dependency "traces", "~> 0.10"