Class: Riak::Client

Inherits:
Object show all
Includes:
Util::Escape, Util::Translation
Defined in:
riak-client/lib/riak/client.rb,
riak-client/lib/riak/search.rb,
riak-client/lib/riak/client/pump.rb,
riak-client/lib/riak/client/curb_backend.rb,
riak-client/lib/riak/client/http_backend.rb,
riak-client/lib/riak/client/excon_backend.rb,
riak-client/lib/riak/client/net_http_backend.rb,
riak-client/lib/riak/client/beefcake/messages.rb,
riak-client/lib/riak/client/protobuffs_backend.rb,
riak-client/lib/riak/client/beefcake/object_methods.rb,
riak-client/lib/riak/client/http_backend/key_streamer.rb,
riak-client/lib/riak/client/http_backend/configuration.rb,
riak-client/lib/riak/client/http_backend/object_methods.rb,
riak-client/lib/riak/client/beefcake_protobuffs_backend.rb,
riak-client/lib/riak/client/http_backend/request_headers.rb,
riak-client/lib/riak/client/http_backend/transport_methods.rb

Overview

A client connection to Riak.

Defined Under Namespace

Classes: CurbBackend, ExconBackend, HTTPBackend, NetHTTPBackend, ProtobuffsBackend

Constant Summary

MAX_CLIENT_ID =

When using integer client IDs, the exclusive upper-bound of valid values. 

4294967296
PROTOCOLS =

Array of valid protocols 

%w[http https pbc]
HOST_REGEX =

Regexp for validating hostnames, lifted from uri.rb in Ruby 1.8.6 

/^(?:(?:(?:[a-zA-Z\d](?:[-a-zA-Z\d]*[a-zA-Z\d])?)\.)*(?:[a-zA-Z](?:[-a-zA-Z\d]*[a-zA-Z\d])?)\.?|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[(?:(?:[a-fA-F\d]{1,4}:)*(?:[a-fA-F\d]{1,4}|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})|(?:(?:[a-fA-F\d]{1,4}:)*[a-fA-F\d]{1,4})?::(?:(?:[a-fA-F\d]{1,4}:)*(?:[a-fA-F\d]{1,4}|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}))?)\])$/n
VALID_OPTIONS = 
[:protocol, :host, :port, :http_port, :pb_port, :prefix, :client_id, :mapred, :luwak, :http_backend, :protobuffs_backend, :ssl, :basic_auth]

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods included from Util::Escape

#escape, #unescape

Methods included from Util::Translation

#i18n_scope, #t

Constructor Details

- (Client) initialize(options = {})

Creates a client connection to Riak

Parameters:

  • options (Hash) (defaults to: {}) —

    configuration options for the client

Options Hash (options):

  • :host (String) — default: '127.0.0.1' —

    The host or IP address for the Riak endpoint

  • :port (Fixnum) — default: 8098 —

    The port of the Riak HTTP endpoint

  • :prefix (String) — default: '/riak/' —

    The URL path prefix to the main HTTP endpoint

  • :mapred (String) — default: '/mapred' —

    The path to the map-reduce HTTP endpoint

  • :client_id (Fixnum, String) — default: rand(MAX_CLIENT_ID) —

    The internal client ID used by Riak to route responses

  • :http_backend (String, Symbol) — default: :NetHTTP —

    which HTTP backend to use

  • :protobuffs_backend (String, Symbol) — default: :Beefcake —

    which Protocol Buffers backend to use

Raises:

  • (ArgumentError) —

    raised if any invalid options are given 



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'riak-client/lib/riak/search.rb', line 29

def initialize(options={})
  unless (options.keys - VALID_OPTIONS).empty?
    raise ArgumentError, t("invalid_options")
  end
  self.protocol           = options[:protocol]           || "http"
  self.ssl                = options[:ssl]                if options[:ssl]
  self.host               = options[:host]               || "127.0.0.1"
  self.http_port          = options[:http_port]          || 8098
  self.pb_port            = options[:pb_port]            || 8087
  self.port               = options[:port]               if options[:port]
  self.prefix             = options[:prefix]             || "/riak/"
  self.mapred             = options[:mapred]             || "/mapred"
  self.luwak              = options[:luwak]              || "/luwak"
  self.http_backend       = options[:http_backend]       || :NetHTTP
  self.protobuffs_backend = options[:protobuffs_backend] || :Beefcake
  self.basic_auth         = options[:basic_auth]         if options[:basic_auth]
  self.client_id          = options[:client_id]          if options[:client_id]
