stomper 1.0.0 → 2.0.0

data/lib/stomper/errors.rb

@@ -0,0 +1,59 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for exceptions associated with this gem.
+module Stomper::Errors
+  # A common base class for errors raised by the Stomper gem
+  # @abstract
+  class StomperError < StandardError; end
+  
+  # Low level error raised when the broker transmits data that violates
+  # the Stomp protocol specification.
+  # @abstract
+  class FatalProtocolError < StomperError; end
+  
+  # Raised when an invalid character is encountered in a header
+  class InvalidHeaderCharacterError < FatalProtocolError; end
+  
+  # Raised when an invalid escape sequence is encountered in a header name or value
+  class InvalidHeaderEscapeSequenceError < FatalProtocolError; end
+  
+  # Raised when a malformed header is encountered. For example, if a header
+  # line does not contain ':'
+  class MalformedHeaderError < FatalProtocolError; end
+  
+  # Raised when a malformed frame is encountered on the stream. For example,
+  # if a frame is not properly terminated with the {Stomper::FrameIO::FRAME_TERMINATOR}
+  # character.
+  class MalformedFrameError < FatalProtocolError; end
+  
+  # An error that is raised as a result of a misconfiguration of the client
+  # connection
+  # @abstract
+  class FatalConnectionError < StomperError; end
+  
+  # Raised when a connection has been configured with an unsupported protocol
+  # version. This can be due to end user misconfiguration, or due to improper
+  # protocol negotiation with the message broker.
+  class UnsupportedProtocolVersionError < FatalConnectionError; end
+  
+  # Raised when an attempt to connect to the broker results in an unexpected
+  # exchange.
+  class ConnectFailedError < FatalConnectionError; end
+  
+  # Raised if the command issued is not supported by the protocol version
+  # negotiated between the client and broker.
+  class UnsupportedCommandError < StomperError; end
+  
+  # An error that is raised as a result frames being generated on
+  # a transaction while it is in an invalid state.
+  # @abstract
+  class TransactionError < StomperError; end
+  
+  # Raised if a transactionable frame is sent in a transaction that has
+  # already been aborted or committed.
+  class TransactionFinalizedError < TransactionError; end
+  
+  # Raised if a BEGIN frame is sent on a transaction that has already
+  # begun.
+  class TransactionStartedError < TransactionError; end
+end

data/lib/stomper/extensions.rb

@@ -0,0 +1,10 @@
+# -*- encoding: utf-8 -*-
+
+# Extensions to {Stomper::Connection} objects
+module Stomper::Extensions
+end
+
+require 'stomper/extensions/common'
+require 'stomper/extensions/scoping'
+require 'stomper/extensions/heartbeat'
+require 'stomper/extensions/events'

data/lib/stomper/extensions/common.rb

