protocol-http 0.26.5 → 0.26.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec1274383518ed67d583ca4bd675984a61c34b2bc4b19600a064fd80e595548a
-  data.tar.gz: cdf454fb4d8c1513dab3f9e1dd48a2b8bf466af01cbb97fcee256fd79d7ec91c
+  metadata.gz: 5821a26af6f718626313da18d47d4aba2e33f0f4ce3809551c91e1a57e10bfbd
+  data.tar.gz: a432928361e31ca78408e444dd05622dd6853e56f40b3581a19fe97d8dac8dcc
 SHA512:
-  metadata.gz: af8dc10e55a1079c3862fe05316d8e1716a0ff4af45e705927e310f707c49fb2c10a13954af9ddee21cca9814037faddeed035691bbc35136bbe058facf354ac
-  data.tar.gz: fdf5fcbb3d7a184aa77e55b3016820fcd34863b401301901232f188cc350c357e76590448ee67a74c032c931f064b9a833291c2b95c48a7da69f767e6887df69
+  metadata.gz: 025540a24e4e72ea76257cee2c3bd4039854d6bd5f0f446553ffb5843aa2a41f278860d3f047b3c0861d8b15b120cbd03e1f54c2714583aabe7556451e6df728
+  data.tar.gz: e5b69ddfe8c874b00f6e36d03f48b71bb985f2c529df5aed4b4417ba1f10c258c768456897fdad1b63a9f257f4271472a3e56f7649664935e56ebb4a1136faf1

data/lib/protocol/http/body/buffered.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2020, by Bryan Powell.
 
 require_relative 'readable'
@@ -12,7 +12,11 @@ module Protocol
 			# A body which buffers all it's contents.
 			class Buffered < Readable
 				# Wraps an array into a buffered body.
-				# @return [Readable, nil] the wrapped body or nil if nil was given.
+				#
+				# For compatibility, also accepts anything that behaves like an `Array(String)`.
+				#
+				# @parameter body [String | Array(String) | Readable | nil] the body to wrap.
+				# @returns [Readable | nil] the wrapped body or nil if nil was given.
 				def self.wrap(body)
 					if body.is_a?(Readable)
 						return body

data/lib/protocol/http/body/readable.rb

@@ -7,17 +7,11 @@
 module Protocol
 	module HTTP
 		module Body
-			# A generic base class for wrapping body instances. Typically you'd override `#read`.
-			# The implementation assumes a sequential unbuffered stream of data.
-			# 	def each -> yield(String | nil)
-			# 	def read -> String | nil
-			# 	def join -> String
-			
-			# 	def finish -> buffer the stream and close it.
-			# 	def close(error = nil) -> close the stream immediately.
-			# end
+			# An interface for reading data from a body.
+			#
+			# Typically, you'd override `#read` to return chunks of data.
 			class Readable
-				# The consumer can call stop to signal that the stream output has terminated.
+				# Close the stream immediately.
 				def close(error = nil)
 				end
 				
@@ -40,6 +34,7 @@ module Protocol
 				end
 				
 				# Read the next available chunk.
+				# @returns [String | Nil] The chunk of data, or `nil` if the stream has finished.
 				def read
 					nil
 				end
@@ -60,12 +55,16 @@ module Protocol
 				end
 				
 				# Read all remaining chunks into a buffered body and close the underlying input.
+				# @returns [Buffered] The buffered body.
 				def finish
 					# Internally, this invokes `self.each` which then invokes `self.close`.
 					Buffered.for(self)
 				end
 				
 				# Enumerate all chunks until finished, then invoke `#close`.
+				#
+				# @yields {|chunk| ...} The block to call with each chunk of data.
+				# 	@parameter chunk [String | Nil] The chunk of data, or `nil` if the stream has finished.
 				def each
 					return to_enum(:each) unless block_given?
 					
@@ -79,6 +78,8 @@ module Protocol
 				end
 				
 				# Read all remaining chunks into a single binary string using `#each`.
+				#
+				# @returns [String | Nil] The binary string containing all chunks of data, or `nil` if the stream has finished (or did not contain any data).
 				def join
 					buffer = String.new.force_encoding(Encoding::BINARY)
 					

data/lib/protocol/http/methods.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 
 module Protocol
 	module HTTP
@@ -65,12 +65,12 @@ module Protocol
 				return to_enum(:each) unless block_given?
 				
 				constants.each do |name|
-					yield name, const_get(name)
+					yield name.downcase, const_get(name)
 				end
 			end
 			
 			self.each do |name, value|
-				define_method(name.downcase) do |location, headers = nil, body = nil|
+				define_method(name) do |location, headers = nil, body = nil|
 					self.call(
 						Request[value, location.to_s, Headers[headers], body]
 					)

data/lib/protocol/http/request.rb

@@ -11,6 +11,17 @@ require_relative 'methods'
 
 module Protocol
 	module HTTP