end

Instance Attribute Details

- (String) basic_auth

The user:pass for http basic authentication

Returns:

  • (String) —

    The user:pass for http basic authentication 



59
60
61
 
# File 'riak-client/lib/riak/client.rb', line 59

def basic_auth
  @basic_auth
end

- (String) client_id

The internal client ID used by Riak to route responses

Returns:

  • (String) —

    The internal client ID used by Riak to route responses 



65
66
67
 
# File 'riak-client/lib/riak/client.rb', line 65

def client_id
  @client_id ||= backend.respond_to?(:get_client_id) ? backend.get_client_id : make_client_id
end

- (String) host

The host or IP address for the Riak endpoint

Returns:

  • (String) —

    The host or IP address for the Riak endpoint 



50
51
52
 
# File 'riak-client/lib/riak/client.rb', line 50

def host
  @host
end

- (Symbol) http_backend

The HTTP backend/client to use

Returns:

  • (Symbol) —

    The HTTP backend/client to use 



81
82
83
 
# File 'riak-client/lib/riak/client.rb', line 81

def http_backend
  @http_backend
end

- (Fixnum) http_port

The HTTP(S) port for the Riak endpoint

Returns:

  • (Fixnum) —

    The HTTP(S) port for the Riak endpoint 



53
54
55
 
# File 'riak-client/lib/riak/client.rb', line 53

def http_port
  @http_port
end

- (String) luwak

The URL path to the luwak HTTP endpoint

Returns:

  • (String) —

    The URL path to the luwak HTTP endpoint 



78
79
80
 
# File 'riak-client/lib/riak/client.rb', line 78

def luwak
  @luwak
end

- (String) mapred

The URL path to the map-reduce HTTP endpoint

Returns:

  • (String) —

    The URL path to the map-reduce HTTP endpoint 



75
76
77
 
# File 'riak-client/lib/riak/client.rb', line 75

def mapred
  @mapred
end

- (Fixnum) pb_port

The Protocol Buffers port for the Riak endpoint

Returns:

  • (Fixnum) —

    The Protocol Buffers port for the Riak endpoint 



56
57
58
 
# File 'riak-client/lib/riak/client.rb', line 56

def pb_port
  @pb_port
end

- (String) prefix

The URL path prefix to the “raw” HTTP endpoint

Returns:

  • (String) —

    The URL path prefix to the “raw” HTTP endpoint 



72
73
74
 
# File 'riak-client/lib/riak/client.rb', line 72

def prefix
  @prefix
end

- (Symbol) protobuffs_backend

The Protocol Buffers backend/client to use

Returns:

  • (Symbol) —

    The Protocol Buffers backend/client to use 



84
85
86
 
# File 'riak-client/lib/riak/client.rb', line 84

def protobuffs_backend
  @protobuffs_backend
end

- (String) protocol

The protocol to use for the Riak endpoint

Returns:

  • (String) —

    The protocol to use for the Riak endpoint 



47
48
49
 
# File 'riak-client/lib/riak/client.rb', line 47

def protocol
  @protocol
end

- (String) solr

The URL path prefix to the Solr HTTP endpoint

Returns:

  • (String) —

    The URL path prefix to the Solr HTTP endpoint 



24
25
26
 
# File 'riak-client/lib/riak/search.rb', line 24

def solr
  @solr
end

- (Object) ssl=(value) (writeonly)

Enables or disables SSL on the client to be utilized by the HTTP Backends 



69
70
71
72
 
# File 'riak-client/lib/riak/client.rb', line 69

def ssl=(value)
  @ssl_options = Hash === value ? value : {}
  value ? ssl_enable : ssl_disable
