qpid_proton 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f385297be1c8a5e6052554821f2231bf09869dfd
-  data.tar.gz: 72345155dbd507d0e2c53fe3a34f27d8f9a4e838
+  metadata.gz: 6495371bf4622d74d87cfd02d4e58323652572eb
+  data.tar.gz: 79af23eb910b3f38a1252530b318c45cafe6af54
 SHA512:
-  metadata.gz: 19d1c1d49c74667d66474320b6f8e382fbc560131286839cba68c8f99e27a660f7627ab6075dd41ba0867a5dd1803dfa4b0ab60930c1a4023fc93c06fc9fc636
-  data.tar.gz: 7ae4b1919814ed6b7091dc36ab758634b3bc82a1deb9b59654a05fc621a5666fe6275ad405c95f4c189d6934db3c58ec4f8dd0196209163c341b6e79c63a5732
+  metadata.gz: 52e822deb2d458caa735b88d0d6dc5d5e6377d16e836d744d80cdf847c1fcff89b1f22e2e178aa653411e2ffecefb7e314dfa3315f10034c77795cecf4146414
+  data.tar.gz: 4cea7fcfbdfadaf4c7fc1319303186c0282292134397c4d536eb46b9e8abccb719164b1b964b09a712aba95fab2193c00a502d1c39fbdace8b6ff636a594fc40

data/examples/README.md

@@ -0,0 +1,76 @@
+## Simple Examples
+
+### The Broker
+
+The examples come with a sample broker which can be used by other examples and which also works as an example itself. For now we'll just start up the broker example and tell it to listen on port 8888:
+
+````
+$ ruby broker.rb amqp://:8888
+Listening on amqp://:8888
+````
+
+This example broker will receive messages, create queues as needed, and deliver messages to endpoints.
+
+### Hello World Using A Broker
+
+Our first example creates an endpoint that sends messages to a queue to which it is subscribed. So it both sends and receives a message.
+
+To start it, simply run:
+
+```
+$ ruby helloworld.rb //:8888
+Hello world!
+```
+
+As you can see, the classic message was output by the example. Now let's take a look at what's going on under the covers.
+
+#### Events When Talking To A Broker
+
+The following events occur while **helloworld.rb** runs:
+
+ * **on_start** - Fired when the application is started.
+ * **on_sendable** - Fired when a message can be sent.
+ * **on_message** - Fired when a message is received.
+
+## More Complex Examples
+
+Now that we've covered the basics with the archetypical hello world app, let's look at some more interesting examples.
+
+The following two client examples send and receive messages to an external broker or server:
+
+ * **simple_send.rb** - connect to a server, send messages to an address
+ * **simple_recv.rb** - connect to a server, receives messages from an address
+
+For example: start `broker.rb`; run `simple_send.rb` to send messages to a
+broker queue; then `simple_recv.rb` to receive the messages from the broker.
+
+The following two examples are *servers* that can be connected to directly, without a broker:
+
+ * **direct_send.rb** - sends messages directly to a receiver and listens for responses itself, and
+ * **direct_recv.rb** - receives messages directly.
+
+For example if you start `direct_recv.rb`, you can connect to it directly with
+`simple_send.rb` vice-versa with `direct_send.rb` and `simple_recv.rb`
+
+In this set of examples we see the following event occurring, in addition to what we've seen before:
+
+ * **on_transport_close** - Fired when the network transport is closed.
+
+## Now About That Broker example
+
+The **broker.rb** example application is a nice demonstration of doing something more interesting in Ruby with Proton.
+
+The way the broker works is to listen to incoming connections, examine the components of the address for that connection, attach that connection to an exchange managing that address and then it sends any messages destined for that address to them.
+
+The components of the broker example include:
+ * **Broker** - A class that extends the MessagingHandler class. It accepts incoming connections, manages subscribing them to exchanges, and transfers messages between them.
+ * **MessageQueue** - Distributes messages to subscriptions.
+
+The Broker manages a map connecting a queue address to the instance of Exchange that holds references to the endpoints of interest.
+
+The broker application demonstrates a new set of events:
+
+ * **on_link_open** - Fired when a remote link is opened. From this event the broker grabs the address and subscribes the link to an exchange for that address.
+ * **on_link_close** - Fired when a remote link is closed. From this event the broker grabs the address and unsubscribes the link from that exchange.
+ * **on_connection_close** - Fired when a remote connection is closed but the local end is still open.
+ * **on_transport_close** - Fired when the protocol transport has closed. The broker removes all links for the disconnected connection, avoiding workign with endpoints that are now gone.

data/examples/broker.rb

