cztop 0.1.0

data/examples/ruby_actor/actor.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+
+##
+# This example shows how to create a simple actor using a Ruby block.
+# Of course it also supports the CZMQ-native way, passing a pointer to
+# a C function. That's how CZTop::Beacon, CZTop::Authenticator, ... are
+# implemented.
+#
+
+counter = 0
+actor = CZTop::Actor.new do |msg, pipe|
+  # This block is called once for every received message.
+
+  case command = msg[0]
+  when "UPCASE"
+    # Upcase second message frame and send back.
+    word = msg[1]
+    puts ">>> Actor converts #{word.inspect} to uppercase."
+    pipe << word.upcase
+  when "COUNT"
+    # Count up.
+    counter += 1
+    puts ">>> Actor has incremented counter to: #{counter}"
+  when "PRODUCE"
+    # Produce multiple messages.
+    num = msg[1].to_i
+    puts ">>> Actor produces #{num} messages."
+    num.times { |i| pipe << "FOO #{i+1}/#{num}" }
+  else
+    # crashes actor #=> Actor#dead? and Actor#crashed? will return true
+    # also, Actor#exception will return this exception.
+    raise "invalid command: #{command}"
+  end
+end
+puts ">>> Actor created."
+
+##
+# Let actor count.
+#
+# Actor#<< is thread-safe.
+#
+actor << "COUNT"
+actor << "COUNT"
+actor << "COUNT"
+actor << "COUNT"
+actor << "COUNT"
+actor << "COUNT"
+
+
+##
+# Request a response from actor.
+#
+# Actor#request is thread-safe and ensures that the right response gets
+# returned.
+#
+puts actor.request(["UPCASE", "foobar"]).inspect
+#=> #<CZTop::Message:0x7f98c8d96000 frames=1 content_size=6 content=["FOOBAR"]>
+
+
+##
+# Let actor produce some messages.
+#
+# Actor#receive is thread-safe, but doesn't guarantee any particular order.
+#
+actor << %w[ PRODUCE 5 ]
+puts actor.receive[0] #1
+puts actor.receive[0] #2
+puts actor.receive[0] #3
+puts actor.receive[0] #4
+puts actor.receive[0] #5
+
+##
+# Let actor die.
+#
+# Blocks until dead.
+actor.terminate
+actor.dead? #=> true
+actor.crashed? #=> false
+actor.exception #=> nil, because it didn't crash
+
+
+__END__
+Example output:
+
+>>> Actor created.
+>>> Actor has incremented counter to: 1
+>>> Actor has incremented counter to: 2
+>>> Actor has incremented counter to: 3
+>>> Actor has incremented counter to: 4
+>>> Actor has incremented counter to: 5
+>>> Actor has incremented counter to: 6
+>>> Actor converts "foobar" to uppercase.
+#<CZTop::Message:0x7f81c55bdca0 frames=1 content_size=6 content=["FOOBAR"]>
+>>> Actor produces 5 messages.
+FOO 1/5
+FOO 2/5
+FOO 3/5
+FOO 4/5
+FOO 5/5

data/examples/simple_req_rep/rep.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+
+# create and bind socket
+socket = CZTop::Socket::REP.new("ipc:///tmp/req_rep_example")
+puts "<<< Socket bound to #{socket.last_endpoint.inspect}"
+
+# Simply echo every message, with every frame String#upcase'd.
+while msg = socket.receive
+  puts "<<< #{msg.to_a.inspect}"
+  socket << msg.to_a.map(&:upcase)
+end

data/examples/simple_req_rep/req.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+
+# connect
+socket = CZTop::Socket::REQ.new("ipc:///tmp/req_rep_example")
+puts ">>> Socket connected."
+
+# simple string
+socket << "foobar"
+msg = socket.receive
+puts ">>> #{msg.to_a.inspect}"
+
+# multi frame message as array
+socket << %w[foo bar baz]
+msg = socket.receive
+puts ">>> #{msg.to_a.inspect}"
+
+# manually instantiating a Message
+msg = CZTop::Message.new("bla")
+msg << "another frame" # append a frame
+socket << msg
+msg = socket.receive
+puts ">>> #{msg.to_a.inspect}"
+
+##
+# This will send 20 additional messages:
+#
+#   ./req.rb 20
+#
+if ARGV.first
+  ARGV.first.to_i.times do
+    socket << ["fooooooooo", "baaaaaar"]
+    puts ">>> " + socket.receive.to_a.inspect
+  end
+end

