rightscale-nanite 0.4.1.4 → 0.4.1.10

data/Rakefile

@@ -10,7 +10,7 @@ end
 require 'rake/clean'
 require 'lib/nanite'
 
-GEM = "nanite"
+GEM = "rightscale-nanite"
 AUTHOR = "Ezra Zygmuntowicz"
 EMAIL = "ezra@engineyard.com"
 HOMEPAGE = "http://github.com/ezmobius/nanite"
@@ -74,3 +74,5 @@ task :docs => :rdoc do
     sh 'firefox rdoc/index.html'
   end
 end
+
+require 'rightscale-nanite.rb'

data/lib/nanite/agent.rb

@@ -86,24 +86,20 @@ module Nanite
     def initialize(opts)
       set_configuration(opts)
       @tags = []
-      @tags << opts[:tag]
+      @tags << opts[:tag] if opts[:tag]
       @tags.flatten!
       @options.freeze
     end
     
     def run
-      log_path = false
-      if @options[:daemonize]
-        log_path = (@options[:log_dir] || @options[:root] || Dir.pwd)
-      end
-      Log.init(@identity, log_path)
+      Log.init(@identity, @options[:log_path])
       Log.level = @options[:log_level] if @options[:log_level]
       @serializer = Serializer.new(@options[:format])
       @status_proc = lambda { parse_uptime(`uptime 2> /dev/null`) rescue 'no status' }
       pid_file = PidFile.new(@identity, @options)
       pid_file.check
       if @options[:daemonize]
-        daemonize
+        daemonize(@identity, @options)
         pid_file.write
         at_exit { pid_file.remove }
       end
@@ -135,6 +131,16 @@ module Nanite
       @deny_token = deny_token
     end
 
+    # Update set of tags published by agent and notify mapper
+    # Add tags in 'new_tags' and remove tags in 'old_tags'
+    def update_tags(new_tags, old_tags)
+      @tags += (new_tags || [])
+      @tags -= (old_tags || [])
+      @tags.uniq!
+      tag_update = TagUpdate.new(identity, new_tags, old_tags)
+      amq.fanout('registration', :no_declare => options[:secure]).publish(serializer.dump(tag_update))
+    end
+
     protected
 
     def set_configuration(opts)
@@ -149,6 +155,11 @@ module Nanite
       opts.delete(:identity) unless opts[:identity]
       @options.update(custom_config.merge(opts))
       @options[:file_root] ||= File.join(@options[:root], 'files')
+      @options[:log_path] = false
+      if @options[:daemonize]
+        @options[:log_path] = (@options[:log_dir] || @options[:root] || Dir.pwd)
+      end
+      
       return @identity = "nanite-#{@options[:identity]}" if @options[:identity]
       token = Identity.generate
       @identity = "nanite-#{token}"
@@ -160,6 +171,7 @@ module Nanite
     def load_actors
       return unless options[:root]
       actors_dir = @options[:actors_dir] || "#{@options[:root]}/actors"
+      Nanite::Log.warn("Actors dir #{actors_dir} does not exist or is not reachable") unless File.directory?(actors_dir)
       actors = @options[:actors]
       Dir["#{actors_dir}/*.rb"].each do |actor|
         next if actors && !actors.include?(File.basename(actor, ".rb"))
@@ -167,7 +179,11 @@ module Nanite
         require actor
       end
       init_path = @options[:initrb] || File.join(options[:root], 'init.rb')
-      instance_eval(File.read(init_path), init_path) if File.exist?(init_path)
+      if File.exist?(init_path)
+        instance_eval(File.read(init_path), init_path) 
+      else
+        Nanite::Log.warn("init.rb #{init_path} does not exist or is not reachable") unless File.exists?(init_path)
+      end
     end
 
     def receive(packet)

data/lib/nanite/amqp.rb

@@ -46,7 +46,11 @@ module Nanite
         :host => options[:host],
         :port => (options[:port] || ::AMQP::PORT).to_i,
         :insist => options[:insist] || false,
-        :retry => options[:retry] || 5
+        :retry => options[:retry] || 5,
+        :connection_status => options[:connection_callback] || proc {|event| 
+          Nanite::Log.debug("CONNECTED to MQ") if event == :connected
+          Nanite::Log.debug("DISCONNECTED from MQ") if event == :disconnected
+        }
       })
       MQ.new(connection)
     end

data/lib/nanite/cluster.rb

