protocol-http 0.54.0 → 0.56.0

data/lib/protocol/http/reference.rb

@@ -1,253 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
-
-require_relative "url"
-
-module Protocol
-	module HTTP
-		# A relative reference, excluding any authority. The path part of an HTTP request.
-		class Reference
-			include Comparable
-			
-			# Generate a reference from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
-			def self.parse(path = "/", parameters = nil)
-				base, fragment = path.split("#", 2)
-				path, query = base.split("?", 2)
-				
-				self.new(path, query, fragment, parameters)
-			end
-			
-			# Initialize the reference.
-			#
-			# @parameter path [String] The path component, e.g. `/foo/bar/index.html`.
-			# @parameter query [String | Nil] The un-parsed query string, e.g. 'x=10&y=20'.
-			# @parameter fragment [String | Nil] The fragment, the part after the '#'.
-			# @parameter parameters [Hash | Nil] User supplied parameters that will be appended to the query part.
-			def initialize(path = "/", query = nil, fragment = nil, parameters = nil)
-				@path = path
-				@query = query
-				@fragment = fragment
-				@parameters = parameters
-			end
-			
-			# @attribute [String] The path component, e.g. `/foo/bar/index.html`.
-			attr_accessor :path
-			
-			# @attribute [String] The un-parsed query string, e.g. 'x=10&y=20'.
-			attr_accessor :query
-			
-			# @attribute [String] The fragment, the part after the '#'.
-			attr_accessor :fragment
-			
-			# @attribute [Hash] User supplied parameters that will be appended to the query part.
-			attr_accessor :parameters
-			
-			# Freeze the reference.
-			#
-			#	@returns [Reference] The frozen reference.
-			def freeze
-				return self if frozen?
-				
-				@path.freeze
-				@query.freeze
-				@fragment.freeze
-				@parameters.freeze
-				
-				super
-			end
-			
-			# Implicit conversion to an array.
-			#
-			# @returns [Array] The reference as an array, `[path, query, fragment, parameters]`.
-			def to_ary
-				[@path, @query, @fragment, @parameters]
-			end
-			
-			# Compare two references.
-			#
-			# @parameter other [Reference] The other reference to compare.
-			# @returns [Integer] -1, 0, 1 if the reference is less than, equal to, or greater than the other reference.
-			def <=> other
-				to_ary <=> other.to_ary
-			end
-			
-			# Type-cast a reference.
-			#
-			# @parameter reference [Reference | String] The reference to type-cast.
-			# @returns [Reference] The type-casted reference.
-			def self.[] reference
-				if reference.is_a? self
-					return reference
-				else
-					return self.parse(reference)
-				end
-			end
-			
-			# @returns [Boolean] Whether the reference has parameters.
-			def parameters?
-				@parameters and !@parameters.empty?
-			end
-			
-			# @returns [Boolean] Whether the reference has a query string.
-			def query?
-				@query and !@query.empty?
-			end
-			
-			# @returns [Boolean] Whether the reference has a fragment.
-			def fragment?
-				@fragment and !@fragment.empty?
-			end
-			
-			# Append the reference to the given buffer.
-			def append(buffer = String.new)
-				if query?
-					buffer << URL.escape_path(@path) << "?" << @query
-					buffer << "&" << URL.encode(@parameters) if parameters?
-				else
-					buffer << URL.escape_path(@path)
-					buffer << "?" << URL.encode(@parameters) if parameters?
-				end
-				
-				if fragment?
-					buffer << "#" << URL.escape(@fragment)
-				end
-				
-				return buffer
-			end
-			
-			# Convert the reference to a string, e.g. `/foo/bar/index.html?x=10&y=20#section`
-			#
-			# @returns [String] The reference as a string.
-			def to_s
-				append
-			end
-			
-			# Merges two references as specified by RFC2396, similar to `URI.join`.
-			def + other
-				other = self.class[other]
-				
-				self.class.new(
-					expand_path(self.path, other.path, true),
-					other.query,
-					other.fragment,
-					other.parameters,
-				)
-			end
-			
-			# Just the base path, without any query string, parameters or fragment.
-			def base
-				self.class.new(@path, nil, nil, nil)
-			end
-			
-			# Update the reference with the given path, parameters and fragment.
-			#
-			# @parameter path [String] Append the string to this reference similar to `File.join`.
-			# @parameter parameters [Hash] Append the parameters to this reference.
-			# @parameter fragment [String] Set the fragment to this value.
-			# @parameter pop [Boolean] If the path contains a trailing filename, pop the last component of the path before appending the new path.
-			# @parameter merge [Boolean] If the parameters are specified, merge them with the existing parameters, otherwise replace them (including query string).
-			def with(path: nil, parameters: false, fragment: @fragment, pop: false, merge: true)
-				if merge
-					# Merge mode: combine new parameters with existing, keep query:
-					# parameters = (@parameters || {}).merge(parameters || {})
-					if @parameters
-						if parameters
-							parameters = @parameters.merge(parameters)
-						else
-							parameters = @parameters
-						end
-					elsif !parameters
-						parameters = @parameters
-					end
-					
-					query = @query
-				else
-					# Replace mode: use new parameters if provided, clear query when replacing:
-					if parameters == false
-						# No new parameters provided, keep existing:
-						parameters = @parameters
-						query = @query
-					else
-						# New parameters provided, replace and clear query:
-						# parameters = parameters
-						query = nil
-					end
-				end
-				
-				if path
-					path = expand_path(@path, path, pop)
-				else
-					path = @path
-				end
-				
-				self.class.new(path, query, fragment, parameters)
-			end
-			
-			private
-			
-			def split(path)
-				if path.empty?
-					[path]
-				else
-					path.split("/", -1)
-				end
-			end
-			
-			def expand_absolute_path(path, parts)
-				parts.each do |part|
-					if part == ".."
-						path.pop
-					elsif part == "."
-						# Do nothing.
-					else
-						path << part
-					end
-				end
-				
-				if path.first != ""
-					path.unshift("")
-				end
-			end
-			
-			def expand_relative_path(path, parts)
-				parts.each do |part|
-					if part == ".." and path.any?
-						path.pop
-					elsif part == "."
-						# Do nothing.
-					else
-						path << part
-					end
-				end
-			end
-			
-			# @param pop [Boolean] whether to remove the last path component of the base path, to conform to URI merging behaviour, as defined by RFC2396.
-			def expand_path(base, relative, pop = true)
-				if relative.start_with? "/"
-					return relative
-				end
-				
-				path = split(base)
-				
-				# RFC2396 Section 5.2:
-				# 6) a) All but the last segment of the base URI's path component is
-				# copied to the buffer.  In other words, any characters after the
-				# last (right-most) slash character, if any, are excluded.
-				path.pop if pop or path.last == ""
-				
-				parts = split(relative)
-				
-				# Absolute path:
-				if path.first == ""
-					expand_absolute_path(path, parts)
-				else
-					expand_relative_path(path, parts)
-				end	
-				
-				return path.join("/")
-			end
-		end
-	end
-end

