Class: HTTP::Message

Inherits:
Object
  • Object
show all
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

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.



840
841
842
843
 
# File 'lib/httpclient/http.rb', line 840

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

Instance Attribute Details

#http_body ⇒ Object

HTTP::Message::Body

message body.



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

def http_body
  @http_body
end

#http_header ⇒ Object Also known as: header

HTTP::Message::Headers

message header.



828
829
830
 
# File 'lib/httpclient/http.rb', line 828

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.



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

def peer_cert
  @peer_cert
end

Class Method Details

.create_query_part_str(query) ⇒ Object

:nodoc:



772
773
774
775
776
777
778
779
780
 
# File 'lib/httpclient/http.rb', line 772

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(str) ⇒ Object

from CGI.escape



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

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

.escape_query(query) ⇒ Object

:nodoc:



782
783
784
785
786
787
788
789
 
# File 'lib/httpclient/http.rb', line 782

def escape_query(query) # :nodoc:
  query.sort_by { |attr, value| attr.to_s }.collect { |attr, value|
    if value.respond_to?(:read)
      value = value.read
    end
    escape(attr.to_s) << '=' << escape(value.to_s)
  }.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) 


767
768
769
770
 
# File 'lib/httpclient/http.rb', line 767

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=.



730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
 
# File 'lib/httpclient/http.rb', line 730

def internal_mime_type(path)
  case path
  when /\.txt$/i
    'text/plain'
  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) 


751
752
753
 
# File 'lib/httpclient/http.rb', line 751

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

.mime_type(path) ⇒ Object

:nodoc:



715
716
717
718
719
720
721
722
723
724
725
726
 
# File 'lib/httpclient/http.rb', line 715

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.



707
708
709
 
# File 'lib/httpclient/http.rb', line 707

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.



702
703
704
 
# File 'lib/httpclient/http.rb', line 702

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) 


756
757
758
 
# File 'lib/httpclient/http.rb', line 756

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.



646
647
648
649
650
651
 
# File 'lib/httpclient/http.rb', line 646

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.



666
667
668
669
670
671
672
673
674
675
676
677
678
 
# File 'lib/httpclient/http.rb', line 666

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) ⇒ Object

Creates a Message instance of response.

body

a String or an IO of response message body.



682
683
684
685
686
687
688
689
 
# File 'lib/httpclient/http.rb', line 682

def new_response(body)
  m = new
  m.http_header.init_response(Status::OK)
  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



805
806
807
808
809
810
811
812
813
814
815
816
 
# File 'lib/httpclient/http.rb', line 805

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



819
820
821
822
823
 
# File 'lib/httpclient/http.rb', line 819

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

Instance Method Details

#content ⇒ Object Also known as: body

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



921
922
923
 
# File 'lib/httpclient/http.rb', line 921

def content
  @http_body.content
end

#contenttype ⇒ Object

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



911
912
913
 
# File 'lib/httpclient/http.rb', line 911

def contenttype
  @http_header.contenttype
end

#contenttype=(contenttype) ⇒ Object

Returns ‘Content-Type’ header value.



916
917
918
 
# File 'lib/httpclient/http.rb', line 916

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

#cookies ⇒ Object

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



939
940
941
942
943
944
945
946
947
948
949
 
# File 'lib/httpclient/http.rb', line 939

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

#dump(dev = '') ⇒ Object

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



847
848
849
850
851
852
853
854
855
856
857
 
# File 'lib/httpclient/http.rb', line 847

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

#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)



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

def headers
  Hash[http_header.all]
end

#http_version ⇒ Object

Returns HTTP version in a HTTP header. String.



866
867
868
 
# File 'lib/httpclient/http.rb', line 866

def http_version
  @http_header.http_version
end

#http_version=(http_version) ⇒ Object

Sets HTTP version in a HTTP header. String.



871
872
873
 
# File 'lib/httpclient/http.rb', line 871

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

#reason ⇒ Object

Returns HTTP status reason phrase in response. String.



901
902
903
 
# File 'lib/httpclient/http.rb', line 901

def reason
  @http_header.reason_phrase
end

#reason=(reason) ⇒ Object

Sets HTTP status reason phrase of response. String.



906
907
908
 
# File 'lib/httpclient/http.rb', line 906

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

#status ⇒ Object Also known as: code, status_code

Returns HTTP status code in response. Integer.



887
888
889
 
# File 'lib/httpclient/http.rb', line 887

def status
  @http_header.status_code
end

#status=(status) ⇒ Object

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



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

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

#version ⇒ Object 



876
877
878
879
 
# File 'lib/httpclient/http.rb', line 876

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

#version=(version) ⇒ Object 



881
882
883
884
 
# File 'lib/httpclient/http.rb', line 881

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