protocol-content 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0631b08562d204932666cba81cddae2505c9dbf9d9c53414493e156aee864c91
-  data.tar.gz: 7c7c22c2fb998b2b6839dcf11e8c20e52de69ef1c11eed26c12014bc27f03401
+  metadata.gz: f4a6369c7d76fff09f34f7fb56203e92dfe32ae5c2346c542124e7b9006fca84
+  data.tar.gz: '0686b2a1d3f10dcc779e4f32ef78d342f016779cdafd458ec13ecec60983c7ed'
 SHA512:
-  metadata.gz: a9d13f6dc00e82e2108083e9069577a4f6a910789bdbe1cc9ee7701a077359ed052a1ad06cd55f0112ff5f833bda4b3581d041934e594d94d5e56405d31a33ee
-  data.tar.gz: 01ac8df9eefddbdde84e412a77a7c8b7848dac3116b04225cc097ccf6903f7644daee17a962dd5e7be9d4000fb86b38083dd803453758c0612034bd0f3d764ca
+  metadata.gz: b06e51d78c61bbc4601bac53715404c8a603155cca03e32cb183026ebb114d9c94424c594f325bcec334cb73a8c2d588e6c11697c6547315219a74273932389c
+  data.tar.gz: 2f97656018bb2e0203593138ce0b0c92c00c3a26667bf16a4c14e782b640e485c2e2d95e21a3ac07f25016b599faaab099ab9304714eda2e6021a0e2d099ad55

data/lib/protocol/content/parameters/builder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/media/set"
+
+module Protocol
+	module Content
+		module Parameters
+			# Builds immutable parameter models using a field DSL.
+			class Builder
+				# Initialize a parameter model builder.
+				# @parameter parser [Parser] The content parser.
+				# @parameter types [Hash] The available type conversions.
+				# @parameter strict [Boolean] Whether unknown fields should produce validation errors.
+				def initialize(parser: Parser.default, types: TYPES, strict: true)
+					@parser = parser
+					@types = types
+					@strict = strict
+					@fields = {}
+				end
+				
+				# Evaluate fields and construct an immutable parameter model.
+				# @yields The parameter fields.
+				# @returns [Model] The frozen parameter model.
+				def build(&block)
+					instance_eval(&block)
+					return Model.new(@parser, @fields, strict: @strict).freeze
+				end
+				
+				# Declare a scalar field.
+				# @parameter name [String] The field name.
+				# @parameter type [Module | #call] The expected value type or converter.
+				# @parameter required [Boolean] Whether the field must be present.
+				# @parameter nullable [Boolean] Whether the field may be nil.
+				# @returns [Field] The field.
+				def field(name, type = Object, required: false, nullable: false)
+					return add(ValueField.new(name, resolve(type), required:, nullable:))
+				end
+				
+				# Declare a streaming file upload.
+				# @parameter name [String] The upload field name.
+				# @parameter required [Boolean] Whether at least one handled upload must be present.
+				# @parameter multiple [Boolean] Whether the field accepts multiple uploads using anonymous array notation.
+				# @parameter accept [Protocol::Media::Set | Array(String | Protocol::Media::Range) | Nil] The accepted media ranges.
+				# @parameter size_limit [Integer | Nil] The maximum accepted upload size.
+				# @returns [Field] The upload field.
+				def upload(name, required: false, multiple: false, accept: nil, size_limit: nil)
+					if size_limit && size_limit < 0
+						raise ArgumentError, "Upload size limit must be non-negative!"
+					end
+					
+					if accept
+						accept = Protocol::Media::Set.for(accept)
+					end
+					
+					return add(UploadField.new(name, required:, multiple:, accept:, size_limit:))
+				end
+				
+				# Construct an enumeration converter from accepted values or an input-to-output mapping.
+				# @parameter values [Array(Object)] The accepted values.
+				# @parameter options [Hash] Additional input-to-output mappings.
+				# @returns [Enumeration] The enumeration converter.
+				def enumeration(*values, **options)
+					return Enumeration.build(*values, **options)
+				end
+				
+				# Declare an array of scalar values or nested argument hierarchies.
+				# @parameter name [String] The array field name.
+				# @parameter type [Module | #call | Nil] The expected element type or converter.
+				# @parameter required [Boolean] Whether the array must be present.
+				# @parameter nullable [Boolean] Whether the array may be nil.
+				# @parameter strict [Boolean] Whether unknown nested fields should produce validation errors.
+				# @yields The nested parameter fields for each array element.
+				# @returns [Field] The array field.
+				def array(name, type = nil, required: false, nullable: false, strict: @strict, &block)
+					if block
+						# A block defines the element shape and cannot be combined with conversion:
+						if type
+							raise ArgumentError, "An array cannot declare both an element type and nested fields!"
+						end
+						
+						model = nested_model(strict:, &block)
+					elsif type
+						type = resolve(type)
+					end
+					
+					return add(ArrayField.new(name, type, model, required:, nullable:))
+				end
+				
+				# Declare a nested argument hierarchy. Without a block, all nested values are accepted.
+				# @parameter name [String] The nested field name.
+				# @parameter required [Boolean] Whether the field must be present.
+				# @parameter nullable [Boolean] Whether the field may be nil.
+				# @parameter strict [Boolean] Whether unknown nested fields should produce validation errors.
+				# @yields The nested parameter fields.
+				# @returns [Field] The nested field.
+				def nested(name, required: false, nullable: false, strict: @strict, &block)
+					if block
+						model = nested_model(strict:, &block)
+					end
+					
+					return add(NestedField.new(name, model, required:, nullable:))
+				end
+				
+				private
+				
+				def resolve(type)
+					# Preserve custom converters without wrapping them:
+					if type.respond_to?(:call)
+						return type
+					end
+					
+					if converter = @types[type]
+						return Type.new(type, &converter)
+					end
+					
+					return Type.new(type)
+				end
+				
+				def nested_model(strict:, &block)
+					return self.class.new(parser: @parser, types: @types, strict:).build(&block)
+				end
+				
+				def add(field)
+					# Reject ambiguous fields for the same input name:
+					if @fields.key?(field.name)
+						raise ArgumentError, "Parameter #{field.name.inspect} is already declared!"
+					end
+					
+					@fields[field.name] = field
+					return field
+				end
+			end
+		end
+	end
+end