end

- (Hash|nil) ssl_options (readonly)

The SSL options that get built when using SSL

Returns:

  • (Hash|nil) —

    The SSL options that get built when using SSL 



62
63
64
 
# File 'riak-client/lib/riak/client.rb', line 62

def ssl_options
  @ssl_options
end

Instance Method Details

- (HTTPBackend, ProtobuffsBackend) backend

Returns a backend for operations that are protocol-independent. You can change which type of backend is used by setting the #protocol.

Returns:



273
274
275
276
277
278
279
280
 
# File 'riak-client/lib/riak/client.rb', line 273

def backend
  @backend ||= case @protocol.to_s
               when /https?/i
                 http
               when /pbc/i
                 protobuffs
               end
end

- (Bucket) bucket(name, options = {}) Also known as: []

Retrieves a bucket from Riak.

Parameters:

  • bucket (String) —

    the bucket to retrieve

  • options (Hash) (defaults to: {}) —

    options for retrieving the bucket

Options Hash (options):

  • :keys (Boolean) — default: false whether to retrieve the bucket keys —

    false whether to retrieve the bucket keys

  • :props (Boolean) — default: false —

    whether to retreive the bucket properties

Returns:

  • (Bucket) —

    the requested bucket 



294
295
296
297
298
299
300
301
302
303
 
# File 'riak-client/lib/riak/client.rb', line 294

def bucket(name, options={})
  unless (options.keys - [:keys, :props]).empty?
    raise ArgumentError, "invalid options"
  end
  @bucket_cache ||= {}
  (@bucket_cache[name] ||= Bucket.new(self, name)).tap do |b|
    b.props if options[:props]
    b.keys  if options[:keys]
  end
end

- (Array<Bucket>) buckets Also known as: list_buckets

Note:

This is an expensive operation and should be used only in development.

Lists buckets which have keys stored in them.

Returns:



310
311
312
 
# File 'riak-client/lib/riak/client.rb', line 310

def buckets
  backend.list_buckets.map {|name| Bucket.new(self, name) }
end

- (Object) delete_file(filename)

Deletes a file stored via the “Luwak” interface

Parameters:

  • filename (String) —

    the key/filename to delete 



368
369
370
371
 
# File 'riak-client/lib/riak/client.rb', line 368

def delete_file(filename)
  http.delete([204,404], luwak, escape(filename))
  true
end

- (true, false) file_exists?(key) Also known as: file_exist?

Checks whether a file exists in “Luwak”.

Parameters:

  • key (String) —

    the key to check

Returns:

  • (true, false) —

    whether the key exists in “Luwak“ 



376
377
378
379
 
# File 'riak-client/lib/riak/client.rb', line 376

def file_exists?(key)
  result = http.head([200,404], luwak, escape(key))
  result[:code] == 200
end

- (IO?) get_file(filename) {|chunk| ... }

Retrieves a large file/IO object from Riak via the “Luwak” interface. Streams the data to a temporary file unless a block is given.

Parameters:

  • filename (String) —

    the key/filename for the object

Yields:

  • (chunk) —

    stream contents of the file through the block. Passing the block will result in nil being returned from the method.

Yield Parameters:

  • chunk (String) —

    a single chunk of the object’s data

Returns:

  • (IO, nil) —

    the file (also having content_type and original_filename accessors). The file will need to be reopened to be read. nil will be returned if a block is given. 



348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'riak-client/lib/riak/client.rb', line 348

def get_file(filename, &block)
  if block_given?
    http.get(200, luwak, escape(filename), &block)
    nil
  else
    tmpfile = LuwakFile.new(escape(filename))
    begin
      response = http.get(200, luwak, escape(filename)) do |chunk|
        tmpfile.write chunk
      end
      tmpfile.content_type = response[:headers]['content-type'].first
      tmpfile
    ensure
      tmpfile.close
    end
  end
end

- (HTTPBackend) http

Automatically detects and returns an appropriate HTTP backend. The HTTP backend is used internally by the Riak client, but can also be used to access the server directly.

Returns:



