linzer 0.7.9.beta2 → 0.7.9

data/lib/linzer/http.rb

@@ -78,6 +78,14 @@ module Linzer
     private
 
     # Executes a signed HTTP request.
+    #
+    # Validates inputs, builds and signs the request, then sends it.
+    #
+    # @param verb [Symbol] the HTTP method (e.g. +:get+, +:post+)
+    # @param uri [String] the request URI
+    # @param options [Hash] request options
+    # @return [Net::HTTPResponse] the response
+    # @raise [Linzer::Error] if the verb or key is invalid
     def request(verb, uri, options = {})
       validate_verb(verb)
 
@@ -100,10 +108,16 @@ module Linzer
       do_request(http, uri, verb, options[:data], signature, headers)
     end
 
+    # Returns the default covered components for signing.
+    # @return [Array<String>]
     def default_components
       Linzer::Options::DEFAULT[:covered_components]
     end
 
+    # Validates that the HTTP verb is recognized.
+    #
+    # @param verb [Symbol] the HTTP method
+    # @raise [Linzer::Error] if the verb is unknown
     def validate_verb(verb)
       method_name = verb.to_s.upcase
       if !known_http_methods.include?(method_name)
@@ -111,17 +125,32 @@ module Linzer
       end
     end
 
+    # Validates that the signing key is present and usable.
+    #
+    # @param key [Linzer::Key] the signing key
+    # @return [Linzer::Key] the validated key
+    # @raise [Linzer::Error] if the key is nil or does not respond to +#sign+
     def validate_key(key)
       raise Linzer::Error, "Key can not be nil!"    if !key
       raise Linzer::Error, "Key object is invalid!" if !key.respond_to?(:sign)
       key
     end
 
+    # Builds request headers, adding a default User-Agent if not present.
+    #
+    # @param headers [Hash] user-provided headers
+    # @return [Hash] headers with User-Agent ensured
     def build_headers(headers)
       return headers if headers.transform_keys(&:downcase).key?("user-agent")
       headers.merge({"user-agent" => "Linzer/#{Linzer::VERSION}"})
     end
 
+    # Builds a Net::HTTP request object for the given method and URI.
+    #
+    # @param method [Symbol] the HTTP method
+    # @param uri [String] the request URI
+    # @param headers [Hash] request headers to set
+    # @return [Net::HTTPRequest] the constructed request
     def build_request(method, uri, headers)
       request_class = Net::HTTP.const_get(method.to_s.capitalize)
       request = request_class.new(URI(uri))
@@ -129,7 +158,10 @@ module Linzer
       request
     end
 
-    # Determines if the HTTP method typically has a request body.
+    # Checks if the HTTP method typically carries a request body.
+    #
+    # @param verb [Symbol] the HTTP method
+    # @return [Boolean] +true+ for POST, PUT, PATCH, and WebDAV write methods
     def with_body?(verb)
       # common HTTP
       return false if %i[get head options trace delete].include?(verb)
@@ -142,6 +174,16 @@ module Linzer
       true
     end
 
+    # Sends the HTTP request with the signature headers attached.
+    #
+    # @param http [Net::HTTP] the HTTP connection
+    # @param uri [String] the request URI
+    # @param verb [Symbol] the HTTP method
+    # @param data [String, nil] the request body
+    # @param signature [Linzer::Signature] the generated signature
+    # @param headers [Hash] request headers
+    # @return [Net::HTTPResponse] the response
+    # @raise [Linzer::Error] if a body is required but not provided
     def do_request(http, uri, verb, data, signature, headers)
       if with_body?(verb)
         if !data

data/lib/linzer/message/adapter/abstract.rb

@@ -10,8 +10,8 @@ module Linzer
       # implements field retrieval, header access, and signature attachment
       # for a specific HTTP message type.
       #
-      # @abstract Subclass and implement {#header}, {#attach!}, {#derived},
-      #   and {#field} to create a new adapter.
+      # @abstract Subclass and implement {#header}, {#derived}, and {#field}
+      #   to create a new adapter.
       #
       # @see Rack::Request Rack request adapter
       # @see Rack::Response Rack response adapter
@@ -84,19 +84,48 @@ module Linzer
           raise Linzer::Error, "Sub-classes are required to implement this method!"
         end
 
+        # Checks whether the request contains HTTP Message Signature headers.
+        #
+        # Returns true if either the "signature-input" or "signature" header
+        # is present.
+        #
+        # @return [Boolean] true if the request includes HTTP Message Signature headers
+        def has_signature?
+          !!header("signature-input") || !!header("signature")
+        end
+
         # Attaches a signature to the underlying HTTP message.
         #