data/lib/protocol/content/parameters/enumeration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Content
+		module Parameters
+			# Converts an exact set of input values to corresponding output values.
+			class Enumeration
+				# Construct an enumeration from accepted values or an input-to-output mapping.
+				# @parameter values [Array(Object)] The accepted values.
+				# @parameter options [Hash] Additional input-to-output mappings.
+				# @returns [Enumeration] The enumeration converter.
+				def self.build(*values, **options)
+					mapping = values.to_h{|value| [value, value]}
+					mapping.update(options)
+					return new(mapping)
+				end
+				
+				# Initialize an enumeration from an input-to-output mapping.
+				# @parameter mapping [Hash] The accepted inputs and corresponding outputs.
+				def initialize(mapping)
+					@mapping = mapping.freeze
+				end
+				
+				# The accepted input values and corresponding output values.
+				attr :mapping
+				
+				# Convert an accepted input value.
+				# @parameter value [Object] The input value.
+				# @returns [Object] The corresponding output value.
+				# @raises [ArgumentError] If the input value is not accepted.
+				def call(value)
+					if @mapping.key?(value)
+						return @mapping[value]
+					end
+					
+					raise ArgumentError, "Invalid enumeration value: #{value.inspect}!"
+				end
+			end
+		end
+	end
+end

data/lib/protocol/content/parameters/error.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../error"
+
+module Protocol
+	module Content
+		module Parameters
+			# A validation error associated with a specific argument path.
+			class Error
+				# Initialize the validation error.
+				# @parameter path [Array(String | Integer)] The path to the invalid argument.
+				# @parameter code [Symbol] The machine-readable error code.
+				# @parameter details [Hash] Additional error details.
+				def initialize(path, code, **details)
+					@path = path
+					@code = code
+					@details = details.freeze
+				end
+				
+				# The path to the invalid argument.
+				attr :path
+				
+				# The machine-readable error code.
+				attr :code
+				
+				# Additional error details.
+				attr :details
+			end
+			
+			# Raised when parsed parameters are invalid.
+			class ValidationError < Protocol::Content::Error
+				# Initialize the validation error.
+				# @parameter result [Result] The invalid parameters result.
+				def initialize(result)
+					@result = result
+					super("Content parameters are invalid!")
+				end
+				
+				# The invalid parameters result.
+				attr :result
+			end
+		end
+	end
+end