241
242
243
244
245
246
247
248
249
250
 
# File 'riak-client/lib/riak/client.rb', line 241

def http
  @http ||= begin
              klass = self.class.const_get("#{@http_backend}Backend")
              if klass.configured?
                klass.new(self)
              else
                raise t('http_configuration', :backend => @http_backend)
              end
            end
end

- (Object) index(index, *docs) - (Object) index(*docs) Also known as: add_doc

Adds documents to a search index via the Solr interface.

Overloads:

  • - (Object) index(index, *docs)

    Adds documents to the specified search index

    Parameters:

    • index (String) —

      the index in which to add/update the given documents

    • docs (Array<Hash>) —

      unnested document hashes, with one key per field

  • - (Object) index(*docs)

    Adds documents to the default search index

    Parameters:

    • docs (Array<Hash>) —

      unnested document hashes, with one key per field

Raises:

  • (ArgumentError) —

    if any documents don’t include ‘id’ key 



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'riak-client/lib/riak/search.rb', line 71

def index(*args)
  index = args.shift if String === args.first # Documents must be hashes of fields
  raise ArgumentError.new(t("search_docs_require_id")) unless args.all? {|d| d.key?("id") || d.key?(:id) }
  xml = Builder::XmlMarkup.new
  xml.add do
    args.each do |doc|
      xml.doc do
        doc.each do |k,v|
          xml.field('name' => k.to_s) { xml.text!(v.to_s) }
        end
      end
    end
  end
  path = [solr, index, "update", xml.target!, {'Content-Type' => 'text/xml'}].compact
  http.post(200, *path)
  true
end

- (String) inspect

A representation suitable for IRB and debugging output.

Returns:

  • (String) —

    A representation suitable for IRB and debugging output. 



383
384
385
 
# File 'riak-client/lib/riak/client.rb', line 383

def inspect
  "#<Riak::Client #{protocol}://#{host}:#{protocol == 'pbc' ? pb_port : http_port}>"
end

- (true, false) ping

Pings the Riak server to check for liveness.

Returns:

  • (true, false) —

    whether the Riak server is alive and reachable 



284
285
286
 
# File 'riak-client/lib/riak/client.rb', line 284

def ping
  backend.ping
end

- (Fixnum) port

Deprecated.

Ports for HTTP(S) and Protocol Buffers are segregated. Use #http_port or #pb_port.

The port of the Riak endpoint

Returns:

  • (Fixnum) —

    The port of the Riak endpoint 



160
161
162
163
164
165
166
167
168
 
# File 'riak-client/lib/riak/client.rb', line 160

def port
  warn(t('deprecated.port', :backtrace => caller.join("\n")))
  case protocol
  when /http/i
    http_port
  when /pbc/i
    pb_port
  end
end

- (Fixnum) port=(value)

Deprecated.

Ports for HTTP(S) and Protocol Buffers are segregated. Use #http_port= or #pb_port=.

Set the port number of the Riak endpoint. This must be an integer between 0 and 65535.

Parameters:

  • value (Fixnum) —

    The port number of the Riak endpoint

Returns:

  • (Fixnum) —

    the assigned port number

Raises:

  • (ArgumentError) —

    if an invalid port number is given 



177
178
179
180
181
182
183
184
185
186
 
# File 'riak-client/lib/riak/client.rb', line 177

def port=(value)
  warn(t('deprecated.port', :backtrace => caller[0..2].join("\n    ")))
  raise ArgumentError, t("port_invalid") unless (0..65535).include?(value)
  case protocol
  when /http/i
    self.http_port = value
  when /pbc/i
    self.pb_port = value
  end
end

- (ProtobuffsBackend) protobuffs

Automatically detects and returns an appropriate Protocol Buffers backend. The Protocol Buffers backend is used internally by the Riak client but can also be used to access the server directly.

Returns:



258
259
260
261
262
263
264
265
266
267
 
# File 'riak-client/lib/riak/client.rb', line 258

