onstomp 1.0.0pre1

data/lib/onstomp/connections/serializers/stomp_1_1.rb

@@ -0,0 +1,134 @@
+# -*- encoding: utf-8 -*-
+
+# Frame serializer / parser for STOMP 1.1 connections.
+class OnStomp::Connections::Serializers::Stomp_1_1
+  include OnStomp::Connections::Serializers::Stomp_1
+  
+  # Mapping of characters to their appropriate escape sequences. This
+  # is used when escaping headers for frames being written to the stream.
+  CHARACTER_ESCAPES = { ':' => "\\c", "\n" => "\\n", "\\" => "\\\\" }
+  
+  # Mapping of escape sequences to their appropriate characters. This
+  # is used when unescaping headers being read from the stream.
+  ESCAPE_SEQUENCES = Hash[CHARACTER_ESCAPES.map { |k,v| [v,k] }]
+
+  # Creates a new serializer and calls {#reset_parser}
+  def initialize
+    reset_parser
+  end
+
+  # Converts a {OnStomp::Components::Frame frame} to a string
+  # @param [OnStomp::Components::Frame] frame
+  # @return [String]
+  def frame_to_string frame
+    frame_to_string_base(make_ct(frame)) do |k,v|
+      "#{escape_header k}:#{escape_header v}\n"
+    end
+  end
+
+  # Escapes a header name or value by replacing special characters with
+  # their appropriate escape sequences. The header will also be encoded to
+  # 'UTF-8' when using Ruby 1.9+
+  # @param [String] s header name or value
+  # @return [String]
+  def escape_header s
+    encode_header(s).gsub(/[:\n\\\\]/) { |c| CHARACTER_ESCAPES[c] }
+  end
+  
+  # Unescapes a header name or pair parsed from the read buffer by converting
+  # known escape sequences into their special characters. The header string
+  # will have a 'UTF-8' encoding forced upon it when using Ruby 1.9+, as per
+  # the STOMP 1.1 spec.
+  # @param [String] s header name or value
+  # @return [String]
+  # @raise [OnStomp::InvalidHeaderEscapeSequenceError]
+  #   if an unknown escape sequence is present in the header name or value
+  def unescape_header s
+    force_header_encoding(s).gsub(/\\.?/) do |c|
+      ESCAPE_SEQUENCES[c] || raise(OnStomp::InvalidHeaderEscapeSequenceError, "#{c}")
+    end
+  end
+  
+  # Splits a header line into a header name / header value pair at the first
+  # ':' character {#unescape_header unescapes} them, and returns the pair.
+  # @param [String] str header line to split
+  # @return [[String, String]]
+  # @raise [OnStomp::MalformedHeaderError] if the header line
+  #   lacks a ':' character
+  def split_header(str)
+    col = str.index(':')
+    unless col
+      raise OnStomp::MalformedHeaderError, "unterminated header: '#{str}'"
+    end
+    [ unescape_header(str[0...col]),
+      unescape_header(str[(col+1)..-1]) ]
+  end
+  
+  # Forces the frame's body to match the charset specified in its +content-type+
+  # header, if applicable.
+  # @param [OnStomp::Components::Frame] frame
+  def prepare_parsed_frame frame
+    force_body_encoding frame
+  end
+  
+  if RUBY_VERSION >= "1.9"
+    # Encodes the given string to 'UTF-8'
+    # @note No-op for Ruby 1.8.x
+    # @param [String] s
+    # @return [String]
+    def encode_header(s)
+      s.encoding.name == 'UTF-8' ? s : s.encode('UTF-8')
+    end
+    # Forces the encoding of the given string to 'UTF-8'
+    # @note No-op for Ruby 1.8.x
+    # @param [String] s
+    # @return [String]
+    def force_header_encoding(s); s.tap { s.force_encoding('UTF-8') }; end
+    # Forces the encoding of the given frame's body to match its charset.
+    # @note No-op for Ruby 1.8.x
+    # @param [OnStomp::Components::Frame] f
+    # @return [OnStomp::Components::Frame]
+    def force_body_encoding f
+      type, subtype, charset = f.content_type
+      charset ||= (type == 'text') ? 'UTF-8' : 'ASCII-8BIT'
+      f.body.force_encoding(charset)
+      f
+    end
+    # Set an appropriate +content-type+ header with +charset+ parameter for
+    # frames with a text body
+    # @note No-op for Ruby 1.8.x
+    # @param [OnStomp::Components::Frame] f
+    # @return [OnStomp::Components::Frame]
+    def make_ct f
+      return f if f.body.nil?
+      t, st = f.content_type
+      enc = f.body.encoding.name
+      if enc != 'ASCII-8BIT'
+        f[:'content-type'] = "#{t||'text'}/#{st||'plain'};charset=#{enc}"
+      end
+      f
+    end
+  else
+    # Encodes the given string to 'UTF-8'
+    # @note No-op for Ruby 1.8.x
+    # @param [String] s
+    # @return [String]
+    def encode_header(s); s; end
+    # Forces the encoding of the given string to 'UTF-8'
+    # @note No-op for Ruby 1.8.x
+    # @param [String] s
+    # @return [String]
+    def force_header_encoding(s); s; end
+    # Forces the encoding of the given frame's body to match its charset.
+    # @note No-op for Ruby 1.8.x
+    # @param [OnStomp::Components::Frame] f
+    # @return [OnStomp::Components::Frame]
+    def force_body_encoding(f); f; end
+    # Set an appropriate +content-type+ header with +charset+ parameter for
+    # frames with a text body
+    # @note No-op for Ruby 1.8.x
+    # @param [OnStomp::Components::Frame] f
+    # @return [OnStomp::Components::Frame]
+    def make_ct(f); f; end
+  end
+end

