lib/maitredee.rb in maitredee-0.8.2 vs lib/maitredee.rb in maitredee-0.8.3

@@ -7,19 +7,38 @@
 require "active_support/json"
 require "pathname"
 require "maitredee/publisher"
 require "maitredee/subscriber"
 require "maitredee/version"
+require "maitredee/adapters/base_adapter"
 require "maitredee/adapters/sns_sqs_adapter"
 require "maitredee/railtie" if defined? ::Rails::Railtie
 
 module Maitredee
   class << self
-    attr_accessor :resource_name_suffix, :schema_path
+
+    # allows you to add a suffix to all your resource names, mostly used for testing but could be useful in other occassions.
+    # @return [String] string appended to all resource names
+    attr_accessor :resource_name_suffix
+
+    # this is the path of the folder in which validation_schema will try to do a lookup. This folder should contain json schemas.
+    # @return [String] path to folder
+    attr_accessor :schema_path
+
+    # the client we use for publishing and setting up workers
+    # @return [Maitredee::Adapters::AbstractAdapter]
     attr_reader :client
-    attr_writer :app_name, :namespace
 
+    # publishes messages using configured adapter
+    #
+    # @param topic [String] topic name
+    # @param body [Hash, Array, String] Any valid json data that can be validated by json-schema
+    # @param schema_name [String] A valid schema name for publishing data
+    # @param event_name [String, nil] Event name for subscriber routing
+    # @param primary_key [#to_s, nil] Key to be used for resource identification
+    #
+    # @return [PublisherMessage] published message
     def publish(
       topic_name:,
       body:,
       schema_name:,
       event_name: nil,
@@ -42,27 +61,43 @@
       client.publish(message)
 
       message
     end
 
+    # configure the adapter, must be executed before loading subscribers
+    #
+    # @param slug [#to_s] name of adapter
+    # @param args [] options to send to the adapter
     def set_client(slug, *args)
       raise "No client set for Maitredee" if slug.nil?
       @client = "::Maitredee::Adapters::#{slug.to_s.camelize}Adapter".constantize.new(*args)
     end
 
+    # set a client without parameters
+    #
+    # @param slug [#to_s] name of adapter
     def client=(slug)
       set_client(slug)
     end
 
+    # build topic resource name from topic name
+    #
+    # @param topic_name [#to_s] topic name
+    # @return [String]
     def topic_resource_name(topic_name)
       [
         namespace,
         topic_name,
         resource_name_suffix
       ].compact.join("--")
     end
 
+    # build queue resource name from queue name and topic name
+    #
+    # @param topic_name [#to_s] topic name
+    # @param queue_name [#to_s] queue name
+    # @return [String]
     def queue_resource_name(topic_name, queue_name)
       [
         namespace,
         topic_name,
         app_name,
@@ -73,10 +108,17 @@
           raise "Cannot have a queue name longer than 80 characters: #{name}"
         end
       end
     end
 
+    # validate a body given a schema name
+    #
+    # @param body [Array, Hash, String] data to send with message
+    # @param schema [String] string key to look up schema to validate against
+    #
+    # @raise [ValidationError] if validation fails
+    # @return [nil]
     def validate!(body, schema)
       errors = schemas[schema].validate(body.as_json)
       properties = errors.map do |error|
         error["data_pointer"]
       end.join(", ")
@@ -84,17 +126,24 @@
       if errors.any?
         raise ValidationError, "Invalid properties: #{properties}"
       end
     end
 
+    # hash to look up schema based of schema_path
+    #
+    # @return Hash[JSONSchemer::Schema::Draft7]
     def schemas
       @schemas ||= Hash.new do |hash, key|
         path = Pathname.new(schema_path).join("#{key}.json")
         hash[key] = JSONSchemer.schema(path)
       end
     end
 
+    # fetch configured app name or automatically fetch from Rails or from ENV["MAITREDEE_APP_NAME"]
+    # used for generating queue_resource_name
+    #
+    # @return [String]
     def app_name
       @app_name ||=
         begin
           rails_app_name =
             if defined?(Rails)
@@ -104,29 +153,44 @@
             rails_app_name ||
             raise("must set app_name for maitredee")
         end
     end
 
+    # set app_name instead of using default
+    # @param [String]
+    attr_writer :app_name
+
+
+    # fetch configured namespace or automatically fetch from ENV["MAITREDEE_NAMESPACE"]
+    # @return [String]
     def namespace
       @namespace ||=
         ENV["MAITREDEE_NAMESPACE"] || raise("must set namespace for maitredee")
     end
 
+    # set namespace instead of using default
+    # @param [String]
+    attr_writer :namespace
+
+    # idempotently configures broker to create topics, queues and subscribe queues to topics
+    # nothing will eveer be deleted or cleaned up
     def configure_broker
       hash_array = Hash.new { |hash, key| hash[key] = [] }
       topics_and_queues =
         subscriber_registry.each_with_object(hash_array) do |subscriber, hash|
           topic_arn = topic_resource_name(subscriber.topic_name)
           hash[topic_arn] << queue_resource_name(subscriber.topic_name, subscriber.queue_name)
         end
       client.configure_broker(topics_and_queues)
     end
 
+    # @api private
     def register_subscriber(klass)
       client.add_worker(klass)
       subscriber_registry.add(klass)
     end
 
+    # @api private
     def subscriber_registry
       @subscriber_registry ||= Set.new
     end
   end