-        # @abstract Subclasses must implement this method.
         # @param signature [Signature] The signature to attach
         # @return [Object] The underlying HTTP message
         def attach!(signature)
-          raise Linzer::Error, "Sub-classes are required to implement this method!"
+          signature_headers = signature.to_h
+
+          unless has_signature?
+            signature_headers.each { |h, v| set_header!(h, v) }
+            return @operation
+          end
+
+          signature_headers.each do |hdr, value|
+            merged = Starry.parse_dictionary(String(header(hdr)))
+            merged.merge!(Starry.parse_dictionary(value))
+            set_header!(hdr, Starry.serialize_dictionary(merged))
+          end
+
+          @operation
+        rescue Starry::ParseError => e
+          raise Error,
+                "Cannot attach signature, invalid signature header(s)!",
+                cause: e
         end
 
         private
 
         # Parses a field name string into a FieldId.
-        # @return [FieldId, nil] The parsed identifier, or nil if invalid
+        #
+        # @param field_name [String] the component identifier string
+        # @return [FieldId, nil] the parsed identifier, or +nil+ if invalid
+        # @raise [Error] if +@status+ is used in a request message
         def parse_field_name(field_name)
           field_id  = FieldId.new(field_name: field_name)
           component = field_id.item
@@ -117,8 +146,12 @@ module Linzer
           raise Linzer::Error, msg unless message.request?
         end
 
-        # Validates component identifier parameters.
-        # @return [Object, nil] The validated name, or nil if invalid
+        # Validates component identifier parameters against RFC 9421 rules.
+        #
+        # @param name [Starry::Item] the parsed component identifier
+        # @param method [Symbol] +:derived+ or +:field+
+        # @return [Starry::Item, nil] the validated name, or +nil+ if
+        #   the parameter combination is invalid
         def validate_parameters(name, method)
           has_unknown = name.parameters.any? { |p, _| !KNOWN_PARAMETERS.include?(p) }
           return nil if has_unknown
@@ -149,6 +182,13 @@ module Linzer
         private_constant :KNOWN_PARAMETERS
 
         # Retrieves a component value with parameter processing.
+        #
+        # Handles +;req+, +;sf+, +;key+, and +;bs+ parameters by
+        # delegating to the corresponding helper methods.
+        #
+        # @param name [Starry::Item] the parsed component identifier
+        # @param method [Symbol] +:derived+ or +:field+
+        # @return [String, Integer, nil] the component value
         def retrieve(name, method)
           if !name.parameters.empty?
             valid_params = validate_parameters(name, method)
@@ -176,6 +216,10 @@ module Linzer
         end
 
         # Processes a structured field value with optional key extraction.
+        #
+        # @param value [String] the raw header value to parse as a dictionary
+        # @param key [String, nil] if present, extracts a single dictionary member
+        # @return [String] the serialized structured field value
         # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.1
         def sf(value, key = nil)
           dict = Starry.parse_dictionary(value)
@@ -188,19 +232,31 @@ module Linzer
           end
         end
 
-        # Binary-wraps a field value.
+        # Binary-wraps a field value as a byte sequence.
+        #
+        # @param value [String] the header value to wrap
+        # @return [String] the serialized byte sequence
         # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.3
         def bs(value)
           Starry.serialize(value.encode(Encoding::ASCII_8BIT))
         end
 
         # Retrieves a trailer field value.
+        #
         # @abstract Subclasses should implement if trailer support is needed.
+        # @param trailer [Object] the trailer field identifier
+        # @return [String, nil] the trailer value
+        # @raise [Error] always, since no built-in adapters support trailers
         def tr(trailer)
           raise Error, "Sub-classes are required to implement this method!"
         end
 
-        # Retrieves a field from the attached request.
+        # Retrieves a field from the attached request (for +;req+ parameter).
+        #
+        # @param field [Starry::Item] the component identifier
+        # @param method [Symbol] +:derived+ or +:field+
+        # @return [String, nil] the value from the attached request, or
+        #   +nil+ if no request is attached
         def req(field, method)
           attached_request? ? @attached_request[String(field)] : nil
         end

