Hoodoo::Services::Discovery

The service discovery mechanism is a way to find Resource implementations running inside service applications that may be available at HTTP URIs, over an AMQP queue or, potentially, any other system. Subclasses implement a particular distinct discovery approach. When implementations of services start up, they announce themselves (via Hoodoo::Services::Middleware) to the discovery engine. When other Resources (or Hoodoo::Client) want to find them, they query the same discovery engine to find out the original announcement information.

Depending on how a discovery engine shares information about announced Resource endpoints, Resources might only be found if they are are on the same local machine; or the same remote host or queue; or they might perhaps be available even if scattered across multiple hosts and/or transport types.

Implementations of service announcement and discovery code must be a subclass of this class, then optionally implement configure_with and (almost certainly, but still optionally) announce_remote; and must always implement discover_remote.

Namespace

CLASS Hoodoo::Services::Discovery::ByConvention
CLASS Hoodoo::Services::Discovery::ByDRb
CLASS Hoodoo::Services::Discovery::ByFlux
CLASS Hoodoo::Services::Discovery::ForAMQP
CLASS Hoodoo::Services::Discovery::ForHTTP
CLASS Hoodoo::Services::Discovery::ForLocal
CLASS Hoodoo::Services::Discovery::ForRemote

Methods

A

announce,
announce_remote

C

configure_with

D

discover,
discover_remote

I

is_local?

N

Class Public methods

new( options = {} ) Link

Create a new instance.

options: Passed to the subclass in use via configure_with. Subclasses define their options. Only instantiate such subclasses, not this 'Base' class; see the subclass documentation for option details.

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 44
def initialize( options = {} )
  @known_local_resources = {}
  configure_with( options )
end

Instance Public methods

announce( resource, version = 1, options = {} ) Link

Indicate that a resource is available locally and broacast its location to whatever discovery service a subclass supports via announce_remote.

resource: Resource name as a Symbol or String (e.g. :Purchase).
version: Endpoint version as an Integer; optional; default is 1.
options: Defined by whatever subclass is in use. See that subclass's documentation for details.

Returns the result of calling announce_remote (in the subclass in use) with the same parameters. See the protected method definition in this base class for details.

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 66
def announce( resource, version = 1, options = {} )
  resource = resource.to_sym
  version  = version.to_i
  result   = announce_remote( resource, version, options )

  @known_local_resources[ resource ] ||= {}
  @known_local_resources[ resource ][ version ] = result

  return result
end

discover( resource, version = 1 ) Link

Find a resource endpoint. This may be recorded locally or via whatever remote discovery mechanism a subclass implements.

resource: Resource name as a Symbol or String (e.g. :Purchase).
version: Endpoint version as an Integer; optional; default is 1.

Returns the result of calling discover_remote (in the subclass in use) with the same parameters. See the protected method definition in this base class for details.

Use is_local? if you need to know that an endpoint was announced through this same instance (“locally”).

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 93
def discover( resource, version = 1 )
  resource = resource.to_sym
  version  = version.to_i

  if ( is_local?( resource, version ) )
    return @known_local_resources[ resource ][ version ]
  else
    return discover_remote( resource, version )
  end
end

is_local?( resource, version = 1 ) Link

Was a resource announced in this instance (“locally”)? Returns true if so, else false.

This only returns true if annouce has been called for the given resource and version.

resource: Resource name as a Symbol or String (e.g. :Purchase).
version: Endpoint version as an Integer; optional; default is 1.

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 116
def is_local?( resource, version = 1 )
  resource = resource.to_sym
  version  = version.to_i

  return @known_local_resources.has_key?( resource ) &&
         @known_local_resources[ resource ].has_key?( version )
end

Instance Protected methods

announce_remote( resource, version, options = {} ) Link

Announce a resource endpoint. Subclasses optionally implement this method to broadcast information to other instances of the same subclass by some subclass-implemented mechanism.

Discovery instance users do not call this method directly. Call announce instead.

Subclasses must return one of the Discovery “For” class instances, e.g. a Hoodoo::Services::Discovery::ForHTTP or Hoodoo::Services::Discovery::ForAMQP instance. This encapsulates the HTTP details required to contact the endpoint, or AMQP (queue) details required to contact the endpoint, respectively.

Subclasses must return nil if it has a problem announcing and cannot provide information for the given resource / version.

resource: Resource name as a String.
version: Endpoint version as an Integer.
options: See subclass documentation for option details.

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 156
def announce_remote( resource, version, options = {} )
  # Implementation is optional and up to subclasses to do.
  nil
end

configure_with( options ) Link

Configure a new instance. Subclasses optionally implement this method to store configuration information relevant to that subclass. Subclasses must document their options.

options: See subclass documentation for option details.

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 132
def configure_with( options )
  # Implementation is optional and up to subclasses to do.
end

discover_remote( resource, version ) Link

Discover the location of a resource endpoint. Subclasses must implement this method to retrieve information about the location of resource endpoints by some subclass-implemented mechanism.

Discovery instance users do not call this method directly. Call discover instead.

If the requested endpoint is not found, subclasses must return nil.

resource: Resource name as a String.
version: Endpoint version as an Integer.

Source: show

# File lib/hoodoo/services/discovery/discovery.rb, line 180
def discover_remote( resource, version )
  raise "Hoodoo::Services::Discovery::Base subclass does not implement remote discovery required for resource '#{ resource }' / version '#{ version }'"
end

Class Hoodoo::Services::Discovery < Object