+		# Represents an HTTP request which can be used both server and client-side.
+		#
+		# ~~~ ruby
+		# require 'protocol/http'
+		# 
+		# # Long form:
+		# Protocol::HTTP::Request.new("http", "example.com", "GET", "/index.html", "HTTP/1.1", Protocol::HTTP::Headers[["accept", "text/html"]])
+		# 
+		# # Short form:
+		# Protocol::HTTP::Request["GET", "/index.html", {"accept" => "text/html"}]
+		# ~~~
 		class Request
 			prepend Body::Reader
 			
@@ -25,28 +36,28 @@ module Protocol
 				@protocol = protocol
 			end
 			
-			# The request scheme, usually one of "http" or "https".
+			# @attribute [String] the request scheme, usually `"http"` or `"https"`.
 			attr_accessor :scheme
-
-			# The request authority, usually a hostname and port number.
+			
+			# @attribute [String] the request authority, usually a hostname and port number, e.g. `"example.com:80"`.
 			attr_accessor :authority
-
-			# The request method, usually one of "GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT" or "OPTIONS".
+			
+			# @attribute [String] the request method, usually one of `"GET"`, `"HEAD"`, `"POST"`, `"PUT"`, `"DELETE"`, `"CONNECT"` or `"OPTIONS"`, etc.
 			attr_accessor :method
-
-			# The request path, usually a path and query string.
+			
+			# @attribute [String] the request path, usually a path and query string, e.g. `"/index.html"`, `"/search?q=hello"`, however it can be any [valid request target](https://www.rfc-editor.org/rfc/rfc9110#target.resource).
 			attr_accessor :path
-
-			# The request version, usually "http/1.0", "http/1.1", "h2", or "h3".
+			
+			# @attribute [String] the request version, usually `"http/1.0"`, `"http/1.1"`, `"h2"`, or `"h3"`.
 			attr_accessor :version
-
-			# The request headers, contains metadata associated with the request such as the user agent, accept (content type), accept-language, etc.
+			
+			# @attribute [Headers] the request headers, usually containing metadata associated with the request such as the `"user-agent"`, `"accept"` (content type), `"accept-language"`, etc.
 			attr_accessor :headers
-
-			# The request body, an instance of Protocol::HTTP::Body::Readable or similar.
+			
+			# @attribute [Body::Readable] the request body. It should only be read once (it may not be idempotent).
 			attr_accessor :body
 
-			# The request protocol, usually empty, but occasionally "websocket" or "webtransport", can be either single value `String` or multi-value `Array` of `String` instances. In HTTP/1, it is used to request a connection upgrade, and in HTTP/2 it is used to indicate a specfic protocol for the stream.
+			# @attribute [String | Array(String) | Nil] the request protocol, usually empty, but occasionally `"websocket"` or `"webtransport"`. In HTTP/1, it is used to request a connection upgrade, and in HTTP/2 it is used to indicate a specfic protocol for the stream.
 			attr_accessor :protocol
 			
 			# Send the request to the given connection.
@@ -54,14 +65,22 @@ module Protocol
 				connection.call(self)
 			end
 			
+			# Whether this is a HEAD request: no body is expected in the response.
 			def head?
 				@method == Methods::HEAD
 			end
 			
+			# Whether this is a CONNECT request: typically used to establish a tunnel.
 			def connect?
 				@method == Methods::CONNECT
 			end
 			
+			# A short-cut method which exposes the main request variables that you'd typically care about.
+			#
+			# @parameter method [String] The HTTP method, e.g. `"GET"`, `"POST"`, etc.
+			# @parameter path [String] The path, e.g. `"/index.html"`, `"/search?q=hello"`, etc.
+			# @parameter headers [Hash] The headers, e.g. `{"accept" => "text/html"}`, etc.
+			# @parameter body [String | Array(String) | Body::Readable] The body, e.g. `"Hello, World!"`, etc. See {Body::Buffered.wrap} for more information about .
 			def self.[](method, path, headers = nil, body = nil)
 				body = Body::Buffered.wrap(body)
 				headers = ::Protocol::HTTP::Headers[headers]
@@ -69,6 +88,7 @@ module Protocol
 				self.new(nil, nil, method, path, nil, headers, body)
 			end
 			
+			# Whether the request can be replayed without side-effects.
 			def idempotent?
 				@method != Methods::POST && (@body.nil? || @body.empty?)
 			end

data/lib/protocol/http/response.rb

@@ -8,9 +8,27 @@ require_relative 'body/reader'
 
 module Protocol
 	module HTTP
+		# Represents an HTTP response which can be used both server and client-side.
+		#
+		# ~~~ ruby
+		# require 'protocol/http'
+		# 
+		# # Long form:
+		# Protocol::HTTP::Response.new("http/1.1", 200, Protocol::HTTP::Headers[["content-type", "text/html"]], Protocol::HTTP::Body::Buffered.wrap("Hello, World!"))
+		# 
+		# # Short form:
+		# Protocol::HTTP::Response[200, {"content-type" => "text/html"}, ["Hello, World!"]]
+		# ~~~
 		class Response
 			prepend Body::Reader
 			
