conrad 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd153974202827badd3ab0b1e74ac823ac9ad67d7ac17ae627afcd0c9c9c5f93
-  data.tar.gz: b549b8ac875f6b0654f693c751946192158538ba3d56fc29b3e4bb896e665467
+  metadata.gz: 178acce18a6f1cd584f74d8bcf4d7d181f6d240ec7e3df10c644aa894f4e9b7b
+  data.tar.gz: 88bd011a135527d7068b85ebf94c9b037205622d475798ae029cf9f2786d446e
 SHA512:
-  metadata.gz: e304189667f80f0e6e7e8a206881d9cfa17d4289d1737ce0c7f96b655a97da5c266f8e3435586bfe9e2b3d3e8b88a112485d27bc53bf3ee5c29a72525a69d896
-  data.tar.gz: 3c95e0f400d386782d8dd00f1ff8203e67f46799b8fa93a538c4419ca5b58fe326d1fcbb6672939a6c12b1fc7e9358e42ddb737247dfa2cb60c725770fc4b9d8
+  metadata.gz: 60998b354a36ac3e14160805d012f323c2362e20ffd92eee9c3a65e605af6ecd394d40f8f649e39cdec222de701faea8b6dcc266aedf6c5b3bebe063c5866dd3
+  data.tar.gz: 48e969b3e326cf32dc6270412840025077443abbe8a71ad62cd6f88ca3eeff6519608bbfced6851df7f3a3296a3bca7e48808eaf894003d264e23a62c9f4c659

data/lib/conrad/collector.rb