@@ -2,13 +2,14 @@ module Nanite
   class Cluster
     attr_reader :agent_timeout, :nanites, :reaper, :serializer, :identity, :amq, :redis, :mapper, :callbacks
 
-    def initialize(amq, agent_timeout, identity, serializer, mapper, state_configuration=nil, callbacks = {})
+    def initialize(amq, agent_timeout, identity, serializer, mapper, state_configuration=nil, tag_store=nil, callbacks = {})
       @amq = amq
       @agent_timeout = agent_timeout
       @identity = identity
       @serializer = serializer
       @mapper = mapper
       @state = state_configuration
+      @tag_store = tag_store
       @security = SecurityProvider.get
       @callbacks = callbacks
       setup_state
@@ -19,7 +20,7 @@ module Nanite
     # determine which nanites should receive the given request
     def targets_for(request)
       return [request.target] if request.target
-      __send__(request.selector, request.type, request.tags).collect {|name, state| name }
+      __send__(request.selector, request.from, request.type, request.tags).collect {|name, state| name }
     end
 
     # adds nanite to nanites map: key is nanite's identity
@@ -30,38 +31,51 @@ module Nanite
       when Register
         if @security.authorize_registration(reg)
           Nanite::Log.info("RECV #{reg.to_s}")
-          nanites[reg.identity] = { :services => reg.services, :status => reg.status, :tags => reg.tags }
-          reaper.timeout(reg.identity, agent_timeout + 1) { nanite_timed_out(reg.identity) }
+          nanites[reg.identity] = { :services => reg.services, :status => reg.status, :tags => reg.tags, :timestamp => Time.now.utc.to_i }
+          reaper.register(reg.identity, agent_timeout + 1) { nanite_timed_out(reg.identity) }
           callbacks[:register].call(reg.identity, mapper) if callbacks[:register]
         else
           Nanite::Log.warn("RECV NOT AUTHORIZED #{reg.to_s}")
         end
       when UnRegister
         Nanite::Log.info("RECV #{reg.to_s}")
+        reaper.unregister(reg.identity)
         nanites.delete(reg.identity)
         callbacks[:unregister].call(reg.identity, mapper) if callbacks[:unregister]
+      when TagUpdate
+        Nanite::Log.info("RECV #{reg.to_s}")
+        nanites.update_tags(reg.identity, reg.new_tags, reg.obsolete_tags)
       else
         Nanite::Log.warn("RECV [register] Invalid packet type: #{reg.class}")
       end
     end
 
     def nanite_timed_out(token)
-      nanite = nanites.delete(token)
-      callbacks[:timeout].call(token, mapper) if callbacks[:timeout]
+      nanite = nanites[token]
+      if nanite && timed_out?(nanite)
+        Nanite::Log.info("Nanite #{token} timed out")
+        nanite = nanites.delete(token)
+        callbacks[:timeout].call(token, mapper) if callbacks[:timeout]
+        true
+      end
     end
-    
+
     def route(request, targets)
       EM.next_tick { targets.map { |target| publish(request, target) } }
     end
 
     def publish(request, target)
-      # We need to initialize the 'target' field of the request object so that the serializer has
-      # access to it.
+      # We need to initialize the 'target' field of the request object so that the serializer and
+      # the security provider have access to it.
       begin
         old_target = request.target
         request.target = target unless target == 'mapper-offline'
-        Nanite::Log.info("SEND #{request.to_s([:from, :tags, :target])}")
-        amq.queue(target).publish(serializer.dump(request), :persistent => request.persistent)
+        if @security.authorize_request(request)
+          Nanite::Log.info("SEND #{request.to_s([:from, :on_behalf, :tags, :target])}")
+          amq.queue(target).publish(serializer.dump(request), :persistent => request.persistent)
+        else
+          Nanite::Log.warn("RECV NOT AUTHORIZED #{request.to_s}")
+        end
       ensure
         request.target = old_target
       end
@@ -74,8 +88,8 @@ module Nanite
     def handle_ping(ping)
       begin
         if nanite = nanites[ping.identity]
-          nanite[:status] = ping.status
-          reaper.reset_with_autoregister_hack(ping.identity, agent_timeout + 1) { nanite_timed_out(ping.identity) }
+          nanites.update_status(ping.identity, ping.status)
+          reaper.update(ping.identity, agent_timeout + 1) { nanite_timed_out(ping.identity) }
         else
           packet = Advertise.new
           Nanite::Log.info("SEND #{packet.to_s} to #{ping.identity}")
