hsdq 0.7.0

data/lib/hsdq/receiver.rb

@@ -0,0 +1,269 @@
+
+module Hsdq
+  # This module process the incoming messages and call one of 5 messages (ack, request, callback, feedback or error)
+  # depending on the type of the message.
+  module Receiver
+
+
+    # **Placeholder for request received. You must override hsdq_request in your HsdqXxx class**<br>
+    # After this method has run, there will be no further processing.
+    #
+    # @param [Hash] message The message to process
+    # @param [Hash] context The request that was originally sent.
+    # @return [String] placeholder string message, will be what your method will be returning.
+    def hsdq_request(message, context);  placeholder; end
+    # **Placeholder for ack received. You must override hsdq_request in your HsdqXxx class**
+    # @see #hsdq_request
+    def hsdq_ack(message, context);      placeholder; end
+    # **Placeholder for callback received. You must override hsdq_request in your HsdqXxx class**
+    # @see #hsdq_request
+    def hsdq_callback(message, context); placeholder; end
+    # **Placeholder for feedback received. You must override hsdq_request in your HsdqXxx class**
+    # @see #hsdq_request
+    def hsdq_feedback(message, context); placeholder; end
+    # **Placeholder for error received. You must override hsdq_request in your HsdqXxx class**
+    # @see #hsdq_request
+    def hsdq_error(message, context);    placeholder; end
+
+    # Send the ACk and start the processing for the message just received.<br>
+    # The processing will be either executed synchronously or a new thread will be started based on the configuration.
+    #
+    # @param [Json string] raw_spark (ephemeral) just popped out of the queue in json format
+    # @param [Hash] options HsdqXxx class configuration options
+    def hsdq_ignit(raw_spark, options)
+      spark = h_spark raw_spark
+      send_ack spark
+      if   valid_spark? spark, options
+        if hsdq_opts[:threaded]
+          # :nocov:
+          hsdq_start_thread -> { sparkle spark, options }
+          # :nocov:
+        else
+          sparkle spark, options
+        end
+      end
+    end
+
+    # blpop return an array [list_name, data]
+    def get_spark(raw_spark)
+      raw_spark.kind_of?(Array) ? raw_spark.last : raw_spark
+    end
+
+    # return the spark (ephemeral part of the message) from the message list
+    # @param [Json string or Array] raw_spark from the list
+    # @return [Hash] spark ready to be used by the system
+    def h_spark(raw_spark)
+      JSON.parse get_spark(raw_spark), {symbolize_names: true}
+    end
+
+    # Entry point for the task to process, this is what is executed in the threads when a message is pulled.
+    # - Pull the burst (line with the request or response) from the the hash<br>
+    # - Pull the context related to a response if it exist
+    # - Set values for the next hop context in case of a request.
+    # - Call one of the 5 methods (request, ack, callback, feedback, error) in your hsdqXxx class (or the placeholder)
+    # based on the message type
+    # @param [Hash] spark
+    # @param [Hash] options hsdq class options from setup
+    def sparkle(spark, options)
+      puts spark.inspect
+      burst, ctx_burst = get_burst spark, options
+      context ctx_burst
+
+      case spark[:type].to_sym
+        when :ack
+          hsdq_ack burst, context
+        when :callback
+          hsdq_callback burst, context
+        when :feedback
+          hsdq_feedback burst, context
+        when :error
+          hsdq_error burst, context
+        when :request
+          set_context spark
+
+          hsdq_request burst, context
+      end
+    end
+
+    # Save for future use context data into the thread_store
+    # @param [Hash] spark
+    def set_context(spark)
+      # store in thread_store for later use
+      sent_to spark[:sender]
+      previous_sender spark[:sender]
+      context_params({ reply_to: spark[:previous_sender], spark_uid: spark[:spark_uid]})
+    end
+
+    # Manage pulling:
+    # - the burst (persistent action) associated with the spark from the matching Redis hash
+    # - if needed the context data
+    # @param [Hash] spark
+    # @param [Hash] _options for the app (not used actually)
+    def get_burst(spark, _options={})
+      # get the context parameters
+      context_h = spark[:context]
+
+      burst_p = -> { cx_data.hget hsdq_key(spark), burst_key(spark) }
+      if response?(spark) && context_h
+        # save previous_sender in thread_store for later reply
+        sent_to context_h[:previous_sender]
+        # set the proc for multi redis to pull the initial request
+        burst_context_p = -> { cx_data.hget hsdq_key(spark), "request_#{context_h[:spark_uid]}" }
+        # exec the redis multi
+        burst_j, burst_context_j = pull_burst(burst_p, burst_context_p)
+      else
+        burst_j, burst_context_j = pull_burst_only burst_p
+      end
+
+      burst         = burst_j ? (JSON.parse burst_j, {symbolize_names: true}) : {}
+      burst_context = burst_context_j ? (JSON.parse burst_context_j, {symbolize_names: true}) : {}
+
+      [burst, burst_context]
+    end
+
+    # Execute a multi transaction to get the burst and the context from Redis in a single call
+    # @param [Proc] burst_p query to pull the burst from redis
+    # @param [Proc] burst_context_p query to pull the context from redis
+    # @return [array] [burst, context]
+    def pull_burst(burst_p, burst_context_p)
+      cx_data.multi do
+        burst_p.call
+        burst_context_p.call
+      end
+    end
+
+    # If there is no context this method is used instead of pull_burst
+    # @see #pull_burst
+    # @param [Proc] burst_p query to pull the burst from redis
+    def pull_burst_only(burst_p)
+      [burst_p.call, nil]
+    end
+
+    # Spark validation, call valid_type?. If invalid:
+    # - an error is sent back to the sender
+    # - false is returned to the processing to stop the action.
+    # @param [Hash] spark
+    # @param [Hash] options Application options
+    # @return [Boolean] true in case of valid spark,
+    # @return [Hash] the error message if an error is raised
+    def   valid_spark?(spark, options)
+      begin
+        raise ArgumentError.new("Illegal type #{spark[:type]}") unless valid_type? spark[:type]
+        'request' == spark[:type] ? check_whitelist(spark, options) : true
+      rescue => e
+        reject_spark spark, e
+        false
+      end
+    end
+
+    # Call whitelisted? to verify the the topic and task are legit.
+    # @param [Hash] spark
+    # @param [Hash] options
+    # @return [Boolean] if whitelist validation is successful
+    # @return [Hash] the error message if an error is raised
+    def check_whitelist(spark, options)
+      begin
+        whitelisted?(spark, options) ? true : (raise ArgumentError.new("Illegal argument in topic or task"))
+      rescue => e
+        reject_spark spark, e
+        false
+      end
+    end
+
+    # validate the topic and the task
+    def whitelisted?(spark, options)
+      valid_topic?(spark, options) && valid_task?(spark, options)
+    end
+
+    # Send an error message back to the sender
+    # @param [Hash] spark The rejected spark
+    # @param [ArgumentError] e if invalid
+    # @return [Hash] the error message
+    def reject_spark(spark, e)
+      error = {
+        sent_to: spark[:sender],
+        uid:     spark[:uid],
+        sender:  channel,
+        params:  spark,
+        data:    e.message
+      }
+      puts "sending error message: #{error}"
+      hsdq_send_error error
+      error
+    end
+
+    # Send the ack back to the sender in case of a request
+    def send_ack(spark)
+      return unless ['request', :request].include? spark[:type]
+      ack_msg = spark.merge sent_to: spark[:sender], sender: channel
+      hsdq_send_ack ack_msg
+    end
+
+    # Hash of the internal authorized message types
+    def hsdq_authorized_types
+      [:request, :ack, :feedback, :callback, :error]
+    end
+
+    # Cached value of the tasks authorized to be processed
+    # @param [Array] tasks Additional tasks to the one setup in the configuration file
+    # @return [Array] the authoriced tasks
+    def hsdq_authorized_tasks(*tasks)
+      if tasks.any?
+        @hsdq_authorized_tasks = [tasks].flatten
+      else
+        @hsdq_authorized_tasks ||= [hsdq_opts[:tasks]].flatten
+      end
+    end
+
+    # Cached value of the topics authorized to be processed
+    def hsdq_authorized_topics(*topics)
+      if topics.any?
+        @hsdq_authorized_topics = [topics].flatten
+      else
+        @hsdq_authorized_topics ||= [hsdq_opts[:topics]].flatten
+      end
+    end
+
+    # @param [Array] tasks REPLACE the tasks set in the configuration file if any
+    # @return [Array] the authoriced tasks
+    def hsdq_set_authorized_tasks(*tasks)
+      @hsdq_authorized_tasks = tasks.flatten
+    end
+
+    # @param [Array] topics REPLACE the topics set in the configuration file if any
+    # @return [Array] the authoriced topics
+    def hsdq_set_authorized_topics(*topics)
+      @hsdq_authorized_topics = topics.flatten
+    end
+
+    # @param [Array] tasks Additional tasks to the ones set in the configuration file
+    # @return [Array] the authoriced tasks
+    def hsdq_add_authorized_tasks(*tasks)
+      @hsdq_authorized_tasks = [hsdq_authorized_tasks, tasks].flatten
+    end
+
+    # @param [Array] topics Additional topics to the ones set in the configuration file
+    # @return [Array] the authoriced topics
+    def hsdq_add_authorized_topics(*topics)
+      @hsdq_authorized_topics = [hsdq_authorized_topics, topics].flatten
+    end
+
+    # test the task against the list of authorised tasks
+    #
+    def valid_task?(spark, _options)
+      return true if spark[:task].nil? || hsdq_authorized_tasks.empty?
+      hsdq_authorized_tasks.include?(spark[:task].to_sym)
+    end
+
+    def valid_topic?(spark, _options)
+      return true if spark[:topic].nil? || hsdq_authorized_topics.empty?
+      hsdq_authorized_topics.include?(spark[:topic].to_sym)
+    end
+
+    # @return [boolean] true if the message received is a response
+    def response?(spark)
+      [:callback, :feedback, :error].include? spark[:type].to_sym
+    end
+
+  end
+end