@@ -0,0 +1,168 @@
+require 'conrad/formatters/json'
+require 'conrad/emitters/stdout'
+require 'conrad/processor_stack'
+require 'conrad/errors'
+
+module Conrad
+  # Used to collect a batch of events and send them using the configured
+  # emitter. This is especially useful for event recording done as part of a
+  # request/response cycle. Events can be collected here then sent at the end of
+  # the request cycle.
+  #
+  # Configuration is set via the class level and individual instances are
+  # spawned that use this configuration. The exception to that is the
+  # `event_metadata` which should be per collector using:
+  # `Conrad::Collector.current.event_metadata = { whatever: 'you want' }`
+  #
+  # A single instance can also be created. By default it will use any values
+  # configured for the class, but accepts override as keyword arguments.
+  class Collector
+    class << self
+      # The set of Processors to use for each event added to each collector
+      # created, by default. Must respond to #call
+      attr_writer :default_processors
+
+      # The Formatter to format each event added to each collector created, by
+      #   default. Must respond to #call
+      attr_writer :default_formatter
+
+      # The Emitter to use for sending events to another place, added to each
+      # collector by default. This should respond to #call. If `emit_as_batch`
+      # is set to true, this method *must* accept an Array of events. Otherwise,
+      # it is expected to accept a Hash.
+      attr_writer :default_emitter
+
+      # Boolean indicating if the events collected should be emitted as a batch
+      # and sent as an Array to to the configured emitter or if they should
+      # instead be sent one-by-one. Defaults to false.
+      attr_accessor :default_emit_as_batch
+
+      # @return [Conrad::Collector] the collector for a given Thread that is
+      #   currently active
+      def current
+        Thread.current[:conrad_collector] ||= new
+      end
+
+      # @return the configured formatter. Defaults to Conrad::Formatters::Json
+      def default_formatter
+        @default_formatter || Conrad::Formatters::JSON.new
+      end
+
+      # @return the configured emitter. Defaults to Conrad::Emitters::Stdout
+      def default_emitter
+        @default_emitter || Conrad::Emitters::Stdout.new
+      end
+
+      # @return [Array<#call>]
+      def default_processors
+        @default_processors || []
+      end
+    end
+
+    # Used to setup metadata that will be added to every event in the collection
+    attr_accessor :event_metadata
+
+    # The events stored in the collector
+    attr_reader :events
+
+    # ProcessorStack used on each event added
+    attr_reader :processors
+
+    # Formatter used to generate sendable format for an Event
+    attr_accessor :formatter
+
+    # Emitter used to send out events
+    attr_accessor :emitter
+
+    # Boolean indicating if events should be sent as a batch or individually by
+    #   default for each Collector instance
+    attr_accessor :emit_as_batch
+    alias emit_as_batch? emit_as_batch
+
+    # @param processors [Array<#call>] set of processors to run. Defaults to
+    #   processors as configured for the class.
+    # @param formatter [#call] Formatter to use. Defaults to
+    #   formatter as configured for the class.
+    # @param emitter [#call] emitter to send events. Defaults to
+    #   emitter as configured for the class.
+    # @param emit_as_batch [Boolean] indicates how to send events. Defaults to
+    #   value configured for class.
+    def initialize(
+      processors: self.class.default_processors,
+      formatter: self.class.default_formatter,
+      emitter: self.class.default_emitter,
+      emit_as_batch: self.class.default_emit_as_batch
+    )
+      @events = []
+      @event_metadata = {}
+      @processors = processors
+      @processor_stack = Conrad::ProcessorStack.new(processors)
+      @formatter = formatter
+      @emitter = emitter
+      @emit_as_batch = emit_as_batch
+    end
+
+    # Adds an event to the Collector to be audited at a later time. The
+    # current collector's event_metadata is added to the event, it is processed,
+    # then it is formatter before being added to the set of events.
+    # If `:halt_conrad_processing` is thrown during the event processing, then
+    # the event will not be added to the collection.
+    #
+    # @param event [Hash]
+    #
+    # @raise [ForbiddenKey] when a key is neither a Symbol nor a String
+    def add_event(event)
+      processed_event = processor_stack.call(event.merge(event_metadata))
+
+      return unless processed_event
+
+      validate_event_keys(processed_event)
+
+      events << formatter.call(processed_event)
+    end
+
+    # Records the events currently in the collection then clears the state of
+    # the Collector by emptying the events stack and clearing out the metadata.
+    def record_events
+      if emit_as_batch?
+        record_events_as_batch
+      else
+        record_individual_events
+      end
+
+      reset_state
+    end
+
+    # Attribute writer for changing the processors for an instance of a
+    # Collector
+    def processors=(processors)
+      @processor_stack = Conrad::ProcessorStack.new(processors)
+      @processors = processors
+    end
+
+    private
+
+    attr_reader :processor_stack
+
+    def validate_event_keys(event)
+      event.each_key do |key|
+        raise ForbiddenKey, key unless key.is_a?(Symbol) || key.is_a?(String)
+      end
+    end
+
+    def record_events_as_batch
+      emitter.call(events)
+    end
+
+    def record_individual_events
+      events.each do |event|
+        emitter.call(event)
+      end
+    end
+
+    def reset_state
+      event_metadata.clear
+      events.clear
+    end
+  end
+end

data/lib/conrad/processor_stack.rb

@@ -0,0 +1,50 @@
+require 'forwardable'
+
+module Conrad
+  # @api private
+  # Contains the main logic to share how processors are handled between the
+  # individual, one-off recorder and the collector.
+  class ProcessorStack
+    include Enumerable
+    extend Forwardable
+
+    # The processors used by this Stack
+    attr_reader :processors
+
+    # Delegate #each and #to_a to the processors Array to allow iterating over
+    # the object as if it were a collection of processors.
+    def_delegators :processors, :each, :to_a
+
+    # @param processors [Array<#call>] set of objects all responding to #call
+    #   that will be used to process an event
+    def initialize(processors)
+      check_callability(processors)
+
+      @processors = processors
+    end
+
+    # Processes an event through the defined set of operations, returning the
+    # final hash. It is possible to `throw :halt_conrad_processing` to stop the
+    # processing stack. There should be no additional arguments to the `throw`
+    # call. At this point, the processing will stop and return nil.
+    #
+    # @return [nil, Hash] nil in the case that halt_conrad_processing has been
+    #   caught, otherwise the result of all the processors which should be a
+    #   Hash.
+    def call(event)
+      catch :halt_conrad_processing do
+        processors.reduce(event) do |previous_built_event, processor|
+          processor.call(previous_built_event)
+        end
+      end
+    end
+
+    private
+
+    def check_callability(processors)
+      processors.each do |processor|
+        raise ArgumentError, "#{processor} does not respond to `#call`" unless processor.respond_to?(:call)
+      end
+    end
+  end
+end