data/lib/protocol/content/parameters/field.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Content
+		module Parameters
+			# Common behavior for fields in a parameter model.
+			class Field
+				def initialize(name, required:)
+					@name = -name.to_s
+					@required = required
+				end
+				
+				attr :name
+				
+				def required?
+					return @required
+				end
+				
+				def upload_field(path)
+					return nil
+				end
+				
+			end
+			
+			class ValueField < Field
+				def initialize(name, type, required:, nullable:)
+					super(name, required:)
+					@type = type
+					@nullable = nullable
+				end
+				
+				def apply(value, output, errors, path)
+					value = Value.materialize(value)
+					
+					# Reject nil unless the field is explicitly nullable:
+					if value.nil?
+						if @nullable
+							output[@name] = nil
+						else
+							errors << Error.new(path, :invalid_type, expected: Type.expected(@type), value: value)
+						end
+						
+						return
+					end
+					
+					# Treat input conversion failures as validation errors:
+					output[@name] = @type.call(value)
+				rescue ArgumentError, TypeError
+					errors << Error.new(path, :invalid_type, expected: Type.expected(@type), value: value)
+				end
+				
+			end
+			
+			class UploadField < Field
+				def initialize(name, required:, multiple:, accept:, size_limit:)
+					super(name, required:)
+					@multiple = multiple
+					@accept = accept
+					@size_limit = size_limit
+				end
+				
+				# Process an upload while its multipart input is available.
+				#
+				# The upload handler must consume or store the streaming upload before parsing can continue. Its return value, or any validation failure, is preserved as an internal value for the later field validation phase.
+				def process(name, upload)
+					upload = Upload.new(upload, size_limit: @size_limit)
+					
+					if @accept
+						media_type = upload.media_type
+						
+						unless media_type
+							return Value::Invalid.new(:unsupported_media_type, media_type:, accepted: @accept)
+						end
+						
+						unless @accept.include?(media_type)
+							return Value::Invalid.new(:unsupported_media_type, media_type:, accepted: @accept)
+						end
+					end
+					
+					begin
+						stored = yield(name, upload)
+						upload.discard
+						return Value::Uploaded.new(stored)
+					rescue Upload::LimitError
+						return Value::Invalid.new(:too_large, limit: upload.size_limit, size: upload.size)
+					end
+				end
+				
+				def upload_field(path)
+					if @multiple
+						# Upload collections require anonymous array notation:
+						accepted = (path == [""])
+					else
+						accepted = path.empty?
+					end
+					
+					if accepted
+						return self
+					end
+					
+					return nil
+				end
+				
+				def apply(value, output, errors, path)
+					# Resolve the outcome produced while the upload was streamed:
+					if @multiple
+						return apply_multiple(value, output, errors, path)
+					end
+					
+					apply_upload(value, errors, path) do |stored|
+						output[@name] = stored
+					end
+				end
+				
+				private
+				
+				# Apply a streaming upload outcome, rejecting ordinary parameter values:
+				def apply_upload(value, errors, path, &block)
+					if value.respond_to?(:apply_upload)
+						return value.apply_upload(errors, path, &block)
+					end
+					
+					errors << Error.new(path, :invalid_type, expected: :upload, value: Value.materialize(value))
+					return false
+				end
+				
+				def apply_multiple(value, output, errors, path)
+					# Upload collections must be represented as arrays by the content parser:
+					unless value.is_a?(Array)
+						errors << Error.new(path, :invalid_type, expected: Array, value: Value.materialize(value))
+						return
+					end
+					
+					# Omit collections containing only uploads which were not handled:
+					if value.any? && value.all?{|item| item.equal?(Value::OMITTED)}
+						if @required
+							errors << Error.new(path, :required)
+						end
+						
+						return
+					end
+					
+					result = []
+					submitted = false
+					
+					value.each_with_index do |item, index|
+						if apply_upload(item, errors, path + [index]){|stored| result << stored}
+							submitted = true
+						end
+					end
+					
+					# Avoid reporting a required error when an upload was submitted but rejected:
+					if @required && result.empty? && !submitted
+						errors << Error.new(path, :required)
+					end
+					
+					output[@name] = result
+				end
+				
+			end
+			
+			class ArrayField < Field
+				def initialize(name, type, model, required:, nullable:)
+					super(name, required:)
+					@type = type
+					@model = model
+					@nullable = nullable
+				end
+				
+				def upload_field(path)
+					# Uploads in arrays must target a declared field on an anonymous element:
+					unless @model
+						return nil
+					end
+					
+					index, *remaining = path
+					
+					unless index&.empty?
+						return nil
+					end
+					
+					return @model.upload_field(remaining)
+				end
+				
+				def apply(value, output, errors, path)
+					# Validate the array itself before processing its elements:
+					if value.nil?
+						if @nullable
+							output[@name] = nil
+						else
+							errors << Error.new(path, :invalid_type, expected: Array, value: value)
+						end
+						
+						return
+					end
+					
+					unless value.is_a?(Array)
+						errors << Error.new(path, :invalid_type, expected: Array, value: value)
+						return
+					end
+					
+					result = []
+					
+					value.each_with_index do |item, index|
+						item_path = path + [index]
+						
+						# Ignore uploads which were not accepted by the field:
+						if item.equal?(Value::OMITTED)
+							next
+						end
+						
+						# Nested arrays validate each element as its own argument hierarchy:
+						if @model
+							result << @model.apply(item, errors, item_path)
+						elsif @type
+							# Typed arrays reject nil rather than passing it to coercion:
+							if item.nil?
+								errors << Error.new(item_path, :invalid_type, expected: Type.expected(@type), value: item)
+								next
+							end
+							
+							begin
+								item = Value.materialize(item)
+								item = @type.call(item)
+								result << item
+							rescue ArgumentError, TypeError
+								errors << Error.new(item_path, :invalid_type, expected: Type.expected(@type), value: item)
+							end
+						else
+							result << Value.materialize(item)
+						end
+					end
+					
+					output[@name] = result
+				end
+				
+				def freeze
+					return self if self.frozen?
+					
+					if @model
+						@model.freeze
+					end
+					
+					super
+				end
+				
+			end
+			
+			class NestedField < Field
+				def initialize(name, model, required:, nullable:)
+					super(name, required:)
+					@model = model
+					@nullable = nullable
+				end
+				
+				def upload_field(path)
+					unless @model
+						return nil
+					end
+					
+					return @model.upload_field(path)
+				end
+				
+				def apply(value, output, errors, path)
+					# Nested fields require a key/value hierarchy:
+					if value.nil?
+						if @nullable
+							output[@name] = nil
+						else
+							errors << Error.new(path, :invalid_type, expected: Hash, value: value)
+						end
+						
+						return
+					end
+					
+					unless value.is_a?(Hash)
+						errors << Error.new(path, :invalid_type, expected: Hash, value: value)
+						return
+					end
+					
+					if @model
+						output[@name] = @model.apply(value, errors, path)
+					else
+						output[@name] = Value.materialize(value)
+					end
+				end
+				
+				def freeze
+					return self if self.frozen?
+					
+					if @model
+						@model.freeze
+					end
+					
+					super
+				end
+			end
+			
+			private_constant :Field, :ValueField, :UploadField, :ArrayField, :NestedField
+		end
+	end
+end

