hoodoo 1.0.5 → 1.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YzEwZWNjMTA5OTJhODlhN2VkZGQxMDQ0NzNhOGVjZjUxMTM2ZmM1Nw==
+    MTFiNjAzNDk4MDdmOTFmNWRkZTg1MmY3ODExMmY3ZGU4MTU3YjkzNg==
   data.tar.gz: !binary |-
-    OTA1MzJjZTZlYzFhY2FiNWUxZWM3MDBiN2QwYzEwNDYyNDM2Y2ZjOA==
+    MjMwNDRjODEzZDU5YmRmM2E0YmRlNTlmYTVkYzA3NmIxMDA3ZjE1Yg==
 SHA512:
   metadata.gz: !binary |-
-    ZDQ4YmVkYmQ3YWEwMWY1NGU1ZDZlYTA2NjAxNzM2NTFiYzk5NjI1NTNmZWE0
-    NGYwYjhlMmIxZmY0YTViZjk4Zjg4ODgzODRjNGQ5MDhmNjEwZjVmZDJhM2Yx
-    ODQzZjliM2NhYTE1NTQ2ZjdjNzk1YTZmNmE3NTM2MGQ2NWFhNjE=
+    ZjEzZDYxZDJjZGI3MWU0NDFmYTYwNzQ2ZmYwZGY4MmQ2Zjc0NWJhZmRiMjli
+    ZjQ0MTA1MzkzYTFkN2RhZTA1YWFkNjc1MDI4MDgwNzYyZDk5YmFhZTdmZDE1
+    ZTJlYjRjZDc5N2IzYmNiNTc0M2Q0NzMzNDhlODk3OTEzZjc0YTU=
   data.tar.gz: !binary |-
-    ODhiYjgzMTFmYTZhOGFhZGM4NDM2OWU3N2MwNjE3OGVhMTk0MGFkNGFhZTg5
-    Y2E5Mzg0YjI3OTBkNzcyNjJhZGI5MjYyN2M5YTYxOWYyYjVjMTgxMGRiM2Ix
-    MGQ4YTBiNWY4MzMzNTI3NWJkODI3ZTE0YWJmYjlkYjI3YWQ4MTg=
+    MzMwNGY1MGZlOTFiZjE3YmI0MDgxYjcwYTUxYTliNTQxNDFjODMwNThkMGUx
+    ZDk5NzE0ZDcwMWY1YzZhMTIxMzgyY2ZiMWJiMTFiZjk4ZmNlMTE0N2JmZThj
+    ZDIxZWM4MzQ0ODc0ODdmNWU5OWEzYmU3ODlkMTE4OTI1ZTNiYWM=

data/lib/hoodoo/client/endpoint/endpoints/amqp.rb

@@ -39,7 +39,7 @@ module Hoodoo
             # to keep Rack happy.
 
             endpoint_uri      = URI.parse( 'http://localhost:80' )
-            endpoint_uri.path = @discovery_result.equivalent_path
+            endpoint_uri.path = @discovery_result.routing_path
 
             @description                  = Hoodoo::Client::Endpoint::HTTPBased::DescriptionOfRequest.new
             @description.discovery_result = @discovery_result
@@ -136,40 +136,58 @@ module Hoodoo
             action = description_of_request.action
             data   = get_data_for_request( description_of_request )
 
-            # Host and port are just there to keep Rack happy at the
+            # Host and port are only provided to keep Rack happy at the
             # receiving end of the over-AMQP synthesised HTTP request.
 