data/lib/onstomp/connections/serializers.rb

@@ -0,0 +1,9 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for {OnStomp::Components::Frame frame} serializers / parsers.
+module OnStomp::Connections::Serializers
+end
+
+require 'onstomp/connections/serializers/stomp_1'
+require 'onstomp/connections/serializers/stomp_1_0'
+require 'onstomp/connections/serializers/stomp_1_1'

data/lib/onstomp/connections/stomp_1.rb

@@ -0,0 +1,69 @@
+# -*- encoding: utf-8 -*-
+
+# Connection behavior common to both STOMP 1.0 and STOMP 1.1 connections
+module OnStomp::Connections::Stomp_1
+  # Creates a CONNECT frame
+  # @return [OnStomp::Components::Frame] CONNECT frame
+  def connect_frame *h
+    create_frame 'CONNECT', h
+  end
+  
+  # Creates a SEND frame
+  # @return [OnStomp::Components::Frame] SEND frame
+  def send_frame d, b, h
+    create_frame 'SEND', [h, {:destination => d}], b
+  end
+  
+  # Creates a BEGIN frame
+  # @return [OnStomp::Components::Frame] BEGIN frame
+  def begin_frame tx, h
+    create_transaction_frame 'BEGIN', tx, h
+  end
+  
+  # Creates a COMMIT frame
+  # @return [OnStomp::Components::Frame] COMMIT frame
+  def commit_frame tx, h
+    create_transaction_frame 'COMMIT', tx, h
+  end
+  
+  # Creates an ABORT frame
+  # @return [OnStomp::Components::Frame] ABORT frame
+  def abort_frame tx, h
+    create_transaction_frame 'ABORT', tx, h
+  end
+  
+  # Creates a DISCONNECT frame
+  # @return [OnStomp::Components::Frame] DISCONNECT frame
+  def disconnect_frame h
+    create_frame 'DISCONNECT', [h]
+  end
+  
+  # Creates a SUBSCRIBE frame
+  # @return [OnStomp::Components::Frame] SUBSCRIBE frame
+  def subscribe_frame d, h
+    create_frame 'SUBSCRIBE', [{:id => OnStomp.next_serial}, h, {:destination => d}]
+  end
+  
+  # Creates an UNSUBSCRIBE frame
+  # @return [OnStomp::Components::Frame] UNSUBSCRIBE frame
+  def unsubscribe_frame f, h
+    id = f.is_a?(OnStomp::Components::Frame) ? f[:id] : f
+    create_frame('UNSUBSCRIBE', [{:id => id}, h]).tap do |f|
+      raise ArgumentError, 'subscription ID could not be determined' unless f.header?(:id)
+    end
+  end
+  
+  private
+  def create_transaction_frame command, tx, headers
+    create_frame command, [headers, {:transaction => tx}]
+  end
+  
+  def create_frame command, layered_headers, body=nil
+    headers = layered_headers.inject({}) do |final, h|
+      h = OnStomp.keys_to_sym(h).delete_if { |k,v| final.key?(k) && (v.nil? || v.empty?) }
+      final.merge!(h)
+      final
+    end
+    OnStomp::Components::Frame.new(command, headers, body)
+  end
+end

