cztop 0.1.0

data/examples/taxi_system/start_broker.sh

@@ -0,0 +1,2 @@
+#!/bin/sh -x
+BROKER_ADDRESS=tcp://127.0.0.1:4455 BROKER_CERT=secret_keys/broker CLIENT_CERTS=public_keys/drivers ./broker.rb

data/examples/taxi_system/start_clients.sh

@@ -0,0 +1,11 @@
+#!/bin/sh -x
+export BROKER_ADDRESS=tcp://127.0.0.1:4455
+export BROKER_CERT=public_keys/broker
+CLIENT_CERT=secret_keys/drivers/driver1_secret ./client.rb &
+CLIENT_CERT=secret_keys/drivers/driver2_secret ./client.rb &
+CLIENT_CERT=secret_keys/drivers/driver3_secret ./client.rb &
+jobs
+jobs -p
+jobs -l
+trap 'kill $(jobs -p)' EXIT
+wait

data/lib/cztop/actor.rb

@@ -0,0 +1,308 @@
+module CZTop
+  # Represents a CZMQ::FFI::Zactor.
+  #
+  # = About Thread-Safety
+  # The instance methods of this class are thread-safe. So it's safe to call
+  # {#<<}, {#request} or even {#terminate} from different threads. Caution:
+  # Use only these methods to communicate with the low-level zactor. Don't use
+  # {Message#send_to} directly to send itself to an {Actor} instance, as it
+  # wouldn't be thread-safe.
+  #
+  # = About termination
+  # Actors should be terminated explicitly, either by calling {#terminate}
+  # from the current process or sending them the "$TERM" command (from
+  # outside). Not terminating them explicitly might make the process block at
+  # exit.
+  #
+  # @example Simple Actor with Ruby block
+  #   result = ""
+  #   a = CZTop::Actor.new do |msg, pipe|
+  #     case msg[0]
+  #     when "foo"
+  #       pipe << "bar"
+  #     when "append"
+  #       result << msg[1].to_s
+  #     when "result"
+  #       pipe << result
+  #     end
+  #   end
+  #   a.request("foo")[0] #=> "bar"
+  #   a.request("foo")[0] #=> "bar"
+  #   a << ["append", "baz"] << ["append", "baz"]
+  #   a.request("result")[0] #=> "bazbaz"
+  #
+  # @see http://api.zeromq.org/czmq3-0:zactor
+  class Actor
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+    include ZsockOptions
+    include SendReceiveMethods
+    include PolymorphicZsockMethods
+    include ::CZMQ::FFI
+
+    # Raised when trying to interact with a terminated actor.
+    class DeadActorError < RuntimeError; end
+
+    # @return [Exception] the exception that crashed this actor, if any
+    attr_reader :exception
+
+    # Creates a new actor. Either pass a callback directly or a block. The
+    # block will be called for every received message.
+    #
+    # In case the given callback is an FFI::Pointer (to a C function), it's
+    # used as-is. It is expected to do the handshake (signal) itself.
+    #
+    # @param callback [FFI::Pointer, Proc, #call] pointer to a C function or
+    #   just anything callable
+    # @param c_args [FFI::Pointer, nil] args, only useful if callback is an
+    #   FFI::Pointer
+    # @yieldparam message [Message]
+    # @yieldparam pipe [Socket::PAIR]
+    # @see #process_messages
+    def initialize(callback = nil, c_args = nil, &handler)
+      @running = true
+      @mtx = Mutex.new
+      @callback = callback || handler
+      @callback = shim(@callback) unless @callback.is_a? ::FFI::Pointer
+      ffi_delegate = Zactor.new(@callback, c_args)
+      attach_ffi_delegate(ffi_delegate)
+      options.sndtimeo = 20#ms # see #<<
+    end
+
+    # Send a message to the actor.
+    # @param message [Object] message to send to the actor, see {Message.coerce}
+    # @return [self] so it's chainable
+    # @raise [DeadActorError] if actor is terminated
+    # @raise [IO::EAGAINWaitWritable, RuntimeError] anything that could be
+    #   raised by {Message#send_to}
+    # @note Normally this method is asynchronous, but if the message is
+    #   "$TERM", it blocks until the actor is terminated.
+    def <<(message)
+      message = Message.coerce(message)
+
+      if TERM == message[0]
+        # NOTE: can't just send this to the actor. The sender might call
+        # #terminate immediately, which most likely causes a hang due to race
+        # conditions.
+        terminate
+      else
+        begin
+          @mtx.synchronize do
+            raise DeadActorError if not @running
+            message.send_to(self)
+          end
+        rescue IO::EAGAINWaitWritable
+          # The sndtimeo has been reached.
+          #
+          # This should fix the race condition (mainly on JRuby) between
+          # @running not being set to false yet but the actor handler already
+          # terminating and thus not able to receive messages anymore.
+          #
+          # This shouldn't result in an infinite loop, since it'll stop as
+          # soon as @running is set to false by #signal_shimmed_handler_death,
+          # at least when using a Ruby handler.
+          #
+          # In case of a C function handler, it MUST NOT crash and only
+          # terminate when being sent the "$TERM" message using #terminate (so
+          # #await_handler_death can set
+          # @running to false).
+          retry
+        end
+      end
+      self
+    end
+
+    # Receive a message from the actor.
+    # @return [Message]
+    # @raise [DeadActorError] if actor is terminated
+    def receive
+      @mtx.synchronize do
+        raise DeadActorError if not @running
+        super
+      end
+    end
+
+    # Same as {#<<}, but also waits for a response from the actor and returns
+    # it.
+    # @param message [Message] the request to the actor
+    # @return [Message] the actor's response
+    # @raise [ArgumentError] if the message is "$TERM" (use {#terminate})
+    def request(message)
+      @mtx.synchronize do
+        raise DeadActorError if not @running
+        message = Message.coerce(message)
+        raise ArgumentError, "use #terminate" if TERM == message[0]
+        message.send_to(self)
+        Message.receive_from(self)
+      end
+    rescue IO::EAGAINWaitWritable
+      # same as in #<<
+      retry
+    end
+
+    # Sends a message according to a "picture".
+    # @see zsock_send() on http://api.zeromq.org/czmq3-0:zsock
+    # @note Mainly added for {Beacon}. If implemented there, it wouldn't be
+    #   thread safe. And it's not that useful to be added to
+    #   {SendReceiveMethods}.
+    # @param picture [String] message's part types
+    # @param args [String, Integer, ...] values, in FFI style (each one
+    #   preceeded with it's type, like <tt>:string, "foo"</tt>)
+    # @return [void]
+    def send_picture(picture, *args)
+      @mtx.synchronize do
+        raise DeadActorError if not @running
+        Zsock.send(ffi_delegate, picture, *args)
+      end
+    end
+
+    # Thread-safe {PolymorphicZsockMethods#wait}.
+    # @return [Integer]
+    def wait
+      @mtx.synchronize do
+        super
+      end
+    end
+
+    # Tells the actor to terminate and waits for it. Idempotent.
+    # @return [Boolean] whether it died just now (+false+ if it was dead
+    #   already)
+    def terminate
+      term_msg = Message.new(TERM)
+      @mtx.synchronize do
+        return false if not @running
+        term_msg.send_to(self)
+        await_handler_death
+        true
+      end
+    rescue IO::EAGAINWaitWritable
+      # same as in #<<
+      retry
+    end
+
+    # @return [Boolean] whether this actor is dead (terminated or crashed)
+    def dead?
+      !@running
+    end
+
+    # @return [Boolean] whether this actor has crashed
+    # @see #exception
+    def crashed?
+      !!@exception # if set, it has crashed
+    end
+
+    private
+
+    # Shims the given handler. The shim is used to do the handshake, to
+    # {#process_messages}, and ensure we're notified when the handler has
+    # terminated.
+    #
+    # @param handler [Proc, #call] the handler used to process messages
+    # @return [FFI::Function] the callback function to be passed to the zactor
+    # @raise [ArgumentError] if invalid handler given
+    def shim(handler)
+      raise ArgumentError, "invalid handler" if !handler.respond_to?(:call)
+
+      @handler_thread = nil
+      @handler_dead_signal = Queue.new # used for signaling
+
+      Zactor.fn do |pipe_delegate, _args|
+        begin
+          @mtx.synchronize do
+            @handler_thread = Thread.current
+            @pipe = Socket::PAIR.from_ffi_delegate(pipe_delegate)
+            @pipe.signal # handshake, so zactor_new() returns
+          end
+          process_messages(handler)
+        rescue Exception
+          @exception = $!
+        ensure
+          signal_shimmed_handler_death
+        end
+      end
+    end
+
+    # @return [Boolean] whether the handler is a Ruby object, like a simple
+    #   block (as opposed to a FFI::Pointer to a C function)
+    def handler_shimmed?
+      !!@handler_thread # if it exists, it's shimmed
+    end
+
+    # the command which causes an actor handler to terminate
+    TERM = "$TERM"
+
+    # Successively receive messages that were sent to the actor and
+    # yield them to the given handler to process them. The a pipe (a
+    # {Socket::PAIR} socket) is also passed to the handler so it can send back
+    # the result of a command, if needed.
+    #
+    # When a message is "$TERM", or when the waiting for a message is
+    # interrupted, execution is aborted and the actor will terminate.
+    #
+    # @param handler [Proc, #call] the handler used to process messages
+    # @yieldparam message [Message] message (e.g. command) received
+    # @yieldparam pipe [Socket::PAIR] pipe to write back something into the
+    #   actor
+    def process_messages(handler)
+      while true
+        begin
+          message = next_message
+        rescue Interrupt
+          break
+        else
+          break if TERM == message[0]
+        end
+
+        handler.call(message, @pipe)
+      end
+    end
+
+    # Receives the next message even across any interrupts.
+    # @return [Message] the next message
+    def next_message
+      @pipe.receive
+    end
+
+    # Creates a new thread that will signal the definitive termination of the
+    # Ruby handler.
+    #
+    # This is needed to avoid the race condition between zactor_destroy()
+    # which will wait for a signal from the handler in case it was able to
+    # send the "$TERM" command, and the @callback which might still haven't
+    # returned, but doesn't receive any messages anymore.
+    #
+    # @return [void]
+    def signal_shimmed_handler_death
+      # NOTE: can't just use ConditionVariable, as the signaling code might be
+      # run BEFORE the waiting code.
+
+      Thread.new do
+        @handler_thread.join
+
+        # NOTE: we do this here and not in #terminate, so it also works when
+        # actor isn't terminated using #terminate
+        @running = false
+
+        @handler_dead_signal.push(nil)
+      end
+    end
+
+    # Waits for the C or Ruby handler to die.
+    # @return [void]
+    def await_handler_death
+      if handler_shimmed?
+        # for Ruby block/Proc object handlers
+        @handler_dead_signal.pop
+
+      else
+        # for handlers that are passed as C functions, we rely on normal death
+        # signal
+
+        # can't use #wait here because of recursive deadlock
+        Zsock.wait(ffi_delegate)
+
+        @running = false
+      end
+    end
+  end
+end