-            alchemy_options = {
-              :host    => description_of_request.endpoint_uri.host,
-              :port    => description_of_request.endpoint_uri.port,
-              :query   => data.query_hash,
-              :body    => data.body_string,
-              :headers => data.header_hash
+            http_method =
+            {
+              :create => 'POST',
+              :update => 'PATCH',
+              :delete => 'DELETE'
+            }[ action ] || 'GET'
+
+            http_message =
+            {
+              'scheme'  => 'http',
+              'verb'    => http_method,
+
+              'host'    => description_of_request.endpoint_uri.host,
+              'port'    => description_of_request.endpoint_uri.port,
+              'path'    => data.full_uri.path,
+              'query'   => data.query_hash,
+
+              'headers' => data.header_hash,
+              'body'    => data.body_string
             }
 
             unless self.session_id().nil? # Session comes from Endpoint superclass
-              alchemy_options[ :session_id ] = self.session_id()
+              http_message[ 'session_id' ] = self.session_id()
             end
 
-            http_method = {
-              :create => 'POST',
-              :update => 'PATCH',
-              :delete => 'DELETE'
-            }[ action ] || 'GET'
+            amqp_response = self.alchemy().send_message_to_resource( http_message )
+
+            description_of_response              = DescriptionOfResponse.new
+            description_of_response.action       = action
+            description_of_response.http_headers = {}
 
-            description_of_response        = DescriptionOfResponse.new
-            description_of_response.action = action
+            if amqp_response == AlchemyFlux::TimeoutError
+              description_of_response.http_status_code = 408
+              description_of_response.raw_body_data    = '408 Timeout'
 
-            amqp_response = self.alchemy().http_request(
-              description_of_request.discovery_result.queue_name,
-              http_method,
-              data.full_uri.path,
-              alchemy_options
-            )
+            elsif amqp_response == AlchemyFlux::MessageNotDeliveredError
+              description_of_response.http_status_code = 404
+              description_of_response.raw_body_data    = '404 Not Found'
 
-            description_of_response.http_status_code = amqp_response.status_code.to_i
-            description_of_response.http_headers     = amqp_response.headers || {}
-            description_of_response.raw_body_data    = amqp_response.body
+            elsif amqp_response.is_a?( Hash )
+              description_of_response.http_status_code = amqp_response[ 'status_code' ].to_i
+              description_of_response.http_headers     = amqp_response[ 'headers'     ] || {}
+              description_of_response.raw_body_data    = amqp_response[ 'body'        ]
+
+            else
+              description_of_response.http_status_code = 500
+              description_of_response.raw_body_data    = '500 Internal Server Error'
+
+            end
 
             return get_data_for_response( description_of_response )
           end

data/lib/hoodoo/discovery.rb

@@ -15,6 +15,6 @@ require 'hoodoo/services/discovery/results/for_local'
 require 'hoodoo/services/discovery/results/for_remote'
 
 require 'hoodoo/services/discovery/discoverers/by_convention'
-require 'hoodoo/services/discovery/discoverers/by_consul'
+require 'hoodoo/services/discovery/discoverers/by_flux'
 require 'hoodoo/services/discovery/discoverers/by_drb/drb_server'
 require 'hoodoo/services/discovery/discoverers/by_drb/by_drb'

data/lib/hoodoo/services/discovery/discoverers/by_flux.rb

@@ -0,0 +1,130 @@
+########################################################################
+# File::    by_flux.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Discover resource endpoint locations via Alchemy Flux.
+# ----------------------------------------------------------------------
+#           03-Mar-2015 (ADH): Created.
+#           21-Jan-2016 (ADH): Reimplemented for Alchemy Flux.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      # Discover resource endpoint locations via Alchemy Flux.
+      #
+      # For Flux, it's less about discovery as it is about convention
+      # and announcing. We have to set some system variables when the
+      # application starts up, _before_ the Rack `run` call gets as
+      # far as the Alchemy Flux server's implementation - in practice
+      # this means announcement needs to happen from the Hoodoo
+      # middleware's constructor, synchronously. The environment
+      # variables tell Flux about this local service's URI-located
+      # endpoints and derive a consistent, replicable 'service name'
+      # from the resources which the service implements.
+      #
+      # Once all that is set up, the local Alchemy instance knows how
+      # to listen for relevant messages for 'this' service on the queue
+      # and Hoodoo in 'this' service knowns which resources are local,
+      # or which are remote; and it knows that Flux is able in turn to
+      # use URI-based to-resource communications for inter-resource
+      # calls without any further explicit discovery within Hoodoo
+      # beyond simply saying "here's the AMQP Flux endpoint class".
+      #
+      class ByFlux < Hoodoo::Services::Discovery
+
+        protected
+
+          # Announce the location of an instance to Alchemy Flux.
+          #
+          # Call via Hoodoo::Services::Discovery::Base#announce.
+          #
+          # +resource+:: Passed to #discover_remote.
+          # +version+::  Passed to #discover_remote.
+          # +options+::  See below.
+          #
+          # The Options hash informs the announcer of the intended endpoint
+          # base URI for the resource and also, where available, provides a
+          # head-up on the full range of resource _names_ that will be
+          # present in this single service application (see
+          # Hoodoo::Services::Service::comprised_of). Keys MUST be Symbols.
+          # Associated required values are:
+          #
+          # +services+:: Array of Hoodoo::Services::Discovery::ForLocal
+          #              instances describing available resources in this
+          #              local service.
+          #
+          def announce_remote( resource, version, options = {} )
+
+            alchemy_resource_paths = ENV[ 'ALCHEMY_RESOURCE_PATHS' ]
+            alchemy_service_name   = ENV[ 'ALCHEMY_SERVICE_NAME'   ]
+
+            # Under Flux, we "announce" via a local environment variable when
+            # this service awakens which tells Flux what to listen for on the
+            # AMQP queue.
+            #
+            # Since inbound HTTP calls into the architecture are based on URIs
+            # and paths, there needs to be a mapping at that point to queue
+            # endpoints. Historically Hoodoo adopted an (in hindsight, unwise)
+            # approach of "/v<version>/<pluralised_resource>" c.f. Rails,
+            # rather than just "/<version>/<resource>" - e.g. there was
+            # "/v1/members" instead of "/1/Member". This means things like the
+            # "ByConvention" discoverer have to use pluralisation rules and
+            # exceptions. It's messy.
+            #
+            # To clean things up, the work on Alchemy Flux sets up *two* paths
+            # in Hoodoo - the old one for backwards compatibility, and a new
+            # one of the above simpler form. Now it's easy to go from version
+            # and resource name to path or back internally with no mappings.
+            #
+            if ( alchemy_resource_paths.nil? ||
+                 alchemy_resource_paths.strip.empty? )
+
+              services = options[ :services ] || []
+              paths    = []
+
+              services.each do | service |
+                custom_path   = service.base_path
+                de_facto_path = service.de_facto_base_path
+
+                paths << custom_path << de_facto_path
+              end
+
+              ENV[ 'ALCHEMY_RESOURCE_PATHS' ] = paths.join( ',' )
+            end
+
+            if ( alchemy_service_name.nil? ||
+                 alchemy_service_name.strip.empty? )
+              ENV[ 'ALCHEMY_SERVICE_NAME' ] = Hoodoo::Services::Middleware::service_name()
+            end
+
+            return discover_remote( resource, version )
+          end
+
+          # Discover the location of an instance.
+          #
+          # Returns a Hoodoo::Services::Discovery::ForAMQP instance if
+          # the endpoint is found, else +nil+.
+          #
+          # Call via Hoodoo::Services::Discovery::Base#announce.
+          #
+          # +resource+:: Passed to #discover_remote.
+          # +version+::  Passed to #discover_remote.
+          #
+          def discover_remote( resource, version )
+            de_facto_path = Hoodoo::Services::Middleware::de_facto_path_for(
+              resource,
+              version
+            )
+
+            return Hoodoo::Services::Discovery::ForAMQP.new(
+              resource: resource,
+              version:  version
+            )
+          end
+
+      end
+    end
+  end
+end

data/lib/hoodoo/services/discovery/results/for_amqp.rb

@@ -25,32 +25,26 @@ module Hoodoo
         #
         attr_accessor :version
 
-        # Queue name for the target service implementation, as a
-        # String (e.g. "service.account").
+        # Path at which the resource is expected to be found on the queue
+        # (routing via Topic Exchange and Alchemy Flux's translations of
+        # paths to keys).
         #
-        attr_accessor :queue_name
-
-        # URL path equivalent that should be mapped to the queue in
-        # #queue_name, as a String (e.g. "/v2/accounts").
-        #
-        attr_accessor :equivalent_path
+        attr_reader :routing_path
 
         # Create an instance with named parameters as follows:
         #
-        # +resource+::       See #resource.
-        # +version+::        See #version.
-        # +queue_name+::     See #queue_name.
-        # +equivalent_pat+:: See #equivalent_pat.
+        # +resource+:: See #resource.
+        # +version+::  See #version.
         #
-        def initialize( resource:,
-                        version:,
-                        queue_name:,
-                        equivalent_path: )
-
-          self.resource        = resource.to_sym
-          self.version         = version.to_i
-          self.queue_name      = queue_name
-          self.equivalent_path = equivalent_path
+        def initialize( resource:, version: )
+
+          @resource     = resource.to_sym
+          @version      = version.to_i
+          @routing_path = Hoodoo::Services::Middleware.de_facto_path_for(
+            resource,
+            version
+          )
+
         end
       end
     end

data/lib/hoodoo/services/discovery/results/for_local.rb

@@ -46,6 +46,17 @@ module Hoodoo
         #
         attr_accessor :routing_regexp
 
+        # The de facto routing equivalent of #base_path. This is not
+        # a custom path based on the interface's declared endpoint; it
+        # is derived directlyf rom resource or version - for example,
+        # "/1/Product" or "/2/Member". String.
+        #
+        attr_accessor :de_facto_base_path
+
+        # As #routing_regexp, but matches #de_facto_base_path.
+        #
+        attr_accessor :de_facto_routing_regexp
+
         # The Hoodoo::Services::Interface subclass _class_ describing the
         # resource interface.
         #
@@ -62,6 +73,8 @@ module Hoodoo
         # +version+::                 See #version.
         # +base_path+::               See #base_path.
         # +routing_regexp+::          See #routing_regexp.
+        # +de_facto_base_path+::      See #de_facto_base_path.
+        # +de_facto_routing_regexp+:: See #de_facto_routing_regexp.
         # +interface_class+::         See #interface_class.
         # +implementation_instance+:: See #implementation_instance.
         #
@@ -69,6 +82,8 @@ module Hoodoo
                         version:,
                         base_path:,
                         routing_regexp:,
+                        de_facto_base_path:,
+                        de_facto_routing_regexp:,
                         interface_class:,
                         implementation_instance: )
 