@@ -0,0 +1,167 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'qpid_proton'
+require 'optparse'
+require 'pathname'
+
+class MessageQueue
+
+  def initialize(dynamic = false)
+    @dynamic = dynamic
+    @queue = Queue.new
+    @consumers = []
+  end
+
+  def subscribe(consumer)
+    @consumers << (consumer)
+  end
+
+  def unsubscribe(consumer)
+    if @consumers.include?(consumer)
+      @consumers.delete(consumer)
+    end
+    @consumers.empty? && (@dynamic || @queue.empty?)
+  end
+
+  def publish(message)
+    @queue << message
+    self.dispatch
+  end
+
+  def dispatch(consumer = nil)
+    if consumer
+      c = [consumer]
+    else
+      c = @consumers
+    end
+
+    while self.deliver_to(c) do
+    end
+  end
+
+  def deliver_to(consumers)
+    result = false
+    consumers.each do |consumer|
+      if consumer.credit > 0 && !@queue.empty?
+        consumer.send(@queue.pop(true))
+        result = true
+      end
+    end
+    return result
+  end
+
+end
+
+class Broker < Qpid::Proton::MessagingHandler
+
+  def initialize(url)
+    super()
+    @url = url
+    @queues = {}
+    begin          # Optional SSL setup, ignore if we don't find cert files etc.
+      @ssl_domain = Qpid::Proton::SSLDomain.new(Qpid::Proton::SSLDomain::MODE_SERVER)
+      cert_passsword = "tserverpw"
+      if Gem.win_platform?       # Use P12 certs for windows schannel
+        @ssl_domain.credentials("ssl_certs/tserver-certificate.p12", "", cert_passsword)
+      else
+        @ssl_domain.credentials("ssl_certs/tserver-certificate.pem", "ssl_certs/tserver-private-key.pem", cert_passsword)
+      end
+      @ssl_domain.allow_unsecured_client # SSL is optional, this is not secure.
+    rescue
+      @ssl_domain = nil # Don't worry if we can't set up SSL.
+    end
+  end
+
+  def on_container_start(container)
+    # Options for incoming connections, provide SSL configuration if we have it.
+    opts = {:ssl_domain => @ssl_domain} if @ssl_domain
+    @listener = container.listen(@url, Qpid::Proton::Listener::Handler.new(opts))
+    STDOUT.puts "Listening on #{@url.inspect}"; STDOUT.flush
+  end
+
+  def queue(address)
+    unless @queues.has_key?(address)
+      @queues[address] = MessageQueue.new
+    end
+    @queues[address]
+  end
+
+  def on_sender_open(sender)
+    if sender.remote_source.dynamic?
+      address = SecureRandom.uuid
+      sender.source.address = address
+      q = MessageQueue.new(true)
+      @queues[address] = q
+      q.subscribe(sender)
+    elsif sender.remote_source.address
+      sender.source.address = sender.remote_source.address
+      self.queue(sender.source.address).subscribe(sender)
+    end
+  end
+
+  def on_receiver_open(receiver)
+    if receiver.remote_target.address
+      receiver.target.address = receiver.remote_target.address
+    end
+  end
+
+  def unsubscribe(link)
+    if @queues.has_key?(link.source.address)
+      if @queues[link.source.address].unsubscribe(link)
+        @queues.delete(link.source.address)
+      end
+    end
+  end
+
+  def on_sender_close(sender)
+    self.unsubscribe(sender)
+  end
+
+  def on_connection_close(connection)
+    self.remove_stale_consumers(connection)
+  end
+
+  def on_transport_close(transport)
+    self.remove_stale_consumers(transport.connection)
+  end
+
+  def remove_stale_consumers(connection)
+    connection.each_sender { |s| unsubscribe(s) }
+  end
+
+  def on_sendable(sender)
+    q = self.queue(sender.source.address)
+    q.dispatch(sender)
+  end
+
+  def on_message(delivery, message)
+    q = self.queue(delivery.link.target.address)
+    q.publish(message)
+  end
+
+end
+
+if ARGV.size != 1
+  STDERR.puts "Usage: #{__FILE__} URL
+Start an example broker listening on URL"
+  return 1
+end
+url, = ARGV
+Qpid::Proton::Container.new(Broker.new(url)).run

data/examples/client.rb