data/lib/onstomp/connections/stomp_1_0.rb

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+
+# A STOMP 1.0 specific connection
+class OnStomp::Connections::Stomp_1_0 < OnStomp::Connections::Base
+  include OnStomp::Connections::Stomp_1
+  # The serializer that will convert {OnStomp::Components::Frame frames} into
+  # raw bytes and will convert raw bytes into {OnStomp::Components::Frame frames}
+  # @return [OnStomp::Connections::Serializers::Stomp_1_0]
+  attr_reader :serializer
+
+  # Calls {OnStomp::Connections::Base#initialize} and creates a STOMP 1.0
+  # serializer
+  def initialize socket, client
+    super
+    @serializer = OnStomp::Connections::Serializers::Stomp_1_0.new
+  end
+
+  # Creates an ACK frame
+  # @return [OnStomp::Components::Frame] ACK frame
+  def ack_frame *args
+    headers = args.last.is_a?(Hash) ? args.pop : {}
+    m_id = args.shift
+    m_id = m_id[:'message-id'] if m_id.is_a?(OnStomp::Components::Frame)
+    create_frame('ACK', [{:'message-id' => m_id}, headers]).tap do |f|
+      raise ArgumentError, 'no message-id to ACK' unless f.header?(:'message-id')
+    end
+  end
+end

data/lib/onstomp/connections/stomp_1_1.rb

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8 -*-
+
+# A STOMP 1.1 specific connection
+class OnStomp::Connections::Stomp_1_1 < OnStomp::Connections::Base
+  include OnStomp::Connections::Stomp_1
+  include OnStomp::Connections::Heartbeating
+  # The serializer that will convert {OnStomp::Components::Frame frames} into
+  # raw bytes and will convert raw bytes into {OnStomp::Components::Frame frames}
+  # @return [OnStomp::Connections::Serializers::Stomp_1_1]
+  attr_reader :serializer
+  
+  # Calls {OnStomp::Connections::Base#initialize} and creates a STOMP 1.0
+  # serializer
+  def initialize socket, client
+    super
+    @serializer = OnStomp::Connections::Serializers::Stomp_1_1.new
+  end
+  
+  # Calls {OnStomp::Connections::Base#configure} then configures heartbeating
+  # parameters.
+  # @param [OnStomp::Components::Frame] connected
+  # @param [{Symbol => Proc}] con_cbs
+  def configure connected, con_cbs
+    super
+    configure_heartbeating client.heartbeats, connected.heart_beat
+  end
+  
+  # Returns true if {OnStomp::Connections::Base#connected?} is true and
+  # we have a {#pulse?}
+  def connected?
+    super && pulse?
+  end
+  
+  # Creates an ACK frame
+  # @return [OnStomp::Components::Frame] ACK frame
+  def ack_frame *args
+    create_ack_or_nack 'ACK', args
+  end
+  
+  # Creates an NACK frame
+  # @return [OnStomp::Components::Frame] NACK frame
+  def nack_frame *args
+    create_ack_or_nack 'NACK', args
+  end
+  
+  # Creates a heartbeat frame (serialized as a single "\n" character)
+  # @return [OnStomp::Components::Frame] heartbeat frame
+  def heartbeat_frame
+    OnStomp::Components::Frame.new
+  end
+  
+  private
+  def create_ack_or_nack(command, args)
+    headers = args.last.is_a?(Hash) ? args.pop : {}
+    m_id = args.shift
+    sub_id = args.shift
+    if m_id.is_a?(OnStomp::Components::Frame)
+      sub_id = m_id[:subscription]
+      m_id = m_id[:'message-id']
+    end
+    create_frame(command, [{:'message-id' => m_id, :subscription => sub_id }, headers]).tap do |f|
+      raise ::ArgumentError, 'missing message-id or subscription headers' unless f.headers?(:'message-id', :subscription)
+    end
+  end
+end

