spacebunny 1.0.0

data/examples/device/publish_with_confirm.rb

@@ -0,0 +1,85 @@
+require 'spacebunny'
+require 'json'
+
+# Prerequisites: you have created a device through the SpaceBunny's web interface. You also have a 'data' channel (name
+# is not mandatory, but we'll use this for our example). You have also enabled 'data' channel for the device. See our
+# Getting Started [link] for a quick introduction to SpaceBunny's base concepts.
+
+# Once everything is set up get your device's API key from SpaceBunny's web application: on the web interface,
+# go to devices section and create or pick an existing device. Click on the 'SHOW CONFIGURATION' link, copy the API key
+# and substitute it here:
+
+device_key = 'your_awesome_device_key'
+
+# Let's instantiate a SpaceBunny client, providing the device's API key, that's the fastest and simplest method
+# to create a new client. If, for some reason, you need to customize the settings, take a look at
+# examples/manual_config.rb for an example of connection settings customization.
+
+dev = Spacebunny::Device.new key
+
+# An equivalent method for providing the API key is through options: Spacebunny::Device.new(key: key)
+
+# We need to call 'connect' in order to open the communication with SpaceBunny platform
+
+dev.connect
+
+# At this point the SDK is auto-configured and ready to use.
+# Configurations are automatically lazy-fetched by the SDK itself when calling 'connect'.
+
+# PUBLISHING MESSAGES WITH CONFIRM
+
+# As said in the prerequisites, we'll assume that 'data' channel is enabled for your device.
+# If you're in doubt, please check that this is true through SpaceBunny's web interface, by clicking on the device
+# 'edit' (pencil icon) and verifying that 'data' channel is present and enabled for this device. Take a look at Getting
+# Started [link] for a quick introduction to SpaceBunny's base concepts.
+
+# Let's publish, for instance, some JSON. Payload can be everything you want, SpaceBunny does not impose any constraint
+# on format or content of payload.
+
+# Publish one message every second for a minute.
+count = 0
+5.times do
+  # Generate some random data
+  payload = {
+      count: count,
+      greetings: 'Hello, World!',
+      temp: rand(20.0..25.0),
+      foo: rand(100..200)
+  }.to_json
+
+  # Hint: the channel name can also be a string e.g: 'data'
+  dev.publish :data, payload, with_confirm: true
+
+  # 'publish' takes two mandatory arguments (channel's name and payload) and a variety of options: one of these options is
+  # the 'with_confirm' flag: when set to true this requires SpaceBunny's platform to confirm the receipt of the message.
+  # This is useful when message delivery assurance is mandatory for your use case.
+  # Take a look at SDK's documentation for further details.
+
+  # Give some feedback on what has been published
+  puts "Published #{payload}"
+
+  # Take a nap...
+  sleep 1
+  # Update counter
+  count += 1
+end
+
+# Wait for publish confirmations: wait for SpaceBunny to confirm that all published messages have been
+# accepted.
+result = dev.wait_for_publish_confirms
+
+# 'wait_for_publish_confirms' waits for every message published, regardless the channel, blocking execution until
+# every confirm (or nack) has been received. 'wait_for_publish_confirms' returns an Hash whose keys are the channels'
+# names on which you have published some message.
+# For instance:
+
+result.each do |channel, status|
+  # If result is false, some message has been nacked. A message may be nacked by SpaceBunny's platform if, for some
+  # reason, it cannot take responsibility for the message
+  unless status[:all_confirmed]
+    # do something with nacked messages
+    status[:nacked_set].each do |nacked_message|
+      # do something with nacked message
+    end
+  end
+end

data/examples/device/receive_messages.rb