@@ -0,0 +1,79 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'qpid_proton'
+require 'optparse'
+
+class Client < Qpid::Proton::MessagingHandler
+
+  def initialize(url, address, requests)
+    super()
+    @url = url
+    @address = address
+    @requests = requests
+  end
+
+  def on_container_start(container)
+    c = container.connect(@url)
+    @sender = c.open_sender(@address)
+    @receiver = c.open_receiver({:dynamic => true})
+  end
+
+  def next_request
+    if @receiver.remote_source.address
+      req = Qpid::Proton::Message.new
+      req.reply_to = @receiver.remote_source.address
+      req.body = @requests.first
+      puts "-> #{req.body}"
+      @sender.send(req)
+    end
+  end
+
+  def on_receiver_open(receiver)
+    next_request
+  end
+
+  def on_message(delivery, message)
+    puts "<- #{message.body}"
+    @requests.delete_at(0)
+    if !@requests.empty?
+      next_request
+    else
+      delivery.connection.close
+    end
+  end
+
+  def on_transport_error(transport)
+    raise "Connection error: #{transport.condition}"
+  end
+
+end
+
+REQUESTS = ["Twas brillig, and the slithy toves",
+            "Did gire and gymble in the wabe.",
+            "All mimsy were the borogroves,",
+            "And the mome raths outgrabe."]
+
+if ARGV.size != 2
+  STDERR.puts "Usage: #{__FILE__} URL ADDRESS
+Connect to URL and send messages to ADDRESS"
+  return 1
+end
+url, address = ARGV
+Qpid::Proton::Container.new(Client.new(url, address, REQUESTS)).run

data/examples/direct_recv.rb

@@ -0,0 +1,61 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'qpid_proton'
+require 'optparse'
+
+class DirectReceive < Qpid::Proton::MessagingHandler
+
+  def initialize(url, address, count)
+    super()
+    @url = url
+    @address = address
+    @expected = count
+    @received = 0
+  end
+
+  class ListenOnce < Qpid::Proton::Listener::Handler
+    def on_open(l) STDOUT.puts "Listening\n"; STDOUT.flush; end
+    def on_accept(l) l.close; end
+  end
+
+  def on_container_start(container)
+    container.listen(@url, ListenOnce.new)
+  end
+
+  def on_message(delivery, message)
+    if @expected.zero? || (@received < @expected)
+      puts "Received: #{message.body}"
+      @received = @received + 1
+      if @received == @expected
+        delivery.connection.close
+      end
+    end
+  end
+end
+
+unless (2..3).include? ARGV.size
+  STDERR.puts "Usage: #{__FILE__} URL ADDRESS [COUNT]
+Listen on URL and receive COUNT messages from ADDRESS"
+  return 1
+end
+url, address, count = ARGV
+count = Integer(count || 10)
+Qpid::Proton::Container.new(DirectReceive.new(url, address, count)).run
+

data/examples/direct_send.rb

@@ -0,0 +1,67 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'qpid_proton'
+require 'optparse'
+
+class DirectSend < Qpid::Proton::MessagingHandler
+
+  def initialize(url, address, expected)
+    super()
+    @url = url
+    @address = address
+    @sent = 0
+    @confirmed = 0
+    @expected = expected
+  end
+
+  class ListenOnce < Qpid::Proton::Listener::Handler
+    def on_open(l) STDOUT.puts "Listening\n"; STDOUT.flush; end
+    def on_accept(l) l.close; end
+  end
+
+  def on_container_start(container)
+    container.listen(@url, ListenOnce.new)
+  end
+
+  def on_sendable(sender)
+    while sender.credit > 0 && @sent < @expected
+      msg = Qpid::Proton::Message.new("sequence #{@sent}", { :id => @sent } )
+      sender.send(msg)
+      @sent = @sent + 1
+    end
+  end
+
+  def on_tracker_accept(tracker)
+    @confirmed = @confirmed + 1
+    if @confirmed == @expected
+      puts "All #{@expected} messages confirmed!"
+      tracker.connection.close
+    end
+  end
+end
+
+unless (2..3).include? ARGV.size
+  STDERR.puts "Usage: #{__FILE__} URL ADDRESS [COUNT]
+Listen on URL and send COUNT messages to ADDRESS"
+  return 1
+end
+url, address, count = ARGV
+count = Integer(count || 10)
+Qpid::Proton::Container.new(DirectSend.new(url, address, count)).run