@@ -76,6 +91,8 @@ module Hoodoo
           self.version                 = version.to_i
           self.base_path               = base_path
           self.routing_regexp          = routing_regexp
+          self.de_facto_base_path      = de_facto_base_path
+          self.de_facto_routing_regexp = de_facto_routing_regexp
           self.interface_class         = interface_class
           self.implementation_instance = implementation_instance
         end

data/lib/hoodoo/services/middleware/amqp_log_message.rb

@@ -3,8 +3,9 @@
 # (C)::     Loyalty New Zealand 2014
 #
 # Purpose:: Structured logging onto an AMQP-based queue, via the
-#           AlchemyAMQ gem. Optional; class is defined only if the
-#           supporting AlchemyAMQ gem's classes are defined.
+#           Alchemy Flux gem. This class just exists to rationalise
+#           any parameters inbound in order to generate a clean
+#           representation for Flux.
 #
 #           The middleware uses this to put log and error messages
 #           on the queue. Interested services use this to read such
@@ -13,173 +14,110 @@
 #           20-Nov-2014 (ADH): Created.
 ########################################################################
 
-# TODO: See spec/alchemy/alchemy-amq.rb. Remove this once 'real' Alchemy
-#       is opened.
-#
-$LOAD_PATH.unshift File.join( File.dirname( __FILE__ ), 'alchemy' )
-
 module Hoodoo; module Services
   class Middleware
 
