mqtt 0.0.9 → 0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2009-2013 Nicholas J Humfrey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/NEWS

@@ -1,6 +1,25 @@
 Ruby MQTT NEWS
 ==============
 
+Ruby MQTT Version 0.1.0 (2013-09-07)
+------------------------------------
+
+* Changed license to MIT, to simplify licensing concerns
+* Improvements for UTF-8 handling under Ruby 1.9
+* Added ```get_packet``` method
+* Added support for a keep-alive value of 0
+* Added a #inspect method to the Packet classes
+* Added checks for the protocol name and version
+* Added check to ensure that packet body isn't too big
+* Added validation of QoS value
+* Added example of using authentication
+* Fixed 'unused variable' warnings
+* Reduced duplicated code in packet parsing
+* Improved testing
+  - Created fake server and integration tests
+  - Better test coverage
+  - Added more tests for error states
+
 
 Ruby MQTT Version 0.0.9 (2012-12-21)
 ------------------------------------

data/README

@@ -46,6 +46,11 @@ Resources
 * GitHub Project: http://github.com/njh/ruby-mqtt
 * API Documentation: http://rubydoc.info/gems/mqtt/frames
 
+License
+-------
+
+The ruby-mqtt gem is licensed under the terms of the MIT license.
+See the file LICENSE for details.
 
 Contact
 -------
@@ -53,4 +58,3 @@ Contact
 * Author:    Nicholas J Humfrey
 * Email:     njh@aelius.com
 * Home Page: http://www.aelius.com/njh/
-* License:   Distributes under the same terms as Ruby

data/lib/mqtt.rb

@@ -5,7 +5,12 @@ require 'socket'
 require 'thread'
 require 'timeout'
 
-require "mqtt/version"
+require 'mqtt/version'
+
+# String encoding monkey patch for Ruby 1.8
+unless String.method_defined?(:force_encoding)
+  require 'mqtt/patches/string_encoding.rb'
+end
 
 module MQTT
 

data/lib/mqtt/client.rb

@@ -220,7 +220,7 @@ class MQTT::Client
     send_packet(packet)
   end
 
-  # Return the next message recieved from the MQTT broker.
+  # Return the next message received from the MQTT broker.
   # An optional topic can be given to subscribe to.
   #
   # The method either returns the topic and message as an array:
@@ -248,6 +248,34 @@ class MQTT::Client
     end
   end
 
+  # Return the next packet object received from the MQTT broker.
+  # An optional topic can be given to subscribe to.
+  #
+  # The method either returns a single packet:
+  #   packet = client.get_packet
+  #   puts packet.topic
+  #
+  # Or can be used with a block to keep processing messages:
+  #   client.get_packet('test') do |packet|
+  #     # Do stuff here
+  #     puts packet.topic
+  #   end
+  #
+  def get_packet(topic=nil)
+    # Subscribe to a topic, if an argument is given
+    subscribe(topic) unless topic.nil?
+
+    if block_given?
+      # Loop forever!
+      loop do
+        yield(@read_queue.pop)
+      end
+    else
+      # Wait for one packet to be available
+      return @read_queue.pop
+    end
+  end
+
   # Returns true if the incoming message queue is empty.
   def queue_empty?
     @read_queue.empty?
@@ -289,7 +317,7 @@ private
       end
 
       # Time to send a keep-alive ping request?
-      if Time.now > @last_pingreq + @keep_alive
+      if @keep_alive > 0 and Time.now > @last_pingreq + @keep_alive
         ping
       end
 

data/lib/mqtt/packet.rb

@@ -1,3 +1,5 @@
+# encoding: BINARY
+
 module MQTT
 
   # Class representing a MQTT Packet
@@ -17,27 +19,21 @@ module MQTT
 
     # Read in a packet from a socket
     def self.read(socket)