data/lib/protocol/content/parameters/model.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/multipart/form_data"
+require "protocol/url/encoding"
+
+module Protocol
+	module Content
+		module Parameters
+			# An immutable model for parsing, filtering, and validating parameters.
+			class Model
+				# Initialize a parameter model.
+				# @parameter parser [Parser] The content parser.
+				# @parameter fields [Hash] The parameter fields.
+				# @parameter strict [Boolean] Whether unknown fields should produce validation errors.
+				def initialize(parser, fields, strict: true)
+					@parser = parser
+					@fields = fields
+					@strict = strict
+				end
+				
+				# The fields in this model, indexed by name.
+				attr :fields
+				
+				# Parse, filter, and validate content parameters.
+				# @parameter media_type [String | Protocol::Media::Type | Nil] The content media type.
+				# @parameter input [Object] The readable content input.
+				# @yields {|name, upload| ...} Each streaming upload. Its return value is inserted into the parsed value.
+				# @returns [Result] The parsed value and validation errors.
+				def parse(media_type, input, &upload_handler)
+					# Replace ephemeral multipart uploads with outcomes which can survive until validation:
+					value = @parser.parse(media_type, input) do |name, item|
+						if item.is_a?(Protocol::Multipart::FormData::Upload)
+							path = Protocol::URL::Encoding.split(name)
+							
+							# Only process uploads accepted by an explicit field:
+							if upload_handler && field = upload_field(path)
+								field.process(name, item, &upload_handler)
+							else
+								Value::OMITTED
+							end
+						else
+							item
+						end
+					end
+					
+					# Apply the model after parsing so ordinary values and upload outcomes follow the same hierarchy:
+					errors = []
+					value = apply(value, errors)
+					return Result.new(value, errors)
+				end
+				
+				# Parse content parameters, raising when validation fails.
+				# @parameter media_type [String | Protocol::Media::Type | Nil] The content media type.
+				# @parameter input [Object] The readable content input.
+				# @yields {|name, upload| ...} Each streaming upload. Its return value is inserted into the parsed value.
+				# @returns [Hash] The valid value.
+				# @raises [ValidationError] If validation fails.
+				def parse!(media_type, input, &block)
+					result = parse(media_type, input, &block)
+					
+					if result.valid?
+						return result.value
+					end
+					
+					raise ValidationError, result
+				end
+				
+				# Apply this model to an existing argument hierarchy.
+				# @parameter value [Object] The parameter hierarchy.
+				# @parameter errors [Array(Error)] The validation error destination.
+				# @parameter path [Array(String | Integer)] The current argument path.
+				# @returns [Hash] The filtered and converted value.
+				def apply(value, errors, path = [])
+					# Parameter models always apply to a key/value hierarchy:
+					unless value.is_a?(Hash)
+						errors << Error.new(path, :invalid_type, expected: Hash, value: value)
+						return {}
+					end
+					
+					# Copy the input so declared fields can be removed without modifying caller-owned data:
+					input = value.dup
+					output = {}
+					
+					# Apply declared values and collect missing required parameters:
+					@fields.each do |name, field|
+						item_path = path + [name]
+						
+						if input.key?(name)
+							item = input.delete(name)
+							
+							if item.equal?(Value::OMITTED)
+								if field.required?
+									errors << Error.new(item_path, :required)
+								end
+							else
+								field.apply(item, output, errors, item_path)
+							end
+						elsif field.required?
+							errors << Error.new(item_path, :required)
+						end
+					end
+					
+					# Reject remaining undeclared values when strict validation is enabled:
+					if @strict
+						input.each_key do |name|
+							errors << Error.new(path + [name], :unknown)
+						end
+					end
+					
+					return output
+				end
+				
+				# Whether an upload path is explicitly accepted by this model.
+				# @parameter path [Array(String)] The decoded upload path.
+				# @returns [Boolean] Whether the upload is accepted.
+				def accepts_upload?(path)
+					return !!upload_field(path)
+				end
+				
+				# Find the upload field which accepts the given decoded path.
+				# @parameter path [Array(String)] The decoded upload path.
+				# @returns [UploadField | Nil] The accepting upload field.
+				def upload_field(path)
+					# Walk fields using the decoded components of the form name:
+					name, *remaining = path
+					
+					unless field = @fields[name]
+						return nil
+					end
+					
+					return field.upload_field(remaining)
+				end
+				
+				# Freeze this model and its fields.
+				# @returns [self] The frozen model.
+				def freeze
+					return self if self.frozen?
+					
+					@parser.freeze
+					@fields.each_value(&:freeze)
+					@fields.freeze
+					super
+				end
+			end
+		end
+	end
+end