data/examples/taxi_system/.gitignore

@@ -0,0 +1,2 @@
+secret_keys/
+public_keys/

data/examples/taxi_system/Makefile

@@ -0,0 +1,2 @@
+README.md: README.gsl generate_keys.rb broker.rb client.rb start_broker.sh start_clients.sh
+	gsl README

data/examples/taxi_system/README.gsl

@@ -0,0 +1,115 @@
+.output "README.md"
+.template 1
+# Taxi System
+
+Suppose you're running a taxi company. You have a set of taxi drivers
+working for you.  You'd like to connect them to your central server, so they're
+ready to get service requests from customers who'd like to get picked up by a
+taxi from some place X. As soon as a customer sends his service request, the
+central server will send the closest taxi nearby that's available to the
+customer.
+
+Of course you want the communication between the broker and the taxi drivers to
+be secure, meaning you want encryption and authentication.
+
+You also want ping-pong heartbeating, as you want to have confidence you can
+get in touch with your taxi drivers any time you want. And if a service
+request can't be delivered to a particular taxi driver, you wanna know
+immediately.
+
+This solution is implemented using CLIENT/SERVER sockets and the CURVE
+security mechanism.
+
+## Broker
+
+Here's a possible implementation of the broker. What you'll have to provide
+are the environment variables `BROKER_ADDRESS` (the public TCP endpoint),
+`BROKER_CERT` (path to the broker's secret+public keys), and `CLIENT_CERTS`
+(directory to taxi drivers' certificates, public keys only).
+
+After the start, the broker will just start listening for the drivers (CLIENT
+sockets) to connect. After a driver has connected, authenticated, and sent its
+`HELLO` message, the broker answers with a `WELCOME` or `WELCOMEBACK` message,
+depending if the driver was connected before (it might have reconnected and
+been assigned a new routing ID).
+
+The broker will present you with a Pry shell. Right before starting the shell,
+there's a small usage information, but it's not very well visible due to Pry's
+noisy start. It's simple, though. Inside that shell, you can use the method
+`#send_command(driver, command)`. Example:
+
+```
+  pry> send_command("driver1", "foobar")
+```
+
+Depending on whether the driver is connected, it'll send the message or report
+that it cannot do so.
+
+```ruby
+.literal from "broker.rb"
+```
+
+## Client
+
+Here you have to provide the environment variables `BROKER_ADDRESS` (ditto),
+`BROKER_CERT` (public key only), `CLIENT_CERT` (taxi driver's certificate
+containing the secret+public keys).
+
+After connecting to the broker and completing the security handshake, the
+client sends a `HELLO` message, after which it immediately expects some answer
+from the broker (see above). After that, it just listens for messages (service
+requests) and prints them into the terminal.
+
+```ruby
+.literal from "client.rb"
+```
+
+## How to run the example
+
+### Generate broker's and drivers' keys
+
+Here's a simple script that'll create the broker's certificate and the taxi
+drivers' certificates. There are also public key only files so a minimum amount
+of information can be made available on one system, e.g. a taxi driver's system
+must not know the broker's secret key. Also, the broker doesn't necessarily
+need to know the clients' secret keys just to authenticate them.
+
+```ruby
+.literal from "generate_keys.rb"
+
+```
+Run it as follows:
+
+```
+\./generate_keys.rb
+```
+
+### Start broker
+
+Run this:
+
+```
+\./start_broker.sh
+```
+
+which will execute the following script:
+
+```sh
+.literal from "start_broker.sh"
+```
+
+### Start driver software instances
+
+Run this in another terminal:
+
+```
+\./start_clients.sh
+```
+
+which will execute the following script:
+
+```sh
+.literal from "start_clients.sh"
+```
+
+.endtemplate

data/examples/taxi_system/README.md

@@ -0,0 +1,276 @@
+# Taxi System
+
+Suppose you're running a taxi company. You have a set of taxi drivers
+working for you.  You'd like to connect them to your central server, so they're
+ready to get service requests from customers who'd like to get picked up by a
+taxi from some place X. As soon as a customer sends his service request, the
+central server will send the closest taxi nearby that's available to the
+customer.
+
+Of course you want the communication between the broker and the taxi drivers to
+be secure, meaning you want encryption and authentication.
+
+You also want ping-pong heartbeating, as you want to have confidence you can
+get in touch with your taxi drivers any time you want. And if a service
+request can't be delivered to a particular taxi driver, you wanna know
+immediately.
+
+This solution is implemented using CLIENT/SERVER sockets and the CURVE
+security mechanism.
+
+## Broker
+
+Here's a possible implementation of the broker. What you'll have to provide
+are the environment variables `BROKER_ADDRESS` (the public TCP endpoint),
+`BROKER_CERT` (path to the broker's secret+public keys), and `CLIENT_CERTS`
+(directory to taxi drivers' certificates, public keys only).
+
+After the start, the broker will just start listening for the drivers (CLIENT
+sockets) to connect. After a driver has connected, authenticated, and sent its
+`HELLO` message, the broker answers with a `WELCOME` or `WELCOMEBACK` message,
+depending if the driver was connected before (it might have reconnected and
+been assigned a new routing ID).
+
+The broker will present you with a Pry shell. Right before starting the shell,
+there's a small usage information, but it's not very well visible due to Pry's
+noisy start. It's simple, though. Inside that shell, you can use the method
+`#send_command(driver, command)`. Example:
+
+```
+  pry> send_command("driver1", "foobar")
+```
+
+Depending on whether the driver is connected, it'll send the message or report
+that it cannot do so.
+
+```ruby
+#!/usr/bin/env ruby
+require 'pry'
+require 'pathname'
+require_relative '../../lib/cztop'
+
+endpoint = ENV["BROKER_ADDRESS"]
+broker_cert = CZTop::Certificate.load ENV["BROKER_CERT"] # secret+public
+client_certs = ENV["CLIENT_CERTS"] # /path/to/client_certs/
+drivers = Pathname.new(client_certs).children.map(&:basename).map(&:to_s)
+
+authenticator = CZTop::Authenticator.new
+authenticator.verbose!
+authenticator.curve(client_certs)
+
+# create and bind socket
+@socket = CZTop::Socket::SERVER.new
+@socket.CURVE_server!(broker_cert)
+#socket.options.sndtimeo = 0
+@socket.options.heartbeat_ivl     = 100#ms
+@socket.options.heartbeat_timeout = 300#ms
+@socket.bind(endpoint)
+
+puts ">>> Socket bound to #{endpoint.inspect}"
+
+# get and print socket events
+Thread.new do
+  monitor = CZTop::Monitor.new(@socket)
+  monitor.listen("ALL")
+  monitor.start
+  while msg = monitor.next
+    puts ">>> Socket event: #{msg.inspect}"
+  end
+end
+
+# receive messages from drivers
+@driver_map = {} # driver name => routing ID
+Thread.new do
+
+  # CZTop::Loop (zloop) doesn't work with SERVER sockets :(
+  poller = CZTop::Poller.new(@socket)
+  while true
+    puts "waiting for socket to become readable ..."
+    socket = poller.wait
+    puts "socket is readable"
+    msg = socket.receive
+    puts "got message"
+    command, argument = msg[0].split("\t", 2)
+
+    case command
+    when "HELLO"
+      driver = argument
+      puts ">>> Driver #{driver.inspect} has connected."
+      welcome = @driver_map.key?(driver) ? "WELCOMEBACK" : "WELCOME"
+
+      # remember driver's assigned message routing ID
+      @driver_map[driver] = msg.routing_id
+
+      # send WELCOME or WELCOMEBACK
+      rep = CZTop::Message.new(welcome)
+      rep.routing_id = @driver_map[driver]
+      socket << rep
+      puts ">>> Sent #{welcome.inspect} to #{driver.inspect}"
+    end
+  end
+end
+
+def send_command(driver, command)
+  if command.nil? || command.empty?
+    puts "!!! No message given."
+    return
+  end
+  if not @driver_map.key?(driver)
+    puts "!!! Driver #{driver.inspect} has never connected."
+    return
+  end
+  puts ">>> Sending message to #{driver.inspect} ..."
+  msg = CZTop::Message.new(command)
+  msg.routing_id = @driver_map[driver]
+  @socket << msg
+rescue SocketError
+  puts "!!! Driver #{driver.inspect} isn't connected anymore."
+end
+
+##
+# REPL for user to play
+#
+puts <<MSG
+You can now send messages to the drivers yourself.
+The use the method #send_command, like this:
+
+pry> send_command("driver1", "PICKUP\t(8.541694,47.376887)")
+
+This should show something like this in the client.rb terminal:
+
+  03:17:01 driver1.1 | received message: "PICKUP\t(8.541694,47.376887)"
+MSG
+
+binding.pry
+```
+
+## Client
+
+Here you have to provide the environment variables `BROKER_ADDRESS` (ditto),
+`BROKER_CERT` (public key only), `CLIENT_CERT` (taxi driver's certificate
+containing the secret+public keys).
+
+After connecting to the broker and completing the security handshake, the
+client sends a `HELLO` message, after which it immediately expects some answer
+from the broker (see above). After that, it just listens for messages (service
+requests) and prints them into the terminal.
+
+```ruby
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+
+endpoint = ENV["BROKER_ADDRESS"]
+broker_cert = CZTop::Certificate.load ENV["BROKER_CERT"] # public only
+client_cert = CZTop::Certificate.load ENV["CLIENT_CERT"]
+
+@socket = CZTop::Socket::CLIENT.new
+@socket.CURVE_client!(client_cert, broker_cert)
+@socket.options.sndtimeo     = 2000#ms
+
+# heartbeating:
+# * send PING every 100ms
+# * close connection after 300ms of no life sign from broker
+# * tell broker to close connection after 500ms of no life sign from client
+@socket.options.heartbeat_ivl     = 100#ms
+@socket.options.heartbeat_timeout = 300#ms
+@socket.options.heartbeat_ttl     = 500#ms
+
+@socket.connect(endpoint)
+puts ">>> connected."
+
+# tell broker who we are
+@socket << "HELLO\t#{client_cert["driver_name"]}"
+puts ">>> sent HELLO."
+welcome = @socket.receive[0]
+puts ">>> got #{welcome}."
+
+poller = CZTop::Poller.new(@socket)
+while true
+  socket = poller.wait
+  message = socket.receive
+  puts ">>> received message: #{message[0].inspect}"
+end
+```
+
+## How to run the example
+
+### Generate broker's and drivers' keys
+
+Here's a simple script that'll create the broker's certificate and the taxi
+drivers' certificates. There are also public key only files so a minimum amount
+of information can be made available on one system, e.g. a taxi driver's system
+must not know the broker's secret key. Also, the broker doesn't necessarily
+need to know the clients' secret keys just to authenticate them.
+
+```ruby
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+require 'fileutils'
+FileUtils.cd(File.dirname(__FILE__))
+FileUtils.mkdir "public_keys"
+FileUtils.mkdir "public_keys/drivers"
+FileUtils.mkdir "secret_keys"
+FileUtils.mkdir "secret_keys/drivers"
+#FileUtils.mkdir "certs/drivers"
+
+DRIVERS = %w[ driver1 driver2 driver3 ]
+
+# broker certificate
+cert = CZTop::Certificate.new
+cert.save("secret_keys/broker")
+cert.save_public("public_keys/broker")
+
+# driver certificates
+DRIVERS.each do |driver_name|
+  cert = CZTop::Certificate.new
+  cert["driver_name"] = driver_name
+  cert.save "secret_keys/drivers/#{driver_name}"
+  cert.save_public "public_keys/drivers/#{driver_name}"
+end
+
+```
+Run it as follows:
+
+```
+./generate_keys.rb
+```
+
+### Start broker
+
+Run this:
+
+```
+./start_broker.sh
+```
+
+which will execute the following script:
+
+```sh
+#!/bin/sh -x
+BROKER_ADDRESS=tcp://127.0.0.1:4455 BROKER_CERT=secret_keys/broker CLIENT_CERTS=public_keys/drivers ./broker.rb
+```
+
+### Start driver software instances
+
+Run this in another terminal:
+
+```
+./start_clients.sh
+```
+
+which will execute the following script:
+
+```sh
+#!/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/examples/taxi_system/broker.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+require 'pry'
+require 'pathname'
+require_relative '../../lib/cztop'
+
+endpoint = ENV["BROKER_ADDRESS"]
+broker_cert = CZTop::Certificate.load ENV["BROKER_CERT"] # secret+public
+client_certs = ENV["CLIENT_CERTS"] # /path/to/client_certs/
+drivers = Pathname.new(client_certs).children.map(&:basename).map(&:to_s)
+
+authenticator = CZTop::Authenticator.new
+authenticator.verbose!
+authenticator.curve(client_certs)
+
+# create and bind socket
+@socket = CZTop::Socket::SERVER.new
+@socket.CURVE_server!(broker_cert)
+#socket.options.sndtimeo = 0
+@socket.options.heartbeat_ivl     = 100#ms
+@socket.options.heartbeat_timeout = 300#ms
+@socket.bind(endpoint)
+
+puts ">>> Socket bound to #{endpoint.inspect}"
+
+# get and print socket events
+Thread.new do
+  monitor = CZTop::Monitor.new(@socket)
+  monitor.listen("ALL")
+  monitor.start
+  while msg = monitor.next
+    puts ">>> Socket event: #{msg.inspect}"
+  end
+end
+
+# receive messages from drivers
+@driver_map = {} # driver name => routing ID
+Thread.new do
+
+  # CZTop::Loop (zloop) doesn't work with SERVER sockets :(
+  poller = CZTop::Poller.new(@socket)
+  while true
+    puts "waiting for socket to become readable ..."
+    socket = poller.wait
+    puts "socket is readable"
+    msg = socket.receive
+    puts "got message"
+    command, argument = msg[0].split("\t", 2)
+
+    case command
+    when "HELLO"
+      driver = argument
+      puts ">>> Driver #{driver.inspect} has connected."
+      welcome = @driver_map.key?(driver) ? "WELCOMEBACK" : "WELCOME"
+
+      # remember driver's assigned message routing ID
+      @driver_map[driver] = msg.routing_id
+
+      # send WELCOME or WELCOMEBACK
+      rep = CZTop::Message.new(welcome)
+      rep.routing_id = @driver_map[driver]
+      socket << rep
+      puts ">>> Sent #{welcome.inspect} to #{driver.inspect}"
+    end
+  end
+end
+
+def send_command(driver, command)
+  if command.nil? || command.empty?
+    puts "!!! No message given."
+    return
+  end
+  if not @driver_map.key?(driver)
+    puts "!!! Driver #{driver.inspect} has never connected."
+    return
+  end
+  puts ">>> Sending message to #{driver.inspect} ..."
+  msg = CZTop::Message.new(command)
+  msg.routing_id = @driver_map[driver]
+  @socket << msg
+rescue SocketError
+  puts "!!! Driver #{driver.inspect} isn't connected anymore."
+end
+
+##
+# REPL for user to play
+#
+puts <<MSG
+You can now send messages to the drivers yourself.
+The use the method #send_command, like this:
+
+pry> send_command("driver1", "PICKUP\t(8.541694,47.376887)")
+
+This should show something like this in the client.rb terminal:
+
+  03:17:01 driver1.1 | received message: "PICKUP\t(8.541694,47.376887)"
+MSG
+
+binding.pry

data/examples/taxi_system/client.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+
+endpoint = ENV["BROKER_ADDRESS"]
+broker_cert = CZTop::Certificate.load ENV["BROKER_CERT"] # public only
+client_cert = CZTop::Certificate.load ENV["CLIENT_CERT"]
+
+@socket = CZTop::Socket::CLIENT.new
+@socket.CURVE_client!(client_cert, broker_cert)
+@socket.options.sndtimeo     = 2000#ms
+
+# heartbeating:
+# * send PING every 100ms
+# * close connection after 300ms of no life sign from broker
+# * tell broker to close connection after 500ms of no life sign from client
+@socket.options.heartbeat_ivl     = 100#ms
+@socket.options.heartbeat_timeout = 300#ms
+@socket.options.heartbeat_ttl     = 500#ms
+
+@socket.connect(endpoint)
+puts ">>> connected."
+
+# tell broker who we are
+@socket << "HELLO\t#{client_cert["driver_name"]}"
+puts ">>> sent HELLO."
+welcome = @socket.receive[0]
+puts ">>> got #{welcome}."
+
+poller = CZTop::Poller.new(@socket)
+while true
+  socket = poller.wait
+  message = socket.receive
+  puts ">>> received message: #{message[0].inspect}"
+end

data/examples/taxi_system/generate_keys.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+require_relative '../../lib/cztop'
+require 'fileutils'
+FileUtils.cd(File.dirname(__FILE__))
+FileUtils.mkdir "public_keys"
+FileUtils.mkdir "public_keys/drivers"
+FileUtils.mkdir "secret_keys"
+FileUtils.mkdir "secret_keys/drivers"
+#FileUtils.mkdir "certs/drivers"
+
+DRIVERS = %w[ driver1 driver2 driver3 ]
+
+# broker certificate
+cert = CZTop::Certificate.new
+cert.save("secret_keys/broker")
+cert.save_public("public_keys/broker")
+
+# driver certificates
+DRIVERS.each do |driver_name|
+  cert = CZTop::Certificate.new
+  cert["driver_name"] = driver_name
+  cert.save "secret_keys/drivers/#{driver_name}"
+  cert.save_public "public_keys/drivers/#{driver_name}"
+end