@@ -83,58 +97,54 @@ module Nanite
         end
       end
     end
-    
+
     # forward request coming from agent
     def handle_request(request)
-      if @security.authorize_request(request)
-        Nanite::Log.info("RECV #{request.to_s([:from, :target, :tags])}") unless Nanite::Log.level == :debug
-        Nanite::Log.debug("RECV #{request.to_s}")
-        case request
-        when Push
-          mapper.send_push(request)
-        else
-          intm_handler = lambda do |result, job|
-            result = IntermediateMessage.new(request.token, job.request.from, mapper.identity, nil, result)
-            forward_response(result, request.persistent)
-          end
-        
-          result = Result.new(request.token, request.from, nil, mapper.identity)
-          ok = mapper.send_request(request, :intermediate_handler => intm_handler) do |res|
-            result.results = res
-            forward_response(result, request.persistent)
-          end
-          
-          if ok == false
-            forward_response(result, request.persistent)
-          end
-        end
+      Nanite::Log.info("RECV #{request.to_s([:from, :on_behalf, :target, :tags])}") unless Nanite::Log.level == :debug
+      Nanite::Log.debug("RECV #{request.to_s}")
+      case request
+      when Push
+        mapper.send_push(request)
       else
-        Nanite::Log.warn("RECV NOT AUTHORIZED #{request.to_s}")
+        intm_handler = lambda do |result, job|
+          result = IntermediateMessage.new(request.token, job.request.from, mapper.identity, nil, result)
+          forward_response(result, request.persistent)
+        end
+
+        result = Result.new(request.token, request.from, nil, mapper.identity)
+        ok = mapper.send_request(request, :intermediate_handler => intm_handler) do |res|
+          result.results = res
+          forward_response(result, request.persistent)
+        end
+
+        if ok == false
+          forward_response(result, request.persistent)
+        end
       end
     end
-    
+
     # forward response back to agent that originally made the request
     def forward_response(res, persistent)
       Nanite::Log.info("SEND #{res.to_s([:to])}")
       amq.queue(res.to).publish(serializer.dump(res), :persistent => persistent)
     end
-    
+
     # returns least loaded nanite that provides given service
-    def least_loaded(service, tags=[])
-      candidates = nanites_providing(service,tags)
+    def least_loaded(from, service, tags=[])
+      candidates = nanites_providing(from, service, tags)
       return [] if candidates.empty?
 
       [candidates.min { |a,b| a[1][:status] <=> b[1][:status] }]
     end
 
     # returns all nanites that provide given service
-    def all(service, tags=[])
-      nanites_providing(service,tags)
+    def all(from, service, tags=[])
+      nanites_providing(from, service,tags)
     end
 
     # returns a random nanite
-    def random(service, tags=[])
-      candidates = nanites_providing(service,tags)
+    def random(from, service, tags=[])
+      candidates = nanites_providing(from, service,tags)
       return [] if candidates.empty?
 
       [candidates[rand(candidates.size)]]
@@ -142,10 +152,10 @@ module Nanite
 
     # selects next nanite that provides given service
     # using round robin rotation
-    def rr(service, tags=[])
+    def rr(from, service, tags=[])
       @last ||= {}
       @last[service] ||= 0
-      candidates = nanites_providing(service,tags)
+      candidates = nanites_providing(from, service,tags)
       return [] if candidates.empty?
       @last[service] = 0 if @last[service] >= candidates.size
       candidate = candidates[@last[service]]
@@ -153,9 +163,18 @@ module Nanite
       [candidate]
     end
 
+    def timed_out?(nanite)
+      nanite[:timestamp].to_i < (Time.now.utc - agent_timeout).to_i
+    end
+
     # returns all nanites that provide the given service
-    def nanites_providing(service, *tags)
-      nanites.nanites_for(service, *tags)
+    def nanites_providing(from, service, tags)
+      nanites.nanites_for(from, service, tags).delete_if do |nanite|
+        if res = timed_out?(nanite[1])
+          Nanite::Log.debug("Ignoring timed out nanite #{nanite[0]} in target selection - last seen at #{nanite[1][:timestamp]}")
+        end
+        res
+      end
     end
 
     def setup_queues
@@ -172,6 +191,7 @@ module Nanite
           handle_ping(ping)
         rescue Exception => e
           Nanite::Log.error("RECV [ping] #{e.message}")
