htty 1.0.0

data/app/htty/cli/http_method_command.rb

@@ -0,0 +1,75 @@
+# Defines HTTY::CLI::HTTPMethodCommand.
+
+require File.expand_path("#{File.dirname __FILE__}/../request")
+require File.expand_path("#{File.dirname __FILE__}/display")
+require File.expand_path("#{File.dirname __FILE__}/commands/cookies_use")
+# This 'require' statement leads to an unresolvable circular dependency.
+# require File.expand_path("#{File.dirname __FILE__}/commands/follow")
+
+module HTTY; end
+
+class HTTY::CLI; end
+
+# Encapsulates behavior common to all HTTP-method-oriented HTTY::CLI::Command
+# subclasses.
+module HTTY::CLI::HTTPMethodCommand
+
+  include HTTY::CLI::Display
+
+  # Returns the name of a category under which help for the _http-get_ command
+  # should appear.
+  def self.category
+    'Issuing Requests'
+  end
+
+  # Performs the command.
+  def perform
+    add_request_if_has_response do |request|
+      request = request.send("#{method}!", *arguments)
+      unless body? || request.body.to_s.empty?
+        puts notice("The body of your #{method.upcase} request is not being " +
+                    'sent')
+      end
+      notify_if_cookies
+      notify_if_follow
+      request
+    end
+    show_response session.last_response
+    self
+  end
+
+private
+
+  # Returns true if the command sends the request body.
+  def body?
+    HTTY::Request::METHODS_SENDING_BODY.include? method
+  end
+
+  def method
+    self.class.name.split('::').last.gsub(/^http/i, '').downcase.to_sym
+  end
+
+  def notify_if_cookies
+    request  = session.requests.last
+    response = session.last_response
+    unless response.cookies.empty? || (request.cookies == response.cookies)
+      puts notice('Type ' +
+                  "#{strong HTTY::CLI::Commands::CookiesUse.command_line} to " +
+                  'use cookies offered in the response')
+    end
+    self
+  end
+
+  def notify_if_follow
+    location_header = session.last_response.headers.detect do |header|
+      header.first == 'Location'
+    end
+    if location_header
+      puts notice('Type ' +
+                  "#{strong HTTY::CLI::Commands::Follow.command_line} to " +
+                  "follow the 'Location' header received in the response")
+    end
+    self
+  end
+
+end

data/app/htty/cli/url_escaping.rb

@@ -0,0 +1,27 @@
+# Defines HTTY::CLI::UrlEscaping.
+
+require 'uri'
+require File.expand_path("#{File.dirname __FILE__}/display")
+
+module HTTY; end
+
+class HTTY::CLI; end
+
+# Encapsulates the URL escaping logic of _htty_'s command-line interface.
+module HTTY::CLI::UrlEscaping
+
+  include HTTY::CLI::Display
+
+  def escape_or_warn_of_escape_sequences(arguments)
+    arguments.collect do |a|
+      if a =~ /%[0-9a-f]{2}/i
+        say "Argument '#{a}' was not URL-escaped because it contains escape " +
+            'sequences'
+        a
+      else
+        URI.escape a
+      end
+    end
+  end
+
+end

data/app/htty/cookies_util.rb

@@ -0,0 +1,36 @@
+# Defines HTTY::CookiesUtil.
+
+module HTTY; end
+
+# Provides support for marshaling HTTP cookies to and from strings.
+module HTTY::CookiesUtil
+
+  # Returns the specified _cookies_string_ HTTP header value deserialized to an
+  # array of cookies.
+  def self.cookies_from_string(cookies_string)
+    return [] unless cookies_string
+    cookies_string.split(COOKIES_DELIMITER).collect do |name_value_string|
+      name_and_value = name_value_string.split(COOKIE_NAME_VALUE_DELIMITER, 2)
+      name_and_value << nil if (name_and_value.length < 2)
+      name_and_value
+    end
+  end
+
+  # Returns the specified array of _cookies_ serialized to an HTTP header value.
+  # Returns +nil+ if _cookies_ is +nil+ or empty or if it contains only +nil+
+  # cookie values.
+  def self.cookies_to_string(cookies)
+    cookies = Array(cookies)
+    return nil if cookies.empty?
+
+    cookies.collect do |name, value|
+      [name, value].compact.join COOKIE_NAME_VALUE_DELIMITER
+    end.join COOKIES_DELIMITER
+  end
+
+protected
+
+  COOKIE_NAME_VALUE_DELIMITER = '='
+  COOKIES_DELIMITER           = '; '
+
+end