data/lib/linzer/message/adapter/faraday/request.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Faraday
+        # Adapter for {::Faraday::Request} objects from the faraday gem.
+        #
+        # Extends the generic request adapter with faraday-specific
+        # derived component retrieval, field lookup, and URI handling.
+        #
+        # @note Not loaded automatically to avoid making faraday a hard
+        #   dependency. Require +"linzer/faraday"+ to register this adapter.
+        #
+        # @see Generic::Request
+        # @see https://github.com/lostisland/faraday faraday gem
+        class Request < Generic::Request
+          private
+
+          # Resolves a derived component value from the request.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value, or +nil+ if unknown
+          def derived(name)
+            url = @operation.path
+            case name.value
+            when "@method"         then @operation.http_method.to_s.upcase
+            when "@target-uri"     then uri.to_s
+            when "@authority"      then url.authority.downcase
+            when "@scheme"         then url.scheme.downcase
+            when "@request-target" then uri.request_uri
+            when "@path"           then url.path
+            when "@query"          then "?%s" % String(uri_query)
+            when "@query-param"    then query_param(uri_query, name)
+            end
+          end
+
+          # Builds the full URI including query parameters.
+          #
+          # @return [URI] the complete request URI with encoded query string
+          def uri
+            uri = @operation.path.dup
+            uri.query = URI.encode_www_form(@operation.params)
+            uri
+          end
+
+          # Returns the raw query string from the request URI.
+          #
+          # Prefers the raw query string from the URI when available,
+          # as Faraday normalises percent-encoding when parsing params
+          # (e.g. +%2D+ becomes +-+), which would break signature
+          # verification.
+          #
+          # @return [String, nil] the raw query string
+          def uri_query
+            url = @operation.path
+            url.query || uri.query
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/faraday/response.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Faraday
+        # Adapter for {::Faraday::Response} objects from the faraday gem.
+        #
+        # Extends the generic response adapter with faraday-specific
+        # derived component retrieval (e.g. +@status+) and header
+        # attachment.
+        #
+        # @note Not loaded automatically to avoid making faraday a hard
+        #   dependency. Require +"linzer/faraday"+ to register this adapter.
+        #
+        # @see Generic::Response
+        # @see https://github.com/lostisland/faraday faraday gem
+        class Response < Generic::Response
+          private
+
+          # Resolves a derived component value from the response.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [Integer, nil] the HTTP status code for +@status+,
+          #   or +nil+ if the component is unknown
+          def derived(name)
+            case name.value
+            when "@status" then @operation.status.to_i
+            end
+          end
+
+          # Sets a header on the underlying HTTP message.
+          #
+          # If a header with the given name already exists, its value is overwritten.
+          #
+          # @param header [String] the header name
+          # @param value [String] the header value
+          # @return [String] the value assigned to the header
+          def set_header!(header, value)
+            @operation.headers[header] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/generic/request.rb

@@ -40,42 +40,49 @@ module Linzer
             @operation[name]
           end
 
-          # Attaches a signature to the request.
-          # @param signature [Signature] The signature to attach
-          # @return [Object] The underlying request object
-          def attach!(signature)
-            signature.to_h.each { |h, v| @operation[h] = v }
-            @operation
-          end
-
           private
 
           def derived(name)
-            unimplemented_method = 'Derived field "@method" lookup is not implemented!'
+            unimplemented_method = 'Derived field "%s" lookup is not implemented!'
+
+            uri = @operation.uri rescue nil
+            raise Error, unimplemented_method % name.value if uri.nil?
+
             case name.value
-            when "@method"         then raise Error, unimplemented_method
-            when "@target-uri"     then @operation.uri.to_s
-            when "@authority"      then @operation.uri.authority.downcase
-            when "@scheme"         then @operation.uri.scheme.downcase
-            when "@request-target" then @operation.uri.request_uri
-            when "@path"           then @operation.uri.path
-            when "@query"          then "?%s" % String(@operation.uri.query)
-            when "@query-param"    then query_param(name)
+            when "@method"         then raise Error, unimplemented_method % name.value
+            when "@target-uri"     then uri.to_s
+            when "@authority"      then uri.authority.downcase
+            when "@scheme"         then uri.scheme.downcase
+            when "@request-target" then uri.request_uri
+            when "@path"           then uri.path
+            when "@query"          then "?%s" % String(uri.query)
+            when "@query-param"    then query_param(uri.query, name)
             end
           end
 