data/lib/protocol/content/parameters/result.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Content
+		module Parameters
+			# The result of parsing and validating content parameters.
+			class Result
+				# Initialize the result.
+				# @parameter value [Hash] The converted and filtered value.
+				# @parameter errors [Array(Error)] The validation errors.
+				def initialize(value, errors)
+					@value = value
+					@errors = errors.freeze
+				end
+				
+				# The converted and filtered value.
+				attr :value
+				
+				# The validation errors.
+				attr :errors
+				
+				# Fetch an entry from the result value.
+				# @parameter key [Object] The value key.
+				# @returns [Object | Nil] The corresponding value.
+				def [](key)
+					return @value[key]
+				end
+				
+				# Fetch an entry nested within the result value.
+				# @parameter path [Array(Object)] The nested value path.
+				# @returns [Object | Nil] The corresponding value.
+				def dig(*path)
+					return @value.dig(*path)
+				end
+				
+				# Whether the parameters are valid.
+				# @returns [Boolean] True when there are no validation errors.
+				def valid?
+					return @errors.empty?
+				end
+			end
+		end
+	end
+end

data/lib/protocol/content/parameters/type.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Content
+		module Parameters
+			# Converts input values to a specific application type.
+			class Type
+				# Resolve the expected output type of a converter.
+				def self.expected(type)
+					if type.respond_to?(:type)
+						return type.type
+					else
+						return type
+					end
+				end
+				
+				# Initialize a type converter.
+				# @parameter type [Object] The expected converted type.
+				# @yields {|value| ...} The conversion operation.
+				def initialize(type, &converter)
+					@type = type
+					@converter = converter
+				end
+				
+				# The expected converted type.
+				attr :type
+				
+				# Convert a value to the declared type.
+				# @parameter value [Object] The input value.
+				# @returns [Object] The converted value.
+				# @raises [TypeError] If the value cannot be converted.
+				def call(value)
+					# Preserve values which already have the expected type:
+					if @type === value
+						return value
+					end
+					
+					if @converter
+						value = @converter.call(value)
+						
+						# Ensure converters produce the type they declare:
+						if @type === value
+							return value
+						end
+					end
+					
+					raise TypeError, "Could not convert #{value.inspect} to #{@type}!"
+				end
+			end
+			
+			private_constant :Type
+		end
+	end
+end

