protocol-content 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0631b08562d204932666cba81cddae2505c9dbf9d9c53414493e156aee864c91
+  data.tar.gz: 7c7c22c2fb998b2b6839dcf11e8c20e52de69ef1c11eed26c12014bc27f03401
+SHA512:
+  metadata.gz: a9d13f6dc00e82e2108083e9069577a4f6a910789bdbe1cc9ee7701a077359ed052a1ad06cd55f0112ff5f833bda4b3581d041934e594d94d5e56405d31a33ee
+  data.tar.gz: 01ac8df9eefddbdde84e412a77a7c8b7848dac3116b04225cc097ccf6903f7644daee17a962dd5e7be9d4000fb86b38083dd803453758c0612034bd0f3d764ca

checksums.yaml.gz.sig

@@ -0,0 +1,5 @@
+@.�ܛ���
:��LAuc�)ɡ.W�L*�$z�n.j��{�n
+B1UT�3߀��Ϭ*��H�Njm`�;�>��<c*F��dYF$}x��?#lX����2_v~�Z4>�&E�'�6l����N��
+�*�'��`s8��
(������?���Lҫ�Ϙ�3�+���� vr�f[�8Q/�	hڵc�#[!�R��d�K9Nu`�6+��l��L!,˾��Ҋ�b��R��fp�����m,Q�������
+G,��z�Cb�(�@�uiD��j�#Z*#
���h�ɵ`�Q"��m�
+�*��U�d�xn����0,����IՂ��.o߽oH��R/u�[i)F��{�y�9*

data/lib/protocol/content/default.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../content"
+require_relative "json_parser"
+
+require "protocol/url/form_data/parser"
+require "protocol/multipart/form_data/parser"
+
+module Protocol
+	module Content
+		class Parser
+			DEFAULT = build do |parser|
+				json_parser = JSONParser.new
+				parser.register(JSONParser::MEDIA_TYPE) do |input|
+					json_parser.parse(input)
+				end
+				
+				url_encoded_form_parser = Protocol::URL::FormData::Parser.new
+				parser.register(Protocol::URL::FormData::Parser::MEDIA_TYPE) do |input, _media_type, &block|
+					url_encoded_form_parser.parse(input, &block)
+				rescue Protocol::URL::LimitError
+					raise ContentTooLargeError
+				end
+				
+				multipart_form_parser = Protocol::Multipart::FormData::Parser.new
+				parser.register(Protocol::Multipart::FormData::Parser::MEDIA_TYPE) do |input, media_type, &block|
+					if boundary = media_type.parameters["boundary"]
+						multipart_form_parser.parse(input, boundary: boundary, &block)
+					else
+						raise ArgumentError, "Multipart media type is missing a boundary!"
+					end
+				rescue Protocol::Multipart::LimitError, Protocol::URL::LimitError
+					raise ContentTooLargeError
+				end
+			end
+			
+			# The default parser for common media types.
+			# @returns [Parser] The frozen default parser.
+			def self.default
+				return DEFAULT
+			end
+		end
+	end
+end

data/lib/protocol/content/error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Content
+		# A generic content error.
+		class Error < StandardError
+		end
+		
+		# Raised when content cannot be parsed.
+		class ParseError < Error
+		end
+		
+		# Raised when content exceeds a configured parser limit.
+		class ContentTooLargeError < ParseError
+		end
+		
+		# Raised when no parser accepts a media type.
+		class UnsupportedMediaTypeError < Error
+			# Initialize the error.
+			# @parameter media_type [Protocol::Media::Type | Nil] The unsupported media type.
+			def initialize(media_type)
+				if media_type
+					super("Unsupported media type: #{media_type}")
+				else
+					super("Missing media type!")
+				end
+				
+				@media_type = media_type
+			end
+			
+			# The unsupported media type, if one was provided.
+			attr :media_type
+		end
+	end
+end

data/lib/protocol/content/json_parser.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "json"
+
+require_relative "error"
+
+module Protocol
+	module Content
+		# Parses JSON content with bounded input size and nesting depth.
+		class JSONParser
+			MEDIA_TYPE = "application/json"
+			
+			# The encoded JSON document size limit.
+			SIZE_LIMIT = 2 * 1024 * 1024
+			
+			# The JSON document nesting depth limit.
+			DEPTH_LIMIT = 32
+			
+			# Initialize the JSON parser.
+			# @parameter size_limit [Integer | Nil] The encoded document size limit.
+			# @parameter depth_limit [Integer | Nil] The document nesting depth limit.
+			# @parameter options [Hash] Options passed to `JSON.parse`.
+			def initialize(size_limit: SIZE_LIMIT, depth_limit: DEPTH_LIMIT, **options)
+				@size_limit = size_limit
+				options[:max_nesting] = depth_limit || false
+				@options = options
+			end
+			
+			# Parse JSON content.
+			# @parameter input [Object] The readable input.
+			# @returns [Object] The decoded JSON value.
+			def parse(input)
+				if @size_limit
+					buffer = String.new.b
+					
+					# Read up to the size limit, allowing for partial reads:
+					while buffer.bytesize < @size_limit
+						chunk = input.read(@size_limit - buffer.bytesize)
+						break unless chunk
+						# An empty chunk cannot make progress, so stop reading:
+						break if chunk.empty?
+						
+						buffer << chunk
+					end
+					
+					if buffer.bytesize == @size_limit && input.read(1)
+						raise ContentTooLargeError, "JSON content size exceeded limit of #{@size_limit}!"
+					end
+				else
+					buffer = input.read
+				end
+				
+				return JSON.parse(buffer, **@options)
+			rescue JSON::NestingError
+				raise ContentTooLargeError
+			end
+		end
+	end
+end

data/lib/protocol/content/parser.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/media/map"
+require "protocol/media/type"
+
+require_relative "error"
+
+module Protocol
+	module Content
+		# Selects a content parser according to its media type.
+		class Parser
+			# Build and freeze a parser.
+			# @yields {|parser| ...} The mutable parser being configured.
+			# 	@parameter parser [Parser] The parser being configured.
+			# @returns [Parser] The configured parser.
+			def self.build
+				parser = self.new
+				yield parser
+				return parser.freeze
+			end
+			
+			# Initialize an empty parser.
+			def initialize
+				@handlers = Protocol::Media::Map.new
+			end
+			
+			# Register a handler for a media type or range.
+			# @parameter media_range [String | Protocol::Media::Range] The accepted media type or range.
+			# @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)
+				if handler && block
+					raise ArgumentError, "Provide either a handler or a block!"
+				end
+				
+				handler ||= block
+				
+				unless handler&.respond_to?(:call)
+					raise ArgumentError, "A content handler must respond to #call!"
+				end
+				
+				@handlers[media_range] = handler
+				return handler
+			end
+			
+			# Parse content using the handler matching its media type.
+			# @parameter media_type [String | Protocol::Media::Type | Nil] The media type.
+			# @parameter input [Object] The readable input.
+			# @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)
+				end
+				
+				raise UnsupportedMediaTypeError, media_type
+			end
+			
+			# Freeze the parser and its handler registry.
+			# @returns [self] The frozen parser.
+			def freeze
+				@handlers.freeze
+				super
+			end
+		end
+	end
+end

data/lib/protocol/content/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Protocol
+	# Models media-typed content carried by protocol messages.
+	module Content
+		VERSION = "0.1.0"
+	end
+end

data/lib/protocol/content.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "content/version"
+require_relative "content/error"
+require_relative "content/parser"
+
+module Protocol
+	# @namespace
+	module Content
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,63 @@
+# Protocol::Content
+
+Provides transport-independent parsing for media-typed content.
+
+[![Development Status](https://github.com/socketry/protocol-content/workflows/Test/badge.svg)](https://github.com/socketry/protocol-content/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/protocol-content/) for more details.
+
+  - [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.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-content/releases/index) for all releases.
+
+### v0.1.0
+
+  - Add media-type parser dispatch for readable content.
+  - Add JSON, URL-encoded form, and multipart form parsers with explicit convenient defaults.
+  - Bound JSON input size and nesting depth using consistently named limits.
+  - Add `ContentTooLargeError` for content parser limit violations.
+  - Forward blocks to content handlers for incremental and streaming parsing.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
+
+## See Also
+
+  - [protocol-http](https://github.com/socketry/protocol-http) provides HTTP message abstractions.
+  - [protocol-media](https://github.com/socketry/protocol-media) provides media type abstractions.
+  - [async-rest](https://github.com/socketry/async-rest) provides asynchronous REST client abstractions.

data/releases.md

@@ -0,0 +1,9 @@
+# Releases
+
+## v0.1.0
+
+  - Add media-type parser dispatch for readable content.
+  - Add JSON, URL-encoded form, and multipart form parsers with explicit convenient defaults.
+  - Bound JSON input size and nesting depth using consistently named limits.
+  - Add `ContentTooLargeError` for content parser limit violations.
+  - Forward blocks to content handlers for incremental and streaming parsing.

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: protocol-content
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: protocol-media
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: protocol-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: protocol-url
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/protocol/content.rb
+- lib/protocol/content/default.rb
+- lib/protocol/content/error.rb
+- lib/protocol/content/json_parser.rb
+- lib/protocol/content/parser.rb
+- lib/protocol/content/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/protocol-content
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/socketry/protocol-content/issues
+  changelog_uri: https://github.com/socketry/protocol-content/blob/main/releases.md
+  documentation_uri: https://socketry.github.io/protocol-content/
+  source_code_uri: https://github.com/socketry/protocol-content.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Provides parsing for media-typed content.
+test_files: []