rufus-jig¶ ↑

A HTTP client, greedy with JSON content, GETting conditionally.

Uses Typhoeus (github.com/typhoeus/typhoeus) or Patron (github.com/toland/patron) or em-http-request (github.com/igrigorik/em-http-request) whenever possible, and falls back to Net::HTTP if that’s all we have.

It depends on rufus-json (github.com/jmettraux/rufus-json) for JSON parsing and dumping.

This library also contains some CouchDB helpers.

To select a HTTP transport layer for rufus-jig, just make sure you have loaded the library before loading rufus-jig.

For Typhoeus:

require 'typhoeus'
require 'rufus/jig'

For Patron:

require 'patron'
require 'rufus/jig'

For em-http-request:

require 'em-http'
require 'rufus/jig'

For net-http-persistent:

require 'net/http/persistent'
require 'rufus/jig'

Let’s say we have an hypothetical document server.

getting…

require 'rufus/jig'

h = Rufus::Jig::Http.new('127.0.0.1', 4567)

p h.get('/document/xyz.json')
  #
  # => { "type" => "letter", "title" => "four birds" }
  #
  # if it's JSON, decodes it immediately

p h.get('/document/xyz.txt')
  #
  # => "letter:\n\nfour birds"

j = h.get('/document', :content_type => 'application/json')
j = h.get('/document', :content_type => :json)
  #
  # 'Accepts' JSON

posting…

p h.post(
  '/documents', '<doc>four birds</doc>', :content_type => 'application/xml')
  #
  # => "created."

For the real thing : github.com/couchrest/couchrest There is also the excellent : github.com/langalex/couch_potato

The class Rufus::Jig::Couch provides a get/put/delete trio that is couch-oriented. Json encoding/decoding is automatically handled as well as

put and delete return nil in case of success and true (conflict) or and exception else.

require 'rufus/jig'

c = Rufus::Jig::Couch.new('127.0.0.1', 5984, 'my_couch_db')

c.put('_id' => 'coffee0', 'category' => 'espresso')
c.put('_id' => 'coffee1', 'category' => 'instantaneous')

doc0 = c.get('coffee0')
doc1 = c.get('coffee1')

c.delete(doc0)

doc1['category'] => 'instant'
c.put(doc1)

c.delete(doc1['_id'], doc1['_rev'])

# ...

c.attach(
  doc0, 'picture', File.read('espresso.jpg'), :content_type => 'image/jpeg')
    # or
c.attach(
  doc0['_id'], doc0['_rev'], 'picture', File.read('espresso.jpg'), :content_type => 'image/jpeg')

picture = c.get('coffe0/picture')

c.detach('coffee0', '1-x-newrevision-whatever', 'picture')

there is also

c.all(:skip => 100, :limit => 100)
c.all(:keys => %w[ doc0 doc1 doc3 ])
  # grabbing multiple docs in one go

c.query('_design/my_design_doc/_view/my_view')
c.query('my_design_doc:my_view')
  # 'querying' a view

c.query_for_docs('my_design_doc:my_view')
  # querying for documents

bulk operations

docs = c.all(:keys => %w[ doc0 doc1 doc3 ])
c.bulk_delete(docs)
  # deleting in one go

docs = c.all(:keys => %w[ doc0 doc1 doc3 ])
docs.each { |doc| doc['status'] = 'copied' }
c.bulk_put(docs)
  # updating in one go

Continuous feed with a 20s heartbeat :

db.on_change do |doc_id, deleted|
  puts "doc #{doc_id} has been #{deleted ? 'deleted' : 'changed'}"
end

db.on_change do |doc_id, deleted, doc|
  puts "doc #{doc_id} has been #{deleted ? 'deleted' : 'changed'}"
  p doc
end

Please note the 3 param block, it includes the changed document (Note : this only work with CouchDB >= 0.11).

This is a blocking method (one may want to wrap it in a thread).

To dump the current content of the Couch database to a ‘backup.dump’ file, one document per line, attachments included:

db.dump("backup.dump")

To load that file later on (or somewhere else):

db.load("backup.dump")

To wipe clean and then load:

db.load("backup.dump", :overwrite => true)

rufus.rubyforge.org/rufus-jig/

rake

or

rspec spec/

tests all (plain jig and CouchDB).

rspec spec/jig

only tests the plain jig stuff.

rspec spec/couch

only tests the CouchDB stuff.

By default net/http is used. To test with another HTTP lib :

JIG_LIB=typhoeus rspec spec/

You can specify patron, em, netp or net. Netp corresponds to seattlerb.rubyforge.org/net-http-persistent/

The specs require the json and sinatra gems. You can spot issues in the file server.log (created when running specs).

• the EM based client cannot deal with non-ASCII paths

On the rufus-ruby list :

groups.google.com/group/rufus-ruby

github.com/jmettraux/rufus-jig/issues

irc.freenode.net #ruote

rufus.rubyforge.org

• John Mettraux, jmettraux.wordpress.com/

• Kenneth Kalmer, www.opensourcery.co.za/

• Torsten Schoenebaum, github.com/tosch/

• Marcello Barnaba, github.com/vjt/

MIT