@@ -0,0 +1,258 @@
+# -*- encoding: utf-8 -*-
+
+# Provides the common interface for a {Stomper::Connection} object.
+module Stomper::Extensions::Common
+  # Extends an object with any additional modules that are appropriate
+  # for the Stomp protocol being used.
+  def self.extend_by_protocol_version(instance, version)
+    if EXTEND_BY_VERSION[version]
+      EXTEND_BY_VERSION[version].each do |mod|
+        instance.extend mod
+      end
+    end
+  end
+  
+  
+  # Transmits a SEND frame to the broker with the specified destination, body
+  # and headers.  If a block is given, a +receipt+ header will be included in the frame
+  # and the block will be invoked when the corresponding RECEIPT frame
+  # is received from the broker. The naming of this method bothers me as it
+  # overwrites a core Ruby method but doing so maintains the consistency of
+  # this interface. If you want to pass a message ala +Object#send+, use the
+  # +__send__+ method instead.
+  # @note You will need to use +__send__+ if you want the behavior of +Object#send+
+  # @param [String] dest the destination for the SEND frame to be delivered to
+  # @param [String] body the body of the SEND frame
+  # @param [{Symbol => String}] additional headers to include in the generated frame
+  # @yield [receipt] invoked when the receipt for this SEND frame has been received
+  # @yieldparam [Stomper::Frame] receipt the RECEIPT frame sent by the broker
+  # @return [Stomper::Frame] the SEND frame sent to the broker
+  def send(dest, body, headers={}, &block)
+    scoped_to = block ? with_receipt(&block) : self
+    scoped_to.transmit create_frame('SEND', headers, { :destination => dest }, body)
+  end
+  alias :puts :send
+  
+  # Transmits a SUBSCRIBE frame to the broker with the specified destination
+  # and headers.  If a block is given, it will be invoked every time a MESSAGE
+  # frame is received from the broker for this subscription.
+  # @param [String] dest the destination for the SEND frame to be delivered to
+  # @param [{Symbol => String}] additional headers to include in the generated frame
+  # @yield [message] invoked when a MESSAGE frame for this subscription is received
+  # @yieldparam [Stomper::Frame] message the MESSAGE frame sent by the broker
+  # @return [Stomper::Frame] the SUBSCRIBE frame sent to the broker
+  def subscribe(dest, headers={}, &block)
+    ::Stomper::Support.keys_to_sym!(headers)
+    if headers[:id].nil? || headers[:id].empty?
+      headers[:id] = ::Stomper::Support.next_serial
+    end
+    subscribe = create_frame('SUBSCRIBE', headers, { :destination => dest })
+    subscription_manager.add(subscribe, block) if block
+    transmit subscribe
+  end
+  
+  # Transmits an UNSUBSCRIBE frame to the broker for the supplied subscription ID,
+  # or SUBSCRIBE frame.
+  # @param [Stomper::Frame, String] frame_or_id the subscription ID or SUBSCRIBE
+  #   frame to unsubscribe from
+  # @return [Stomper::Frame] the UNSUBSCRIBE frame sent to the broker
+  # @raise [ArgumentError] if subscription ID cannot be determined.
+  def unsubscribe(frame_or_id, headers={})
+    sub_id = frame_or_id.is_a?(::Stomper::Frame) ? frame_or_id[:id] : frame_or_id
+    raise ArgumentError, 'subscription ID could not be determined' if sub_id.nil? || sub_id.empty?
+    if subscription_manager.subscribed_id? sub_id
+      transmit create_frame('UNSUBSCRIBE', headers, { :id => sub_id })
+    elsif subscription_manager.subscribed_destination? sub_id
+      subscription_manager.ids_for_destination(sub_id).map do |id|
+        transmit create_frame('UNSUBSCRIBE', headers, { :id => id })
+      end
+    end
+  end
+  
+  # Transmits a BEGIN frame to the broker to start a transaction named by +tx_id+.
+  # When directly handling transaction management in this fashion, it is up to
+  # you to ensure the uniqueness of transaction ids, that frames within this
+  # transaction have their +transaction+ header set, and that transactions are
+  # appropriately committed or aborted.
+  # @see Stomper::Extensions::Scoping#with_transaction
+  # @see #abort
+  # @see #commit
+  # @param [String] tx_id ID of the transaction to begin
+  # @param [{Symbol => String}] additional headers to include in the generated frame
+  # @return [Stomper::Frame] the BEGIN frame sent to the broker
+  def begin(tx_id, headers={})
+    transmit create_frame('BEGIN', headers, {:transaction => tx_id})
+  end
+  
+  # Transmits an ABORT frame to the broker to rollback a transaction named by +tx_id+.
+  # When directly handling transaction management in this fashion, it is up to
+  # you to ensure the uniqueness of transaction ids, that frames within this
+  # transaction have their +transaction+ header set, and that transactions are
+  # appropriately committed or aborted.
+  # @see Stomper::Extensions::Scoping#with_transaction
+  # @see #begin
+  # @see #commit
+  # @param [String] tx_id ID of the transaction to abort
+  # @param [{Symbol => String}] additional headers to include in the generated frame
+  # @return [Stomper::Frame] the ABORT frame sent to the broker
+  def abort(tx_id, headers={})
+    transmit create_frame('ABORT', headers, {:transaction => tx_id})
+  end
+  
+  # Transmits a COMMIT frame to the broker to complete a transaction named by +tx_id+.
+  # When directly handling transaction management in this fashion, it is up to
+  # you to ensure the uniqueness of transaction ids, that frames within this
+  # transaction have their +transaction+ header set, and that transactions are
+  # appropriately committed or aborted.
+  # @see Stomper::Extensions::Scoping#with_transaction
+  # @see #begin
+  # @see #abort
+  # @param [String] tx_id ID of the transaction to complete
+  # @param [{Symbol => String}] additional headers to include in the generated frame
+  # @return [Stomper::Frame] the COMMIT frame sent to the broker
+  def commit(tx_id, headers={})
+    transmit create_frame('COMMIT', headers, {:transaction => tx_id})
+  end
+  
+  # Disconnects from the broker. This is polite disconnect, in that it first
+  # transmits a DISCONNECT frame before closing the underlying socket. If the
+  # broker and client are using the Stomp 1.1 protocol, a receipt can be requested
+  # for the DISCONNECT frame, and the connection will remain active until
+  # the receipt is received or the broker closes the connection on its end.
+  # @param [{Symbol => String}] an optional set of headers to include in the
+  #   DISCONNECT frame (these can include event handlers, such as :on_receipt)
+  def disconnect(headers={})
+    transmit create_frame('DISCONNECT', headers, {})
+  end
+  
+  # Transmits an ACK frame to the broker to acknowledge that a corresponding
+  # MESSAGE frame has been processed by the client.
+  # @note If the negotiated Stomp protocol version is 1.1, this method will be
+  #   overridden by {Stomper::Extensions::Common::V1_1#ack}
+  # @overload ack(message, headers={})
+  #   @param [Stomper::Frame] message the MESSAGE frame to acknowledge
+  #   @param [{Object => String}] headers optional headers to include with the ACK frame
+  # @overload ack(message_id, headers={})
+  #   @param [String] message_id the ID of a MESSAGE frame to acknowledge
+  #   @param [{Object => String}] headers optional headers to include with the ACK frame
+  # @return [Stomper::Frame] the ACK frame sent to the broker
+  # @example Gonna need some examples for this one...
+  def ack(*args)
+    headers = args.last.is_a?(Hash) ? args.pop : {}
+    m_id = args.shift
+    if m_id.is_a?(::Stomper::Frame)
+      m_id = m_id[:'message-id']
+    end
+    m_headers = [ [:'message-id', m_id] ].inject({}) do |mh, (k,v)|
+      mh[k] = v unless v.nil? || v.empty?
+      mh
+    end
+    an_frame = create_frame('ACK', headers, m_headers)
+    raise ::ArgumentError, 'message ID could not be determined' if an_frame[:'message-id'].nil? || an_frame[:'message-id'].empty?
+    transmit an_frame
+  end
+
+  # Always raises an error because the NACK frame is only available to connections
+  # using version 1.1 of the Stomp protocol.
+  # @note If the negotiated Stomp protocol version is 1.1, this method will be
+  #   overridden by {Stomper::Extensions::Common::V1_1#nack}
+  # @see Stomper::Extensions::Protocol_1_1#nack
+  # @raise [Stomper::Errors::UnsupportedCommandError]
+  def nack(*args)
+    raise ::Stomper::Errors::UnsupportedCommandError, 'NACK'
+  end
+  
+  def create_frame(command, u_head, m_head, body=nil)
+    ::Stomper::Frame.new(command,
+      ::Stomper::Support.keys_to_sym(u_head).merge(m_head), body)
+  end
+  private :create_frame
+  
+  # Stomp Protocol 1.1 extensions to the common interface.
+  module V1_1
+    # Acknowledge that a MESSAGE frame has been received and successfully 
+    # processed. The Stomp 1.1 protocol now requires that both ID of the
+    # message and the ID of the subscription the message arrived on must be
+    # specified in the ACK frame's headers.
+    # @overload ack(message, headers={})
+    #   Transmit an ACK frame fro the MESSAGE frame. The appropriate
+    #   subscription ID will be determined from the MESSAGE frame's
+    #   +subscription+ header value.
+    #   @param [Stomper::Frame] message the MESSAGE frame to acknowledge
+    #   @param [{Object => String}] headers optional headers to include with the ACK frame
+    # @overload ack(message, subscription_id, headers={})
+    #   Transmit an ACK frame for the MESSAGE frame, but use the supplied
+    #   subscription ID instead of trying to determine it from the MESSAGE
+    #   frame's headers. You should use this method of the broker you are
+    #   connected to does not include a +subscribe+ header on MESSAGE frames.
+    #   @param [Stomper::Frame] message the MESSAGE frame to acknowledge
+    #   @param [String] subscription_id the ID of the subscription MESSAGE was delivered on.
+    #   @param [{Object => String}] headers optional headers to include with the ACK frame
+    # @overload ack(message_id, subscription_id, headers={})
+    #   Transmit an ACK frame for the MESSAGE frame with an ID of +message_id+
+    #   delivered on the subscription with an ID of +subscription_id+.
+    #   @param [String] message_id the ID of the MESSAGE frame to acknowledge
+    #   @param [String] subscription_id the ID of the subscription MESSAGE was delivered on.
+    #   @param [{Object => String}] headers optional headers to include with the ACK frame
+    # @return [Stomper::Frame] the ACK frame sent to the broker
+    # @raise [ArgumentError] if the message or subscription IDs cannot be
+    #   determined
+    # @example Gonna need some examples for this one...
+    def ack(message_or_id, *args)
+      transmit create_ack_or_nack('ACK', message_or_id, args)
+    end
+
+    # Inform the broker that a MESSAGE frame was not processed. A NACK frame
+    # is, in effect, the opposite of an ACK frame. The NACK command is a new
+    # feature introduced in Stomp 1.1, hence why it is unavailable to Stomp
+    # 1.0 connections.
+    # @overload nack(message, headers={})
+    #   Transmit a NACK frame fro the MESSAGE frame. The appropriate
+    #   subscription ID will be determined from the MESSAGE frame's
+    #   +subscription+ header value.
+    #   @param [Stomper::Frame] message the MESSAGE frame to un-acknowledge
+    #   @param [{Object => String}] headers optional headers to include with the NACK frame
+    # @overload nack(message, subscription_id, headers={})
+    #   Transmit a NACK frame for the MESSAGE frame, but use the supplied
+    #   subscription ID instead of trying to determine it from the MESSAGE
+    #   frame's headers. You should use this method of the broker you are
+    #   connected to does not include a +subscribe+ header on MESSAGE frames.
+    #   @param [Stomper::Frame] message the MESSAGE frame to un-acknowledge
+    #   @param [String] subscription_id the ID of the subscription MESSAGE was delivered on.
+    #   @param [{Object => String}] headers optional headers to include with the NACK frame
+    # @overload nack(message_id, subscription_id, headers={})
+    #   Transmit a NACK frame for the MESSAGE frame with an ID of +message_id+
+    #   delivered on the subscription with an ID of +subscription_id+.
+    #   @param [String] message_id the ID of the MESSAGE frame to un-acknowledge
+    #   @param [String] subscription_id the ID of the subscription MESSAGE was delivered on.
+    #   @param [{Object => String}] headers optional headers to include with the NACK frame
+    # @return [Stomper::Frame] the NACK frame sent to the broker
+    # @raise [ArgumentError] if the message or subscription IDs cannot be
+    #   determined
+    # @example Gonna need some examples for this one...
+    def nack(message_or_id, *args)
+      transmit create_ack_or_nack('NACK', message_or_id, args)
+    end
+
+    def create_ack_or_nack(command, m_id, args)
+      headers = args.last.is_a?(Hash) ? args.pop : {}
+      sub_id = args.shift
+      if m_id.is_a?(::Stomper::Frame)
+        sub_id = m_id[:subscription] if sub_id.nil? || sub_id.empty?
+        m_id = m_id[:'message-id']
+      end
+      [[:message, m_id], [:subscription, sub_id]].each do |(k,v)|
+        raise ::ArgumentError, "#{k} ID could not be determined" if v.nil? || v.empty?
+      end
+      create_frame(command, headers,
+        {:'message-id' => m_id, :subscription => sub_id })
+    end
+    private :create_ack_or_nack
+  end
+  
+  # A mapping between protocol versions and modules to include
+  EXTEND_BY_VERSION = {
+    '1.0' => [ ],
+    '1.1' => [ ::Stomper::Extensions::Common::V1_1 ]
+  }
+end

