Module: Riak::Client::HTTPBackend::TransportMethods

Included in:
Riak::Client::HTTPBackend
Defined in:
riak-client/lib/riak/client/http_backend/transport_methods.rb

Overview

Methods related to performing HTTP requests in a consistent fashion across multiple client libraries. HTTP/1.1 verbs are presented as methods.

Instance Method Summary (collapse)

Instance Method Details

- (Object) basic_auth_header 



158
159
160
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 158

def basic_auth_header
  @client.basic_auth ? {"Authorization" => "Basic #{Base64::encode64(@client.basic_auth)}"} : {}
end

- (Object) client_id 



148
149
150
151
152
153
154
155
156
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 148

def client_id
  value = @client.client_id
  case value
  when Integer
    b64encode(value)
  when String
    value
  end
end

- (Hash) default_headers

Default header hash sent with every request, based on settings in the client

Returns:

  • (Hash) —

    headers that will be merged with user-specified headers on every request 



141
142
143
144
145
146
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 141

def default_headers
  {
    "Accept" => "multipart/mixed, application/json;q=0.7, */*;q=0.5",
    "X-Riak-ClientId" => client_id
  }.merge(basic_auth_header)
end

- (Hash) delete(expect, *resource) - (Hash) delete(expect, *resource, headers) - (Hash) delete(expect, *resource, headers = {}) {|chunk| ... }

Performs a DELETE request to the specified resource on the Riak server.

Overloads:

  • - (Hash) delete(expect, *resource, headers)

    Send the request with custom headers

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

  • - (Hash) delete(expect, *resource, headers = {}) {|chunk| ... }

    Stream the response body through the supplied block

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

    Yields:

    • (chunk) —

      yields successive chunks of the response body as strings

    Returns:

    • (Hash) —

      response data, containing only the :headers and :code keys

Parameters:

  • expect (Fixnum, Array) —

    the expected HTTP response code(s) from Riak

  • resource (String, Array<String,Hash>) —

    a relative path or array of path segments and optional query params Hash that will be joined to the root URI

Returns:

  • (Hash) —

    response data, containing :headers, :code and :body keys

Raises:

  • (FailedRequest) —

    if the response code doesn’t match the expected response 



118
119
120
121
122
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 118

def delete(expect, *resource, &block)
  headers = default_headers.merge(resource.extract_options!)
  verify_path!(resource)
  perform(:delete, path(*resource), headers, expect, &block)
end

- (Hash) get(expect, *resource) - (Hash) get(expect, *resource, headers) - (Hash) get(expect, *resource, headers = {}) {|chunk| ... }

Performs a GET request to the specified resource on the Riak server.

Overloads:

  • - (Hash) get(expect, *resource, headers)

    Send the request with custom headers

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

  • - (Hash) get(expect, *resource, headers = {}) {|chunk| ... }

    Stream the response body through the supplied block

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

    Yields:

    • (chunk) —

      yields successive chunks of the response body as strings

    Returns:

    • (Hash) —

      response data, containing only the :headers and :code keys

Parameters:

  • expect (Fixnum, Array) —

    the expected HTTP response code(s) from Riak

  • resource (String, Array<String,Hash>) —

    a relative path or array of path segments and optional query params Hash that will be joined to the root URI

Returns:

  • (Hash) —

    response data, containing :headers, :body, and :code keys

Raises:

  • (FailedRequest) —

    if the response code doesn’t match the expected response 



56
57
58
59
60
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 56

def get(expect, *resource, &block)
  headers = default_headers.merge(resource.extract_options!)
  verify_path!(resource)
  perform(:get, path(*resource), headers, expect, &block)
end

- (Hash) head(expect, *resource) - (Hash) head(expect, *resource, headers)

Performs a HEAD request to the specified resource on the Riak server.

Overloads:

  • - (Hash) head(expect, *resource, headers)

    Send the request with custom headers

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

Parameters:

  • expect (Fixnum, Array) —

    the expected HTTP response code(s) from Riak

  • resource (String, Array<String,Hash>) —

    a relative path or array of path segments and optional query params Hash that will be joined to the root URI

Returns:

  • (Hash) —

    response data, containing only the :headers and :code keys

Raises:

  • (FailedRequest) —

    if the response code doesn’t match the expected response 



36
37
38
39
40
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 36

def head(expect, *resource)
  headers = default_headers.merge(resource.extract_options!)
  verify_path!(resource)
  perform(:head, path(*resource), headers, expect)
end

- (URI) path(*segments)

Calculates an absolute URI from a relative path specification

Parameters:

  • segments (Array<String,Hash>) —

    a relative path or sequence of path segments and optional query params Hash that will be joined to the root URI

Returns:

  • (URI) —

    an absolute URI for the resource 



171
172
173
174
175
176
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 171