data/lib/hsdq/sender.rb

@@ -0,0 +1,124 @@
+
+module Hsdq
+# This module is holding the methods for the sender (emitter) for your hsdq class.
+#
+# It is holding proxy methods setting the correct type to send your messages
+  module Sender
+    include Connectors
+
+    # To be use by your application to send a request from your hsdq class. This is a Proxy for hsdq_send to send request messages
+    #
+    # @param [Hash] message The request you want to send
+    # @return [Hash] your original message with the system additional parameters
+    # @return [Boolean] false if the message's validation failed
+    def hsdq_send_request(message)
+      hsdq_send(message.merge(type: :request))
+    end
+
+    # Ack message is the acknowledgement that message has been received by the receiver (Subscriber).
+    #
+    # Ack is sent automatically by the system. This method is to send additional ack messages if needed. (very seldom used)
+    #
+    # @param [Hash] message for the acknowledge you want to send (sent automatically by the system)
+    # @return [Hash] your original message with the system additional parameters
+    # @return [Boolean] false if the message's validation failed
+    def hsdq_send_ack(message)
+      hsdq_send(message.merge(type: :ack))
+    end
+
+    # Callback messages are the final step for a successful response.
+    #
+    # @param [Hash] message for the callback you want to send
+    # @return [Hash] your original message with the system additional parameters
+    # @return [Boolean] false if the message's validation failed
+    def hsdq_send_callback(message)
+      hsdq_send(message.merge(type: :callback))
+    end
+
+    # Feedback messages are the intermediate messages used to update the sender of the progress of it's request.
+    #
+    # @param [Hash] message for the feedback you want to send
+    # @return [Hash] your original message with the system additional parameters
+    # @return [Boolean] false if the message's validation failed
+    def hsdq_send_feedback(message)
+      hsdq_send(message.merge(type: :feedback))
+    end
+
+    # Error messages are used to return an error message to the sender in case of error during the processing.
+    #
+    # Error messages are also automatically sent by the system in case of validation error at message recetion.
+    #
+    # @param [Hash] message for the error message you want to send
+    # @return [Hash] your original message with the system additional parameters
+    # @return [Boolean] false if the message's validation failed
+    def hsdq_send_error(message)
+      hsdq_send(message.merge(type: :error))
+    end
+
+    # Generic method to send any type of message. It is preferred to use the the send proxy methods that are setting
+    # the correct type for the message the application has to send: hsdq_send_request, callback etc..
+    # The message type must be provided.
+    #
+    # @param [Hash] message to send
+    # @return [Hash] original message with the system additional parameters if the message is sent
+    # @return [Boolean] false if the message's validation failed
+    def hsdq_send(message)
+      message = prepare_message message
+      if valid_keys?(message) && valid_type?(message[:type])
+        spark = build_spark(message)
+        send_message message, spark
+      else
+        false
+      end
+    end
+
+    # Send the message using a Redis multi in order to do everything within a single transaction
+    # @param [Hash] message to send, will be stored as an entry in the message hash
+    # @param [Hash] spark the ephemeral part of the message. pushed to a list
+    # @return [String] "OK"
+    def send_message(message, spark)
+      # avoid further processing into the multi redis command
+      channel_name = message[:sent_to]
+      h_key        = hsdq_key message
+      burst_j      = message.to_json
+      spark_j      = spark.to_json
+      bkey         = burst_key(message)
+
+      cx_data.multi do
+        cx_data.hset   h_key,   bkey, burst_j
+        cx_data.expire h_key,   259200 #3 days todo set by options
+        cx_data.rpush  channel_name, spark_j
+      end
+    end
+
+    # Complete the message with the key values needed by the system
+    # @param [Hash] message original message
+    # @return [Hash] message with the additional system data
+    def prepare_message(message)
+      message[:sender]           = channel
+      message[:uid]            ||= current_uid || SecureRandom.uuid
+      message[:spark_uid]        = SecureRandom.uuid
+      message[:tstamp]           = Time.now.utc
+      message[:context]          = context_params
+      message[:previous_sender]  = previous_sender
+      message[:sent_to]        ||= sent_to
+      message
+    end
+
+    # Generate the spark from the message. The spark is ephemeral so everything in the spark is included into the message hash.
+    # @param [Hash] message to be sent
+    # @return [Hash] spark, the tiny part pushed to the list
+    def build_spark(message)
+      keys = [:sender, :uid, :spark_uid, :tstamp, :context, :previous_sender, :type, :topic, :task ]
+      spark = keys.inject({}) { |memo, param| memo.merge(param => message[param]) }
+      spark
+    end
+
+    # Validate that the minimum necessary keys are present into the message before sending it.
+    # @param [Hash] message The full message to be sent (including the system data)
+    def valid_keys?(message)
+      [:sender, :sent_to, :type, :uid] - message.keys == []
+    end
+
+  end
+end