data/lib/stomper/extensions/events.rb

@@ -0,0 +1,213 @@
+# -*- encoding: utf-8 -*-
+
+# Module for event based extensions.
+module Stomper::Extensions::Events
+  # A mapping of event names that are just aliases for other event names.
+  ALIASED_EVENTS = {
+    :on_stomp => :on_connect,
+    :before_stomp => :before_connect,
+    :on_connection_disconnected => :on_connection_closed
+  }
+  
+  # Register a callback to be fired when an ABORT frame is sent to the broker.
+  # @return [self]
+  def on_abort(&block); bind_callback(:on_abort, block); end
+  # Register a callback to be fired before an ABORT frame is sent to the broker.
+  # @return [self]
+  def before_abort(&block); bind_callback(:before_abort, block); end
+  
+  # Register a callback to be fired when an ACK frame is sent to the broker.
+  # @return [self]
+  def on_ack(&block); bind_callback(:on_ack, block); end
+  # Register a callback to be fired before an ACK frame is sent to the broker.
+  # @return [self]
+  def before_ack(&block); bind_callback(:before_ack, block); end
+  
+  # Register a callback to be fired when a BEGIN frame is sent to the broker.
+  # @return [self]
+  def on_begin(&block); bind_callback(:on_begin, block); end
+  # Register a callback to be fired before a BEGIN frame is sent to the broker.
+  # @return [self]
+  def before_begin(&block); bind_callback(:before_begin, block); end
+  
+  # Register a callback to be fired when a COMMIT frame is sent to the broker.
+  # @return [self]
+  def on_commit(&block); bind_callback(:on_commit, block); end
+  # Register a callback to be fired before a COMMIT frame is sent to the broker.
+  # @return [self]
+  def before_commit(&block); bind_callback(:before_commit, block); end
+  
+  # Register a callback to be fired when a CONNECT frame is sent to the broker.
+  # @return [self]
+  def on_connect(&block); bind_callback(:on_connect, block); end
+  # Register a callback to be fired before a CONNECT frame is sent to the broker.
+  # @return [self]
+  def before_connect(&block); bind_callback(:before_connect, block); end
+  alias :on_stomp :on_connect
+  alias :before_stomp :before_connect
+  
+  # Register a callback to be fired when a CONNECTED frame is received from the broker.
+  # @return [self]
+  def on_connected(&block); bind_callback(:on_connected, block); end
+  
+  # Register a callback to be fired when a DISCONNECT frame is sent to the broker.
+  # @return [self]
+  def on_disconnect(&block); bind_callback(:on_disconnect, block); end
+  # Register a callback to be fired before a DISCONNECT frame is sent to the broker.
+  # @return [self]
+  def before_disconnect(&block); bind_callback(:before_disconnect, block); end
+  
+  # Register a callback to be fired when an ERROR frame is received from the broker.
+  # @return [self]
+  def on_error(&block); bind_callback(:on_error, block); end
+  
+  # Register a callback to be fired when a MESSAGE frame is received from the broker.
+  # @return [self]
+  def on_message(&block); bind_callback(:on_message, block); end
+  
+  # Register a callback to be fired when a NACK frame is sent to the broker.
+  # @return [self]
+  def on_nack(&block); bind_callback(:on_nack, block); end
+  # Register a callback to be fired before a NACK frame is sent to the broker.
+  # @return [self]
+  def before_nack(&block); bind_callback(:before_nack, block); end
+  
+  # Register a callback to be fired when a RECEIPT frame is received from the broker.
+  # @return [self]
+  def on_receipt(&block); bind_callback(:on_receipt, block); end
+  
+  # Register a callback to be fired when a SEND frame is sent to the broker.
+  # @return [self]
+  def on_send(&block); bind_callback(:on_send, block); end
+  # Register a callback to be fired before a SEND frame is sent to the broker.
+  # @return [self]
+  def before_send(&block); bind_callback(:before_send, block); end
+  
+  # Register a callback to be fired when a SUBSCRIBE frame is sent to the broker.
+  # @return [self]
+  def on_subscribe(&block); bind_callback(:on_subscribe, block); end
+  # Register a callback to be fired before a SUBSCRIBE frame is sent to the broker.
+  # @return [self]
+  def before_subscribe(&block); bind_callback(:before_subscribe, block); end
+  
+  # Register a callback to be fired when an UNSUBSCRIBE frame is sent to the broker.
+  # @return [self]
+  def on_unsubscribe(&block); bind_callback(:on_unsubscribe, block); end
+  # Register a callback to be fired before an UNSUBSCRIBE frame is sent to the broker.
+  # @return [self]
+  def before_unsubscribe(&block); bind_callback(:before_unsubscribe, block); end
+  
+  # Register a callback to be fired when a heartbeat is sent to the broker.
+  # @return [self]
+  def on_client_beat(&block); bind_callback(:on_client_beat, block); end
+  # Register a callback to be fired before a heartbeat frame is sent to the broker.
+  # @return [self]
+  def before_client_beat(&block); bind_callback(:before_client_beat, block); end
+  
+  # Register a callback to be fired when a heartbeat is received from the
+  # broker.
+  # @return [self]
+  def on_broker_beat(&block); bind_callback(:on_broker_beat, block); end
+
+  # Register a callback to be fired when a connection to the broker has
+  # been fully established. The connection is fully established once the
+  # client has sent a CONNECT frame, the broker has replied with CONNECTED
+  # and protocol versions and heartbeat strategies have been negotiated (if
+  # applicable.)
+  # @return [self]
+  def on_connection_established(&block); bind_callback(:on_connection_established, block); end
+  
+  # Register a callback to be fired when a connection to the broker has
+  # been closed. This event will be triggered by
+  # {Stomper::Connection#disconnect} as well as any IO exception that shuts
+  # the connection down.  In the event that the socket closes unexpectedly,
+  # {#on_connection_terminated} will be triggered before this event.
+  # @see #on_connection_terminated
+  # @return [self]
+  def on_connection_closed(&block); bind_callback(:on_connection_closed, block); end
+  alias :on_connection_disconnected :on_connection_closed
+  
+  # Register a callback to be fired when a connection to the broker has
+  # died as per the negotiated heartbeat strategy. This event is triggered
+  # through {Stomper::Connection#transmit} and {Stomper::Connection#receive}
+  # when heartbeat death has been detected. You should not expect this event
+  # to trigger at the precise moment the heartbeat strategy failed.
+  # @note This event is not triggered the moment heartbeat death occurs.
+  # @return [self]
+  def on_connection_died(&block); bind_callback(:on_connection_died, block); end
+  
+  # Register a callback to be fired when a connection to the broker has
+  # been unexpectedly terminated. This event will NOT be triggered by
+  # {Stomper::Connection#disconnect}.
+  # @see #on_connection_closed
+  # @return [self]
+  def on_connection_terminated(&block); bind_callback(:on_connection_terminated, block); end
+  
+  # Register a callback to be fired before transmitting any frame. If the
+  # supplied block makes any changes to the frame argument, those changes
+  # will be sent to the remaining #before_transmitting callbacks, and 
+  # ultimately will be passed on to the broker. This provides a convenient
+  # way to modify frames before transmission without having to subclass or
+  # otherwise extend the {Stomper::Connection} class. Furhter,
+  # changing the {Stomper::Frame#command command} attribute of the frame
+  # will change the frame-specific event that is triggered.
+  # @return [self]
+  def before_transmitting(&block); bind_callback(:before_transmitting, block); end
+  
+  # Register a callback to be fired after transmitting any frame.
+  # Changes made to the frame object will be passed along to all remaining
+  # {#after_transmitting} callbacks. Furhter,
+  # changing the {Stomper::Frame#command command} attribute of the frame
+  # will change the frame-specific event that is triggered.
+  # @return [self]
+  def after_transmitting(&block); bind_callback(:after_transmitting, block); end
+  
+  # Register a callback to be fired before receiving any frame. As a frame
+  # has not yet been received, callbacks invoked on this event will have
+  # to work with very limited information.
+  # @return [self]
+  def before_receiving(&block); bind_callback(:before_receiving, block); end
+  
+  # Register a callback to be fired after receiving any frame. Like
+  # the #before_transmitting event, any changes made to the frame will be
+  # passed along to all remaining {#after_receiving} callbacks. Furhter,
+  # changing the {Stomper::Frame#command command} attribute of the frame
+  # will change the frame-specific event that is triggered.
+  # @return [self]
+  def after_receiving(&block); bind_callback(:after_receiving, block); end
+  
+  # Binds a +Proc+ to be invoked when the given +event_name+ is triggered.
+  # @param [Symbol] event_name
+  # @param [Proc] cb_proc
+  # @return [self]
+  def bind_callback(event_name, cb_proc)
+    @event_callbacks ||= {}
+    @event_callbacks[event_name] ||= []
+    @event_callbacks[event_name] << cb_proc
+    self
+  end
+  
+  def trigger_event(event_name, *args)
+    event_name = ALIASED_EVENTS[event_name] ? ALIASED_EVENTS[event_name] : event_name
+    @event_callbacks[event_name] && @event_callbacks[event_name].each { |cb| cb.call(*args) }
+  end
+  private :trigger_event
+  
+  def trigger_received_frame(frame, *args); trigger_frame(frame, :on, :on_broker_beat, args); end
+  private :trigger_received_frame
+  
+  def trigger_transmitted_frame(frame, *args); trigger_frame(frame, :on, :on_client_beat, args); end
+  private :trigger_transmitted_frame
+  
+  def trigger_before_transmitted_frame(frame, *args); trigger_frame(frame, :before, :before_client_beat, args); end
+  private :trigger_before_transmitted_frame
+  
+  def trigger_frame(frame, timing, beat_event, args)
+    if (f_comm = frame.command && frame.command.downcase.to_sym)
+      trigger_event(:"#{timing}_#{f_comm}", frame, *args)
+    else
+      trigger_event(beat_event, frame, *args)
+    end
+  end
+  private :trigger_frame
+end