data/lib/cztop/authenticator.rb

@@ -0,0 +1,97 @@
+module CZTop
+
+  # Authentication for ZeroMQ security mechanisms.
+  #
+  # This is implemented using an {Actor}.
+  #
+  # @see http://api.zeromq.org/czmq3-0:zauth
+  class Authenticator
+    include ::CZMQ::FFI
+
+    # function pointer to the `zauth()` function
+    ZAUTH_FPTR = ::CZMQ::FFI.ffi_libraries.each do |dl|
+      fptr = dl.find_function("zauth")
+      break fptr if fptr
+    end
+    raise LoadError, "couldn't find zauth()" if ZAUTH_FPTR.nil?
+
+    # This installs authentication on all {Socket}s and {Actor}s. Until you
+    # add policies, all incoming _NULL_ connections are allowed,
+    # and all _PLAIN_ and _CURVE_ connections are denied.
+    def initialize
+      @actor = Actor.new(ZAUTH_FPTR)
+    end
+
+    # @return [Actor] the actor behind this authenticator
+    attr_reader :actor
+
+    # Terminates the authenticator.
+    # @return [void]
+    def terminate
+      @actor.terminate
+    end
+
+    # Enable verbose logging of commands and activity.
+    # @return [void]
+    def verbose!
+      @actor << "VERBOSE"
+      @actor.wait
+    end
+
+    # Add a list of IP addresses to the whitelist. For _NULL_, all clients
+    # from these addresses will be accepted. For _PLAIN_ and _CURVE_, they
+    # will be allowed to continue with authentication.
+    #
+    # @param addrs [String] IP address(es) to allow
+    # @return [void]
+    def allow(*addrs)
+      @actor << ["ALLOW", *addrs]
+      @actor.wait
+    end
+
+    # Add a list of IP addresses to the blacklist. For all security
+    # mechanisms, this rejects the connection without any further
+    # authentication. Use either a whitelist, or a blacklist, not not both. If
+    # you define both a whitelist and a blacklist, only the whitelist takes
+    # effect.
+    #
+    # @param addrs [String] IP address(es) to deny
+    # @return [void]
+    def deny(*addrs)
+      @actor << ["DENY", *addrs]
+      @actor.wait
+    end
+
+    # Configure PLAIN security mechanism using a plain-text password file. The
+    # password file will be reloaded automatically if modified externally.
+    #
+    # @param filename [String] path to the password file
+    # @return [void]
+    def plain(filename)
+      @actor << ["PLAIN", *filename]
+      @actor.wait
+    end
+
+    ANY_CERTIFICATE = "*"
+
+    # Configure CURVE authentication, using a directory that holds all public
+    # client certificates, i.e. their public keys. The certificates must have been
+    # created using {Certificate#save}/{Certificate#save_public}. You can add
+    # and remove certificates in that directory at any time.
+    #
+    # @param directory [String] the directory to take the keys from (the
+    #   default value will allow any certificate)
+    # @return [void]
+    def curve(directory = ANY_CERTIFICATE)
+      @actor << ["CURVE", directory]
+      @actor.wait
+    end
+
+    # Configure GSSAPI authentication.
+    # @return [void]
+    def gssapi
+      @actor << "GSSAPI"
+      @actor.wait
+    end
+  end
+end