def path(*segments)
  query = segments.extract_options!.to_param
  root_uri.merge(segments.join("/").gsub(/\/+/, "/").sub(/^\//, '')).tap do |uri|
    uri.query = query if query.present?
  end
end

- (Hash) perform(method, uri, headers, expect, body = nil) {|chunk| ... }

This method is abstract.

Subclasses must implement this internal method to perform HTTP requests according to the API of their HTTP libraries.

Executes requests according to the underlying HTTP client library semantics.

Parameters:

  • method (Symbol) —

    one of :head, :get, :post, :put, :delete

  • uri (URI) —

    the HTTP URI to request

  • headers (Hash) —

    headers to send along with the request

  • expect (Fixnum, Array) —

    the expected response code(s)

  • body (String, #read) (defaults to: nil) —

    the PUT or POST request body

Yields:

  • (chunk) —

    if the method is not :head, successive chunks of the response body will be yielded as strings

Returns:

  • (Hash) —

    response data, containing :headers, :code and :body keys. Only :headers and :code should be present when the body is streamed or the method is :head.

Raises:

  • (NotImplementedError) —

    if a subclass does not implement this method 



135
136
137
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 135

def perform(method, uri, headers, expect, body=nil)
  raise NotImplementedError
end

- (Hash) post(expect, *resource, body) - (Hash) post(expect, *resource, body, headers) - (Hash) post(expect, *resource, body, headers = {}) {|chunk| ... }

Performs a POST request to the specified resource on the Riak server.

Overloads:

  • - (Hash) post(expect, *resource, body, headers)

    Send the request with custom headers

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

  • - (Hash) post(expect, *resource, body, headers = {}) {|chunk| ... }

    Stream the response body through the supplied block

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

    Yields:

    • (chunk) —

      yields successive chunks of the response body as strings

    Returns:

    • (Hash) —

      response data, containing only the :headers and :code keys

Parameters:

  • expect (Fixnum, Array) —

    the expected HTTP response code(s) from Riak

  • resource (String, Array<String>) —

    a relative path or array of path segments that will be joined to the root URI

  • body (String) —

    the request body to send to the server

Returns:

  • (Hash) —

    response data, containing :headers, :code and :body keys

Raises:

  • (FailedRequest) —

    if the response code doesn’t match the expected response 



98
99
100
101
102
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 98

def post(expect, *resource, &block)
  headers = default_headers.merge(resource.extract_options!)
  uri, data = verify_path_and_body!(resource)
  perform(:post, path(*uri), headers, expect, data, &block)
end

- (Hash) put(expect, *resource, body) - (Hash) put(expect, *resource, body, headers) - (Hash) put(expect, *resource, body, headers = {}) {|chunk| ... }

Performs a PUT request to the specified resource on the Riak server.

Overloads:

  • - (Hash) put(expect, *resource, body, headers)

    Send the request with custom headers

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

  • - (Hash) put(expect, *resource, body, headers = {}) {|chunk| ... }

    Stream the response body through the supplied block

    Parameters:

    • headers (Hash) —

      custom headers to send with the request

    Yields:

    • (chunk) —

      yields successive chunks of the response body as strings

    Returns:

    • (Hash) —

      response data, containing only the :headers and :code keys

Parameters:

  • expect (Fixnum, Array) —

    the expected HTTP response code(s) from Riak

  • resource (String, Array<String,Hash>) —

    a relative path or array of path segments and optional query params Hash that will be joined to the root URI

  • body (String) —

    the request body to send to the server

Returns:

  • (Hash) —

    response data, containing :headers, :code, and :body keys

Raises:

  • (FailedRequest) —

    if the response code doesn’t match the expected response 



77
78
79
80
81
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 77

def put(expect, *resource, &block)
  headers = default_headers.merge(resource.extract_options!)
  uri, data = verify_path_and_body!(resource)
  perform(:put, path(*uri), headers, expect, data, &block)
end

- (Boolean) return_body?(method, code, has_block)

Checks whether a combination of the HTTP method, response code, and block should result in returning the :body in the response hash. Use internally when implementing #perform.

Parameters:

  • method (Symbol) —

    the HTTP method

  • code (String, Fixnum) —

    the received response code

  • has_block (Boolean) —

    whether a streaming block was passed to #perform. Pass block_given? to this parameter.

Returns:

  • (Boolean) —

    whether to return the body in the response hash 



216
217
218
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 216

def return_body?(method, code, has_block)
  method != :head && !valid_response?([204,205,304], code) && !has_block
end

- (URI) root_uri

The calculated root URI for the Riak HTTP endpoint

Returns:

  • (URI) —

    The calculated root URI for the Riak HTTP endpoint 



163
164
165
166
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 163

def root_uri
  protocol = client.ssl_enabled? ? "https" : "http"
  URI.parse("#{protocol}://#{client.host}:#{client.http_port}")
end

- (Boolean) valid_response?(expected, actual)

Checks the expected response codes against the actual response code. Use internally when implementing #perform.

Parameters:

  • expected (String, Fixnum, Array<String,Fixnum>) —

    the expected response code(s)

  • actual (String, Fixnum) —

    the received response code

Returns:

  • (Boolean) —

    whether the actual response code is acceptable given the expectations 



206
207
208
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 206

def valid_response?(expected, actual)
  Array(expected).map(&:to_i).include?(actual.to_i)
end

- (Object) verify_path!(resource)

Verifies that the specified resource is valid

Parameters:

  • resource (String, Array) —

    the resource specification

Raises:

  • (ArgumentError) —

    if the resource path is too short 



196
197
198
199
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 196

def verify_path!(resource)
  resource = Array(resource).flatten
  raise ArgumentError, t("resource_path_short") unless resource.length > 1 || resource.include?(@client.mapred)
end

- (Object) verify_path_and_body!(args)

Verifies that both a resource path and body are present in the arguments

Parameters:

  • args (Array) —

    the arguments to verify

Raises:

  • (ArgumentError) —

    if the body or resource is missing, or if the body is not a String 



181
182
183
184
185
186
187
188
189
190
191
 
# File 'riak-client/lib/riak/client/http_backend/transport_methods.rb', line 181

def verify_path_and_body!(args)
  body = args.pop
  begin
    verify_path!(args)
  rescue ArgumentError
    raise ArgumentError, t("path_and_body_required")
  end

  raise ArgumentError, t("request_body_type") unless String === body || body.respond_to?(:read)
  [args, body]
end