Class: HTTP::Message

Inherits:
Object
  • Object
show all
Includes:
HTTPClient::Util
Defined in:
lib/httpclient/http.rb,
lib/oauthclient.rb

Overview

Represents a HTTP message. A message is for a request or a response.

Request message is generated from given parameters internally so users don’t need to care about it. Response message is the instance that methods of HTTPClient returns so users need to know how to extract HTTP response data from Message.

Some attributes are only for a request or a response, not both.

How to use HTTP response message

  1. Gets response message body.

    res = clnt.get(url)
p res.content #=> String

  2. Gets response status code.

    res = clnt.get(url)
p res.status #=> 200, 501, etc. (Integer)

  3. Gets response header.

    res = clnt.get(url)
res.header['set-cookie'].each do |value|
  p value
end
assert_equal(1, res.header['last-modified'].size)
p res.header['last-modified'].first

Defined Under Namespace

Classes: Body, Headers

Constant Summary collapse

CRLF = 
"\r\n"
VERSION_WARNING = 
'Message#version (Float) is deprecated. Use Message#http_version (String) instead.'
@@mime_type_handler = 
nil

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from HTTPClient::Util

#argument_to_hash, hash_find_value, #http?, #https?, #keyword_argument, try_require, uri_dirname, uri_part_of, urify, #warning

Constructor Details

#initialize ⇒ Message

Creates a Message. This method should be used internally. Use Message.new_connect_request, Message.new_request or Message.new_response instead.



949
950
951
952
953
 
# File 'lib/httpclient/http.rb', line 949

def initialize # :nodoc:
  @http_header = Headers.new
  @http_body = @peer_cert = nil
  @previous = nil
end

Instance Attribute Details

#http_body ⇒ Object

HTTP::Message::Body

message body.



936
937
938
 
# File 'lib/httpclient/http.rb', line 936

def http_body
  @http_body
end

#http_header ⇒ Object Also known as: header

HTTP::Message::Headers

message header.



933
934
935
 
# File 'lib/httpclient/http.rb', line 933

def http_header
  @http_header
end

#oauth_params ⇒ Object

Returns the value of attribute oauth_params.



13
14
15
 
# File 'lib/oauthclient.rb', line 13

def oauth_params
  @oauth_params
end

#peer_cert ⇒ Object

OpenSSL::X509::Certificate

response only. server certificate which is used for retrieving the response.



940
941
942
 
# File 'lib/httpclient/http.rb', line 940

def peer_cert
  @peer_cert
end

#previous ⇒ Object

The other Message object when this Message is generated instead of the Message because of redirection, negotiation, or format conversion.



944
945
946
 
# File 'lib/httpclient/http.rb', line 944

def previous
  @previous
end

Class Method Details

.create_query_part_str(query) ⇒ Object

:nodoc:



852
853
854
855
856
857
858
859
860
 
# File 'lib/httpclient/http.rb', line 852

def create_query_part_str(query) # :nodoc:
  if multiparam_query?(query)
    escape_query(query)
  elsif query.respond_to?(:read)
    query = query.read
  else
    query.to_s
  end
end

.escape_query(query) ⇒ Object

:nodoc:



873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
 
# File 'lib/httpclient/http.rb', line 873

def escape_query(query) # :nodoc:
  pairs = []
  query.each { |attr, value|
    left = escape(attr.to_s) << '='
    if values = Array.try_convert(value)
      values.each { |v|
        if v.respond_to?(:read)
          v = v.read
        end
        pairs.push(left + escape(v.to_s))
      }
    else
      if value.respond_to?(:read)
        value = value.read
      end
      pairs.push(left << escape(value.to_s))
    end
  }
  pairs.join('&')
end

.file?(obj) ⇒ Boolean

Returns true if the given object is a File. In HTTPClient, a file is;

  • must respond to :read for retrieving String chunks.

  • must respond to :pos and :pos= to rewind for reading. Rewinding is only needed for following HTTP redirect. Some IO impl defines :pos= but raises an Exception for pos= such as StringIO but there’s no problem as far as using it for non-following methods (get/post/etc.)

Returns:

  • (Boolean) 


847
848
849
850
 
# File 'lib/httpclient/http.rb', line 847

def file?(obj)
  obj.respond_to?(:read) and obj.respond_to?(:pos) and
    obj.respond_to?(:pos=)
end

.internal_mime_type(path) ⇒ Object

Default MIME type handler. See mime_type_handler=.



808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
 
# File 'lib/httpclient/http.rb', line 808

def internal_mime_type(path)
  case path
  when /\.txt$/i
    'text/plain'
  when /\.xml$/i
    'text/xml'
  when /\.(htm|html)$/i
    'text/html'
  when /\.doc$/i
    'application/msword'
  when /\.png$/i
    'image/png'
  when /\.gif$/i
    'image/gif'
  when /\.(jpg|jpeg)$/i
    'image/jpeg'
  else
    'application/octet-stream'
  end