-          def query_param(name)
+          # Sets a header on the underlying HTTP message.
+          #
+          # If a header with the given name already exists, its value is overwritten.
+          #
+          # @param header [String] the header name
+          # @param value [String] the header value
+          # @return [String] the value assigned to the header
+          def set_header!(header, value)
+            @operation[header] = value
+          end
+
+          def query_param(uri_query, name)
             param_name = name.parameters["name"]
             return nil if !param_name
             decoded_param_name = URI.decode_uri_component(param_name)
-            params = CGI.parse(@operation.uri.query)
+            params = CGI.parse(uri_query)
             URI.encode_uri_component(params[decoded_param_name]&.first)
           end
 
           def field(name)
             has_tr = name.parameters["tr"]
             return nil if has_tr # HTTP requests don't have trailer fields
-            value = @operation[name.value.to_s]
+            value = header(name.value.to_s)
             value.dup&.strip
           end
         end

data/lib/linzer/message/adapter/generic/response.rb

@@ -31,16 +31,19 @@ module Linzer
             @operation[name]
           end
 
-          # Attaches a signature to the response.
-          # @param signature [Signature] The signature to attach
-          # @return [Object] The underlying response object
-          def attach!(signature)
-            signature.to_h.each { |h, v| @operation[h] = v }
-            @operation
-          end
-
           private
 
+          # Sets a header on the underlying HTTP message.
+          #
+          # If a header with the given name already exists, its value is overwritten.
+          #
+          # @param header [String] the header name
+          # @param value [String] the header value
+          # @return [String] the value assigned to the header
+          def set_header!(header, value)
+            @operation[header] = value
+          end
+
           def derived(name)
             raise Linzer::Error, "Sub-classes are required to implement this method!"
           end

data/lib/linzer/message/adapter/http_gem/common.rb

@@ -20,22 +20,30 @@ module Linzer
             @operation.headers[name]
           end
 
-          # Attaches a signature to the response.
-          # @param signature [Signature] The signature to attach
-          # @return [Object] The underlying response object
-          def attach!(signature)
-            signature.to_h.each { |h, v| @operation.headers[h] = v }
-            @operation
-          end
-
           private
 
+          # Retrieves an HTTP field value from the request or response headers.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the stripped header value, or +nil+ if the
+          #   field has a +tr+ (trailer) parameter or is not present
           def field(name)
             has_tr = name.parameters["tr"]
             return nil if has_tr # XXX: is there a library actually supporting trailers?
             value = @operation.headers[name.value.to_s]
             value.dup&.strip
           end
+
+          # Sets a header on the underlying HTTP message.
+          #
+          # If a header with the given name already exists, its value is overwritten.
+          #
+          # @param header [String] the header name
+          # @param value [String] the header value
+          # @return [String] the value assigned to the header
+          def set_header!(header, value)
+            @operation.headers[header] = value
+          end
         end
       end
     end

data/lib/linzer/message/adapter/http_gem/request.rb

@@ -15,6 +15,14 @@ module Linzer
 
           private
 
+          # Resolves a derived component value from the request.
+          #
+          # Overrides the generic implementation for http.rb-specific
+          # accessor methods: +uri.host+ for +@authority+ and
+          # +verb+ for +@method+.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value
           def derived(name)
             return @operation.uri.host         if name.value == "@authority"
             return @operation.verb.to_s.upcase if name.value == "@method"

data/lib/linzer/message/adapter/http_gem/response.rb

@@ -19,6 +19,13 @@ module Linzer
 
           private
 
+          # Resolves a derived component value from the response.
+          #
+          # Uses +HTTP::Response#status+ converted to Integer for
+          # the +@status+ component.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [Integer, nil] the HTTP status code, or +nil+ if unknown
           def derived(name)
             case name.value
             when "@status" then @operation.status.to_i

data/lib/linzer/message/adapter/net_http/request.rb

@@ -14,6 +14,14 @@ module Linzer
         class Request < Generic::Request
           private
 
+          # Resolves a derived component value from the request.
+          #
+          # Overrides the generic implementation to use
+          # +Net::HTTPRequest#method+ for the +@method+ component,
+          # which returns the HTTP verb as an uppercase string.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value
           def derived(name)
             return @operation.method if name.value == "@method"
             super

data/lib/linzer/message/adapter/net_http/response.rb

@@ -11,6 +11,13 @@ module Linzer
         class Response < Generic::Response
           private
 
+          # Resolves a derived component value from the response.
+          #
+          # Uses +Net::HTTPResponse#code+ (a String) converted to Integer
+          # for the +@status+ component.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [Integer, nil] the HTTP status code, or +nil+ if unknown
           def derived(name)
             case name.value
             when "@status" then @operation.code.to_i