data/lib/protocol/content/parameters/upload.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/media/type"
+require "protocol/media/registry"
+require "protocol/multipart/readable"
+
+module Protocol
+	module Content
+		module Parameters
+			# A field-constrained streaming upload.
+			class Upload
+				include Protocol::Multipart::Readable
+				
+				GENERIC_MEDIA_TYPE = "application/octet-stream"
+				private_constant :GENERIC_MEDIA_TYPE
+				
+				# Raised when a streaming upload exceeds its field size limit.
+				class LimitError < StandardError
+				end
+				
+				# Initialize a constrained upload.
+				# @parameter delegate [Object] The underlying streaming upload.
+				# @parameter size_limit [Integer | Nil] The maximum accepted size.
+				def initialize(delegate, size_limit: nil)
+					@delegate = delegate
+					@size_limit = size_limit
+					@size = 0
+					@declared_media_type = nil
+					
+					if header = delegate.headers["content-type"]
+						@declared_media_type = Protocol::Media::Type.parse(header.to_s)
+					end
+					
+					@media_type = @declared_media_type
+					
+					# Fall back to the submitted filename when the declared type carries no useful classification:
+					if !@media_type || @media_type.name == GENERIC_MEDIA_TYPE
+						if record = Protocol::Media::Registry.for_path(self.filename)
+							if record.type.name != GENERIC_MEDIA_TYPE
+								@media_type = record.type
+							end
+						end
+					end
+				end
+				
+				# The submitted filename.
+				def filename
+					return @delegate.filename
+				end
+				
+				# The multipart headers associated with this upload.
+				def headers
+					return @delegate.headers
+				end
+				
+				# The media type declared by the submitting client, if present.
+				attr :declared_media_type
+				
+				# The declared media type, or the type inferred from the filename when the declaration is absent or generic.
+				attr :media_type
+				
+				# The maximum accepted size, if configured.
+				attr :size_limit
+				
+				# The number of bytes consumed through this constrained upload.
+				attr :size
+				
+				# Whether the complete upload has been consumed.
+				def ended?
+					return @delegate.ended?
+				end
+				
+				# Iterate over the upload while enforcing its field size limit.
+				# @parameter chunk_size [Integer] The maximum chunk size.
+				# @yields {|chunk| ...} Each upload chunk.
+				# @returns [self] The upload.
+				# @raises [LimitError] If the upload exceeds its field size limit.
+				def each(chunk_size = 8192)
+					return to_enum(:each, chunk_size) unless block_given?
+					
+					@delegate.each(chunk_size) do |chunk|
+						@size += chunk.bytesize
+						
+						if @size_limit && @size > @size_limit
+							raise LimitError, "Upload size exceeded field limit of #{@size_limit}!"
+						end
+						
+						yield chunk
+					end
+					
+					return self
+				end
+				
+				# Consume any unread upload content while enforcing the field size limit.
+				# @returns [Nil] The upload content is discarded.
+				def discard
+					each {|_chunk|}
+					return nil
+				end
+			end
+		end
+	end
+end