@@ -0,0 +1,109 @@
+require 'spacebunny'
+require 'json'
+
+# Prerequisites: you have created a device through the SpaceBunny's web interface. See our Getting Started [link]
+# for a quick introduction to SpaceBunny's base concepts.
+
+# Once everything is set up get your device's API key from SpaceBunny's web application: on the web interface,
+# go to devices section and create or pick an existing device. Click on the 'SHOW CONFIGURATION' link, copy the API key
+# and substitute it here:
+
+key = 'your_awesome_device_key'
+
+# Let's instantiate a SpaceBunny (AMQP by default) client, providing the device's API key, that's the fastest and simplest method
+# to create a new client. If, for some reason, you need to customize the settings, take a look at
+# examples/manual_config.rb for an example of connection settings customization.
+
+dev = Spacebunny::Device.new key
+
+# An equivalent method for providing the API key is through options: Spacebunny::Device.new(key: key)
+
+# We need to call 'connect' in order to open the communication with SpaceBunny platform
+
+dev.connect
+
+# At this point the SDK is auto-configured and ready to use.
+# Configurations are automatically lazy-fetched by the SDK itself when calling 'connect'.
+
+
+# RECEIVING MESSAGES
+
+puts "Waiting for messages. Publish some from SpaceBunny's web interface to try this out:"
+
+# Receiving messages is trivial:
+
+dev.inbox(wait: true, ack: :auto) do |message|
+  puts "Received: #{message.payload}"
+end
+
+# A Ruby block must be supplied to the 'inbox' method. It yields a Device::Message object containing
+# all the useful data:
+#
+# dev.inbox do |message|
+#   puts "payload: #{message.payload}"
+#
+#   # metadata that can be accessed as an Hash.
+#   # metadata[:headers] contains the message's headers for instance
+#   puts "metadata: #{message.metadata}"
+#
+#   # sender_id (id of the device that sent the message)
+#   puts "sender_id: #{message.sender_id}"
+#
+#   # channel name i.e. the name of the channel on which the message has been published
+#   puts "channel_name: #{message.channel_name}"
+#
+#   # Connection and other low level info
+#   puts "delivery_info: #{message.delivery_info}"
+# end
+
+# inbox method's options:
+# 'wait' (default false) causes the script to wait forever on the receive block. This is useful
+# for 'read-only' scripts like workers or similar.
+# 'ack' option can have two values: :manual (default) or :auto. When :manual you are responsible to ack the messages,
+# for instance:
+#
+# dev.inbox(block: true, ack: :manual) do |message|
+#   puts "Received: #{message.payload}"
+#   message.ack
+# end
+# When 'ack' is :auto then the SDK will automatically ack the messages when the code provided in the inbox block
+# has terminated execution. This behaviour is useful in cases in which the code executed inside the inbox block
+# will always lead to an acked message (no matter the operations' result).
+# If your code can lead to errors and, for instance, the message must be reprocessed, you must use :manual ack
+# and manually call 'ack' as seen in the example above.
+# Call 'nack' in case the message needs to be reprocessed and it will remain on SpaceBunny until successfully
+# acked. For instance:
+
+# dev.inbox(block: true, ack: :manual) do |message|
+#   puts message.payload
+#
+#   begin
+#     # Do something nasty...
+#     raise
+#
+#     # If everything is ok, ack
+#     # (note that this code will never be reached)
+#     message.ack
+#   rescue Exception => e
+#     message.nack
+#   end
+# end
+
+# ack options are:
+#   multiple: false   ack multiple messages at once. Ack all the unacked
+#                     messages up to the current one
+
+# nack options are:
+#   multiple: false   nack multiple messages at once. Nack all the messages up
+#                     to the current one
+#   requeue: false    requeue message. If false (default), the message will be
+#                     discarded by SpaceBunny. If true message will made
+#                     requeued and made available for delivery again
+
+
+# Other 'inbox' options:
+# 'discard_from_api' (default false) causes the SDK to filter out messages published through APIs (or WEB UI) or
+# generally sent directly through SpaceBunny's platform.
+# 'discard_mine' (default false) causes the SKD to filter out auto-messages i.e. messages sent from this device
+# and, for some reason, returned to the sender. This can happen in some particular situation such as when using m2m
+# groups.

data/examples/device/tls_connection.rb

