Class: Shamu::Events::EventsService

Inherits:
Services::Service show all
Defined in:
lib/shamu/events/events_service.rb

Overview

The EventsService handles receiving messages (#publish) and dispatching them to all registered subscribers (#subscriber). The actual delivery and message transport is defined by the concrete implementations of the EventService. See "Included Event Systems" below.

Use . or / to namespace and group channels. Channels are not related to each other but namespacing can help organize and group channels in reports and back-end tools.

Events are not guaranteed to be delivered and may be delivered more than once. Event processing should be idempotent and resilient to message loss.

Included Event Systems

  • In Memory intended for decoupling services all running withing the same process. This is the default.
  • ActiveRecord for low volume high-latency communications in a smaller system.

Selecting an Event System

Shamu relies on Scorpion to resolve dependencies. To select which event system to use, prepare the scorpion with specific hunting instructions.

Scorpion.prepare do
  capture Shamu::Events::ActiveRecord::Service
end

Direct Known Subclasses

ActiveRecord::Service, InMemory::Service

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Services::Service

#cache_for, #cached_lookup, #entity_list, #entity_lookup_list, #find_by_lookup, #lazy_association, #lookup_association

Class Method Details

.bridge(from, to, *channels)

This method returns an undefined value.

Subscribe to the given channels from one service and forward them to another service.

Parameters:

  • from (EventsService) —

    the service to subscribe to.

  • to (EventsService) —

    the service to forward to.

  • the (Array<String>) —

    channels to forwar.



87
88
89
90
91
92
93
 
# File 'lib/shamu/events/events_service.rb', line 87

def self.bridge( from, to, *channels )
  Array( channels ).each do |channel|
    from.subscribe( channel ) do |message|
      to.publish channel, message
    end
  end
end

.create(scorpion, *args, &block) ⇒ EventsService

Prepare the default event service implementation to use. The default event service can be overridden when setting up the scorpion.

Examples:

Scorpion.prepare do
  capture Shamu::Events::EventsService do |scorpion, *args|
    scorpion.fetch Shamu::Events::InMemory::AsyncService, *args
  end
end

Returns:



50
51
52
 
# File 'lib/shamu/events/events_service.rb', line 50

def self.create( scorpion, *args, &block )
  @events_service ||= scorpion.fetch InMemory::Service
end

Instance Method Details

#deserialize(raw) ⇒ Message

Deserialize a message back to a Message instance.

Parameters:

  • raw (String) —

    data.

Returns:

  • (Message) —

    the deserialized message.



116
117
118
119
120
 
# File 'lib/shamu/events/events_service.rb', line 116

def deserialize( raw )
  hash = MultiJson.load( raw )
  message_class = hash["class"].constantize
  scorpion.fetch message_class, hash["attributes"]
end

#publish(channel, message)

This method returns an undefined value.

Publish a well-defined Message to a known channel so that any client that has subscribed will receive a copy of the message to process.

Events are delivered asynchronously. There is no guarantee that a subscriber has received or processed a message.

Parameters:

  • channel (String) —

    to publish to.

  • message (Message) —

    to publish.



64
65
66
 
# File 'lib/shamu/events/events_service.rb', line 64

def publish( channel, message )
  fail NotImplementedError
end

#serialize(message) ⇒ String

Serialize a message so that it can be transfered from publisher to subsriber.

Parameters:

  • message (Message) —

    to serializer.

Returns:

  • (String) —

    the serialized message.



104
105
106
107
108
 
# File 'lib/shamu/events/events_service.rb', line 104

def serialize( message )
  MultiJson.dump \
    class: message.class.name,
    attributes: message.to_attributes
end

#subscribe(channel) {|message| ... }

This method returns an undefined value.

Subscribe to receive notifications of events on the named channel. Any time a publisher pushes a message callback will be invoked with a copy of the message.

Parameters:

  • channel (String) —

    to listen to.

Yields:

  • (message)

Yield Parameters:



76
77
78
 
# File 'lib/shamu/events/events_service.rb', line 76

def subscribe( channel, &callback )
  fail NotImplementedError
end