protocol-http 0.26.5 → 0.26.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec1274383518ed67d583ca4bd675984a61c34b2bc4b19600a064fd80e595548a
-  data.tar.gz: cdf454fb4d8c1513dab3f9e1dd48a2b8bf466af01cbb97fcee256fd79d7ec91c
+  metadata.gz: 54ef214891be3dd78e03f7c061f9b6e6f754efc9fc28445f5d8924d779c217bd
+  data.tar.gz: 6a637bcae7852f2acf31d9ff76a35781da93e6e33efb26131fe9ef0466c21cdc
 SHA512:
-  metadata.gz: af8dc10e55a1079c3862fe05316d8e1716a0ff4af45e705927e310f707c49fb2c10a13954af9ddee21cca9814037faddeed035691bbc35136bbe058facf354ac
-  data.tar.gz: fdf5fcbb3d7a184aa77e55b3016820fcd34863b401301901232f188cc350c357e76590448ee67a74c032c931f064b9a833291c2b95c48a7da69f767e6887df69
+  metadata.gz: 56f697b23039bebe8edbc71c2ddfbbc60c552de4d87403785004f7adbb76456a0c37005cd5b307f415cadba9ca1f91bfc0825a5924f0ede2c88e538f2c77cdcc
+  data.tar.gz: 733dd1c04f5bd2e900a563940a546d749084eacd5725707cfb2255c7a1259d858a4b598b3de840951751a1d2e286c60d13bed4d4fe1b8fbc934ec918d6f311c9

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

@@ -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/methods.rb

@@ -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/version.rb

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

data/lib/protocol/http.rb

@@ -4,3 +4,8 @@
 # Copyright, 2018-2023, by Samuel Williams.
 
 require_relative "http/version"
+
+require_relative 'http/headers'
+require_relative 'http/request'
+require_relative 'http/response'
+require_relative 'http/middleware'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.26.5
+  version: 0.26.6
 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-06-24 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.