@@ -0,0 +1,65 @@
+require 'spacebunny'
+require 'json'
+
+# Prerequisites: you have created a device through the Space Bunny's web interface. You also have a 'data' channel (name
+# is not mandatory, but we'll use this for our example). You have also enabled 'data' channel for the device. See our
+# Getting Started [link] for a quick introduction to Space Bunny's base concepts.
+
+# Once everything is set up get your device's API key from Space Bunny's web application: on the web interface,
+# go to devices section and create or pick an existing device. Click on the 'SHOW CONFIGURATION' link, copy the API key
+# and substitute it here:
+
+device_key = 'your_awesome_device_key'
+
+# Let's instantiate a Space Bunny client, providing the device's API key, that's the fastest and simplest method
+# to create a new client.
+# Provide `tls: true` to use instantiate a tls-secured connection
+
+dev = Spacebunny::Device.new device_key, tls: true
+
+# An equivalent method for providing the API key is through options: Spacebunny::Device.new(key: key)
+
+# We need to call 'connect' in order to open the communication with Space Bunny platform
+
+dev.connect
+
+# At this point the SDK is auto-configured and ready to use.
+# Configurations are automatically lazy-fetched by the SDK itself when calling 'connect'.
+
+# PUBLISHING MESSAGES
+
+# As said in the prerequisites, we'll assume that 'data' channel is enabled for your device.
+# If you're in doubt, please check that this is true through Space Bunny's web interface, by clicking on the device
+# 'edit' (pencil icon) and verifying that 'data' channel is present and enabled for this device. Take a look at Getting
+# Started [link] for a quick introduction to Space Bunny's base concepts.
+
+# Let's publish, for instance, some JSON. Payload can be everything you want, Space Bunny does not impose any constraint
+# on format or content of payload.
+
+# Publish one message every second for a minute.
+count = 0
+60.times do
+  # Generate some random data
+  payload = {
+      count: count,
+      greetings: "Hello from #{dev.name}!",
+      temp: rand(20.0..25.0),
+      foo: rand(100..200)
+  }.to_json
+
+  # Hint: the channel name can also be a string e.g: 'data'
+  dev.publish :data, payload
+
+  # 'publish' takes two mandatory arguments (channel's name and payload) and a variety of options: one of these options is
+  # the 'with_confirm' flag: when set to true this requires Space Bunny's platform to confirm the receipt of the message.
+  # This is useful when message delivery assurance is mandatory for your use case.
+  # Take a look at SDK's documentation for further details.
+
+  # Give some feedback on what has been published
+  puts "Published #{payload}"
+
+  # Take a nap...
+  sleep 1
+  # Update counter
+  count += 1
+end

data/examples/live_stream/receive_messages.rb

@@ -0,0 +1,128 @@
+require 'spacebunny'
+
+# Prerequisites:
+# - You have created a Live Stream named 'live_data' through the SpaceBunny's web interface.
+# - The Live Stream has, as sources, two devices' 'data' channel.
+# See our Getting Started [link] for a quick introduction to SpaceBunny's base concepts.
+
+# Once everything is set up go to Users section on SpaceBunny Web UI, select one user and click on 'Access Keys'
+# Pick or create one access key and copy 'Client' and 'Secret'.
+
+client = 'live_stream_key_client'
+secret = 'live_stream_key_secret'
+
+# Instantiate a Spacebunny::LiveStream (AMQP by default) client, providing the 'client' and 'secret' options.
+
+live = Spacebunny::LiveStream.new client: client, secret: secret
+
+# We need to call 'connect' in order to open the communication with SpaceBunny platform
+
+live.connect
+
+# At this point the SDK is auto-configured and ready to use.
+# Configurations are automatically lazy-fetched by the SDK itself.
+
+# RECEIVING MESSAGES
+
+# For the sake of this test, we need first to publish some message.
+# If you have configured correctly your Live Stream from Web Interface, it should have at least two devices' data
+# channels as sources: pick one of the devices and copy its Api Key. Fire up another terminal, edit
+# examples/device/auto_config_publish.rb   paste the Device Key and run the script.
+
+puts 'Waiting for live messages'
+
+# Receiving messages is trivial:
+
+live.message_from_cache :live_data, wait: true, ack: :auto do |message|
+  puts "Received: #{message.payload}"
+end
+
+# An alternative to the 'message_from_cache' method is:
+# live.message_from :live_data, from_cache: true, wait: true, ack: :auto do |message|
+#   puts "Received #{message.payload}"
+# end
+
+# Now fire up another terminal, copy the other device's Api Key and replace it in the auto_config_publish.rb
+# script. If you take a look at the output of running live_stream/receive_messages.rb (this running script)
+# you should see that messages from the devices are almost alternated.
+
+# You may notice that we used 'message_from_cache' method: each LiveStream has its own cache that will keep always
+# last 100 messages (FIFO, when there are more than 100 messages, the oldest ones get discarded).
+# If you want to consume messages in a parallel way, you should use the cache and connect as many LiveStream Clients
+# as you need: this way messages will be equally and uniquely distributed to clients.
+# A nacked message will return to the queue and will be delivered to the next available client.
+
+# Conversely, if you want that each client will receive a copy of each message, don't use the cache:
+
+# live.message_from :live_data, wait: true, ack: :auto do |message|
+#   puts "Received a copy of #{message.payload}"
+# end
+
+# Every client subscribed to the LiveStream in this way will receive a copy of the message.
+
+### Options and notes
+#
+# A Ruby block must be supplied to the 'message_from' and 'message_from_cache' methods.
+# These methods yield a Device::Message object that wrap all the useful data:
+#
+# dev.message_from do |message|
+#   puts "payload: #{message.payload}"
+#
+#   # metadata that can be accessed as an Hash.
+#   # metadata[:headers] contains the message's headers for instance
+#   puts "metadata: #{message.metadata}"
+#
+#   # sender_id (id of the device that sent the message)
+#   puts "sender_id: #{message.sender_id}"
+#
+#   # channel name i.e. the name of the channel on which the message has been published
+#   puts "channel_name: #{message.channel_name}"
+#
+#   # Connection and other low level info
+#   puts "delivery_info: #{message.delivery_info}"
+# end
+
+# message_from (message_from_cache) methods' options:
+# 'wait' (default false) causes the script to wait forever on the receive block. This is useful
+# for 'read-only' scripts like workers or similar.
+# 'ack' option can have two values: :manual (default) or :auto. When :manual you are responsible to ack the messages,
+# for instance:
+#
+# dev.message_from(block: true, ack: :manual) do |message|
+#   puts "Received: #{message.payload}"
+#   message.ack
+# end
+#
+# When 'ack' is :auto then the SDK will automatically ack the messages when the code provided in the message_from block
+# has terminated execution. This behaviour is useful in cases in which the code executed inside the message_from block
+# will always lead to an acked message (no matter the operations' result).
+# If your code can lead to errors and, for instance, the message must be reprocessed, you must use :manual ack
+# and manually call 'ack' as seen in the example above.
+# Call 'nack' in case the message needs to be reprocessed and it will remain on SpaceBunny until successfully
+# acked. For instance:
+
+# dev.message_from(block: true, ack: :manual) do |message|
+#   puts message.payload
+#
+#   begin
+#     # Do something nasty...
+#     raise
+#
+#     # If everything is ok, ack
+#     # (note that this code will never be reached)
+#     message.ack
+#   rescue Exception => e
+#     message.nack
+#   end
+# end
+
+# ack options are:
+#   multiple: false   ack multiple messages at once. Ack all the unacked
+#                     messages up to the current one
+
+# nack options are:
+#   multiple: false   nack multiple messages at once. Nack all the messages up
+#                     to the current one
+#   requeue: false    requeue message. If false (default), the message will be
+#                     discarded by SpaceBunny. If true message will made
+#                     requeued and made available for delivery again

