iron_mq 3.1.0 → 4.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ce00af7c17301f12971aae72083ba984718c11be
+  data.tar.gz: 42965aeda2d296af77c3125a663132c7beb0a450
+SHA512:
+  metadata.gz: 0f40c8007eba47c0982c091e9857b79ff2be1c112416a0094196601e3744be3516680a9f67f9c2f8ebb543d09a84418e20f5e12d1960c424d612a5413fcb0028
+  data.tar.gz: 162e8e411c13837561c0c8bc1e3a5bd874ccd5df8110e1ae0b832994df27560217192d3d1c8c2fc03fb295f23ca2ba344646e73bd77ebb86ea4e6c014f55d8f9

data/Gemfile.lock

@@ -1,32 +1,33 @@
 PATH
   remote: .
   specs:
-    iron_mq (3.1.0)
+    iron_mq (4.0.0)
       iron_core (>= 0.5.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     beanstalk-client (1.1.1)
-    concur (1.0.2)
-    ethon (0.5.7)
+    concur (2.0.0)
+    ethon (0.5.9)
       ffi (~> 1.2.0)
       mime-types (~> 1.18)
     ffi (1.2.1)
     iron_core (0.5.1)
       rest (>= 2.2.0)
-    mime-types (1.19)
-    minitest (4.4.0)
+    mime-types (1.21)
+    minitest (4.6.2)
     net-http-persistent (2.8)
+    quicky (0.4.0)
     rake (10.0.3)
     rest (2.2.0)
       net-http-persistent
       rest-client (>= 0.3.0)
     rest-client (1.6.7)
       mime-types (>= 1.16)
-    test-unit (2.5.3)
-    typhoeus (0.5.4)
-      ethon (~> 0.5.7)
+    test-unit (2.5.4)
+    typhoeus (0.6.1)
+      ethon (~> 0.5.9)
     uber_config (1.0.5)
 
 PLATFORMS
@@ -38,6 +39,7 @@ DEPENDENCIES
   iron_mq!
   minitest
   net-http-persistent
+  quicky
   rake
   test-unit
   typhoeus (>= 0.5.4)

data/README.md

@@ -6,113 +6,338 @@ much as possible so if you see an option in the API docs, you can use it in the
 
 http://dev.iron.io/mq/reference/api/
 
-Getting Started
-==============
+#Getting Started
 
 1\. Install the gem:
 
-    gem install iron_mq
+```ruby
+gem install iron_mq
+```
 
-2\. Setup your Iron.io credentials: http://dev.iron.io/articles/configuration/
+2\. Setup your Iron.io credentials: http://dev.iron.io/mq/reference/configuration/
 
 3\. Create an IronMQ client object:
 
-    @ironmq = IronMQ::Client.new()
+```ruby
+ironmq = IronMQ::Client.new
+```
 
 Or pass in credentials:
 
-    @ironmq = IronMQ::Client.new(token: MY_TOKEN, project_id: MY_PROJECT_ID)
-
+```ruby
+ironmq = IronMQ::Client.new(:token => "MY_TOKEN", :project_id => "MY_PROJECT_ID")
+```
 
-The Basics
-=========
+#The Basics
 
-**Get a Queue object**
+###Get a Queue Object
 
 You can have as many queues as you want, each with their own unique set of messages.
 
-    @queue = @ironmq.queue("my_queue")
-
-Now you can use it:
+```ruby
+queue = ironmq.queue("my_queue")
+```
 
-### Post a message on the queue:
+Now you can use it.
 
-    @queue.post("hello world!")
+### Post a Message on a Queue
 
-Post a message with options:
+Messages are placed on the queue in a FIFO arrangement.
+If a queue does not exist, it will be created upon the first posting of a message.
 
-    @queue.post("hello world!", delay: 3600)
+```ruby
+queue.post("hello world!")
+```
 
-### Get a message off the queue:
+### Retrieve Queue Information
 
-    msg = @queue.get()
-    puts msg.body
+```ruby
+queue.info # => {"id"=>"5127bf043264140e863e2283", "name"=>"my_queue", ...}
+queue.id   # => "5127bf043264140e863e2283"
+```
 
-Get a message with options:
+### Get a Message off a Queue
 
-    msg = @queue.get(timeout: 300)
+```ruby
+msg = queue.get
+msg.body # => "hello world!"
+```
 
-When you pop/get a message from the queue, it will NOT be deleted. It will eventually go back onto the queue after
-a timeout if you don't delete it (default timeout is 60 seconds).
+When you pop/get a message from the queue, it is no longer on the queue but it still exists within the system.
+You have to explicitly delete the message or else it will go back onto the queue after the `timeout`.
+The default `timeout` is 60 seconds. Minimal `timeout` is 30 seconds.
 
-### Delete a message from the queue:
+### Delete a Message from a Queue
 
-    msg.delete # or @queue.delete(msg.id)
+```ruby
+msg.delete
+# or
+queue.delete(msg.id)
+```
 
 Be sure to delete a message from the queue when you're done with it.
 
-### Poll for messages:
 
-    @queue.poll do |msg|
-      puts msg.body
-    end
+#Client
+
+`IronMQ::Client` is based on `IronCore::Client` and provides easy access to the queues and messages.
+
+```ruby
+ironmq = IronMQ::Client.new(:token => "MY_TOKEN", :project_id => "MY_PROJECT_ID")
+```
+
+### List Queues
+
+```ruby
+all_queues = ironmq.queues.list # => [#<IronMQ::Queue:...>, ...]
+# or
+all_queues = ironmq.queues.all  # => [#<IronMQ::Queue:...>, ...]
+```
+
+**Optional parameters:**
+
+* `page`: The 0-based page to view. The default is 0.
+* `per_page`: The number of queues to return per page. The default is 30, the maximum is 100.
+
+```ruby
+queues = ironmq.queues.all(:page => 1, :per_page => 10)
+```
+
+### Get Queue by Name
+
+```ruby
+queue = ironmq.queue "my_queue" # => #<IronMQ::Queue:...>
+```
+
+**Note:** if queue with desired name does not exist it returns fake queue.
+Queue will be created automatically on post of first message or queue configuration update.
+
+#Queues
+
+### Retrieve Queue Information
+
+```ruby
+info = queue.info # => {"id"=>"5127bf043264140e863e2283", "name"=>"my_queue", ...}
+```
+
+Shortcuts for `queue.info[key]`:
+
+```ruby
+id = queue.id # => "5127bf043264140e863e2283"
+# Does queue exists on server? Alias for `queue.id.nil?`
+is_new = queue.new? # => false
+
+size = queue.size # => 7
+name = queue.name # => "my_queue"
+overall_messages = queue.total_messages # => 13
+subscribers = queue.subscribers # => [{"url" => "http://..."}, ...]
+
+push_type = queue.push_type # => "multicast"
+# Does queue Push Queue? Alias for `queue.push_type.nil?`
+is_push_queue = queue.push_queue? # => true
+```
+
+**Warning:** to be sure configuration information is up-to-date
+client library call IronMQ API each time you request for any parameter except `queue.name`.
+In this case you may prefer to use `queue.info` to have `Hash` with all available info parameters.
+
+### Delete a Message Queue
+
+```ruby
+response = queue.delete_queue # => #<IronMQ::ResponseBase:...>
+```
+
+### Post Messages to a Queue
+
+**Single message:**
+
+```ruby
+response = queue.post("something helpful") # => #<IronMQ::ResponseBase:...>
+# or
+response = queue.post("with parameteres", :timeout => 300) # => #<IronMQ::ResponseBase:...>
+
+message_id = response.id # => "5847899158098068288"
+status_message = response.msg # => "Messages put on queue."
+http_code = response.code # => 200
+```
+
+**Multiple messages:**
+```ruby
+# [{:body => VALUE}, ...] format is required
+messages = [{:body => "first"}, {:body => "second"}]
+
+response = queue.post(messages) # => {"ids" => ["5847899158098068288", ...], "msg" => "Messages put on queue."}
+# or
+response = queue.post(messages, :timeout => 300) # => {"ids" => ["5847899158098068288", ...], "msg" => "Messages put on queue."}
+```
+
+**Optional parameters:**
+
+* `timeout`: After timeout (in seconds), item will be placed back onto queue.
+You must delete the message from the queue to ensure it does not go back onto the queue.
+ Default is 60 seconds. Minimum is 30 seconds. Maximum is 86,400 seconds (24 hours).
+
+* `delay`: The item will not be available on the queue until this many seconds have passed.
+Default is 0 seconds. Maximum is 604,800 seconds (7 days).
+
+* `expires_in`: How long in seconds to keep the item on the queue before it is deleted.
+Default is 604,800 seconds (7 days). Maximum is 2,592,000 seconds (30 days).
+
+### Get Messages from a Queue
+
+```ruby
+message = queue.get # => #<IronMQ::Message:...>
+
+# or N messages
+messages = queue.get(:n => 7) # => [#<IronMQ::Message:...>, ...]
+
+# or message by ID
+message = queue.get "5127bf043264140e863e2283" # => #<IronMQ::Message:...>
+```
+
+**Optional parameters:**
+
+* `n`: The maximum number of messages to get. Default is 1. Maximum is 100.
+
+* `timeout`: timeout: After timeout (in seconds), item will be placed back onto queue.
+You must delete the message from the queue to ensure it does not go back onto the queue.
+If not set, value from POST is used. Default is 60 seconds. Minimum is 30 seconds.
+Maximum is 86,400 seconds (24 hours).
+
+When `n` parameter is specified and greater than 1 method returns `Array` of `Queue`s.
+Otherwise, `Queue` object would be returned.
+
+### Touch a Message on a Queue
+
+Touching a reserved message extends its timeout by the duration specified when the message was created, which is 60 seconds by default.
+
+```ruby
+message = queue.get # => #<IronMQ::Message:...>
+
+message.touch # => #<IronMQ::ResponseBase:...>
+```
+
+### Release Message
+
+```ruby
+message = queue.get => #<IronMQ::Message:...>
+
+response = message.release # => #<IronMQ::ResponseBase:...>
+# or
+response = message.release(:delay => 42) # => #<IronMQ::ResponseBase:...>
+```
+
+**Optional parameters:**
+
+* `delay`: The item will not be available on the queue until this many seconds have passed.
+Default is 0 seconds. Maximum is 604,800 seconds (7 days).
+
+### Delete a Message from a Queue
+
+```ruby
+message = queue.get # => #<IronMQ::Queue:...>
+
+message.delete # => #<IronMQ::ResponseBase:...>
+# or
+queue.delete_message(message.id) # => #<IronMQ::ResponseBase:...>
+```
+
+### Peek Messages from a Queue
+
+Peeking at a queue returns the next messages on the queue, but it does not reserve them.
+
+```ruby
+message = queue.peek # => #<IronMQ::Message:...>
+# or multiple messages
+messages = queue.peek(:n => 13) # => [#<IronMQ::Message:...>, ...]
+```
+
+**Optional parameters:**
+
+* `n`: The maximum number of messages to peek. Default is 1. Maximum is 100.
+
+### Poll for Messages
+
+```ruby
+queue.poll { |msg| puts msg.body }
+```
 
 Polling will automatically delete the message at the end of the block.
 
-Queue Information
-=================
+### Clear a Queue
 
-    queue = @client.queue("my_queue")
-    puts "size: #{queue.size}"
+```ruby
+queue.clear # => #<IronMQ::ResponseBase:...>
+```
 
+#Push Queues
 
-Push Queues
-===========
+IronMQ push queues allow you to setup a queue that will push to an endpoint, rather than having to poll the endpoint. 
+[Here's the announcement for an overview](http://blog.iron.io/2013/01/ironmq-push-queues-reliable-message.html). 
 
-IronMQ push queues allow you to setup a queue that will push to an endpoint, rather than having to poll the endpoint.
+### Update a Message Queue
 
-LINK TO BLOG POST
+```ruby
+queue_info = queue.update(options) # => {"id"=>"5127bf043264140e863e2283", "name"=>"my_queue", ...}
+```
 
-### Set subscribers on a queue:
+**The following parameters are all related to Push Queues:**
 
-Subscribers can be any http endpoint. push_type is one of:
+* `subscribers`: An array of subscriber hashes containing a “url” field.
+This set of subscribers will replace the existing subscribers.
+To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint.
+See below for example json.
+* `push_type`: Either `multicast` to push to all subscribers or `unicast` to push to one and only one subscriber. Default is `multicast`.
+* `retries`: How many times to retry on failure. Default is 3.
+* `retries_delay`: Delay between each retry in seconds. Default is 60.
 
-- multicast - will push to all endpoints/subscribers
-- unicast - will push to one and only one endpoint/subscriber
+### Set Subscribers on a Queue
 
+Subscribers can be any HTTP endpoint. `push_type` is one of:
+
+* `multicast`: will push to all endpoints/subscribers
+* `unicast`: will push to one and only one endpoint/subscriber
 
 ```ruby
-subscribers = []
-subscribers << {url: "http://rest-test.iron.io/code/200?store=key1"}
-subscribers << {url: "http://rest-test.iron.io/code/200?store=key2"}
-res = @queue.update_queue(:subscribers => subscribers,
-                               :push_type => t)
+ptype = :multicast
+subscribers = [
+  {url: "http://rest-test.iron.io/code/200?store=key1"}
+  {url: "http://rest-test.iron.io/code/200?store=key2"}
+]
+
+queue.update(:subscribers => subscribers, :push_type => ptype)
 ```
 
-### Add/remove subscribers on a queue
+### Add/Remove Subscribers on a Queue
 
 ```ruby
-@queue.add_subscriber({url: "http://nowhere.com"})
-# Or to remove a subscriber:
-@queue.remove_subscriber({url: "http://nowhere.com"})
+queue.add_subscriber({url: "http://nowhere.com"})
+
+queue.remove_subscriber({url: "http://nowhere.com"})
 ```
 
-### Get message push status
+### Get Message Push Status
 
 After pushing a message:
 
 ```ruby
-queue.messages.get(m.id).subscribers
+subscribers = queue.get(msg.id).subscribers # => [#<IronMQ::Subscriber:...>, ...]
+# old syntax, still supported
+subscribers = queue.messages.get(msg.id).subscribers # => [#<IronMQ::Subscriber:...>, ...]
+
+subscribers.each { |ss| puts "#{ss.id}: #{(ss.code == 200) ? 'Success' : 'Fail'}" }
 ```
 
 Returns an array of subscribers with status.
+
+### Delete Message Push Status
+
+```ruby
+subscribers = queue.get(msg.id).subscribers # => [#<IronMQ::Subscriber:...>, ...]
+
+subscribers.each { |ss| ss.delete }
+```
+
+
+-------------
+© 2011 - 2013 Iron.io Inc. All Rights Reserved.

data/iron_mq.gemspec

@@ -1,8 +1,8 @@
 require File.expand_path('../lib/iron_mq/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Travis Reeder"]
-  gem.email         = ["travis@iron.io"]
+  gem.authors       = ["Yury Yantsevich", "Travis Reeder"]
+  gem.email         = ["yury@iron.io", "travis@iron.io"]
   gem.description   = "Ruby client for IronMQ by www.iron.io"
   gem.summary       = "Ruby client for IronMQ by www.iron.io"
   gem.homepage      = "https://github.com/iron-io/iron_mq_ruby"
@@ -26,6 +26,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "typhoeus", ">= 0.5.4"
   gem.add_development_dependency "concur"
   gem.add_development_dependency "net-http-persistent"
+  gem.add_development_dependency "quicky"
 
 end
 

data/lib/iron_mq/client.rb

@@ -16,11 +16,10 @@ module IronMQ
           :host => IronMQ::Client::AWS_US_EAST_HOST,
           :port => 443,
           :api_version => 1,
-          :user_agent => 'iron_mq_ruby-' + IronMQ::VERSION + ' (iron_core_ruby-' + IronCore.version + ')',
-          :queue_name => 'default'
+          :user_agent => 'iron_mq_ruby-' + 'very_new' + ' (iron_core_ruby-' + IronCore.version + ')'
       }
 
-      super('iron', 'mq', options, default_options, [:project_id, :token, :api_version, :queue_name])
+      super('iron', 'mq', options, default_options, [:project_id, :token, :api_version])
 
       IronCore::Logger.error 'IronMQ', "Token is not set", IronCore::Error if @token.nil?
 
@@ -35,19 +34,43 @@ module IronMQ
     end
 
     def base_url
-      super + @api_version.to_s + '/'
+      @base_url = "#{super}#{@api_version}/projects/#{@project_id}/queues"
     end
 
-    def queue(name)
-      return Queue.new(self, {"name" => name})
+    def queues_list(options = {})
+      response = parse_response(get('', options)) # GET base_url
+      # returns list of evaluated queues
+      response.each_with_object([]) { |q_info, ret| ret << Queue.new(self, q_info["name"]) }
     end
 
-    def messages
-      return Messages.new(self)
+    alias_method :list, :queues_list
+    alias_method :all, :queues_list
+
+    def queues_get(name)
+      Queue.new(self, name)
     end
 
+    alias_method :queue, :queues_get
+
+    # Backward compatibility for
+    #   client.queues.get(:name => "my_queue")
+    #   client.queues.get("name" => "my_queue")
+    def get(*args)
+      if args.size == 1 && args[0].is_a?(Hash)
+        queue_name = (args[0][:name] || args[0]["name"]).to_s
+        queue_name.empty? ? super : queues_get(queue_name)
+      else
+        super
+      end
+    end
+
+    # Backward compatibility, adds possibility to call
+    #   client.queues.all
+    #   client.queues.list
+    #   client.queues.queue(name)
     def queues
-      return Queues.new(self)
+      self
     end
   end
+
 end

data/lib/iron_mq/messages.rb

@@ -1,128 +1,45 @@
 require 'cgi'
 
 module IronMQ
-  class Messages
 
-    attr_reader :client, :queue
+  class Message < ResponseBase
+    attr_reader :queue
 
-    def initialize(client, queue=nil)
-      @client = client
+    def initialize(queue, data)
       @queue = queue
+      super(data, 200)
     end
 
-
-    def path(options={})
-      options[:queue_name] ||= ((@queue ? @queue.name : nil) || @client.queue_name)
-      options[:project_id] = @client.project_id
-      Messages.path(options)
+    def touch
+      call_api_and_parse_response(:post, "/touch")
     end
 
-    def self.path(options)
-      path = "#{Queues.path(options)}/messages"
-      if options[:msg_id]
-        path << "/#{options[:msg_id]}"
-      end
-      path
+    def release(options = {})
+      call_api_and_parse_response(:post, "/release", options)
     end
 
-    # options:
-    #  :queue_name => can specify an alternative queue name
-    #  :timeout => amount of time before message goes back on the queue
-    def get(options={})
-      if options.is_a?(String)
-        # assume it's an id
-        puts 'get_by_id'
-        return Message.new(self, {'id'=>options}, options)
-        #r = @client.get(path(:msg_id=>options))
-        #p r
-        #return r
-      end
-      res = @client.parse_response(@client.get(path(options), options))
-      ret = []
-      res["messages"].each do |m|
-        ret << Message.new(self, m, options)
-      end
-      if options[:n] || options['n']
-        return ret
-      else
-        if ret.size > 0
-          return ret[0]
-        else
-          return nil
-        end
-      end
-    end
+    # `options` was kept for backward compatibility
+    def subscribers(options = {})
+      response = call_api_and_parse_response(:get, "/subscribers", {}, false)
 
-    # options:
-    #  :queue_name => can specify an alternative queue name
-    #  :delay => time to wait before message will be available on the queue
-    #  :timeout => The time in seconds to wait after message is taken off the queue, before it is put back on. Delete before :timeout to ensure it does not go back on the queue.
-    #  :expires_in => After this time, message will be automatically removed from the queue.
-    def post(payload, options={})
-      batch = false
-      if payload.is_a?(Array)
-        batch = true
-        msgs = payload
-      else
-        options[:body] = payload
-        msgs = []
-        msgs << options
-      end
-      to_send = {}
-      to_send[:messages] = msgs
-      res = @client.parse_response(@client.post(path(options), to_send))
-      if batch
-        return res
-      else
-        return ResponseBase.new({"id"=>res["ids"][0], "msg"=>res["msg"]})
+      response['subscribers'].each_with_object([]) do |subscriber, ret|
+        ret << Subscriber.new(subscriber, self, options)
       end
     end
 
-    def delete(message_id, options={})
-      path2 = "#{self.path(options)}/#{message_id}"
-      res = @client.parse_response(@client.delete(path2))
-      return ResponseBase.new(res)
-    end
-
-    def release(message_id, options={})
-      path2 = "#{self.path(options)}/#{message_id}/release"
-      res = @client.parse_response(@client.post(path2, options))
-      return ResponseBase.new(res)
-    end
-
-  end
-
-  class Message < ResponseBase
-    attr_reader :messages
-
-    def initialize(messages, res, options={})
-      super(res)
-      @messages = messages
-      @options = options
-    end
-
-    def body
-      raw["body"]
-    end
-
     def delete
-      @messages.delete(self.id, @options)
+      call_api_and_parse_response(:delete)
     end
 
-    def release(options={})
-      options2 = options || {}
-      options2 = options.merge(@options) if @options
-      @messages.release(self.id, options2)
+    def call_api_and_parse_response(meth, ext_path = "", options = {}, instantiate = true)
+      @queue.call_api_and_parse_response(meth, "#{path(ext_path)}", options, instantiate)
     end
 
-    def subscribers(options={})
-      res = @messages.client.get(@messages.path(options.merge(:msg_id => id)) + "/subscribers", options)
-      res = @messages.client.parse_response(res)
-      ret = []
-      res['subscribers'].each do |m|
-        ret << Subscriber.new(m, self, options)
-      end
-      ret
+    private
+
+    def path(ext_path)
+      "/messages/#{id}#{ext_path}"
     end
   end
+
 end