data/lib/onstomp/connections.rb

@@ -0,0 +1,119 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for protocol specific connections used to communicate with
+# STOMP brokers.
+module OnStomp::Connections
+  # Default SSL options to use when establishing an SSL connection.
+  DEFAULT_SSL_OPTIONS = {
+    :verify_mode => OpenSSL::SSL::VERIFY_PEER |
+      OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT,
+    :ca_file => nil,
+    :ca_path => nil,
+    :cert => nil,
+    :key => nil,
+    :post_connection_check => true
+  }
+  
+  # Returns a list of supported protocol versions
+  # @return [Array<String>]
+  def self.supported
+    PROTOCOL_VERSIONS.keys.sort
+  end
+  
+  # Filters a list of supplied versions to only those
+  # that are supported. Results are in the same order as they are found
+  # in {.supported}. If none of the supplied versions are supported, an
+  # empty list is returned.
+  # @param [Array<String>] vers versions to filter
+  # @return [Array<String>]
+  def self.select_supported vers
+    vers = Array(vers)
+    supported.select { |v| vers.include? v }
+  end
+  
+  # Creates an initial {OnStomp::Connections::Stomp_1_0 connection} to
+  # the client's broker uri, performs the CONNECT/CONNECTED frame exchange,
+  # and returns a {OnStomp::Connections::Base connection} suitable for the
+  # negotiated STOMP protocol version.
+  # @param [OnStomp::Client] client
+  # @param [{#to_sym => #to_s}] u_head user specified headers for CONNECT frame
+  # @param [{#to_sym => #to_s}] c_head client specified headers for CONNECT frame
+  # @param [{Symbol => Proc}] con_cbs event callbacks to install on the final
+  #   connection
+  # @return [OnStomp::Connections::Base] instance of Base subclass suited for
+  #   negotiated protocol version
+  # @raise [OnStomp::OnStompError] if negotiating the connection raises an
+  #   such an error.
+  def self.connect client, u_head, c_head, con_cbs
+    init_con = create_connection('1.0', nil, client)
+    ver, connected = init_con.connect client, u_head, c_head
+    begin
+      negotiate_connection(ver, init_con, client).tap do |final_con|
+        final_con.configure connected, con_cbs
+      end
+    rescue OnStomp::OnStompError
+      # Perform a blocking close.
+      init_con.close true
+      raise
+    end
+  end
+  
+  private
+  def self.negotiate_connection vers, con, client
+    supports_protocol?(vers,con) ? con :
+      create_connection(vers, con.socket, client)
+  end
+  
+  def self.supports_protocol? ver, con
+    con.is_a? PROTOCOL_VERSIONS[ver]
+  end
+  
+  def self.create_connection ver, sock, client
+    unless sock
+      meth = client.ssl ? :ssl :
+        client.uri.respond_to?(:onstomp_socket_type) ?
+          client.uri.onstomp_socket_type : :tcp
+      sock = __send__(:"create_socket_#{meth}", client)
+    end
+    PROTOCOL_VERSIONS[ver].new sock, client
+  end
+  
+  def self.create_socket_tcp client
+    TCPSocket.new(client.uri.host || 'localhost', client.uri.port)
+  end
+  
+  def self.create_socket_ssl client
+    uri = client.uri
+    host = uri.host || 'localhost'
+    ssl_opts = client.ssl.is_a?(Hash) ? client.ssl : {}
+    ssl_opts = DEFAULT_SSL_OPTIONS.merge(ssl_opts)
+    context = OpenSSL::SSL::SSLContext.new
+    post_check = ssl_opts.delete(:post_connection_check)
+    post_check_host = (post_check == true) ? host : post_check
+    DEFAULT_SSL_OPTIONS.keys.each do |k|
+      context.__send__(:"#{k}=", ssl_opts[k]) if ssl_opts.key?(k)
+    end
+    tcp_sock = create_socket_tcp(client)
+    socket = OpenSSL::SSL::SSLSocket.new(tcp_sock, context)
+    socket.sync_close = true
+    socket.connect
+    socket.post_connection_check(post_check_host) if post_check_host
+    socket
+  end
+end
+
+require 'onstomp/connections/serializers'
+require 'onstomp/connections/base'
+require 'onstomp/connections/stomp_1'
+require 'onstomp/connections/heartbeating'
+require 'onstomp/connections/stomp_1_0'
+require 'onstomp/connections/stomp_1_1'
+
+module OnStomp::Connections
+  # A mapping of protocol versions to the connection classes that support
+  # them.
+  PROTOCOL_VERSIONS = {
+    '1.0' => OnStomp::Connections::Stomp_1_0,
+    '1.1' => OnStomp::Connections::Stomp_1_1
+  }
+end