data/lib/protocol/content/parameters/value.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Content
+		module Parameters
+			# Internal values carry upload outcomes from streaming parsing into field validation.
+			module Value
+				class Omitted
+					def apply_upload(errors, path)
+						return false
+					end
+				end
+				
+				OMITTED = Omitted.new.freeze
+				
+				class Invalid
+					def initialize(code, **details)
+						@code = code
+						@details = details
+					end
+					
+					attr :code
+					attr :details
+					
+					def apply_upload(errors, path)
+						errors << Error.new(path, @code, **@details)
+						return true
+					end
+				end
+				
+				class Uploaded
+					def initialize(value)
+						@value = value
+					end
+					
+					attr :value
+					
+					def apply_upload(errors, path)
+						yield(@value)
+						return true
+					end
+				end
+				
+				def self.materialize(value)
+					case value
+					when Hash
+						result = {}
+						value.each do |key, item|
+							# Remove omitted uploads while preserving the surrounding hierarchy:
+							unless item.equal?(OMITTED)
+								result[key.to_s] = materialize(item)
+							end
+						end
+						return result
+					when Array
+						# Remove omitted uploads while preserving accepted array values:
+						return value.filter_map do |item|
+							unless item.equal?(OMITTED)
+								materialize(item)
+							end
+						end
+					else
+						return value
+					end
+				end
+			end
+			
+			private_constant :Value
+		end
+	end
+end

data/lib/protocol/content/parameters.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "default"
+require_relative "parameters/type"
+require_relative "parameters/enumeration"
+require_relative "parameters/error"
+require_relative "parameters/result"
+require_relative "parameters/value"
+require_relative "parameters/upload"
+require_relative "parameters/field"
+require_relative "parameters/model"
+require_relative "parameters/builder"
+
+module Protocol
+	module Content
+		# Builds parameter models for filtering, conversion, and validation.
+		module Parameters
+			# The built-in parameter type conversions.
+			TYPES = {
+				Integer => ->(value) do
+					# Reject non-string values rather than relying on implicit numeric coercion:
+					unless value.is_a?(String)
+						raise TypeError
+					end
+					
+					Integer(value, 10)
+				end,
+				Float => ->(value){Float(value)},
+			}.freeze
+			
+			# Build an immutable parameter model.
+			# @parameter parser [Parser] The content parser.
+			# @parameter types [Hash] The available type conversions.
+			# @parameter strict [Boolean] Whether unknown fields should produce validation errors.
+			# @yields The parameter fields.
+			# @returns [Model] The frozen parameter model.
+			def self.build(parser: Parser.default, types: TYPES, strict: true, &block)
+				return Builder.new(parser:, types:, strict:).build(&block)
+			end
+		end
+	end
+end

data/lib/protocol/content/parser.rb

@@ -3,7 +3,6 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "protocol/media/map"
 require "protocol/media/type"
 
 require_relative "error"
@@ -24,17 +23,17 @@ module Protocol
 			
 			# Initialize an empty parser.
 			def initialize
-				@handlers = Protocol::Media::Map.new
+				@handlers = {}
 			end
 			
-			# Register a handler for a media type or range.
-			# @parameter media_range [String | Protocol::Media::Range] The accepted media type or range.
+			# Register a handler for a media type.
+			# @parameter media_type [String | Protocol::Media::Type] The accepted media type.
 			# @parameter handler [#call | Nil] The content handler.
 			# @yields {|input, media_type| ...} The content to parse.
 			# 	@parameter input [Object] The readable input.
 			# 	@parameter media_type [Protocol::Media::Type] The parsed media type.
 			# @returns [#call] The registered handler.