def protobuffs
  @protobuffs ||= begin
                    klass = self.class.const_get("#{@protobuffs_backend}ProtobuffsBackend")
                    if klass.configured?
                      klass.new(self)
                    else
                      raise t('protobuffs_configuration', :backend => @protobuffs_backend)
                    end
                  end
end

- (Object) remove(index, specs) - (Object) remove(specs) Also known as: delete_doc, deindex

Removes documents from a search index via the Solr interface.

Overloads:

  • - (Object) remove(index, specs)

    Removes documents from the specified index

    Parameters:

    • index (String) —

      the index from which to remove documents

    • specs (Array<Hash>) —

      the specificaiton of documents to remove (must contain ‘id’ or ‘query’ keys)

  • - (Object) remove(specs)

    Removes documents from the default index

    Parameters:

    • specs (Array<Hash>) —

      the specification of documents to remove (must contain ‘id’ or ‘query’ keys)

Raises:

  • (ArgumentError) —

    if any document specs don’t include ‘id’ or ‘query’ keys 



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'riak-client/lib/riak/search.rb', line 99

def remove(*args)
  index = args.shift if String === args.first
  raise ArgumentError.new(t("search_remove_requires_id_or_query")) unless args.all? { |s|
    s.include? :id or 
    s.include? 'id' or 
    s.include? :query or 
    s.include? 'query'
  }
  xml = Builder::XmlMarkup.new
  xml.delete do
    args.each do |spec|
      spec.each do |k,v|
        xml.tag!(k.to_sym, v)
      end
    end
  end
  path = [solr, index, "update", xml.target!, {'Content-Type' => 'text/xml'}].compact
  http.post(200, *path)
  true
end

- (Hash) search(index, query, options = {}) - (Hash) search(query, options = {}) Also known as: select

Performs a search via the Solr interface.

Overloads:

  • - (Hash) search(index, query, options = {})

    Parameters:

    • index (String) —

      the index to query on

    • query (String) —

      a Lucene query string

  • - (Hash) search(query, options = {})

    Queries the default index

    Parameters:

    • query (String) —

      a Lucene query string

Parameters:

  • options (Hash) —

    extra options for the Solr query

Returns:

  • (Hash) —

    the query result, containing the ‘responseHeaders’ and ‘response’ keys 



49
50
51
52
53
54
55
56
57
58
59
 
# File 'riak-client/lib/riak/search.rb', line 49

def search(*args)
  options = args.extract_options!
  index, query = args[-2], args[-1]  # Allows nil index, while keeping it as first argument
  path = [solr, index, "select", {"q" => query, "wt" => "json"}.merge(options.stringify_keys), {}].compact
  response = http.get(200, *path)
  if response[:headers]['content-type'].include?("application/json")
    JSON.parse(response[:body])
  else
    response[:body]
  end
end

- (Boolean) ssl_enabled?

Checks if SSL is enabled for HTTP

Returns:



233
234
235
 
# File 'riak-client/lib/riak/client.rb', line 233

def ssl_enabled?
  protocol == 'https' || @ssl_options.present?
end

- (String) store_file(filename, content_type, data) - (String) store_file(content_type, data)

Stores a large file/IO-like object in Riak via the “Luwak” interface.

Overloads:

  • - (String) store_file(filename, content_type, data)

    Stores the file at the given key/filename

    Parameters:

    • filename (String) —

      the key/filename for the object

    • content_type (String) —

      the MIME Content-Type for the data

    • data (IO, String) —

      the contents of the file

  • - (String) store_file(content_type, data)

    Stores the file with a server-determined key/filename

    Parameters:

    • content_type (String) —

      the MIME Content-Type for the data

    • data (String, #read) —

      the contents of the file

Returns:

  • (String) —

    the key/filename where the object was stored 



326
327
328
329
330
331
332
333
334
335
 
# File 'riak-client/lib/riak/client.rb', line 326

def store_file(*args)
  data, content_type, filename = args.reverse
  if filename
    http.put(204, luwak, escape(filename), data, {"Content-Type" => content_type})
    filename
  else
    response = http.post(201, luwak, data, {"Content-Type" => content_type})
    response[:headers]["location"].first.split("/").last
  end
end