data/examples/live_stream/tls_connection.rb

@@ -0,0 +1,22 @@
+require 'spacebunny'
+
+# Prerequisites:
+# - You have created a Live Stream named 'live_data' through the SpaceBunny's web interface.
+# - The Live Stream has, as sources, two devices' 'data' channel.
+# See our Getting Started [link] for a quick introduction to SpaceBunny's base concepts.
+
+# Once everything is set up go to Users section on SpaceBunny Web UI, select one user and click on 'Access Keys'
+# Pick or create one access key and copy 'Client' and 'Secret'.
+
+client = 'live_stream_key_client'
+secret = 'live_stream_key_secret'
+
+# Instantiate a Spacebunny::LiveStream (AMQP by default) client, providing the 'client' and 'secret' options.
+# Also provide  tls: true to  establish a tls-encrypted connection
+
+live = Spacebunny::LiveStream.new client: client, secret: secret, tls: true
+live.connect
+
+live.message_from_cache :live_data, ack: :auto, wait: true do |message|
+  puts "Received: #{message.payload}"
+end

data/lib/spacebunny.rb

@@ -0,0 +1,23 @@
+# require 'active_support/core_ext/hash/keys'
+
+module Spacebunny
+  class << self
+    attr_accessor :logger
+  end
+end
+
+require 'spacebunny/version'
+require 'spacebunny/utils'
+require 'spacebunny/logger'
+require 'spacebunny/exceptions'
+require 'spacebunny/endpoint_connection'
+require 'spacebunny/device/base'
+require 'spacebunny/device/message'
+require 'spacebunny/device/amqp'
+require 'spacebunny/live_stream/base'
+require 'spacebunny/live_stream/message'
+require 'spacebunny/live_stream/amqp'
+
+def path_to_resources(path)
+  File.join(File.dirname(File.expand_path(__FILE__)), path)
+end