+          callbacks[:exception].call(e, msg, mapper) rescue nil if callbacks[:exception]
         end
       end
       hb_fanout = amq.fanout('heartbeat', :durable => true)
@@ -188,6 +208,7 @@ module Nanite
           register(serializer.load(msg))
         rescue Exception => e
           Nanite::Log.error("RECV [register] #{e.message}")
+          callbacks[:exception].call(e, msg, mapper) rescue nil if callbacks[:exception]
         end
       end
       reg_fanout = amq.fanout('registration', :durable => true)
@@ -197,13 +218,14 @@ module Nanite
         amq.queue("registration-#{identity}", :exclusive => true).bind(reg_fanout).subscribe &handler
       end
     end
-    
+
     def setup_request_queue
       handler = lambda do |msg|
         begin
           handle_request(serializer.load(msg))
         rescue Exception => e
           Nanite::Log.error("RECV [request] #{e.message}")
+          callbacks[:exception].call(e, msg, mapper) rescue nil if callbacks[:exception]
         end
       end
       req_fanout = amq.fanout('request', :durable => true)
@@ -219,16 +241,14 @@ module Nanite
       when String
         # backwards compatibility, we assume redis if the configuration option
         # was a string
-        Nanite::Log.info("[setup] using redis for state storage")
         require 'nanite/state'
-        @nanites = Nanite::State.new(@state)
-      when Hash
+        @nanites = Nanite::State.new(@state, @tag_store)
       else
         require 'nanite/local_state'
         @nanites = Nanite::LocalState.new
       end
     end
-    
+
     def shared_state?
       !@state.nil?
     end

data/lib/nanite/daemonize.rb

@@ -1,13 +1,13 @@
 module Nanite
   module DaemonizeHelper
-    def daemonize
+    def daemonize(identity, options = {})
       exit if fork
       Process.setsid
       exit if fork
-      File.umask 0000
       STDIN.reopen "/dev/null"
-      STDOUT.reopen "/dev/null", "a"
-      STDERR.reopen STDOUT
+      STDOUT.reopen "#{options[:log_path]}/nanite.#{identity}.out", "a"
+      STDERR.reopen "#{options[:log_path]}/nanite.#{identity}.err", "a"
+      File.umask 0000
     end
   end
 end

data/lib/nanite/local_state.rb

@@ -14,7 +14,7 @@ module Nanite
       all(:tags)
     end
 
-    def nanites_for(service, *tags)
+    def nanites_for(from, service, tags)
       tags = tags.dup.flatten
       nanites = select { |name, state| state[:services].include?(service) }
       unless tags.empty?
@@ -24,6 +24,10 @@ module Nanite
       end.to_a
     end
 
+    def update_status(name, status)
+      self[name].update(:status => status, :timestamp => Time.now.utc.to_i)
+    end
+    
     private
 
     def all(key)

data/lib/nanite/log.rb

@@ -35,7 +35,7 @@ module Nanite
       # Throws an ArgumentError if you feed it a bogus log level (that is not
       # one of :debug, :info, :warn, :error, :fatal or the corresponding strings or a valid Logger level)
       def level=(loglevel)
-        init() unless @logger
+        init unless @logger
         lvl = case loglevel
           when String  then loglevel.intern
           when Integer then LEVELS.invert[loglevel]

data/lib/nanite/mapper.rb

@@ -76,10 +76,15 @@ module Nanite
     # secure      : use Security features of rabbitmq to restrict nanites to themselves
     #
     # prefetch    : Sets prefetch (only supported in RabbitMQ >= 1.6)
-    # callbacks   : A set of callbacks to have code executed on specific events, supported events are :register,
-    #               :unregister and :timeout. Parameter must be a hash with the corresponding events as keys and
-    #               a block as value. The block will get the corresponding nanite's identity and a copy of the   
-    #               mapper
+    #
+    # callbacks   : A set of callbacks to be executed on specific events. Supported events are :register,
+    #               :unregister, :timeout and :exception. This option must be a hash with event names as
+    #               as keys and Procs as values. The Proc's arity (number of parameters) depends on the
+    #               type of callback:
+    #                    exception  -- the exception, the message being processed, a reference to the mapper
+    #                    all others -- the corresponding nanite's identity, a reference to the mapper
+    #
+    # tag_store   : Name of class which implements tag store backend interface, RedisTagStore by default
     #
     # Connection options:
     #
@@ -116,6 +121,10 @@ module Nanite
       @options.update(custom_config.merge(options))
       @identity = "mapper-#{@options[:identity]}"
       @options[:file_root] ||= File.join(@options[:root], 'files')