data/app/htty/no_location_header_error.rb

@@ -0,0 +1,12 @@
+# Defines HTTY::NoLocationHeaderError.
+
+module HTTY; end
+
+# Indicates that the _Location_ header was missing from HTTY::Request#response.
+class HTTY::NoLocationHeaderError < StandardError
+
+  def initialize
+    super "response does not have a 'Location' header"
+  end
+
+end

data/app/htty/no_response_error.rb

@@ -0,0 +1,12 @@
+# Defines HTTY::NoResponseError.
+
+module HTTY; end
+
+# Indicates that HTTY::Request#response was missing.
+class HTTY::NoResponseError < StandardError
+
+  def initialize
+    super 'request does not have a response'
+  end
+
+end

data/app/htty/no_set_cookie_header_error.rb

@@ -0,0 +1,13 @@
+# Defines HTTY::NoSetCookieHeaderError.
+
+module HTTY; end
+
+# Indicates that the _Set-Cookie_ header was missing from
+# HTTY::Request#response.
+class HTTY::NoSetCookieHeaderError < StandardError
+
+  def initialize
+    super "response does not have a 'Set-Cookie' header"
+  end
+
+end

data/app/htty/ordered_hash.rb

@@ -0,0 +1,69 @@
+# Defines HTTY::OrderedHash.
+
+module HTTY; end
+
+# Represents a Hash that preserves the insertion order of values. This class
+# exists because Hash did not have this behavior in Ruby v1.8.7 and earlier.
+class HTTY::OrderedHash
+
+  def initialize(hash={})
+    @inner_hash = {}
+    hash.each_pair do |key, value|
+      @inner_hash[key] = value
+    end
+    @inner_keys = []
+    @inner_hash.each_key do |k|
+      @inner_keys << k
+    end
+  end
+
+  def initialize_copy(source) #:nodoc:
+    super
+    @inner_hash = @inner_hash.dup
+    @inner_keys = @inner_keys.dup
+  end
+
+  def [](key)
+    @inner_hash[key]
+  end
+
+  def []=(key, value)
+    @inner_keys << key unless @inner_hash.key?(key)
+    @inner_hash[key] = value
+    self
+  end
+
+  def ==(other_hash)
+    if other_hash.kind_of?(self.class)
+      return (other_hash.instance_variable_get('@inner_hash') == @inner_hash) &&
+             (other_hash.instance_variable_get('@inner_keys') == @inner_keys)
+    end
+    if other_hash.kind_of?(@inner_hash.class)
+      return other_hash.keys.all? do |k|
+        other_hash[k] == @inner_hash[k]
+      end
+    end
+    false
+  end
+
+  def clear
+    @inner_hash.clear
+    @inner_keys.clear
+  end
+
+  def delete(key)
+    @inner_keys.delete(key) if @inner_hash.key?(key)
+    @inner_hash.delete key
+  end
+
+  def empty?
+    @inner_hash.empty?
+  end
+
+  def to_a
+    @inner_keys.inject([]) do |result, key|
+      result + [[key, @inner_hash[key]]]
+    end
+  end
+
+end

data/app/htty/payload.rb