data/lib/spacebunny/device/amqp.rb

@@ -0,0 +1,158 @@
+require 'bunny'
+
+module Spacebunny
+  module Device
+    class Amqp < Base
+      DEFAULT_CHANNEL_OPTIONS = { passive: true }
+      ACK_TYPES = [:manual, :auto]
+
+      attr_reader :built_channels, :built_exchanges, :client
+
+      def initialize(*args)
+        super(:amqp, *args)
+        @built_channels = {}
+        @built_exchanges = {}
+      end
+
+      def connect
+        # 'Fix' attributes: start from common connection configs and adjust attributes to match what Bunny
+        # wants as connection args
+        connection_params = connection_configs.dup
+        connection_params[:user] = connection_params.delete :device_id
+        connection_params[:password] = connection_params.delete :secret
+        connection_params[:port] = connection_params.delete(:tls_port) if connection_params[:tls]
+        connection_params[:recover_from_connection_close] = connection_params.delete :auto_recover
+        connection_params[:log_level] = connection_params.delete(:log_level) || ::Logger::ERROR
+
+        # Re-create client every time connect is called
+        @client = Bunny.new(connection_params)
+        @client.start
+      end
+
+      def channel_from_name(name)
+        # In @built_channels in fact we have exchanges
+        with_channel_check name do
+          @built_exchanges[name]
+        end
+      end
+
+      def disconnect
+        super
+        client.stop
+      end
+
+      def input_channel
+        return @input_channel if @input_channel
+        @input_channel = client.create_channel
+      end
+
+      def on_receive(options = {})
+        unless block_given?
+          raise BlockRequired
+        end
+        blocking = options.fetch :wait, false
+        to_ack, auto_ack = parse_ack options.fetch(:ack, :manual)
+
+        input_queue.subscribe(block: blocking, manual_ack: to_ack) do |delivery_info, metadata, payload|
+          message = Device::Message.new self, options, delivery_info, metadata, payload
+
+          # Skip message if required
+          if message.blacklisted?
+            message.nack
+            next
+          end
+
+          yield message
+
+          # If ack is :auto then ack current message
+          if to_ack && auto_ack
+            message.ack
+          end
+        end
+      end
+      alias_method :inbox, :on_receive
+
+      def publish(channel_name, message, options = {})
+        check_client
+        channel_key = if options[:with_confirm]
+                        "#{channel_name}_confirm"
+                      else
+                        channel_name
+                      end.to_sym
+
+        unless @built_exchanges[channel_key]
+          @built_exchanges[channel_key] = create_channel(channel_name, options)
+        end
+        # Call Bunny publish method
+        @built_exchanges[channel_key].publish message, channel_options(channel_name, options)
+      end
+
+      def wait_for_publish_confirms
+        results = {}
+        threads = []
+        @built_channels.each do |name, channel|
+          if channel.using_publisher_confirmations?
+            threads << Thread.new do
+              results[name] = { all_confirmed: channel.wait_for_confirms, nacked_set: channel.nacked_set }
+            end
+          end
+        end
+        threads.map{ |t| t.join }
+        results
+      end
+
+      private
+
+      # Merge default channel options with provided ones
+      def channel_options(channel, options)
+        options.merge({routing_key: "#{id}.#{channel}" })
+      end
+
+      # Check if client has been prepared.
+      def check_client
+        unless client
+          raise ClientNotSetup
+        end
+        unless client.connected?
+          if raise_on_error
+            raise ClientNotConnected
+          else
+            @logger.error 'Client not connected! Check internet connection'
+          end
+        end
+      end
+
+      def create_channel(name, options = {})
+        with_channel_check name do
+          channel = client.create_channel
+          if options.delete(:with_confirm)
+            channel.confirm_select
+          end
+          @built_channels[name] = channel
+          channel.direct(id, DEFAULT_CHANNEL_OPTIONS)
+        end
+      end
+
+      def input_queue
+        return @input_queue if @input_queue
+        @input_queue = input_channel.queue "#{id}.inbox", passive: true
+      end
+
+      def parse_ack(ack)
+        to_ack = false
+        auto_ack = false
+        if ack
+          raise AckTypeError unless ACK_TYPES.include?(ack)
+          to_ack = true
+          case ack
+            when :manual
+              auto_ack = false
+            when :auto
+              auto_ack = true
+          end
+        end
+        return to_ack, auto_ack
+      end
+    end
+  end
+end