+      @options[:log_path] = false
+      if @options[:daemonize]
+        @options[:log_path] = (@options[:log_dir] || @options[:root] || Dir.pwd)
+      end
       @options.freeze
     end
 
@@ -125,7 +134,7 @@ module Nanite
       pid_file = PidFile.new(@identity, @options)
       pid_file.check
       if @options[:daemonize]
-        daemonize
+        daemonize(@identity, @options)
         pid_file.write
         at_exit { pid_file.remove }
       else
@@ -288,21 +297,18 @@ module Nanite
           job_warden.process(msg)
         rescue Exception => e
           Nanite::Log.error("RECV [result] #{e.message}")
+          callbacks[:exception].call(e, msg, mapper) rescue nil if callbacks[:exception]          
         end
       end
     end
 
     def setup_logging
-      log_path = false
-      if @options[:daemonize]
-        log_path = (@options[:log_dir] || @options[:root] || Dir.pwd)
-      end
-      Nanite::Log.init(@identity, log_path)
+      Nanite::Log.init(@identity, @options[:log_path])
       Nanite::Log.level = @options[:log_level] if @options[:log_level]
     end
 
     def setup_cluster
-      @cluster = Cluster.new(@amq, @options[:agent_timeout], @options[:identity], @serializer, self, @options[:redis], @options[:callbacks])
+      @cluster = Cluster.new(@amq, @options[:agent_timeout], @options[:identity], @serializer, self, @options[:redis], @options[:tag_store], @options[:callbacks])
     end
   end
 end

data/lib/nanite/mapper_proxy.rb

@@ -49,7 +49,15 @@ module Nanite
       push.persistent = opts.key?(:persistent) ? opts[:persistent] : options[:persistent]
       Nanite::Log.info("SEND #{push.to_s([:tags, :target])}")
       amqp.fanout('request', :no_declare => options[:secure]).publish(serializer.dump(push))
-    end    
+    end
+
+    # Update tags registered by mapper for agent
+    def update_tags(new_tags, obsolete_tags)
+      raise "Mapper proxy not initialized" unless identity && options
+      update = TagUpdate.new(identity, new_tags, obsolete_tags)
+      Nanite::Log.info("SEND #{update.to_s}")
+      amqp.fanout('registration', :no_declare => options[:secure]).publish(serializer.dump(update))
+    end
     
     # Handle intermediary result
     def handle_intermediate_result(res)

data/lib/nanite/packets.rb

@@ -112,15 +112,16 @@ module Nanite
   # payload  is arbitrary data that is transferred from mapper to actor
   #
   # Options:
-  # from     is sender identity
-  # token    is a generated request id that mapper uses to identify replies
-  # reply_to is identity of the node actor replies to, usually a mapper itself
-  # selector is the selector used to route the request
-  # target   is the target nanite for the request
+  # from      is sender identity
+  # on_behalf is agent identity that should be used to authorize request
+  # token     is a generated request id that mapper uses to identify replies
+  # reply_to  is identity of the node actor replies to, usually a mapper itself
+  # selector  is the selector used to route the request
+  # target    is the target nanite for the request
   # persistent signifies if this request should be saved to persistent storage by the AMQP broker
   class Request < Packet
 
-    attr_accessor :from, :payload, :type, :token, :reply_to, :selector, :target, :persistent, :tags
+    attr_accessor :from, :on_behalf, :payload, :type, :token, :reply_to, :selector, :target, :persistent, :tags
 
     DEFAULT_OPTIONS = {:selector => :least_loaded}
 
@@ -130,6 +131,7 @@ module Nanite
       @payload    = payload
       @size       = size
       @from       = opts[:from]
+      @on_behalf  = opts[:on_behalf]
       @token      = opts[:token]
       @reply_to   = opts[:reply_to]
       @selector   = opts[:selector]
@@ -140,15 +142,17 @@ module Nanite
 
     def self.json_create(o)
       i = o['data']
-      new(i['type'], i['payload'], { :from     => i['from'],     :token      => i['token'],
-                                     :reply_to => i['reply_to'], :selector   => i['selector'],
-                                     :target   => i['target'],   :persistent => i['persistent'],
-                                     :tags     => i['tags'] }, o['size'])
+      new(i['type'], i['payload'], { :from     => i['from'],         :on_behalf => i['on_behalf'],
+                                     :token      => i['token'],      :reply_to => i['reply_to'], 
+                                     :selector   => i['selector'],   :target   => i['target'],
+                                     :persistent => i['persistent'], :tags     => i['tags'] },
+                                   o['size'])
     end
 
     def to_s(filter=nil)
       log_msg = "#{super} <#{token}> #{type}"
       log_msg += " from #{id_to_s(from)}" if filter.nil? || filter.include?(:from)
