Class: HTTP::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/httpclient/http.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"
@@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.



791
792
793
794
 
# File 'lib/httpclient/http.rb', line 791

def initialize # :nodoc:
  @header = Headers.new
  @body = @peer_cert = nil
end

Instance Attribute Details

#body ⇒ Object

HTTP::Message::Body

message body.



782
783
784
 
# File 'lib/httpclient/http.rb', line 782

def body
  @body
end

#header ⇒ Object

HTTP::Message::Headers

message header.



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

def header
  @header
end

#peer_cert ⇒ Object

OpenSSL::X509::Certificate

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



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

def peer_cert
  @peer_cert
end

Class Method Details

.create_query_part_str(query) ⇒ Object

:nodoc:



750
751
752
753
754
755
756
757
758
 
# File 'lib/httpclient/http.rb', line 750

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



770
771
772
773
774
 
# File 'lib/httpclient/http.rb', line 770

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

.escape_query(query) ⇒ Object

:nodoc:



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

def escape_query(query) # :nodoc:
  query.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 :path and returns a path for Content-Disposition.

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


745
746
747
748
 
# File 'lib/httpclient/http.rb', line 745

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

.internal_mime_type(path) ⇒ Object

Default MIME type handler. See mime_type_handler=.



707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
 
# File 'lib/httpclient/http.rb', line 707

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

Float

Returns:

  • (Boolean) 


728
729
730
 
# File 'lib/httpclient/http.rb', line 728

def keep_alive_enabled?(version)
  version >= 1.1
end

.mime_type(path) ⇒ Object

:nodoc:



692
693
694
695
696
697
698
699
700
701
702
703
 
# File 'lib/httpclient/http.rb', line 692

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.



684
685
686
 
# File 'lib/httpclient/http.rb', line 684

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.



679
680
681
 
# File 'lib/httpclient/http.rb', line 679

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) 


733
734
735
 
# File 'lib/httpclient/http.rb', line 733

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.



623
624
625
626
627
628
 
# File 'lib/httpclient/http.rb', line 623

def new_connect_request(uri)
  m = new
  m.header.init_connect_request(uri)
  m.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.



643
644
645
646
647
648
649
650
651
652
653
654
655
 
# File 'lib/httpclient/http.rb', line 643

def new_request(method, uri, query = nil, body = nil, boundary = nil)
  m = new
  m.header.init_request(method, uri, query)
  m.body = Body.new
  m.body.init_request(body || '', boundary)
  if body
    m.header.body_size = m.body.size
    m.header.chunked = true if m.body.size.nil?
  else
    m.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.



659
660
661
662
663
664
665
666
 
# File 'lib/httpclient/http.rb', line 659

def new_response(body)
  m = new
  m.header.init_response(Status::OK)
  m.body = Body.new
  m.body.init_response(body)
  m.header.body_size = m.body.size || 0
  m
end

Instance Method Details

#content ⇒ Object

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



861
862
863
 
# File 'lib/httpclient/http.rb', line 861

def content
  @body.content
end

#contenttype ⇒ Object

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



851
852
853
 
# File 'lib/httpclient/http.rb', line 851

def contenttype
  @header.contenttype
end

#contenttype=(contenttype) ⇒ Object

Returns ‘Content-Type’ header value.



856
857
858
 
# File 'lib/httpclient/http.rb', line 856

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

#dump(dev = '') ⇒ Object

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



798
799
800
801
802
803
804
805
806
807
808
 
# File 'lib/httpclient/http.rb', line 798

def dump(dev = '')
  str = header.dump + CRLF
  if header.chunked
    dev = body.dump_chunked(str, dev)
  elsif body
    dev = body.dump(str, dev)
  else
    dev << str
  end
  dev
end

#reason ⇒ Object

Returns HTTP status reason phrase in response. String.



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

def reason
  @header.reason_phrase
end

#reason=(reason) ⇒ Object

Sets HTTP status reason phrase of response. String.



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

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

#status ⇒ Object Also known as: code, status_code

Returns HTTP status code in response. Integer.



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

def status
  @header.status_code
end

#status=(status) ⇒ Object

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



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

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

#version ⇒ Object

Returns HTTP version in a HTTP header. Float.



817
818
819
 
# File 'lib/httpclient/http.rb', line 817

def version
  @header.http_version
end

#version=(version) ⇒ Object

Sets HTTP version in a HTTP header. Float.



822
823
824
 
# File 'lib/httpclient/http.rb', line 822

def version=(version)
  @header.http_version = version
end