+			# Create a new response.
+			#
+			# @parameter version [String | Nil] The HTTP version, e.g. `"HTTP/1.1"`. If `nil`, the version may be provided by the server sending the response.
+			# @parameter status [Integer] The HTTP status code, e.g. `200`, `404`, etc.
+			# @parameter headers [Hash] The headers, e.g. `{"content-type" => "text/html"}`, etc.
+			# @parameter body [Body::Readable] The body, e.g. `"Hello, World!"`, etc.
+			# @parameter protocol [String | Array(String)] The protocol, e.g. `"websocket"`, etc.
 			def initialize(version = nil, status = 200, headers = Headers.new, body = nil, protocol = nil)
 				@version = version
 				@status = status
@@ -19,12 +37,22 @@ module Protocol
 				@protocol = protocol
 			end
 			
+			# @attribute [String | Nil] The HTTP version, usually one of `"HTTP/1.1"`, `"HTTP/2"`, etc.
 			attr_accessor :version
+			
+			# @attribute [Integer] The HTTP status code, e.g. `200`, `404`, etc.
 			attr_accessor :status
+			
+			# @attribute [Hash] The headers, e.g. `{"content-type" => "text/html"}`, etc.
 			attr_accessor :headers
+			
+			# @attribute [Body::Readable] The body, e.g. `"Hello, World!"`, etc.
 			attr_accessor :body
+			
+			# @attribute [String | Array(String) | Nil] The protocol, e.g. `"websocket"`, etc.
 			attr_accessor :protocol
 			
+			# Whether the response is considered a hijack: the connection has been taken over by the application and the server should not send any more data.
 			def hijack?
 				false
 			end
@@ -93,6 +121,15 @@ module Protocol
 			# @deprecated Use {#internal_server_error?} instead.
 			alias server_failure? internal_server_error?
 			
+			# A short-cut method which exposes the main response variables that you'd typically care about. It follows the same order as the `Rack` response tuple, but also includes the protocol.
+			#
+			# ~~~ ruby
+			# 	Response[200, {"content-type" => "text/html"}, ["Hello, World!"]]
+			# ~~~
+			#
+			# @parameter status [Integer] The HTTP status code, e.g. `200`, `404`, etc.
+			# @parameter headers [Hash] The headers, e.g. `{"content-type" => "text/html"}`, etc.
+			# @parameter body [String | Array(String) | Body::Readable] The body, e.g. `"Hello, World!"`, etc. See {Body::Buffered.wrap} for more information about .
 			def self.[](status, headers = nil, body = nil, protocol = nil)
 				body = Body::Buffered.wrap(body)
 				headers = ::Protocol::HTTP::Headers[headers]
@@ -100,6 +137,9 @@ module Protocol
 				self.new(nil, status, headers, body, protocol)
 			end
 			
+			# Create a response for the given exception.
+			#
+			# @parameter exception [Exception] The exception to generate the response for.
 			def self.for_exception(exception)
 				Response[500, Headers['content-type' => 'text/plain'], ["#{exception.class}: #{exception.message}"]]
 			end

data/lib/protocol/http/url.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2023, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2022, by Herrick Fang.
 
 module Protocol
@@ -65,9 +65,13 @@ module Protocol
 			end
 			
 			def self.split(name)
-				name.scan(/([^\[]+)|(?:\[(.*?)\])/).flatten!.compact!
+				name.scan(/([^\[]+)|(?:\[(.*?)\])/)&.tap do |parts|
+					parts.flatten!
+					parts.compact!
+				end
 			end
 			
+			# Assign a value to a nested hash.
 			def self.assign(keys, value, parent)
 				top, *middle = keys
 				
@@ -95,6 +99,10 @@ module Protocol
 				self.scan(string) do |name, value|
 					keys = self.split(name)
 					
+					if keys.empty?
+						raise ArgumentError, "Invalid key path: #{name.inspect}!"
+					end
+					
 					if keys.size > maximum
 						raise ArgumentError, "Key length exceeded limit!"
 					end

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.26.5"
+		VERSION = "0.26.7"
 	end
 end

data/lib/protocol/http.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2023, by Samuel Williams.
+# Copyright, 2018-2024, by Samuel Williams.
 
 require_relative "http/version"
+
+require_relative 'http/headers'
+require_relative 'http/request'
+require_relative 'http/response'
+require_relative 'http/middleware'

data/readme.md

@@ -30,11 +30,11 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+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.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+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
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.26.5
+  version: 0.26.7
 platform: ruby
 authors:
 - Samuel Williams
@@ -47,7 +47,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-05-04 00:00:00.000000000 Z
+date: 2024-07-07 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -114,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Provides abstractions to handle HTTP protocols.