Class: HTTP::Message
- Inherits:
-
Object
- Object
- HTTP::Message
- 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
-
Gets response message body.
res = clnt.get(url) p res.content #=> String
-
Gets response status code.
res = clnt.get(url) p res.status #=> 200, 501, etc. (Integer)
-
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
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
-
#http_body ⇒ Object
- HTTP::Message::Body
-
message body.
-
#http_header ⇒ Object
(also: #header)
- HTTP::Message::Headers
-
message header.
-
#oauth_params ⇒ Object
Returns the value of attribute oauth_params.
-
#peer_cert ⇒ Object
- OpenSSL::X509::Certificate
-
response only.
-
#previous ⇒ Object
The other Message object when this Message is generated instead of the Message because of redirection, negotiation, or format conversion.
Class Method Summary collapse
-
.create_query_part_str(query) ⇒ Object
:nodoc:.
-
.escape_query(query) ⇒ Object
:nodoc:.
-
.file?(obj) ⇒ Boolean
Returns true if the given object is a File.
-
.internal_mime_type(path) ⇒ Object
Default MIME type handler.
-
.keep_alive_enabled?(version) ⇒ Boolean
Returns true if the given HTTP version allows keep alive connection.
-
.mime_type(path) ⇒ Object
:nodoc:.
-
.mime_type_handler ⇒ Object
(also: get_mime_type_func)
Returns MIME type handler.
-
.mime_type_handler=(handler) ⇒ Object
(also: set_mime_type_func)
Sets MIME type handler.
-
.multiparam_query?(query) ⇒ Boolean
Returns true if the given query (or body) has a multiple parameter.
-
.new_connect_request(uri) ⇒ Object
Creates a Message instance of ‘CONNECT’ request.
-
.new_request(method, uri, query = nil, body = nil, boundary = nil) ⇒ Object
Creates a Message instance of general request.
-
.new_response(body, req = nil) ⇒ Object
Creates a Message instance of response.
-
.parse(query) ⇒ Object
from CGI.parse.
-
.unescape(string) ⇒ Object
from CGI.unescape.
Instance Method Summary collapse
-
#body_encoding ⇒ Object
Returns content encoding.
-
#content ⇒ Object
(also: #body)
Returns a content of message body.
-
#content_type ⇒ Object
(also: #contenttype)
Returns ‘Content-Type’ header value.
-
#content_type=(content_type) ⇒ Object
(also: #contenttype=)
Sets ‘Content-Type’ header value.
-
#cookies ⇒ Object
Extracts cookies from ‘Set-Cookie’ header.
-
#dump(dev = '') ⇒ Object
Dumps message (header and body) to given dev.
-
#escape(str) ⇒ Object
:nodoc:.
-
#headers ⇒ Object
Returns Hash of header.
-
#http_version ⇒ Object
Returns HTTP version in a HTTP header.
-
#http_version=(http_version) ⇒ Object
Sets HTTP version in a HTTP header.
-
#initialize ⇒ Message
constructor
Creates a Message.
-
#ok? ⇒ Boolean
Convenience method to return boolean of whether we had a successful request.
-
#reason ⇒ Object
Returns HTTP status reason phrase in response.
-
#reason=(reason) ⇒ Object
Sets HTTP status reason phrase of response.
- #redirect? ⇒ Boolean
-
#see_other? ⇒ Boolean
SEE_OTHER is a redirect, but it should sent as GET.
-
#status ⇒ Object
(also: #code, #status_code)
Returns HTTP status code in response.
-
#status=(status) ⇒ Object
Sets HTTP status code of response.
- #version ⇒ Object
- #version=(version) ⇒ Object
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.
944 945 946 947 948 |
# File 'lib/httpclient/http.rb', line 944 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.
931 932 933 |
# File 'lib/httpclient/http.rb', line 931 def http_body @http_body end |
#http_header ⇒ Object Also known as: header
- HTTP::Message::Headers
-
message header.
928 929 930 |
# File 'lib/httpclient/http.rb', line 928 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.
935 936 937 |
# File 'lib/httpclient/http.rb', line 935 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.
939 940 941 |
# File 'lib/httpclient/http.rb', line 939 def previous @previous end |
Class Method Details
.create_query_part_str(query) ⇒ Object
:nodoc:
847 848 849 850 851 852 853 854 855 |
# File 'lib/httpclient/http.rb', line 847 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:
868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 |
# File 'lib/httpclient/http.rb', line 868 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.)
842 843 844 845 |
# File 'lib/httpclient/http.rb', line 842 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=.
805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 |
# File 'lib/httpclient/http.rb', line 805 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
826 827 828 |
# File 'lib/httpclient/http.rb', line 826 def keep_alive_enabled?(version) version >= '1.1' end |
.mime_type(path) ⇒ Object
:nodoc:
790 791 792 793 794 795 796 797 798 799 800 801 |
# File 'lib/httpclient/http.rb', line 790 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.
782 783 784 |
# File 'lib/httpclient/http.rb', line 782 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.
777 778 779 |
# File 'lib/httpclient/http.rb', line 777 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.
831 832 833 |
# File 'lib/httpclient/http.rb', line 831 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.
721 722 723 724 725 726 |
# File 'lib/httpclient/http.rb', line 721 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.
741 742 743 744 745 746 747 748 749 750 751 752 753 |
# File 'lib/httpclient/http.rb', line 741 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.
757 758 759 760 761 762 763 764 |
# File 'lib/httpclient/http.rb', line 757 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
905 906 907 908 909 910 911 912 913 914 915 916 |
# File 'lib/httpclient/http.rb', line 905 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
919 920 921 922 923 |
# File 'lib/httpclient/http.rb', line 919 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
1029 1030 1031 |
# File 'lib/httpclient/http.rb', line 1029 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.
1034 1035 1036 |
# File 'lib/httpclient/http.rb', line 1034 def content @http_body.content end |
#content_type ⇒ Object Also known as: contenttype
Returns ‘Content-Type’ header value.
1017 1018 1019 |
# File 'lib/httpclient/http.rb', line 1017 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.
1022 1023 1024 |
# File 'lib/httpclient/http.rb', line 1022 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?
1052 1053 1054 1055 1056 1057 1058 1059 1060 |
# File 'lib/httpclient/http.rb', line 1052 def = http_header['set-cookie'] unless .empty? uri = http_header.request_uri .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 <<.
952 953 954 955 956 957 958 959 960 961 962 |
# File 'lib/httpclient/http.rb', line 952 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:
891 892 893 894 895 |
# File 'lib/httpclient/http.rb', line 891 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)
1045 1046 1047 |
# File 'lib/httpclient/http.rb', line 1045 def headers Hash[*http_header.all.flatten] end |
#http_version ⇒ Object
Returns HTTP version in a HTTP header. String.
972 973 974 |
# File 'lib/httpclient/http.rb', line 972 def http_version @http_header.http_version end |
#http_version=(http_version) ⇒ Object
Sets HTTP version in a HTTP header. String.
977 978 979 |
# File 'lib/httpclient/http.rb', line 977 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
1063 1064 1065 |
# File 'lib/httpclient/http.rb', line 1063 def ok? HTTP::Status.successful?(status) end |
#reason ⇒ Object
Returns HTTP status reason phrase in response. String.
1007 1008 1009 |
# File 'lib/httpclient/http.rb', line 1007 def reason @http_header.reason_phrase end |
#reason=(reason) ⇒ Object
Sets HTTP status reason phrase of response. String.
1012 1013 1014 |
# File 'lib/httpclient/http.rb', line 1012 def reason=(reason) @http_header.reason_phrase = reason end |
#redirect? ⇒ Boolean
1067 1068 1069 |
# File 'lib/httpclient/http.rb', line 1067 def redirect? HTTP::Status.redirect?(status) end |
#see_other? ⇒ Boolean
SEE_OTHER is a redirect, but it should sent as GET
1072 1073 1074 |
# File 'lib/httpclient/http.rb', line 1072 def see_other? status == HTTP::Status::SEE_OTHER end |
#status ⇒ Object Also known as: code, status_code
Returns HTTP status code in response. Integer.
993 994 995 |
# File 'lib/httpclient/http.rb', line 993 def status @http_header.status_code end |
#status=(status) ⇒ Object
Sets HTTP status code of response. Integer. Reason phrase is updated, too.
1002 1003 1004 |
# File 'lib/httpclient/http.rb', line 1002 def status=(status) @http_header.status_code = status end |
#version ⇒ Object
982 983 984 985 |
# File 'lib/httpclient/http.rb', line 982 def version warn(VERSION_WARNING) @http_header.http_version.to_f end |
#version=(version) ⇒ Object
987 988 989 990 |
# File 'lib/httpclient/http.rb', line 987 def version=(version) warn(VERSION_WARNING) @http_header.http_version = version end |