data/lib/hsdq/session.rb

@@ -0,0 +1,59 @@
+module Hsdq
+  module Session
+
+    # Store in the session layer in the session hash one or an array of key values (string or json)
+    # Create the session hash if it do not exist.
+    # @param [String] session_id Use session_key to create the namespaced key based on session_id
+    # @param [Hash or Array of key/values] key_values
+    def hsdq_session_set(session_id, *key_values)
+      key_values = key_values[0].to_a if 1 == key_values.flatten.size && key_values[0].is_a?(Hash)
+      hkey = session_key(session_id)
+
+      cx_session.multi do
+        cx_session.hmset hkey,  *key_values.flatten
+        cx_session.expire hkey, 259200 #3 days todo set by options
+      end
+    end
+
+    # Retrieve the session hash from the session layer and return the data (see below)
+    # @param [String] session_id used to build the unique namespaced key to retrieve the session hash
+    # @param [Array of String] keys either an array of keys or nil or nothing
+    # @return [Array] of values in the order of the keys passed
+    # @return [Hash] in the case of no keys passed, return a hash of all the data stored
+    def hsdq_session(session_id, *keys)
+      if keys.any?
+        #get only the provided keys
+        cx_session.hmget session_key(session_id), *keys
+      else
+        # get all keys return a hash
+        cx_session.hgetall session_key(session_id)
+      end
+    end
+
+    # delete all keys from the session
+    def hsdq_session_del(session_id, *keys)
+      cx_session.hdel session_key(session_id), *keys.flatten
+    end
+
+    # delete the whole session hash
+    def hsdq_session_destroy(session_id)
+      cx_session.del session_key(session_id)
+    end
+
+    # reset the expiration time for the session
+    def hsdq_session_expire(session_id, in_seconds)
+      cx_session.expire session_key(session_id), in_seconds
+    end
+
+    # return the expiration time remaining before expiration
+    def hsdq_session_expire_in(session_id)
+      cx_session.ttl session_key(session_id)
+    end
+
+    # check if a key exist in the session hash
+    def hsdq_session_key?(session_id, key)
+      cx_session.hexists session_key(session_id), key
+    end
+
+  end
+end