data/lib/cztop/beacon.rb

@@ -0,0 +1,96 @@
+module CZTop
+  # Used for LAN discovery and presence.
+  #
+  # This is implemented using an {Actor}.
+  #
+  # @see http://api.zeromq.org/czmq3-0:zbeacon
+  class Beacon
+    include ::CZMQ::FFI
+
+    # function pointer to the `zbeacon()` function
+    ZBEACON_FPTR = ::CZMQ::FFI.ffi_libraries.each do |dl|
+      fptr = dl.find_function("zbeacon")
+      break fptr if fptr
+    end
+    raise LoadError, "couldn't find zbeacon()" if ZBEACON_FPTR.nil?
+
+    # Initialize new Beacon.
+    def initialize
+      @actor = Actor.new(ZBEACON_FPTR)
+    end
+
+    # @return [Actor] the actor behind this Beacon
+    attr_reader :actor
+
+    # Terminates the beacon.
+    # @return [void]
+    def terminate
+      @actor.terminate
+    end
+
+    # Enable verbose logging of commands and activity.
+    # @return [void]
+    def verbose!
+      @actor << "VERBOSE"
+    end
+
+    # Run the beacon on the specified UDP port.
+    # @param port [Integer] port number to
+    # @return [String] hostname, which can be used as endpoint for incoming
+    #   connections
+    # @raise [SystemCallError] if the system doesn't support UDP broadcasts
+    def configure(port)
+      @actor.send_picture("si", :string, "CONFIGURE", :int, port)
+      hostname = Zstr.recv(@actor)
+      return hostname unless hostname.empty?
+      raise NotImplementedError, "system doesn't support UDP broadcasts"
+    end
+
+    # @return [Integer] maximum length of data to {#publish}
+    MAX_BEACON_DATA = 255
+
+    # Start broadcasting a beacon.
+    # @param data [String] data to publish
+    # @param interval [Integer] interval in msec
+    # @raise [ArgumentError] if data is longer than {MAX_BEACON_DATA} bytes
+    # @return [void]
+    def publish(data, interval)
+      raise ArgumentError, "data too long" if data.bytesize > MAX_BEACON_DATA
+      @actor.send_picture("sbi", :string, "PUBLISH", :string, data,
+                              :int, data.bytesize, :int, interval)
+    end
+
+    # Stop broadcasting the beacon.
+    # @return [void]
+    def silence
+      @actor << "SILENCE"
+    end
+
+    # Start listening to beacons from peers.
+    # @param filter [String] do a prefix match on received beacons
+    # @return [void]
+    def subscribe(filter)
+      @actor.send_picture("sb", :string, "SUBSCRIBE",
+                          :string, filter, :int, filter.bytesize)
+    end
+
+    # Just like {#subscribe}, but subscribe to all peer beacons.
+    # @return [void]
+    def listen
+      @actor.send_picture("sb", :string, "SUBSCRIBE",
+                          :string, nil, :int, 0)
+    end
+
+    # Stop listening to other peers.
+    # @return [void]
+    def unsubscribe
+      @actor << "UNSUBSCRIBE"
+    end
+
+    # Receive next beacon from a peer.
+    # @return [Message] 2-frame message with ([ipaddr, data])
+    def receive
+      @actor.receive
+    end
+  end
+end