end

.keep_alive_enabled?(version) ⇒ Boolean

Returns true if the given HTTP version allows keep alive connection.

version

String

Returns:

  • (Boolean) 


831
832
833
 
# File 'lib/httpclient/http.rb', line 831

def keep_alive_enabled?(version)
  version >= '1.1'
end

.mime_type(path) ⇒ Object

:nodoc:



793
794
795
796
797
798
799
800
801
802
803
804
 
# File 'lib/httpclient/http.rb', line 793

def mime_type(path) # :nodoc:
  if @@mime_type_handler
    res = @@mime_type_handler.call(path)
    if !res || res.to_s == ''
      return 'application/octet-stream'
    else
      return res
    end
  else
    internal_mime_type(path)
  end
end

.mime_type_handler ⇒ Object Also known as: get_mime_type_func

Returns MIME type handler.



785
786
787
 
# File 'lib/httpclient/http.rb', line 785

def mime_type_handler
  @@mime_type_handler
end

.mime_type_handler=(handler) ⇒ Object Also known as: set_mime_type_func

Sets MIME type handler.

handler must respond to :call with a single argument :path and returns a MIME type String e.g. ‘text/html’. When the handler returns nil or an empty String, ‘application/octet-stream’ is used.

When you set nil to the handler, internal_mime_type is used instead. The handler is nil by default.



780
781
782
 
# File 'lib/httpclient/http.rb', line 780

def mime_type_handler=(handler)
  @@mime_type_handler = handler
end

.multiparam_query?(query) ⇒ Boolean

Returns true if the given query (or body) has a multiple parameter.

Returns:

  • (Boolean) 


836
837
838
 
# File 'lib/httpclient/http.rb', line 836

def multiparam_query?(query)
  query.is_a?(Array) or query.is_a?(Hash)
end

.new_connect_request(uri) ⇒ Object

Creates a Message instance of ‘CONNECT’ request. ‘CONNECT’ request does not have Body.

uri

an URI that need to connect. Only uri.host and uri.port are used.



724
725
726
727
728
729
 
# File 'lib/httpclient/http.rb', line 724

def new_connect_request(uri)
  m = new
  m.http_header.init_connect_request(uri)
  m.http_header.body_size = nil
  m
end

.new_request(method, uri, query = nil, body = nil, boundary = nil) ⇒ Object

Creates a Message instance of general request.

method

HTTP method String.

uri

an URI object which represents an URL of web resource.

query

a Hash or an Array of query part of URL. e.g. { “a” => “b” } => ‘host/part?a=b’ Give an array to pass multiple value like

[“a”, “b”], [“a”, “c”]

> ‘host/part?a=b&a=c’

body

a Hash or an Array of body part. e.g. { “a” => “b” } => ‘a=b’. Give an array to pass multiple value like

[“a”, “b”], [“a”, “c”]

> ‘a=b&a=c’.

boundary

When the boundary given, it is sent as a multipart/form-data using this boundary String.



744
745
746
747
748
749
750
751
752
753
754
755
756
 
# File 'lib/httpclient/http.rb', line 744

def new_request(method, uri, query = nil, body = nil, boundary = nil)
  m = new
  m.http_header.init_request(method, uri, query)
  m.http_body = Body.new
  m.http_body.init_request(body || '', boundary)
  if body
    m.http_header.body_size = m.http_body.size
    m.http_header.chunked = true if m.http_body.size.nil?
  else
    m.http_header.body_size = nil
  end
  m
end

.new_response(body, req = nil) ⇒ Object

Creates a Message instance of response.

body

a String or an IO of response message body.



760
761
762
763
764
765
766
767
 
# File 'lib/httpclient/http.rb', line 760

def new_response(body, req = nil)
  m = new
  m.http_header.init_response(Status::OK, req)
  m.http_body = Body.new
  m.http_body.init_response(body)
  m.http_header.body_size = m.http_body.size || 0
  m
end

.parse(query) ⇒ Object

from CGI.parse



910
911
912
913
914
915
916
917
918
919
920
921
 
# File 'lib/httpclient/http.rb', line 910

def parse(query)
  params = Hash.new([].freeze)
  query.split(/[&;]/n).each do |pairs|
    key, value = pairs.split('=',2).collect{|v| unescape(v) }
    if params.has_key?(key)
      params[key].push(value)
    else
      params[key] = [value]
    end
  end
  params
end

.unescape(string) ⇒ Object

from CGI.unescape



924
925
926
927
928
 
# File 'lib/httpclient/http.rb', line 924

def unescape(string)
  string.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n) do
    [$1.delete('%')].pack('H*')
  end
end

Instance Method Details

#body_encoding ⇒ Object

Returns content encoding



1034
1035
1036
 
# File 'lib/httpclient/http.rb', line 1034

def body_encoding
  @http_header.body_encoding
end

#content ⇒ Object Also known as: body

Returns a content of message body. A String or an IO.