+      log_msg += " on behalf of #{id_to_s(on_behalf)}" if on_behalf && (filter.nil? || filter.include?(:on_behalf))
       log_msg += " to #{id_to_s(target)}" if target && (filter.nil? || filter.include?(:target))
       log_msg += ", reply_to #{id_to_s(reply_to)}" if reply_to && (filter.nil? || filter.include?(:reply_to))
       log_msg += ", tags #{tags.inspect}" if tags && !tags.empty? && (filter.nil? || filter.include?(:tags))
@@ -165,14 +169,15 @@ module Nanite
   # payload  is arbitrary data that is transferred from mapper to actor
   #
   # Options:
-  # from     is sender identity
-  # token    is a generated request id that mapper uses to identify replies
-  # selector is the selector used to route the request
-  # target   is the target nanite for the request
+  # from      is sender identity
+  # on_behalf is agent identity that should be used to authorize request
+  # token     is a generated request id that mapper uses to identify replies
+  # selector  is the selector used to route the request
+  # target    is the target nanite for the request
   # persistent signifies if this request should be saved to persistent storage by the AMQP broker
   class Push < Packet
 
-    attr_accessor :from, :payload, :type, :token, :selector, :target, :persistent, :tags
+    attr_accessor :from, :on_behalf, :payload, :type, :token, :selector, :target, :persistent, :tags
 
     DEFAULT_OPTIONS = {:selector => :least_loaded}
 
@@ -182,6 +187,7 @@ module Nanite
       @payload    = payload
       @size       = size
       @from       = opts[:from]
+      @on_behalf  = opts[:on_behalf]
       @token      = opts[:token]
       @selector   = opts[:selector]
       @target     = opts[:target]
@@ -191,14 +197,17 @@ module Nanite
 
     def self.json_create(o)
       i = o['data']
-      new(i['type'], i['payload'], { :from       => i['from'],       :token  => i['token'],
-                                     :selector   => i['selector'],   :target => i['target'],
-                                     :persistent => i['persistent'], :tags   => i['tags'] }, o['size'])
+      new(i['type'], i['payload'], { :from   => i['from'],   :on_behalf  => i['on_behalf'],
+                                     :token  => i['token'],  :selector   => i['selector'],   
+                                     :target => i['target'], :persistent => i['persistent'], 
+                                     :tags   => i['tags'] },
+                                   o['size'])
     end
 
     def to_s(filter=nil)
       log_msg = "#{super} <#{token}> #{type}"
       log_msg += " from #{id_to_s(from)}" if filter.nil? || filter.include?(:from)
+      log_msg += " on behalf of #{id_to_s(on_behalf)}" if on_behalf && (filter.nil? || filter.include?(:on_behalf))
       log_msg += ", target #{id_to_s(target)}" if target && (filter.nil? || filter.include?(:target))
       log_msg += ", tags #{tags.inspect}" if tags && !tags.empty? && (filter.nil? || filter.include?(:tags))
       log_msg += ", payload #{payload.inspect}" if filter.nil? || filter.include?(:payload)
@@ -360,6 +369,33 @@ module Nanite
     end
 
   end
- 
+
+  # packet that is sent by agents to the mapper
+  # to update their tags
+  class TagUpdate < Packet
+
+    attr_accessor :identity, :new_tags, :obsolete_tags
+
+    def initialize(identity, new_tags, obsolete_tags, size=nil)
+      @identity      = identity
+      @new_tags      = new_tags
+      @obsolete_tags = obsolete_tags
+      @size          = size
+    end
+
+    def self.json_create(o)
+      i = o['data']
+      new(i['identity'], i['new_tags'], i['obsolete_tags'], o['size'])
+    end
+
+    def to_s
+      log_msg = "#{super} #{id_to_s(identity)}"
+      log_msg += ", new tags: #{new_tags.join(', ')}" if new_tags && !new_tags.empty?
+      log_msg += ", obsolete tags: #{obsolete_tags.join(', ')}" if obsolete_tags && !obsolete_tags.empty?
+      log_msg
+    end
+
+  end
+
 end