-      # Read in the packet header and work out the class
-      header = read_byte(socket)
-      type_id = ((header & 0xF0) >> 4)
-      packet_class = MQTT::PACKET_TYPES[type_id]
-
-      # Create a new packet object
-      packet = packet_class.new(
-        :duplicate => ((header & 0x08) >> 3),
-        :qos => ((header & 0x06) >> 1),
-        :retain => ((header & 0x01) >> 0)
+      # Read in the packet header and create a new packet object
+      packet = create_from_header(
+        read_byte(socket)
       )
 
       # Read in the packet length
       multiplier = 1
       body_length = 0
+      pos = 1
       begin
         digit = read_byte(socket)
         body_length += ((digit & 0x7F) * multiplier)
         multiplier *= 0x80
-      end while ((digit & 0x80) != 0x00)
-      # FIXME: only allow 4 bytes?
+        pos += 1
+      end while ((digit & 0x80) != 0x00) and pos <= 4
 
       # Store the expected body length in the packet
       packet.instance_variable_set('@body_length', body_length)
@@ -58,29 +54,24 @@ module MQTT
     # Parse the header and create a new packet object of the correct type
     # The header is removed from the buffer passed into this function
     def self.parse_header(buffer)
-      # Work out the class
-      type_id = ((buffer.unpack("C*")[0] & 0xF0) >> 4)
-      packet_class = MQTT::PACKET_TYPES[type_id]
-      if packet_class.nil?
-        raise ProtocolException.new("Invalid packet type identifier: #{type_id}")
+      # Check that the packet is a long as the minimum packet size
+      if buffer.bytesize < 2
+        raise ProtocolException.new("Invalid packet: less than 2 bytes long")
       end
 
       # Create a new packet object
-      packet = packet_class.new(
-        :duplicate => ((buffer.unpack("C*")[0] & 0x08) >> 3) == 0x01,
-        :qos => ((buffer.unpack("C*")[0] & 0x06) >> 1),
-        :retain => ((buffer.unpack("C*")[0] & 0x01) >> 0) == 0x01
-      )
+      bytes = buffer.unpack("C5")
+      packet = create_from_header(bytes.first)
 
       # Parse the packet length
       body_length = 0
       multiplier = 1
       pos = 1
       begin
-        if buffer.length <= pos
+        if buffer.bytesize <= pos
           raise ProtocolException.new("The packet length header is incomplete")
         end
-        digit = buffer.unpack("C*")[pos]
+        digit = bytes[pos]
         body_length += ((digit & 0x7F) * multiplier)
         multiplier *= 0x80
         pos += 1
@@ -89,12 +80,28 @@ module MQTT
       # Store the expected body length in the packet
       packet.instance_variable_set('@body_length', body_length)
 
-      # Delete the variable length header from the raw packet passed in
+      # Delete the fixed header from the raw packet passed in
       buffer.slice!(0...pos)
 
       return packet
     end
 
+    # Create a new packet object from the first byte of a MQTT packet
+    def self.create_from_header(byte)
+      # Work out the class
+      type_id = ((byte & 0xF0) >> 4)
+      packet_class = MQTT::PACKET_TYPES[type_id]
+      if packet_class.nil?
+        raise ProtocolException.new("Invalid packet type identifier: #{type_id}")
+      end
+
+      # Create a new packet object
+      packet_class.new(
+        :duplicate => ((byte & 0x08) >> 3) == 0x01,
+        :qos => ((byte & 0x06) >> 1),
+        :retain => ((byte & 0x01) >> 0) == 0x01
+      )
+    end
 
     # Create a new empty packet
     def initialize(args={})
@@ -137,6 +144,9 @@ module MQTT
     # Set the Quality of Service level (0/1/2)
     def qos=(arg)
       @qos = arg.to_i
+      if @qos < 0 or @qos > 2
+        raise "Invalid QoS value: #{@qos}"
+      end
     end
 
     # Set the length of the packet body
@@ -146,9 +156,9 @@ module MQTT
 
     # Parse the body (variable header and payload) of a packet
     def parse_body(buffer)
-      if buffer.length != body_length
+      if buffer.bytesize != body_length
         raise ProtocolException.new(
-          "Failed to parse packet - input buffer (#{buffer.length}) is not the same as the body length buffer (#{body_length})"
+          "Failed to parse packet - input buffer (#{buffer.bytesize}) is not the same as the body length header (#{body_length})"
         )
       end
     end
@@ -172,8 +182,13 @@ module MQTT
       # Get the packet's variable header and payload
       body = self.encode_body
 
+      # Check that that packet isn't too big
+      body_length = body.bytesize
+      if body_length > 268435455
+        raise "Error serialising packet: body is more than 256MB"
+      end
+
       # Build up the body length field bytes
-      body_length = body.length
       begin
         digit = (body_length % 128)
         body_length = (body_length / 128)
@@ -186,6 +201,9 @@ module MQTT
       header.pack('C*') + body
     end
 
+    def inspect
+      "\#<#{self.class}>"
+    end
 
     protected
 
@@ -199,11 +217,14 @@ module MQTT
       [val.to_i].pack('n')
     end
 
-    # Encode a string and return it
+    # Encode a UTF-8 string and return it
     # (preceded by the length of the string)
     def encode_string(str)
-      str = str.to_s unless str.is_a?(String)
-      encode_short(str.length) + str
+      str = str.to_s.encode('UTF-8')
+
+      # Force to binary, when assembling the packet
+      str.force_encoding('ASCII-8BIT')
+      encode_short(str.bytesize) + str
     end
 
     # Remove a 16-bit unsigned integer from the front of buffer
@@ -225,7 +246,9 @@ module MQTT
     # Remove string from the front of buffer
     def shift_string(buffer)
       len = shift_short(buffer)
-      shift_data(buffer,len)
+      str = shift_data(buffer,len)
+      # Strings in MQTT v3.1 are all UTF-8
+      str.force_encoding('UTF-8')
     end
 
 
@@ -235,7 +258,7 @@ module MQTT
     def self.read_byte(socket)
       byte = socket.read(1)
       if byte.nil?
-        raise ProtocolException
+        raise ProtocolException.new("Failed to read byte from socket")
       end
       byte.unpack('C').first
     end
@@ -265,12 +288,12 @@ module MQTT
       # Get serialisation of packet's body
       def encode_body
         body = ''
-        if @topic.nil?
+        if @topic.nil? or @topic.to_s.empty?
           raise "Invalid topic name when serialising packet"
         end
         body += encode_string(@topic)
         body += encode_short(@message_id) unless qos == 0
-        body += payload.to_s
+        body += payload.to_s.force_encoding('ASCII-8BIT')
         return body
       end
 
@@ -279,7 +302,27 @@ module MQTT
         super(buffer)
         @topic = shift_string(buffer)
         @message_id = shift_short(buffer) unless qos == 0
-        @payload = buffer.dup
+        @payload = buffer
+      end
+
+      def inspect
+        "\#<#{self.class}: " +
+        "d#{duplicate ? '1' : '0'}, " +
+        "q#{qos}, " +
+        "r#{retain ? '1' : '0'}, " +
+        "m#{message_id}, " +
+        "'#{topic}', " +
+        "#{inspect_payload}>"
+      end
+
+      protected
+      def inspect_payload
+        str = payload.to_s
+        if str.bytesize < 16
+          "'#{str}'"
+        else
+          "... (#{str.bytesize} bytes)"
+        end
       end
     end
 
@@ -323,12 +366,16 @@ module MQTT
       # Get serialisation of packet's body
       def encode_body
         body = ''
-        if @client_id.nil? or @client_id.length < 1 or @client_id.length > 23
+        if @client_id.nil? or @client_id.bytesize < 1 or @client_id.bytesize > 23
           raise "Invalid client identifier when serialising packet"
         end
         body += encode_string(@protocol_name)
         body += encode_bytes(@protocol_version.to_i)
 
+        if @keep_alive < 0
+          raise "Invalid keep-alive value: cannot be less than 0"
+        end
+
         # Set the Connect flags
         @connect_flags = 0
         @connect_flags |= 0x02 if @clean_session
@@ -343,6 +390,7 @@ module MQTT
         body += encode_string(@client_id)
         unless will_topic.nil?
           body += encode_string(@will_topic)
+          # The MQTT v3.1 specification says that the payload is a UTF-8 string
           body += encode_string(@will_payload)
         end
         body += encode_string(@username) unless @username.nil?
@@ -354,7 +402,20 @@ module MQTT
       def parse_body(buffer)
         super(buffer)
         @protocol_name = shift_string(buffer)
-        @protocol_version = shift_byte(buffer)
+        @protocol_version = shift_byte(buffer).to_i
+
+        if @protocol_name != 'MQIsdp'
+          raise ProtocolException.new(
+            "Unsupported protocol name: #{@protocol_name}"
+          )
+        end
+
+        if @protocol_version != 3
+          raise ProtocolException.new(
+            "Unsupported protocol version: #{@protocol_version}"
+          )
+        end
+
         @connect_flags = shift_byte(buffer)
         @clean_session = ((@connect_flags & 0x02) >> 1) == 0x01
         @keep_alive = shift_short(buffer)
@@ -364,15 +425,26 @@ module MQTT
           @will_qos = ((@connect_flags & 0x18) >> 3)
           @will_retain = ((@connect_flags & 0x20) >> 5) == 0x01
           @will_topic = shift_string(buffer)
+          # The MQTT v3.1 specification says that the payload is a UTF-8 string
           @will_payload = shift_string(buffer)
         end
-        if ((@connect_flags & 0x80) >> 7) == 0x01 and buffer.length > 0
+        if ((@connect_flags & 0x80) >> 7) == 0x01 and buffer.bytesize > 0
           @username = shift_string(buffer)
         end
-        if ((@connect_flags & 0x40) >> 6) == 0x01 and buffer.length > 0
+        if ((@connect_flags & 0x40) >> 6) == 0x01 and buffer.bytesize > 0
           @password = shift_string(buffer)
         end
       end
+
+      def inspect
+        str = "\#<#{self.class}: "
+        str += "keep_alive=#{keep_alive}"
+        str += ", clean" if clean_session
+        str += ", client_id='#{client_id}'"
+        str += ", username='#{username}'" unless username.nil?
+        str += ", password=..." unless password.nil?
+        str += ">"
+      end
     end
 
     # Class representing an MQTT Connect Acknowledgment Packet
@@ -416,12 +488,16 @@ module MQTT
       # Parse the body (variable header and payload) of a Connect Acknowledgment packet
       def parse_body(buffer)
         super(buffer)
-        unused = shift_byte(buffer)
+        _unused = shift_byte(buffer)
         @return_code = shift_byte(buffer)
         unless buffer.empty?
           raise ProtocolException.new("Extra bytes at end of Connect Acknowledgment packet")
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X>" % return_code
+      end
     end
 
     # Class representing an MQTT Publish Acknowledgment packet
@@ -447,6 +523,10 @@ module MQTT
           raise ProtocolException.new("Extra bytes at end of Publish Acknowledgment packet")
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X>" % message_id
+      end
     end
 
     # Class representing an MQTT Publish Received packet
@@ -472,6 +552,10 @@ module MQTT
           raise ProtocolException.new("Extra bytes at end of Publish Received packet")
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X>" % message_id
+      end
     end
 
     # Class representing an MQTT Publish Release packet
@@ -497,6 +581,10 @@ module MQTT
           raise ProtocolException.new("Extra bytes at end of Publish Release packet")
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X>" % message_id
+      end
     end
 
     # Class representing an MQTT Publish Complete packet
@@ -522,6 +610,10 @@ module MQTT
           raise ProtocolException.new("Extra bytes at end of Publish Complete packet")
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X>" % message_id
+      end
     end
 
     # Class representing an MQTT Client Subscribe packet
@@ -597,12 +689,19 @@ module MQTT
         super(buffer)
         @message_id = shift_short(buffer)
         @topics = []
-        while(buffer.length>0)
+        while(buffer.bytesize>0)
           topic_name = shift_string(buffer)
           topic_qos = shift_byte(buffer)
           @topics << [topic_name,topic_qos]
         end
       end
+
+      def inspect
+        str = "\#<#{self.class}: 0x%2.2X, %s>" % [
+          message_id,
+          topics.map {|t| "'#{t[0]}':#{t[1]}"}.join(', ')
+        ]
+      end
     end
 
     # Class representing an MQTT Subscribe Acknowledgment packet
@@ -643,10 +742,14 @@ module MQTT
       def parse_body(buffer)
         super(buffer)
         @message_id = shift_short(buffer)
-        while(buffer.length>0)
+        while(buffer.bytesize>0)
           @granted_qos << shift_byte(buffer)
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X, qos=%s>" % [message_id, granted_qos.join(',')]
+      end
     end
 
     # Class representing an MQTT Client Unsubscribe packet
@@ -684,10 +787,17 @@ module MQTT
       def parse_body(buffer)
         super(buffer)
         @message_id = shift_short(buffer)
-        while(buffer.length>0)
+        while(buffer.bytesize>0)
           @topics << shift_string(buffer)
         end
       end
+
+      def inspect
+        str = "\#<#{self.class}: 0x%2.2X, %s>" % [
+          message_id,
+          topics.map {|t| "'#{t}'"}.join(', ')
+        ]
+      end
     end
 
     # Class representing an MQTT Unsubscribe Acknowledgment packet
@@ -713,6 +823,10 @@ module MQTT
           raise ProtocolException.new("Extra bytes at end of Unsubscribe Acknowledgment packet")
         end
       end
+
+      def inspect
+        "\#<#{self.class}: 0x%2.2X>" % message_id
+      end
     end
 
     # Class representing an MQTT Ping Request packet
@@ -762,7 +876,6 @@ module MQTT
         end
       end
     end
-
   end