data/lib/onstomp/interfaces/client_configurable.rb

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+
+# Module for configurable attributes specific to {OnStomp::Client client} objects.
+module OnStomp::Interfaces::ClientConfigurable
+  # Includes {OnStomp::Interfaces::UriConfigurable} into +base+ and
+  # extends {OnStomp::Interfaces::ClientConfigurable::ClassMethods}
+  # @param [Module] base
+  def self.included(base)
+    base.__send__ :include, OnStomp::Interfaces::UriConfigurable
+    base.extend ClassMethods
+  end
+  
+  # Provides attribute methods for {OnStomp::Client client} objects.
+  module ClassMethods
+    # Creates a readable and writeable attribute with the given name that
+    # defaults to the {OnStomp::Connections.supported supported} protocol
+    # versions and is {OnStomp::Connections.select_supported filtered} to
+    # those versions when assigned. Corresponds to which protocol versions
+    # should be used for a given client's connection.
+    # @param [Symbol] nm name of attribute
+    def attr_configurable_protocols nm
+      attr_configurable_arr(nm, :default => OnStomp::Connections.supported) do |vers|
+        OnStomp::Connections.select_supported(vers).tap do |valid|
+          raise OnStomp::UnsupportedProtocolVersionError, vers.inspect if valid.empty?
+        end
+      end
+    end
+    
+    # Creates a readable and writeable attribute with the given name that
+    # defaults to [0, 0] and is mapped to a pair of non-negative integers
+    # when assigned. Corresponds to what heartbeating strategy should be used
+    # for a given client's connection where [0, 0] indicates no heartbeating
+    # should be performed.
+    # @note This attribute is only useful with STOMP 1.1 connections.
+    # @param [Symbol] nm name of attribute
+    def attr_configurable_client_beats nm
+      attr_configurable_arr(nm, :default => [0,0]) do |val|
+        val.map { |b| bi = b.to_i; bi < 0 ? 0 : bi }
+      end
+    end
+    
+    # Creates a readable and writeable attribute with the given name that
+    # defaults to the {OnStomp::Components::ThreadedProcessor} and if set
+    # to nil will instead use {OnStomp::Components::NilProcessor}. Corresponds
+    # the the class to use when create new processor instances when a client
+    # is connected.
+    # @param [Symbol] nm name of attribute
+    def attr_configurable_processor nm
+      attr_configurable_class(nm,
+        :default => OnStomp::Components::ThreadedProcessor) do |pr|
+        pr || OnStomp::Components::NilProcessor
+      end
+    end
+  end
+end

data/lib/onstomp/interfaces/client_events.rb