-    begin
-      require 'alchemy-amq' # Optional
+    # A representation of a log message placed on an AMQP-based queue.
+    # The primary expected communications interface is Alchemy Flux at
+    # the time of writing.
+    #
+    class AMQPLogMessage
 
-      # For AlchemyAMQ gem users, the AMQPLogMessage class provides an
-      # AlchemyAMQ::Message subclass used for sending structured log data to
-      # the queue. Hoodoo::Logger uses this.
+      # The Time +strftime+ formatter used for string conversions in this
+      # class.
       #
-      # See the AlchemyAMQ gem for more details.
+      TIME_FORMATTER = '%Y-%m-%d %H:%M:%S.%12N %Z'
+
+      # A UUID to assign to this log message. See Hoodoo::UUID::generate.
       #
-      class AMQPLogMessage < ::AlchemyAMQ::Message
-
-        # The named "type" of this message, to be registered with AlchemyAMQ.
-        #
-        TYPE = 'hoodoo_service_middleware_amqp_log_message'
-
-        # The Time +strftime+ formatter used for string conversions in this
-        # class.
-        #
-        TIME_FORMATTER = '%Y-%m-%d %H:%M:%S.%12N %Z'
-
-        # This line of code registers wth AlchemyAMQ, but also makes RDoc
-        # screw up. RDoc decides that we have a new module,
-        # Hoodoo::Services::Middleware::AMQPLogMessage::AlchemyAMQ. Very
-        # strange...
-        #
-        ::AlchemyAMQ::Message.register_type( TYPE, self )
-
-        # ...so do _this_ purely so that we can get 100% real documentation
-        # coverage without it being clouded by RDoc's hiccups.
-
-        # This documentation exists purely to work around an RDoc hiccup where
-        # it thinks such a module exists.
-        #
-        # See file "services/middleware/amqp_log_message.rb" for details.
-        #
-        module AlchemyAMQ
-        end
+      attr_accessor :id
 