data/lib/conrad/recorder.rb

@@ -1,6 +1,7 @@
 require 'conrad/errors'
 require 'conrad/emitters/stdout'
 require 'conrad/formatters/json'
+require 'conrad/processor_stack'
 
 module Conrad
   # Provides the ability to record an event took place.
@@ -11,14 +12,14 @@ module Conrad
   # @!attribute [r] formatter
   #    Configured formatter for creating the final event. Defaults to
   #    JSON.
-  #    @see Conrad::JSON
+  #    @see Conrad::Formatters::JSON
   # @!attribute [r] emitter
   #    Configured emitter for sending the final event. Defaults to
   #    Stdout.
-  #    @see Conrad::Stdout
+  #    @see Conrad::Emitters::Stdout
   # @!attribute [r] processors
   #    Configured processors for processing the event pre-formatting and
-  #    emission. Defaults to an empty array.
+  #    emission. Defaults to an empty enumerable.
   class Recorder
     attr_reader :formatter, :emitter, :processors
 
@@ -36,11 +37,12 @@ module Conrad
       emitter: Conrad::Emitters::Stdout.new,
       processors: []
     )
-      check_callability(formatter: formatter, emitter: emitter, processors: processors)
+      check_callability(formatter: formatter, emitter: emitter)
 
       @formatter = formatter
       @emitter = emitter
       @processors = processors
+      @processor_stack = Conrad::ProcessorStack.new(processors)
     end
 
     # Processes the given event, formats it, then emits it. It is possible
@@ -51,13 +53,11 @@ module Conrad
     #
     # @param event [Hash] the set of key value pairs to be emitted
     #   as a single audit event. It is expected that all keys will be given as
-    #   Symbols or Strings. All values should be of a type that matches the
-    #   SCALAR_TYPES or an array once the processor cycle is complete but before
-    #   final formatting.
+    #   Symbols or Strings.
     #
     # @raise [ForbiddenKey] when a key is neither a Symbol nor a String
     def audit_event(event)
-      processed_event = process_event(event)
+      processed_event = processor_stack.call(event)
 
       return unless processed_event
 
@@ -68,11 +68,11 @@ module Conrad
 
     private
 
-    def process_event(event)
-      catch :halt_conrad_processing do
-        processors.reduce(event) do |previous_built_event, processor|
-          processor.call(previous_built_event)
-        end
+    attr_reader :processor_stack
+
+    def validate_event_keys(event)
+      event.each_key do |key|
+        raise ForbiddenKey, key unless key.is_a?(Symbol) || key.is_a?(String)
       end
     end
 
@@ -82,16 +82,10 @@ module Conrad
       )
     end
 
-    def check_callability(formatter:, emitter:, processors:)
-      [formatter, emitter, *processors].each do |callable|
+    def check_callability(formatter:, emitter:)
+      [formatter, emitter].each do |callable|
         raise ArgumentError, "#{callable} does not respond to `#call`" unless callable.respond_to?(:call)
       end
     end
-
-    def validate_event_keys(event)
-      event.each_key do |key|
-        raise ForbiddenKey, key unless key.is_a?(Symbol) || key.is_a?(String)
-      end
-    end
   end
 end

data/lib/conrad/version.rb

@@ -1,5 +1,5 @@
 # :nodoc:
 module Conrad
   # :nodoc:
-  VERSION = '2.0.0'.freeze
+  VERSION = '2.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: conrad
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Jonathon Anderson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-04 00:00:00.000000000 Z
+date: 2019-01-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk
@@ -74,10 +74,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/conrad.rb
+- lib/conrad/collector.rb
 - lib/conrad/emitters/sqs.rb
 - lib/conrad/emitters/stdout.rb
 - lib/conrad/errors.rb
 - lib/conrad/formatters/json.rb
+- lib/conrad/processor_stack.rb
 - lib/conrad/processors.rb
 - lib/conrad/processors/add_timestamp.rb
 - lib/conrad/processors/add_uuid.rb