data/lib/protocol/http/url.rb

@@ -1,149 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
-# Copyright, 2022, by Herrick Fang.
-
-module Protocol
-	module HTTP
-		# Helpers for working with URLs.
-		module URL
-			# Escapes a string using percent encoding, e.g. `a b` -> `a%20b`.
-			#
-			# @parameter string [String] The string to escape.
-			# @returns [String] The escaped string.
-			def self.escape(string, encoding = string.encoding)
-				string.b.gsub(/([^a-zA-Z0-9_.\-]+)/) do |m|
-					"%" + m.unpack("H2" * m.bytesize).join("%").upcase
-				end.force_encoding(encoding)
-			end
-			
-			# Unescapes a percent encoded string, e.g. `a%20b` -> `a b`.
-			#
-			# @parameter string [String] The string to unescape.
-			# @returns [String] The unescaped string.
-			def self.unescape(string, encoding = string.encoding)
-				string.b.gsub(/%(\h\h)/) do |hex|
-					Integer($1, 16).chr
-				end.force_encoding(encoding)
-			end
-			
-			# Matches characters that are not allowed in a URI path segment. According to RFC 3986 Section 3.3 (https://tools.ietf.org/html/rfc3986#section-3.3), a valid path segment consists of "pchar" characters. This pattern identifies characters that must be percent-encoded when included in a URI path segment.
-			NON_PATH_CHARACTER_PATTERN = /([^a-zA-Z0-9_\-\.~!$&'()*+,;=:@\/]+)/.freeze
-			
-			# Escapes non-path characters using percent encoding. In other words, this method escapes characters that are not allowed in a URI path segment. According to RFC 3986 Section 3.3 (https://tools.ietf.org/html/rfc3986#section-3.3), a valid path segment consists of "pchar" characters. This method percent-encodes characters that are not "pchar" characters.
-			#
-			# @parameter path [String] The path to escape.
-			# @returns [String] The escaped path.
-			def self.escape_path(path)
-				encoding = path.encoding
-				path.b.gsub(NON_PATH_CHARACTER_PATTERN) do |m|
-					"%" + m.unpack("H2" * m.bytesize).join("%").upcase
-				end.force_encoding(encoding)
-			end
-			
-			# Encodes a hash or array into a query string. This method is used to encode query parameters in a URL. For example, `{"a" => 1, "b" => 2}` is encoded as `a=1&b=2`.
-			#
-			# @parameter value [Hash | Array | Nil] The value to encode.
-			# @parameter prefix [String] The prefix to use for keys.
-			def self.encode(value, prefix = nil)
-				case value
-				when Array
-					return value.map {|v|
-						self.encode(v, "#{prefix}[]")
-					}.join("&")
-				when Hash
-					return value.map {|k, v|
-						self.encode(v, prefix ? "#{prefix}[#{escape(k.to_s)}]" : escape(k.to_s))
-					}.reject(&:empty?).join("&")
-				when nil
-					return prefix
-				else
-					raise ArgumentError, "value must be a Hash" if prefix.nil?
-					
-					return "#{prefix}=#{escape(value.to_s)}"
-				end
-			end
-			
-			# Scan a string for URL-encoded key/value pairs.
-			# @yields {|key, value| ...}
-			# 	@parameter key [String] The unescaped key.
-			# 	@parameter value [String] The unescaped key.
-			def self.scan(string)
-				string.split("&") do |assignment|
-					next if assignment.empty?
-					
-					key, value = assignment.split("=", 2)
-					
-					yield unescape(key), value.nil? ? value : unescape(value)
-				end
-			end
-			
-			# Split a key into parts, e.g. `a[b][c]` -> `["a", "b", "c"]`.
-			#
-			# @parameter name [String] The key to split.
-			# @returns [Array(String)] The parts of the key.
-			def self.split(name)
-				name.scan(/([^\[]+)|(?:\[(.*?)\])/)&.tap do |parts|
-					parts.flatten!
-					parts.compact!
-				end
-			end
-			
-			# Assign a value to a nested hash.
-			#
-			# @parameter keys [Array(String)] The parts of the key.
-			# @parameter value [Object] The value to assign.
-			# @parameter parent [Hash] The parent hash.
-			def self.assign(keys, value, parent)
-				top, *middle = keys
-				
-				middle.each_with_index do |key, index|
-					if key.nil? or key.empty?
-						parent = (parent[top] ||= Array.new)
-						top = parent.size
-						
-						if nested = middle[index+1] and last = parent.last
-							top -= 1 unless last.include?(nested)
-						end
-					else
-						parent = (parent[top] ||= Hash.new)
-						top = key
-					end
-				end
-				
-				parent[top] = value
-			end
-			
-			# Decode a URL-encoded query string into a hash.
-			#
-			# @parameter string [String] The query string to decode.
-			# @parameter maximum [Integer] The maximum number of keys in a path.
-			# @parameter symbolize_keys [Boolean] Whether to symbolize keys.
-			# @returns [Hash] The decoded query string.
-			def self.decode(string, maximum = 8, symbolize_keys: false)
-				parameters = {}
-				
-				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
-					
-					if symbolize_keys
-						keys.collect!{|key| key.empty? ? nil : key.to_sym}
-					end
-					
-					self.assign(keys, value, parameters)
-				end
-				
-				return parameters
-			end
-		end
-	end
-end