-        # A UUID to assign to this log message. See Hoodoo::UUID::generate.
-        #
-        attr_accessor :id
-
-        # Logging level. See Hoodoo::Logger.
-        #
-        attr_accessor :level
-
-        # Logging component. See Hoodoo::Logger.
-        #
-        attr_accessor :component
-
-        # Component log code. See Hoodoo::Logger.
-        #
-        attr_accessor :code
-
-        # The time at which this log message is being reported to the Logger
-        # instance. This is a formatted *String* to high accuracy. See also
-        # #reported_at=.
-        #
-        attr_reader :reported_at
-
-        # Set the time read back by #reported_at using a Time instance. This
-        # is formatted internally as a String via TIME_FORMATTER and reported
-        # as such in subsequent calls to #reported_at.
-        #
-        # Conversion from Time to String is done here, rather than by the
-        # caller setting this instance's variables, so that we can internally
-        # enforce the accuracy required for this field.
-        #
-        # +time+:: The Time instance to set (and process into a string
-        #          internally via TIME_FORMATTER), *or* a String instance
-        #          already so formatted, *or* +nil+ to clear the value.
-        #
-        def reported_at=( time )
-          if time.is_a?( String )
-            @reported_at = time
-          elsif time.is_a?( Time )
-            @reported_at = time.strftime( TIME_FORMATTER )
-          else
-            @reported_at = nil
-          end
-        end
+      # Logging level. See Hoodoo::Logger.
+      #
+      attr_accessor :level
 
-        # Log payload. See Hoodoo::Logger.
-        #
-        attr_accessor :data
-
-        # Optional calling Caller ID, via session data inside the payload - see
-        # Hoodoo::Logger.
-        #
-        attr_accessor :caller_id
-
-        # Optional interaction UUID, via session data inside the payload - see
-        # Hoodoo::Logger.
-        #
-        attr_accessor :interaction_id
-
-        # Optional hash of identity properties from the session data inside the
-        # payload - see Hoodoo::Logger.
-        #
-        attr_accessor :identity
-
-        # Create an instance with options keyed on the attributes defined for
-        # the class.
-        #
-        def initialize(options = {})
-          update( options ) # Should be called before 'super'
-          super( options )
-
-          @type = AMQPLogMessage::TYPE
-        end
+      # Logging component. See Hoodoo::Logger.
+      #
+      attr_accessor :component
 