@@ -0,0 +1,48 @@
+# Defines HTTY::Payload.
+
+require File.expand_path("#{File.dirname __FILE__}/ordered_hash")
+
+module HTTY; end
+
+# Encapsulates the headers and body of an HTTP(S) request or response.
+class HTTY::Payload
+
+  # Returns the body of the payload.
+  attr_reader :body
+
+  # Returns +true+ if _other_payload_ is equivalent to the payload.
+  def ==(other_payload)
+    return false unless other_payload.kind_of?(HTTY::Payload)
+    (other_payload.body == body) && (other_payload.headers == headers)
+  end
+  alias :eql? :==
+
+  # Returns an array of the headers belonging to the payload.
+  def headers
+    @headers.to_a
+  end
+
+protected
+
+  # Initializes a new HTTY::Payload with attribute values specified in the
+  # _attributes_ hash.
+  #
+  # Valid _attributes_ keys include:
+  #
+  # * <tt>:body</tt>
+  # * <tt>:headers</tt>
+  def initialize(attributes={})
+    @body    = attributes[:body]
+    @headers = HTTY::OrderedHash.new
+    Array(attributes[:headers]).each do |name, value|
+      @headers[name] = value
+    end
+  end
+
+  def initialize_copy(source) #:nodoc:
+    super
+    @body    = @body.dup if @body
+    @headers = @headers.dup
+  end
+
+end

data/app/htty/request.rb