-			def register(media_range, handler = nil, &block)
+			def register(media_type, handler = nil, &block)
 				if handler && block
 					raise ArgumentError, "Provide either a handler or a block!"
 				end
@@ -45,7 +44,8 @@ module Protocol
 					raise ArgumentError, "A content handler must respond to #call!"
 				end
 				
-				@handlers[media_range] = handler
+				media_type = Protocol::Media::Type.for(media_type)
+				@handlers[media_type.name] = handler
 				return handler
 			end
 			
@@ -55,10 +55,12 @@ module Protocol
 			# @yields {...} An optional block forwarded to the selected content handler.
 			# @returns [Object] The parsed content value.
 			def parse(media_type, input, &block)
-				media_type = Protocol::Media::Type.for(media_type)
-				
-				if media_type && handler = @handlers[media_type]
-					return handler.call(input, media_type, &block)
+				if media_type
+					media_type = Protocol::Media::Type.for(media_type)
+					
+					if handler = @handlers[media_type.name]
+						return handler.call(input, media_type, &block)
+					end
 				end
 				
 				raise UnsupportedMediaTypeError, media_type
@@ -67,6 +69,8 @@ module Protocol
 			# Freeze the parser and its handler registry.
 			# @returns [self] The frozen parser.
 			def freeze
+				return self if self.frozen?
+				
 				@handlers.freeze
 				super
 			end

data/lib/protocol/content/version.rb

@@ -7,6 +7,6 @@
 module Protocol
 	# Models media-typed content carried by protocol messages.
 	module Content
-		VERSION = "0.1.0"
+		VERSION = "0.2.0"
 	end
 end

data/lib/protocol/content.rb

@@ -6,6 +6,7 @@
 require_relative "content/version"
 require_relative "content/error"
 require_relative "content/parser"
+require_relative "content/parameters"
 
 module Protocol
 	# @namespace

data/readme.md

@@ -10,10 +10,18 @@ Please see the [project documentation](https://socketry.github.io/protocol-conte
 
   - [Getting Started](https://socketry.github.io/protocol-content/guides/getting-started/index) - This guide explains how to parse media-typed content using built-in and custom parsers.
 
+  - [Content Parameters](https://socketry.github.io/protocol-content/guides/parameters/index) - This guide explains how to build a parameter model that interprets parsed content as operation-specific arguments using <code class="language-ruby">Protocol::Content::Parameters</code>.
+
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/protocol-content/releases/index) for all releases.
 
+### v0.2.0
+
+  - Add declarative content parameter filtering, conversion, validation, and upload handling.
+  - Add exact enumeration validation and input mapping for content parameters.
+  - Add field-specific upload media type and size constraints.
+
 ### v0.1.0
 
   - Add media-type parser dispatch for readable content.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.2.0
+
+  - Add declarative content parameter filtering, conversion, validation, and upload handling.
+  - Add exact enumeration validation and input mapping for content parameters.
+  - Add field-specific upload media type and size constraints.
+
 ## v0.1.0
 
   - Add media-type parser dispatch for readable content.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-content
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -54,6 +54,20 @@ dependencies:
         version: '2.0'
 - !ruby/object:Gem::Dependency
   name: protocol-media
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: protocol-media-registry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -72,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: protocol-url
   requirement: !ruby/object:Gem::Requirement
@@ -102,6 +116,16 @@ files:
 - lib/protocol/content/default.rb
 - lib/protocol/content/error.rb
 - lib/protocol/content/json_parser.rb
+- lib/protocol/content/parameters.rb
+- lib/protocol/content/parameters/builder.rb
+- lib/protocol/content/parameters/enumeration.rb
+- lib/protocol/content/parameters/error.rb
+- lib/protocol/content/parameters/field.rb
+- lib/protocol/content/parameters/model.rb
+- lib/protocol/content/parameters/result.rb
+- lib/protocol/content/parameters/type.rb
+- lib/protocol/content/parameters/upload.rb
+- lib/protocol/content/parameters/value.rb
 - lib/protocol/content/parser.rb
 - lib/protocol/content/version.rb
 - license.md