hoodoo 1.0.2

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

@@ -0,0 +1,58 @@
+########################################################################
+# File::    for_amqp.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Describe a resource endpoint location in a way that allows
+#           it to be contacted over AMQP (e.g. via Alchemy).
+# ----------------------------------------------------------------------
+#           03-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      # Describe a resource endpoint location in a way that allows
+      # it to be contacted over AMQP (e.g. via Alchemy).
+      #
+      class ForAMQP
+
+        # The resource name described, as a Symbol (e.g. +:Purchase+).
+        #
+        attr_accessor :resource
+
+        # Resource endpoint version, as an Integer (e.g. 2).
+        #
+        attr_accessor :version
+
+        # Queue name for the target service implementation, as a
+        # String (e.g. "service.account").
+        #
+        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
+
+        # Create an instance with named parameters as follows:
+        #
+        # +resource+::       See #resource.
+        # +version+::        See #version.
+        # +queue_name+::     See #queue_name.
+        # +equivalent_pat+:: See #equivalent_pat.
+        #
+        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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+########################################################################
+# File::    for_http.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Describe a resource endpoint location in a way that allows
+#           it to be contacted over HTTP.
+# ----------------------------------------------------------------------
+#           03-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      # Describe a resource endpoint location in a way that allows
+      # it to be contacted over HTTP.
+      #
+      class ForHTTP
+
+        # The resource name described, as a Symbol (e.g. +:Purchase+).
+        #
+        attr_accessor :resource
+
+        # Resource endpoint version, as an Integer (e.g. 2).
+        #
+        attr_accessor :version
+
+        # Full URI (as a URI object) at which the resource endpoint
+        # implementation can be contacted.
+        #
+        attr_accessor :endpoint_uri
+
+        # Full URI (as a URI object) of an HTTP proxy to use as an
+        # override to <tt>ENV['HTTP_PROXY']</tt> which Ruby itself
+        # will otherwise read. Will be +nil+ for no proxy override.
+        #
+        attr_accessor :proxy_uri
+
+        # An optional String indicating a relative or absolute file
+        # path to the location of a .pem format Certificate
+        # Authority file (trust store), which may include multliple
+        # certificates. The certificates in the file will be used
+        # by Net::HTTP to validate the SSL Ceritificate Chain
+        # presented by remote servers, when calling endpoints over
+        # HTTPS with Hoodoo::Client.
+        #
+        # Default +nil+ value should be used in nearly all cases
+        # and uses Ruby OpenSSL defaults which are generally
+        # Operating System provided.
+        #
+        attr_accessor :ca_file
+
+        # Optional Float indicating the Net::HTTP read timeout value.
+        # This operates at the HTTP transport level and is independent
+        # of any timeouts set within the API providing server.
+        #
+        attr_accessor :http_timeout
+
+        # Create an instance with named parameters as follows:
+        #
+        # +resource+::     See #resource.
+        # +version+::      See #version.
+        # +endpoint_uri+:: See #endpoint_uri.
+        # +proxy_uri+::    See #proxy_uri. Optional.
+        # +ca_file+::      See #ca_file. Optional.
+        # +http_timeout+:: See #http_timeout. Optional.
+        #
+        def initialize( resource:,
+                        version:,
+                        endpoint_uri:,
+                        proxy_uri:    nil,
+                        ca_file:      nil,
+                        http_timeout: nil )
+
+          self.resource     = resource.to_sym
+          self.version      = version.to_i
+          self.endpoint_uri = endpoint_uri
+          self.proxy_uri    = proxy_uri
+          self.ca_file      = ca_file
+          self.http_timeout = http_timeout
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+########################################################################
+# File::    for_local.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Describe a resource endpoint location in a way that allows
+#           it to be method-called from the service middleware directly.
+# ----------------------------------------------------------------------
+#           10-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      # Describe a resource endpoint location in a way that allows it to be
+      # method-called from the service middleware directly.
+      #
+      # This is a very special case class used for the inter-resource local
+      # call code in Hoodoo::Services::Middleware. It really exists only for
+      # semantic purposes; the middleware calls via Hoodoo::Client::Endpoint
+      # subclass Hoodoo::Sevices::Middleware::InterResourceLocal; and the
+      # Endpoint subclass family are supposed to use result classes from the
+      # Hoodoo::Services::Discovery engine when they configure instances.
+      #
+      # This isn't actually enforced anywhere, but conceptually it's cleanest
+      # to follow the same pattern.
+      #
+      class ForLocal
+
+        # The resource name described, as a Symbol (e.g. +:Purchase+).
+        #
+        attr_accessor :resource
+
+        # Resource endpoint version, as an Integer (e.g. 2).
+        #
+        attr_accessor :version
+
+        # The base path of this resource and version - for example,
+        # "/v1/products" or "/v2/members". String.
+        #
+        attr_accessor :base_path
+
+        # A regular expression which matches the #base_path and any
+        # identifier data, allowing inbound URI-based requests to be
+        # routed to this endpoint. Regexp instance.
+        #
+        attr_accessor :routing_regexp
+
+        # The Hoodoo::Services::Interface subclass _class_ describing the
+        # resource interface.
+        #
+        attr_accessor :interface_class
+
+        # The Hoodoo::Services::Implementation subclass _instance_
+        # which implements the interface described by #interface_class.
+        #
+        attr_accessor :implementation_instance
+
+        # Create an instance with named parameters as follows:
+        #
+        # +resource+::                See #resource.
+        # +version+::                 See #version.
+        # +base_path+::               See #base_path.
+        # +routing_regexp+::          See #routing_regexp.
+        # +interface_class+::         See #interface_class.
+        # +implementation_instance+:: See #implementation_instance.
+        #
+        def initialize( resource:,
+                        version:,
+                        base_path:,
+                        routing_regexp:,
+                        interface_class:,
+                        implementation_instance: )
+
+          self.resource                = resource.to_sym
+          self.version                 = version.to_i
+          self.base_path               = base_path
+          self.routing_regexp          = routing_regexp
+          self.interface_class         = interface_class
+          self.implementation_instance = implementation_instance
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+########################################################################
+# File::    for_remote.rb
+# (C)::     Loyalty New Zealand 2015
+#
+# Purpose:: Describe a "pseudo" resource endpoint location in terms of
+#           an interation context and wrapped "real" endpoint instance.
+# ----------------------------------------------------------------------
+#           10-Mar-2015 (ADH): Created.
+########################################################################
+
+module Hoodoo
+  module Services
+    class Discovery # Just used as a namespace here
+
+      # Describe a "pseudo" resource endpoint location in terms of
+      # an interation context and wrapped "real" endpoint instance.
+      #
+      # This is a very special case class used for wrapping endpoints in, for
+      # example, the inter-resource remote call code in the middleware and in
+      # the auto-session code in Hoodoo::Client::Endpoint::AutoSession.
+      #
+      class ForRemote
+
+        # The resource name described, as a Symbol (e.g. +:Purchase+).
+        #
+        attr_accessor :resource
+
+        # Resource endpoint version, as an Integer (e.g. 2).
+        #
+        attr_accessor :version
+
+        # A wrapped Endpoint class, which will be used for the *actual* call
+        # to the remote resource, after pre/post-processing in the context of
+        # #source_interaction (e.g. augmenting session permissions with
+        # source-resource-interface-specified additions necessary to call the
+        # target remote resource).
+        #
+        attr_accessor :wrapped_endpoint
+
+        # Create an instance with named parameters as follows:
+        #
+        # +resource+::         See #resource.
+        # +version+::          See #version.
+        # +wrapped_endpoint+:: See #wrapped_endpoint.
+        #
+        def initialize( resource:,
+                        version:,
+                        wrapped_endpoint: )
+
+          self.resource         = resource.to_sym
+          self.version          = version.to_i
+          self.wrapped_endpoint = wrapped_endpoint
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,186 @@
+########################################################################
+# File::    amqp_log_message.rb
+# (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.
+#
+#           The middleware uses this to put log and error messages
+#           on the queue. Interested services use this to read such
+#           messages from the queue.
+# ----------------------------------------------------------------------
+#           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
+
+      # 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.
+      #
+      # See the AlchemyAMQ gem for more details.
+      #
+      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
+
+        # 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
+
+        # 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
+
+        # 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
+
+        # Unpack a serialized representation into this instance. See the
+        # AlchemyAMQ gem and AlchemyAMQ::Message#deserialize.
+        #
+        def deserialize
+          super
+          update( @content )
+        end
+
+        # 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       ]
+        end
+      end
+
+    rescue LoadError # Optional file 'alchemy-amq' is absent
+    end
+
+  end
+end; end