@@ -0,0 +1,471 @@
+# Defines HTTY::Request.
+
+require 'pathname'
+require 'uri'
+require File.expand_path("#{File.dirname __FILE__}/../htty")
+require File.expand_path("#{File.dirname __FILE__}/cookies_util")
+require File.expand_path("#{File.dirname __FILE__}/no_location_header_error")
+require File.expand_path("#{File.dirname __FILE__}/no_response_error")
+require File.expand_path("#{File.dirname __FILE__}/no_set_cookie_header_error")
+require File.expand_path("#{File.dirname __FILE__}/payload")
+require File.expand_path("#{File.dirname __FILE__}/requests_util")
+require File.expand_path("#{File.dirname __FILE__}/response")
+
+module HTTY; end
+
+# Encapsulates an HTTP(S) request.
+class HTTY::Request < HTTY::Payload
+
+  COOKIES_HEADER_NAME = 'Cookie'
+
+  METHODS_SENDING_BODY = [:post, :put]
+
+  # Returns a URI authority (a combination of userinfo, host, and port)
+  # corresponding to the specified _components_ hash. Valid _components_ keys
+  # include:
+  #
+  # * <tt>:userinfo</tt>
+  # * <tt>:host</tt>
+  # * <tt>:port</tt>
+  def self.build_authority(components)
+    userinfo_and_host = [components[:userinfo],
+                         components[:host]].compact.join('@')
+    all               = [userinfo_and_host, components[:port]].compact.join(':')
+    return nil if (all == '')
+    all
+  end
+
+  # Returns a combination of a URI path, query, and fragment, corresponding to
+  # the specified _components_ hash. Valid _components_ keys include:
+  #
+  # * <tt>:path</tt>
+  # * <tt>:query</tt>
+  # * <tt>:fragment</tt>
+  def self.build_path_query_and_fragment(components)
+    path     = components[:path]
+    query    = components[:query]    ? "?#{components[:query]}"    : nil
+    fragment = components[:fragment] ? "##{components[:fragment]}" : nil
+    all      = [path, query, fragment].compact.join
+    return nil if (all == '')
+    all
+  end
+
+  # Returns a URI corresponding to the specified _components_ hash, or raises
+  # URI::InvalidURIError. Valid _components_ keys include:
+  #
+  # * <tt>:scheme</tt>
+  # * <tt>:userinfo</tt>
+  # * <tt>:host</tt>
+  # * <tt>:port</tt>
+  # * <tt>:path</tt>
+  # * <tt>:query</tt>
+  # * <tt>:fragment</tt>
+  def self.build_uri(components)
+    scheme                  = (components[:scheme] || 'http') + '://'
+    authority               = build_authority(components)
+    path_query_and_fragment = build_path_query_and_fragment(components)
+    path_query_and_fragment ||= '/' if authority
+    unless scheme == 'http://'
+      raise ArgumentError, "#{scheme.inspect} is not yet supported"
+    end
+    URI.parse([scheme, authority, path_query_and_fragment].join)
+  end
+
+  # Returns a URI corresponding to the specified _address_, or raises
+  # URI::InvalidURIError.
+  def self.parse_uri(address)
+    address = '0.0.0.0' if address.nil? || (address == '')
+
+    scheme_missing = false
+    if (address !~ /^[a-z]+:\/\//) && (address !~ /^mailto:/)
+      scheme_missing = true
+      address = 'http://' + address
+    end
+
+    scheme,
+    userinfo,
+    host,
+    port,
+    registry, # Not used by HTTP
+    path,
+    opaque,   # Not used by HTTP
+    query,
+    fragment = URI.split(address)
+
+    scheme = nil if scheme_missing
+    path   = nil if (path == '')
+
+    unless scheme
+      scheme = (port.to_i == URI::HTTPS::DEFAULT_PORT) ? 'https' : 'http'
+    end
+
+    build_uri :scheme   => scheme,
+              :userinfo => userinfo,
+              :host     => host,
+              :port     => port,
+              :path     => path,
+              :query    => query,
+              :fragment => fragment
+  end
+
+protected
+
+  def self.clear_cookies_if_host_changes(request)
+    previous_host = request.uri.host
+    yield
+    request.cookies_remove_all unless request.uri.host == previous_host
+    request
+  end
+
+public
+
+  # Returns the HTTP method of the request, if any.
+  attr_reader :request_method
+
+  # Returns the response received for the request, if any.
+  attr_reader :response
+
+  # Returns the URI of the request.
+  attr_reader :uri
+
+  # Initializes a new HTTY::Request with a #uri corresponding to the specified
+  # _address_.
+  def initialize(address)
+    super({:headers => [['User-Agent', "htty/#{HTTY::VERSION}"]]})
+    @uri = self.class.parse_uri(address)
+    establish_content_length
+  end
+
+  def initialize_copy(source) #:nodoc:
+    super
+    @response = @response.dup if @response
+    @uri      = @uri.dup
+  end
+
+  # Returns +true+ if _other_request_ is equivalent to the request.
+  def ==(other_request)
+    return false unless super(other_request)
+    return false unless other_request.kind_of?(self.class)
+    (other_request.response == response) && (other_request.uri == uri)
+  end
+  alias :eql? :==
+
+  # Establishes a new #uri corresponding to the specified _address_. If the host
+  # of the _address_ is different from the host of #uri, then #cookies are
+  # cleared.
+  def address(address)
+    uri = self.class.parse_uri(address)
+    if response
+      dup = dup_without_response
+      return self.class.clear_cookies_if_host_changes(dup) do
+        dup.uri = uri
+      end
+    end
+
+    self.class.clear_cookies_if_host_changes self do
+      @uri = uri
+    end
+  end
+
+  # Sets the body of the request.
+  def body_set(body)
+    return dup_without_response.body_set(body) if response
+
+    @body = body ? body.to_s : nil
+    establish_content_length
+  end
+
+  # Clears the body of the request.
+  def body_unset
+    body_set nil
+  end
+
+  # Makes an HTTP +CONNECT+ request using the path of #uri.
+  def connect!
+    request! :connect
+  end
+
+  # Appends to #cookies using the specified _name_ (required) and _value_
+  # (optional).
+  def cookie_add(name, value=nil)
+    return dup_without_response.cookie_add(name, value) if response
+
+    cookies_string = HTTY::CookiesUtil.cookies_to_string(cookies +
+                                                         [[name.to_s, value]])
+    if cookies_string
+      @headers[COOKIES_HEADER_NAME] = cookies_string
+    else
+      @headers.delete COOKIES_HEADER_NAME
+    end
+    self
+  end
+
+  # Removes the last element of #cookies having the specified _name_.
+  def cookie_remove(name)
+    return dup_without_response.cookie_remove(name) if response
+
+    # Remove just one matching cookie from the end.
+    rejected = false
+    new_cookies = cookies.reverse.reject do |cookie_name, cookie_value|
+      if !rejected && (cookie_name == name)
+        rejected = true
+      else
+        false
+      end
+    end.reverse
+
+    cookies_string = HTTY::CookiesUtil.cookies_to_string(new_cookies)
+    if cookies_string
+      @headers[COOKIES_HEADER_NAME] = cookies_string
+    else
+      @headers.delete COOKIES_HEADER_NAME
+    end
+    self
+  end
+
+  # Returns an array of the cookies belonging to the request.
+  def cookies
+    HTTY::CookiesUtil.cookies_from_string @headers[COOKIES_HEADER_NAME]
+  end
+
+  # Removes all #cookies.
+  def cookies_remove_all
+    return dup_without_response.cookies_remove_all if response
+
+    @headers.delete COOKIES_HEADER_NAME
+    self
+  end
+
+  # Sets #cookies according to the _Set-Cookie_ header of the specified
+  # _response_, or raises either HTTY::NoResponseError or
+  # HTTY::NoSetCookieHeaderError.
+  def cookies_use(response)
+    raise HTTY::NoResponseError unless response
+
+    cookies_header = response.headers.detect do |name, value|
+      name == HTTY::Response::COOKIES_HEADER_NAME
+    end
+    unless cookies_header && cookies_header.last
+      raise HTTY::NoSetCookieHeaderError
+    end
+    header_set COOKIES_HEADER_NAME, cookies_header.last
+  end
+
+  # Makes an HTTP +DELETE+ request using the path of #uri.
+  def delete!
+    request! :delete
+  end
+
+  # Establishes a new #uri according to the _Location_ header of the specified
+  # _response_, or raises either HTTY::NoResponseError or
+  # HTTY::NoLocationHeaderError.
+  def follow(response)
+    raise HTTY::NoResponseError unless response
+
+    location_header = response.headers.detect do |name, value|
+      name == 'Location'
+    end
+    unless location_header && location_header.last
+      raise HTTY::NoLocationHeaderError
+    end
+    address location_header.last
+  end
+
+  # Establishes a new #uri with the specified _fragment_.
+  def fragment_set(fragment)
+    rebuild_uri :fragment => fragment
+  end
+
+  # Establishes a new #uri without a fragment.
+  def fragment_unset
+    fragment_set nil
+  end
+
+  # Makes an HTTP +GET+ request using the path of #uri.
+  def get!
+    request! :get
+  end
+
+  # Makes an HTTP +HEAD+ request using the path of #uri.
+  def head!
+    request! :head
+  end
+
+  # Appends to #headers or changes the element of #headers using the specified
+  # _name_ and _value_.
+  def header_set(name, value)
+    return dup_without_response.header_set(name, value) if response
+
+    name = name.to_s
+    if value.nil?
+      @headers.delete name
+      return self
+    end
+
+    @headers[name] = value.to_s
+    self
+  end
+
+  # Removes the element of #headers having the specified _name_.
+  def header_unset(name)
+    header_set name, nil
+  end
+
+  # Returns an array of the headers belonging to the payload. If
+  # _include_content_length_ is +false+, then a 'Content Length' header will be
+  # omitted. If _include_content_length_ is not specified, then it will be
+  # +true+ if #request_method is an HTTP method for which body content is
+  # expected.
+  def headers(include_content_length=
+              METHODS_SENDING_BODY.include?(request_method))
+    unless include_content_length
+      return super().reject do |name, value|
+        name == 'Content-Length'
+      end
+    end
+
+    super()
+  end
+
+  # Removes all #headers.
+  def headers_unset_all
+    return dup_without_response.headers_unset_all if response
+
+    @headers.clear
+    self
+  end
+
+  # Establishes a new #uri with the specified _host_.
+  def host_set(host)
+    rebuild_uri :host => host
+  end
+
+  # Makes an HTTP +OPTIONS+ request using the path of #uri.
+  def options!
+    request! :options
+  end
+
+  # Makes an HTTP +PATCH+ request using the path of #uri.
+  def patch!
+    request! :patch
+  end
+
+  # Establishes a new #uri with the specified _path_ which may be absolute or
+  # relative.
+  def path_set(path)
+    absolute_path = (Pathname.new(uri.path) + path).to_s
+    rebuild_uri :path => absolute_path
+  end
+
+  # Establishes a new #uri with the specified _port_.
+  def port_set(port)
+    rebuild_uri :port => port
+  end
+
+  # Makes an HTTP +POST+ request using the path of #uri.
+  def post!
+    request! :post
+  end
+
+  # Makes an HTTP +PUT+ request using the path of #uri.
+  def put!
+    request! :put
+  end
+
+  # Establishes a new #uri, with the specified _value_ for the query-string
+  # parameter specified by _name_.
+  def query_set(name, value)
+    query     = uri.query ? "&#{uri.query}&" : ''
+    parameter = Regexp.new("&#{Regexp.escape name}=.+?&")
+    if query =~ parameter
+      new_query = value.nil? ?
+                  query.gsub(parameter, '&') :
+                  query.gsub(parameter, "&#{name}=#{value}&")
+    else
+      new_query = value.nil? ? query : "#{query}#{name}=#{value}"
+    end
+    new_query = new_query.gsub(/^&/, '').gsub(/&$/, '')
+    new_query = nil if (new_query == '')
+    rebuild_uri :query => new_query
+  end
+
+  # Establishes a new #uri, without the query-string parameter specified by
+  # _name_.
+  def query_unset(name)
+    query_set name, nil
+  end
+
+  # Establishes a new #uri without a query string.
+  def query_unset_all
+    rebuild_uri :query => nil
+  end
+
+  # Establishes a new #uri with the specified _scheme_.
+  def scheme_set(scheme)
+    rebuild_uri :scheme => scheme
+  end
+
+  # Makes an HTTP +TRACE+ request using the path of #uri.
+  def trace!
+    request! :trace
+  end
+
+  # Establishes a new #uri with the specified _userinfo_.
+  def userinfo_set(userinfo)
+    rebuild_uri :userinfo => userinfo
+  end
+
+  # Establishes a new #uri without userinfo.
+  def userinfo_unset
+    userinfo_set nil
+  end
+
+protected
+
+  def dup_without_response
+    request = self.dup
+    request.response = nil
+    request.instance_variable_set '@request_method', nil
+    request
+  end
+
+  def establish_content_length
+    header_set 'Content-Length', body.to_s.length
+  end
+
+  def path_query_and_fragment
+    self.class.build_path_query_and_fragment :path     => uri.path,
+                                             :query    => uri.query,
+                                             :fragment => uri.fragment
+  end
+
+  def rebuild_uri(changed_components)
+    return dup_without_response.rebuild_uri(changed_components) if response
+
+    components = URI::HTTP::COMPONENT.inject({}) do |result, c|
+      result.merge c => uri.send(c)
+    end
+    self.class.clear_cookies_if_host_changes self do
+      @uri = self.class.build_uri(components.merge(changed_components))
+    end
+  end
+
+  attr_writer :response
+
+  attr_writer :uri
+
+private
+
+  def authority
+    self.class.build_authority :userinfo => uri.userinfo,
+                               :host     => uri.host,
+                               :port     => uri.port
+  end
+
+  def request!(method)
+    request = response ? dup_without_response : self
+    request.instance_variable_set '@request_method', method
+    HTTY::RequestsUtil.send method, request
+  end
+
+end