data/examples/example_test.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+require 'minitest/autorun'
+require 'qpid_proton'
+require 'socket'
+require 'rbconfig'
+
+begin
+  MiniTest::Test
+rescue NameError                # For older versions of MiniTest
+  MiniTest::Test = MiniTest::Unit::TestCase
+end
+
+# URL with an unused port
+def test_url()
+  "amqp://:#{TCPServer.open(0) { |s| s.addr[1] }}"
+end
+
+
+class ExampleTest < MiniTest::Test
+
+  def run_script(*args)
+    return IO.popen([ RbConfig.ruby ] + args.map { |a| a.to_s })
+  end
+
+  def assert_output(want, *args)
+    assert_equal(want.strip, run_script(*args).read.strip)
+  end
+
+  def test_helloworld
+    assert_output("Hello world!", "helloworld.rb", $url, __method__)
+  end
+
+  def test_client_server
+    want =  <<EOS
+-> Twas brillig, and the slithy toves
+<- TWAS BRILLIG, AND THE SLITHY TOVES
+-> Did gire and gymble in the wabe.
+<- DID GIRE AND GYMBLE IN THE WABE.
+-> All mimsy were the borogroves,
+<- ALL MIMSY WERE THE BOROGROVES,
+-> And the mome raths outgrabe.
+<- AND THE MOME RATHS OUTGRABE.
+EOS
+    server = run_script("server.rb", $url, __method__)
+    assert_output(want.strip, "client.rb", $url, __method__)
+  ensure
+    Process.kill :TERM, server.pid if server
+  end
+
+  def test_send_recv
+    assert_output("All 10 messages confirmed!", "simple_send.rb", $url, __method__)
+    want = (0..9).reduce("") { |x,y| x << "Received: sequence #{y}\n" }
+    assert_output(want.strip, "simple_recv.rb", $url, __method__)
+  end
+
+  def test_ssl_send_recv
+    out = run_script("ssl_send.rb", $url, __method__).read.strip
+    assert_match(/Connection secured with "...*\"\nAll 10 messages confirmed!/, out)
+    want = (0..9).reduce("") { |x,y| x << "Received: sequence #{y}\n" }
+    assert_output(want.strip, "simple_recv.rb", $url, __method__)
+  end
+
+  def test_direct_recv
+    url = test_url
+      p = run_script("direct_recv.rb", url, __method__)
+      p.readline                # Wait till ready
+      assert_output("All 10 messages confirmed!", "simple_send.rb", url, __method__)
+      want = (0..9).reduce("") { |x,y| x << "Received: sequence #{y}\n" }
+      assert_equal(want.strip, p.read.strip)
+  end
+
+  def test_direct_send
+    url = test_url
+    p = run_script("direct_send.rb", url, __method__)
+    p.readline                # Wait till ready
+    want = (0..9).reduce("") { |x,y| x << "Received: sequence #{y}\n" }
+    assert_output(want.strip, "simple_recv.rb", url, __method__)
+    assert_equal("All 10 messages confirmed!", p.read.strip)
+  end
+end
+
+# Start the broker before all tests.
+$url = test_url
+$broker = IO.popen([RbConfig.ruby, 'broker.rb', $url])
+$broker.readline
+
+# Kill the broker after all tests
+MiniTest.after_run do
+  Process.kill(:TERM, $broker.pid) if $broker
+end

data/examples/helloworld.rb

@@ -0,0 +1,57 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'qpid_proton'
+require 'optparse'
+
+class HelloWorld < Qpid::Proton::MessagingHandler
+
+  def initialize(url, address)
+    super()
+    @url, @address = url, address
+  end
+
+  def on_container_start(container)
+    conn = container.connect(@url)
+    conn.open_sender(@address)
+    conn.open_receiver(@address)
+  end
+
+  def on_sendable(sender)
+    sender.send(Qpid::Proton::Message.new("Hello world!"))
+    sender.close
+  end
+
+  def on_message(delivery, message)
+    puts message.body
+    delivery.connection.close
+  end
+
+  def on_transport_error(transport)
+    raise "Connection error: #{transport.condition}"
+  end
+end
+
+if ARGV.size != 2
+  STDERR.puts "Usage: #{__FILE__} URL ADDRESS
+Connect to URL, send a message to ADDRESS and receive it back"
+  return 1
+end
+url, address = ARGV
+Qpid::Proton::Container.new(HelloWorld.new(url, address)).run

data/examples/server.rb

@@ -0,0 +1,70 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+require 'qpid_proton'
+require 'optparse'
+
+class Server < Qpid::Proton::MessagingHandler
+
+  def initialize(url, address)
+    super()
+    @url = url
+    @address = address
+    @senders = {}
+  end
+
+  def on_container_start(container)
+    c = container.connect(@url)
+    c.open_receiver(@address)
+    @relay = nil
+  end
+
+  def on_connection_open(connection)
+    if connection.offered_capabilities &&
+        connection.offered_capabilities.contain?("ANONYMOUS-RELAY")
+      @relay = connection.open_sender({:target => nil})
+    end
+  end
+
+  def on_message(delivery, message)
+    return unless message.reply_to  # Not a request message
+    puts "<- #{message.body}"
+    unless (sender = @relay)
+      sender = (@senders[message.reply_to] ||= delivery.connection.open_sender(message.reply_to))
+    end
+    reply = Qpid::Proton::Message.new
+    reply.address = message.reply_to
+    reply.body = message.body.upcase
+    puts "-> #{reply.body}"
+    reply.correlation_id = message.correlation_id
+    sender.send(reply)
+  end
+
+  def on_transport_error(transport)
+    raise "Connection error: #{transport.condition}"
+  end
+end
+
+if ARGV.size != 2
+  STDERR.puts "Usage: #{__FILE__} URL ADDRESS
+Server listening on URL, reply to messages to ADDRESS"
+  return 1
+end
+url, address = ARGV
+Qpid::Proton::Container.new(Server.new(url, address)).run