data/lib/cztop/certificate.rb

@@ -0,0 +1,176 @@
+module CZTop
+  # Represents a CZMQ::FFI::Zcert.
+  class Certificate
+    include HasFFIDelegate
+    extend CZTop::HasFFIDelegate::ClassMethods
+    include ::CZMQ::FFI
+
+    # Warns if CURVE security isn't available.
+    # @return [void]
+    def self.check_curve_availability
+      return if Zproc.has_curve
+      warn "CZTop: CURVE isn't available. Consider installing libsodium."
+    end
+
+    # Loads a certificate from a file.
+    # @param filename [String, Pathname, #to_s] path to certificate file
+    # @return [Certificate] the loaded certificate
+    def self.load(filename)
+      ptr = Zcert.load(filename.to_s)
+      from_ffi_delegate(ptr)
+    end
+
+    # Creates a new certificate from the given keys.
+    # @param public_key [String] binary public key (32 bytes)
+    # @param secret_key [String] binary secret key (32 bytes)
+    # @return [Certificate] the fresh certificate
+    # @raise [ArgumentError] if keys passed are invalid
+    # @raise [SystemCallError] if this fails
+    def self.new_from(public_key, secret_key)
+      raise ArgumentError, "no public key given" unless public_key
+      raise ArgumentError, "no secret key given" unless secret_key
+
+      raise ArgumentError, "invalid public key size" if public_key.bytesize != 32
+      raise ArgumentError, "invalid secret key size" if secret_key.bytesize != 32
+
+      ptr = Zcert.new_from(public_key, secret_key)
+      from_ffi_delegate(ptr)
+    end
+
+    # Initialize a new in-memory certificate with random keys.
+    def initialize
+      attach_ffi_delegate(Zcert.new)
+    end
+
+    # Returns the public key either as Z85-encoded ASCII string (default) or
+    # binary string.
+    # @param format [Symbol] +:z85+ for Z85, +:binary+ for binary
+    # @return [String] public key
+    def public_key(format: :z85)
+      case format
+      when :z85
+        ffi_delegate.public_txt.read_string.force_encoding(Encoding::ASCII)
+      when :binary
+        ffi_delegate.public_key.read_string(32)
+      else
+        raise ArgumentError, "invalid format: %p" % format
+      end
+    end
+
+    # Returns the secret key either as Z85-encoded ASCII string (default) or
+    # binary string.
+    # @param format [Symbol] +:z85+ for Z85, +:binary+ for binary
+    # @return [String] secret key
+    # @return [nil] if secret key is undefined (like after loading from a file
+    #   created using {#save_public})
+    def secret_key(format: :z85)
+      case format
+      when :z85
+        key = ffi_delegate.secret_txt.read_string.force_encoding(Encoding::ASCII)
+        return nil if key.count("0") == 40
+      when :binary
+        key = ffi_delegate.secret_key.read_string(32)
+        return nil if key.count("\0") == 32
+      else
+        raise ArgumentError, "invalid format: %p" % format
+      end
+      key
+    end
+
+    # Get metadata.
+    # @param key [String] metadata key
+    # @return [String] value for meta key
+    # @return [nil] if metadata key is not set
+    def [](key)
+      ptr = ffi_delegate.meta(key)
+      return nil if ptr.null?
+      ptr.read_string
+    end
+    # Set metadata.
+    # @param key [String] metadata key
+    # @param value [String] metadata value
+    # @return [value]
+    def []=(key, value)
+      if value
+        ffi_delegate.set_meta(key, "%s", :string, value)
+      else
+        ffi_delegate.unset_meta(key)
+      end
+    end
+
+    # Returns meta keys set.
+    # @return [Array<String>]
+    def meta_keys
+      zlist = ffi_delegate.meta_keys
+      first_key = zlist.first
+      return [] if first_key.null?
+      keys = [first_key.read_string]
+      while key = zlist.next
+        break if key.null?
+        keys << key.read_string
+      end
+      keys
+    end
+
+    # Save full certificate (public + secret) to files.
+    # @param filename [String, #to_s] path/filename to public file
+    # @return [void]
+    # @raise [ArgumentError] if path is invalid
+    # @raise [SystemCallError] if this fails
+    # @note This will create two files: one of the public key and one for the
+    #   secret key. The secret filename is filename + "_secret".
+    def save(filename)
+      # see https://github.com/zeromq/czmq/issues/1244
+      raise ArgumentError, "filename can't be empty" if filename.to_s.empty?
+      rc = ffi_delegate.save(filename.to_s)
+      return if rc == 0
+      raise_zmq_err("error while saving to file %p" % filename)
+    end
+
+    # Saves the public key to file in ZPL ({Config}) format.
+    # @param filename [String, #to_s] path/filename to public file
+    # @return [void]
+    # @raise [SystemCallError] if this fails
+    def save_public(filename)
+      rc = ffi_delegate.save_public(filename.to_s)
+      return if rc == 0
+      raise_zmq_err("error while saving to the file %p" % filename)
+    end
+
+    # Saves the secret key to file in ZPL ({Config}) format.
+    # @param filename [String, #to_s] path/filename to secret file
+    # @return [void]
+    # @raise [SystemCallError] if this fails
+    def save_secret(filename)
+      rc = ffi_delegate.save_secret(filename.to_s)
+      return if rc == 0
+      raise_zmq_err("error while saving to the file %p" % filename)
+    end
+
+    # Applies this certificate on a {Socket} or {Actor}.
+    # @param zocket [Socket, Actor] path/filename to secret file
+    # @return [void]
+    # @raise [SystemCallError] if secret key is undefined
+    def apply(zocket)
+      raise ArgumentError, "invalid zocket argument %p" % zocket unless zocket
+      return ffi_delegate.apply(zocket) unless secret_key.nil?
+      raise_zmq_err("secret key is undefined")
+    end
+
+    # Duplicates the certificate.
+    # @return [Certificate]
+    # @raise [SystemCallError] if this fails
+    def dup
+      ptr = ffi_delegate.dup
+      return from_ffi_delegate(ptr) unless ptr.null?
+      raise_zmq_err("unable to duplicate certificate")
+    end
+
+    # Compares this certificate to another.
+    # @param other [Cert] other certificate
+    # @return [Boolean] whether they have the same keys
+    def ==(other)
+      ffi_delegate.eq(other.ffi_delegate)
+    end
+  end
+end