1039
1040
1041
 
# File 'lib/httpclient/http.rb', line 1039

def content
  @http_body.content
end

#content_type ⇒ Object Also known as: contenttype

Returns ‘Content-Type’ header value.



1022
1023
1024
 
# File 'lib/httpclient/http.rb', line 1022

def content_type
  @http_header.content_type
end

#content_type=(content_type) ⇒ Object Also known as: contenttype=

Sets ‘Content-Type’ header value. Overrides if already exists.



1027
1028
1029
 
# File 'lib/httpclient/http.rb', line 1027

def content_type=(content_type)
  @http_header.content_type = content_type
end

#cookies ⇒ Object

Extracts cookies from ‘Set-Cookie’ header. Supports ‘Set-Cookie’ in response header only. Do we need ‘Cookie’ support in request header?



1057
1058
1059
1060
1061
1062
1063
1064
1065
 
# File 'lib/httpclient/http.rb', line 1057

def cookies
  set_cookies = http_header['set-cookie']
  unless set_cookies.empty?
    uri = http_header.request_uri
    set_cookies.map { |str|
      WebAgent::Cookie.parse(str, uri)
    }.flatten
  end
end

#dump(dev = '') ⇒ Object

Dumps message (header and body) to given dev. dev needs to respond to <<.



957
958
959
960
961
962
963
964
965
966
967
 
# File 'lib/httpclient/http.rb', line 957

def dump(dev = '')
  str = @http_header.dump + CRLF
  if @http_header.chunked
    dev = @http_body.dump_chunked(str, dev)
  elsif @http_body
    dev = @http_body.dump(str, dev)
  else
    dev << str
  end
  dev
end

#escape(str) ⇒ Object

:nodoc:



896
897
898
899
900
 
# File 'lib/httpclient/http.rb', line 896

def escape(str) # :nodoc:
  str.dup.force_encoding(Encoding::ASCII_8BIT).gsub(/([^ a-zA-Z0-9_.-]+)/) {
    '%' + $1.unpack('H2' * $1.bytesize).join('%').upcase
  }.tr(' ', '+')
end

#headers ⇒ Object

Returns Hash of header. key and value are both String. Each key has a single value so you can’t extract exact value when a message has multiple headers like ‘Set-Cookie’. Use header for that purpose. (It returns an Array always)



1050
1051
1052
 
# File 'lib/httpclient/http.rb', line 1050

def headers
  Hash[*http_header.all.flatten]
end

#http_version ⇒ Object

Returns HTTP version in a HTTP header. String.



977
978
979
 
# File 'lib/httpclient/http.rb', line 977

def http_version
  @http_header.http_version
end

#http_version=(http_version) ⇒ Object

Sets HTTP version in a HTTP header. String.



982
983
984
 
# File 'lib/httpclient/http.rb', line 982

def http_version=(http_version)
  @http_header.http_version = http_version
end

#ok? ⇒ Boolean

Convenience method to return boolean of whether we had a successful request

Returns:

  • (Boolean) 


1068
1069
1070
 
# File 'lib/httpclient/http.rb', line 1068

def ok?
  HTTP::Status.successful?(status)
end

#reason ⇒ Object

Returns HTTP status reason phrase in response. String.



1012
1013
1014
 
# File 'lib/httpclient/http.rb', line 1012

def reason
  @http_header.reason_phrase
end

#reason=(reason) ⇒ Object

Sets HTTP status reason phrase of response. String.



1017
1018
1019
 
# File 'lib/httpclient/http.rb', line 1017

def reason=(reason)
  @http_header.reason_phrase = reason
end

#redirect? ⇒ Boolean

Returns:

  • (Boolean) 


1072
1073
1074
 
# File 'lib/httpclient/http.rb', line 1072

def redirect?
  HTTP::Status.redirect?(status)
end

#see_other? ⇒ Boolean

SEE_OTHER is a redirect, but it should sent as GET

Returns:

  • (Boolean) 


1077
1078
1079
 
# File 'lib/httpclient/http.rb', line 1077

def see_other?
  status == HTTP::Status::SEE_OTHER
end

#status ⇒ Object Also known as: code, status_code

Returns HTTP status code in response. Integer.



998
999
1000
 
# File 'lib/httpclient/http.rb', line 998

def status
  @http_header.status_code
end

#status=(status) ⇒ Object

Sets HTTP status code of response. Integer. Reason phrase is updated, too.



1007
1008
1009
 
# File 'lib/httpclient/http.rb', line 1007

def status=(status)
  @http_header.status_code = status
end

#version ⇒ Object 



987
988
989
990
 
# File 'lib/httpclient/http.rb', line 987

def version
  warning(VERSION_WARNING)
  @http_header.http_version.to_f
end

#version=(version) ⇒ Object 



992
993
994
995
 
# File 'lib/httpclient/http.rb', line 992

def version=(version)
  warning(VERSION_WARNING)
  @http_header.http_version = version
end