-        # Seralize this instance. See the AlchemyAMQ gem and
-        # AlchemyAMQ::Message#serialize.
-        #
-        def serialize
-          @content = {
-            :id             => @id,
-            :level          => @level,
-            :component      => @component,
-            :code           => @code,
-            :reported_at    => @reported_at,
-
-            :data           => @data,
-
-            :interaction_id => @interaction_id,
-            :caller_id      => @caller_id,
-            :identity       => @identity
-          }
-
-          super
-        end
+      # Component log code. See Hoodoo::Logger.
+      #
+      attr_accessor :code
 
-        # Unpack a serialized representation into this instance. See the
-        # AlchemyAMQ gem and AlchemyAMQ::Message#deserialize.
-        #
-        def deserialize
-          super
-          update( @content )
+      # The time at which this log message is being reported to the Logger
+      # instance. This is a formatted *String* to high accuracy. See also
+      # #reported_at=.
+      #
+      attr_reader :reported_at
+
+      # Set the time read back by #reported_at using a Time instance. This
+      # is formatted internally as a String via TIME_FORMATTER and reported
+      # as such in subsequent calls to #reported_at.
+      #
+      # Conversion from Time to String is done here, rather than by the
+      # caller setting this instance's variables, so that we can internally
+      # enforce the accuracy required for this field.
+      #
+      # +time+:: The Time instance to set (and process into a string
+      #          internally via TIME_FORMATTER), *or* a String instance
+      #          already so formatted, *or* +nil+ to clear the value.
+      #
+      def reported_at=( time )
+        if time.is_a?( String )
+          @reported_at = time
+        elsif time.is_a?( Time )
+          @reported_at = time.strftime( TIME_FORMATTER )
+        else
+          @reported_at = nil
         end
+      end
+
+      # Log payload. See Hoodoo::Logger.
+      #
+      attr_accessor :data
 
-        # Set public attribute values according to an options hash keyed on
-        # the attributes defined for the class.
-        #
-        def update( options )
-          self.id             = options[ :id             ]
-          self.level          = options[ :level          ]
-          self.component      = options[ :component      ]
-          self.code           = options[ :code           ]
-          self.reported_at    = options[ :reported_at    ]
-
-          self.data           = options[ :data           ]
-
-          self.interaction_id = options[ :interaction_id ]
-          self.caller_id      = options[ :caller_id      ]
-          self.identity       = options[ :identity       ]
+      # Optional calling Caller ID, via session data inside the payload - see
+      # Hoodoo::Logger.
+      #
+      attr_accessor :caller_id
+
+      # Optional interaction UUID, via session data inside the payload - see
+      # Hoodoo::Logger.
+      #
+      attr_accessor :interaction_id
+
+      # Optional hash of identity properties from the session data inside the
+      # payload - see Hoodoo::Logger.
+      #
+      attr_accessor :identity
+
+      # Create an instance with options keyed on the attributes defined for
+      # the class. Option keys may be Strings or Symbols but must only match
+      # defined attribute names.
+      #
+      def initialize( options = {} )
+        options.each do | name, value |
+          send( "#{ name }=", value )
         end
       end
 
-    rescue LoadError # Optional file 'alchemy-amq' is absent
+      # Retrieve a simple Hash representation of this instance.
+      #
+      def to_h
+        {
+          'id'             => @id,
+          'level'          => @level,
+          'component'      => @component,
+          'code'           => @code,
+          'reported_at'    => @reported_at,
+
+          'data'           => @data,
+
+          'interaction_id' => @interaction_id,
+          'caller_id'      => @caller_id,
+          'identity'       => Hoodoo::Utilities.stringify( @identity )
+        }
+      end
     end
 
   end