@@ -0,0 +1,168 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for {OnStomp::Client client} events
+# There are a few special event methods that will be passed on
+# to the client's connection, they are:
+# * +on_connection_established+ => {OnStomp::Interfaces::ConnectionEvents#on_established}
+# * +on_connection_died+ => {OnStomp::Interfaces::ConnectionEvents#on_died}
+# * +on_connection_terminated+ => {OnStomp::Interfaces::ConnectionEvents#on_terminated}
+# * +on_connection_closed+ => {OnStomp::Interfaces::ConnectionEvents#on_closed}
+module OnStomp::Interfaces::ClientEvents
+  include OnStomp::Interfaces::EventManager
+
+  # @group Client Frame Event Bindings
+  
+  # Binds a callback to be invoked when an ACK frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :ack, :before, :on
+  # Binds a callback to be invoked when a NACK frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :nack, :before, :on
+  # Binds a callback to be invoked when a BEGIN frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :begin, :before, :on
+  # Binds a callback to be invoked when an ABORT frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :abort, :before, :on
+  # Binds a callback to be invoked when a COMMIT frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :commit, :before, :on
+  # Binds a callback to be invoked when a SEND frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :send, :before, :on
+  # Binds a callback to be invoked when a SUBSCRIBE frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :subscribe, :before, :on
+  # Binds a callback to be invoked when an UNSUBSCRIBE frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :unsubscribe, :before, :on
+  # Binds a callback to be invoked when a DISCONNECT frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :disconnect, :before, :on
+  # Binds a callback to be invoked when a client heartbeat is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :client_beat, :before, :on
+  
+  # @group Broker Frame Event Bindings
+  
+  # Binds a callback to be invoked when an ERROR frame is received
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :error, :before, :on
+  # Binds a callback to be invoked when a MESSAGE frame is received
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :message, :before, :on
+  # Binds a callback to be invoked when a RECEIPT frame is received
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :receipt, :before, :on
+  # Binds a callback to be invoked when a broker heartbeat is received
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :broker_beat, :before, :on
+
+  # @group Frame Exchange Event Bindings
+  
+  # Binds a callback to be invoked when any frame is transmitted
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :transmitting, :before, :after
+  # Binds a callback to be invoked when any frame is received
+  # @yield [frame, client] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Components::Frame] frame
+  # @yieldparam [OnStomp::Client] client
+  create_event_methods :receiving, :before, :after
+  
+  # @endgroup
+
+  # Helpers for setting up connection events through a client
+  [:established, :terminated, :died, :closed].each do |ev|
+    module_eval <<-EOS
+      def on_connection_#{ev}(&cb)
+        if connection
+          connection.on_#{ev}(&cb)
+        else
+          pending_connection_events[:on_#{ev}] << cb
+        end
+      end
+    EOS
+  end
+  
+  # Returns a hash of event bindings that should be set on a
+  # {OnStomp::Connections::Base connection}, but were set on the client
+  # because the connection does not exist yet.
+  # @return [{Symbol => Array<Proc>}]
+  def pending_connection_events
+    @pending_connection_events ||= Hash.new { |h,k| h[k] = [] }
+  end
+  
+  # Triggers an event named by the supplied frame, prefixed with the supplied
+  # prefix. If the supplied frame is a 'heart-beat', origin will be used to
+  # dispatch appropriate heart-beat event (client_beat or broker_beat)
+  # @param [OnStomp::Components::Frame] f the frame trigger this event
+  # @param [:on, :before, etc] pref the prefix for the event name
+  # @param [:client, :broker] origin
+  def trigger_frame_event f, pref, origin
+    e = f.command ? :"#{pref}_#{f.command.downcase}" :
+      :"#{pref}_#{origin}_beat"
+    trigger_event e, f, self
+  end
+  
+  # Triggers the :before_receiving event and the
+  # +before+ prefixed frame specific event (eg: +:before_error+).
+  # @param [OnStomp::Components::Frame] f
+  def trigger_before_receiving f
+    trigger_event :before_receiving, f, self
+    trigger_frame_event f, :before, :broker
+  end
+  
+  # Triggers the :after_receiving event and the
+  # +on+ prefixed frame specific event (eg: +:on_message+)
+  # @param [OnStomp::Components::Frame] f
+  def trigger_after_receiving f
+    trigger_event :after_receiving, f, self
+    trigger_frame_event f, :on, :broker
+  end
+  
+  # Triggers the :before_transmitting event and the
+  # +before+ prefixed frame specific event (eg: +:before_disconnect+).
+  # @param [OnStomp::Components::Frame] f
+  def trigger_before_transmitting f
+    trigger_event :before_transmitting, f, self
+    trigger_frame_event f, :before, :client
+  end
+  
+  # Triggers the :after_transmitting event and the
+  # +on+ prefixed frame specific event (eg: +:on_send+).
+  # @param [OnStomp::Components::Frame] f
+  def trigger_after_transmitting f
+    trigger_event :after_transmitting, f, self
+    trigger_frame_event f, :on, :client
+  end
+end