data/lib/linzer/message/adapter/rack/common.rb

@@ -24,11 +24,19 @@ module Linzer
 
           private
 
+          # Validates that the operation is exclusively a request or response.
+          # @raise [Error] if the operation is both or neither
           def validate
             msg = "Message instance must be an HTTP request or response"
             raise Error.new msg if response? == request?
           end
 
+          # Validates that a header name is non-empty.
+          #
+          # @param name [String] the header name
+          # @return [String] the validated header name
+          # @raise [ArgumentError] if the name is blank
+          # @raise [Linzer::Error] if the name is otherwise invalid
           def validate_header_name(name)
             raise ArgumentError.new, "Blank header name." if name.empty?
             name.to_str
@@ -40,6 +48,13 @@ module Linzer
             # :nocov:
           end
 
+          # Converts an HTTP header name to Rack's environment key format.
+          #
+          # Rack stores headers as uppercase with underscores and an +HTTP_+
+          # prefix, except for +Content-Type+ and +Content-Length+.
+          #
+          # @param field_name [String] the HTTP header name (e.g. +"content-type"+)
+          # @return [String] the Rack env key (e.g. +"CONTENT_TYPE"+ or +"HTTP_ACCEPT"+)
           def rack_header_name(field_name)
             validate_header_name field_name
 
@@ -52,6 +67,10 @@ module Linzer
             end
           end
 
+          # Resolves a derived component value from the Rack request/response.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value, or +nil+ if unknown
           def derived(name)
             method = DERIVED_COMPONENT[name.value]
 
@@ -64,6 +83,11 @@ module Linzer
             value || derive(@operation, method)
           end
 
+          # Retrieves an HTTP field value from the Rack request or response.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the stripped header value, or +nil+ if the
+          #   field has a +tr+ (trailer) parameter or is not present
           def field(name)
             has_tr = name.parameters["tr"]
             return nil if has_tr
@@ -79,6 +103,14 @@ module Linzer
             field_value.dup&.strip
           end
 
+          # Invokes a method on the Rack operation to extract a derived value.
+          #
+          # Applies post-processing for +@query+ (prepends +?+) and
+          # +@authority+/+@scheme+ (downcases).
+          #
+          # @param operation [Rack::Request, Rack::Response] the Rack object
+          # @param method [Symbol] the method to call
+          # @return [String, nil] the derived value
           def derive(operation, method)
             return nil unless operation.respond_to?(method)
             value = operation.public_send(method)
@@ -87,6 +119,11 @@ module Linzer
             value
           end
 
+          # Extracts a single query parameter value by name.
+          #
+          # @param name [Starry::Item] the component with a +name+ parameter
+          # @return [String, nil] the percent-encoded parameter value, or
+          #   +nil+ if the parameter is missing or not found
           def query_param(name)
             param_name = name.parameters["name"]
             return nil if !param_name

data/lib/linzer/message/adapter/rack/request.rb

@@ -27,14 +27,17 @@ module Linzer
             @operation.get_header(rack_header_name(name))
           end
 
-          # Attaches a signature to the request.
-          # @param signature [Signature] The signature to attach
-          # @return [::Rack::Request] The request with signature headers
-          def attach!(signature)
-            signature.to_h.each do |h, v|
-              @operation.set_header(rack_header_name(h), v)
-            end
-            @operation
+          private
+
+          # Sets a header on the underlying HTTP message.
+          #
+          # If a header with the given name already exists, its value is overwritten.
+          #
+          # @param header [String] the header name
+          # @param value [String] the header value
+          # @return [String] the value assigned to the header
+          def set_header!(header, value)
+            @operation.set_header(rack_header_name(header), value)
           end
         end
       end

data/lib/linzer/message/adapter/rack/response.rb

@@ -28,14 +28,17 @@ module Linzer
             @operation.get_header(name)
           end
 
-          # Attaches a signature to the response.
-          # @param signature [Signature] The signature to attach
-          # @return [::Rack::Response] The response with signature headers
-          def attach!(signature)
-            signature.to_h.each do |h, v|
-              @operation.set_header(h, v)
-            end
-            @operation
+          private
+
+          # Sets a header on the underlying HTTP message.
+          #
+          # If a header with the given name already exists, its value is overwritten.
+          #
+          # @param header [String] the header name
+          # @param value [String] the header value
+          # @return [String] the value assigned to the header
+          def set_header!(header, value)
+            @operation.set_header(header, value)
           end
         end
       end