conrad 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb4af3e930e6793ecb9a869e52c0150ea2aa87753b3f062713c872b5042ea754
+  data.tar.gz: 73c9bdc8e25b35527cf7064c934ef4a5762c2705c2b6c1c22bcc56c102fab547
+SHA512:
+  metadata.gz: e16f4db32806aa47a4411a6b9dbc5964eb522f477f48d2e97995839636b0b66e73bbc6392f02756d12e4a9f8244d1f17d6693a17082c08a5ac623de2408495dd
+  data.tar.gz: a866c01f282c5cfa5b1b71c83d9653dd697f25252f448d3df1b772d05bcc838bf127f4fb92a36f3848372ded0aac1473ca68761620a1309a0ce00456a9a18d99

data/lib/conrad/add_timestamp.rb

@@ -0,0 +1,52 @@
+require 'conrad/errors'
+
+module Conrad
+  # Used to add timestamps to an audit event in seconds or milliseconds.
+  #
+  # @!attribute [r] generator
+  #    object used to generate the timestamp
+  class AddTimestamp
+    # :nodoc:
+    class Error < Conrad::Error; end
+
+    # Types of units supported for generation.
+    ALLOWED_TIME_UNITS = %i[milliseconds seconds].freeze
+
+    attr_reader :generator, :timestamp_key
+
+    # Creates a new instance of AddTimestmap processor
+    #
+    # @param units [Symbol] type of time units for the timestamp generated.
+    #   Allows :seconds or :milliseconds.
+    # @param timestamp_key [Symbol] key to add to the event hash.
+    # @raise [ArgumentError] if the given units value is not one of
+    #   ALLOWED_TIME_UNITS
+    def initialize(units: :milliseconds, timestamp_key: :timestamp)
+      unless ALLOWED_TIME_UNITS.include? units
+        raise ArgumentError, "Provided units of `#{units}` must be one of #{ALLOWED_TIME_UNITS}"
+      end
+
+      @generator = generator_from_units(units)
+      @timestamp_key = timestamp_key
+    end
+
+    # Generates and adds a timestamp to the provided Hash.
+    #
+    # @param event [Hash]
+    # @return [Hash]
+    def call(event)
+      event.merge(timestamp_key => generator.call)
+    end
+
+    private
+
+    def generator_from_units(units)
+      case units
+      when :milliseconds then -> { (Time.now.to_f * 1000).to_i }
+      when :seconds then -> { Time.now.to_i }
+      else
+        raise UnrecognizedTimeUnit, units
+      end
+    end
+  end
+end

data/lib/conrad/add_uuid.rb

@@ -0,0 +1,24 @@
+require 'securerandom'
+
+module Conrad
+  # Generalized processor for inserting a UUID into the event. Allows
+  # configuring the key used for insertion.
+  #
+  # @!attribute [r] uuid_key
+  #    The key inserted into the event hash for the generated UUID.
+  class AddUUID
+    attr_reader :uuid_key
+
+    # @param uuid_key [Symbol] key to use for the generated UUID
+    def initialize(uuid_key = :event_uuid)
+      @uuid_key = uuid_key
+    end
+
+    # @param event [Hash] the current event
+    #
+    # @return [Hash] the hash with the UUID inserted
+    def call(event)
+      event.merge(uuid_key => SecureRandom.uuid)
+    end
+  end
+end

data/lib/conrad/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Conrad
+  # Base error class
+  class Error < StandardError
+    # :nodoc:
+    def to_s
+      'An unexpected error has occurred'
+    end
+  end
+
+  # Error raised when the value of an event attribute is not of one of the
+  # allowed types
+  class ForbiddenValue < Error
+    def initialize(key, value)
+      @key = key
+      @value = value
+    end
+
+    # :nodoc:
+    def to_s
+      "Key of #{@key} provided invalid value type of #{@value.class}"
+    end
+  end
+
+  # Error raised when the key of an event attribute is not of one of the
+  # allowed types
+  class ForbiddenKey < Error
+    def initialize(key)
+      @key = key
+    end
+
+    # :nodoc:
+    def to_s
+      "Invalid key #{@key}. Keys must be either Strings or Symbols"
+    end
+  end
+end

data/lib/conrad/json_formatter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Conrad
+  # Formats a given Hash into a presentable JSON format.
+  class JSONFormatter
+    # Formats a given Hash into a presentable JSON format.
+    #
+    # @param event [Hash] event to be formatted
+    #
+    # @return [String] JSON formatted string
+    def call(event)
+      event.to_json
+    end
+  end
+end

data/lib/conrad/recorder.rb

@@ -0,0 +1,93 @@
+require 'conrad/errors'
+require 'conrad/stdout_emitter'
+require 'conrad/json_formatter'
+
+module Conrad
+  # Provides the ability to record an event took place.
+  # Currently recording an event accepts a hash and passes it through the
+  # configured processors, formatter, and emitter. Each of these may transform,
+  # validate, format, and send the event as the user sees fit.
+  #
+  # @!attribute [r] formatter
+  #    Configured formatter for creating the final event. Defaults to
+  #    JSONFormatter.
+  #    @see Conrad::JSONFormatter
+  # @!attribute [r] emitter
+  #    Configured emitter for sending the final event. Defaults to
+  #    StdoutEmitter.
+  #    @see Conrad::StdoutEmitter
+  # @!attribute [r] processors
+  #    Configured processors for processing the event pre-formatting and
+  #    emission. Defaults to an empty array.
+  class Recorder
+    attr_reader :formatter, :emitter, :processors
+
+    # All arguments passed must *explicitly* respond to a `call` method.
+    #
+    # @param formatter [#call] formatter for creating the final event
+    # @param emitter [#call] emitter for sending the final event
+    # @param processors [Array<#call>] processors for processing the event
+    #   pre-formatting and emission
+    #
+    # @raise [ArgumentError] if the formatter, emitter, or any of the
+    #   processors do not respond_to? `call` with a truthy value.
+    def initialize(formatter: JSONFormatter.new, emitter: StdoutEmitter.new, processors: [])
+      check_callability(formatter: formatter, emitter: emitter, processors: processors)
+
+      @formatter = formatter
+      @emitter = emitter
+      @processors = processors
+    end
+
+    # Processes the given event, formats it, then emits it. 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 the audit event will be discarded. The formatter
+    # and the emitter will not be called.
+    #
+    # @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.
+    #
+    # @raise [ForbiddenKey] when a key is neither a Symbol nor a String
+    def audit_event(event)
+      processed_event = process_event(event)
+
+      return unless processed_event
+
+      validate_event_keys(processed_event)
+
+      format_and_emit(processed_event)
+    end
+
+    private
+
+    def process_event(event)
+      catch :halt_conrad_processing do
+        processors.reduce(event) do |previous_built_event, processor|
+          processor.call(previous_built_event)
+        end
+      end
+    end
+
+    def format_and_emit(event)
+      emitter.call(
+        formatter.call(event)
+      )
+    end
+
+    def check_callability(formatter:, emitter:, processors:)
+      [formatter, emitter, *processors].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/stdout_emitter.rb

@@ -0,0 +1,9 @@
+module Conrad
+  # Basic emitter for sending events to $stdout.
+  class StdoutEmitter
+    # Puts an event to $stdout.
+    def call(event)
+      puts event
+    end
+  end
+end

data/lib/conrad/version.rb

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

data/lib/conrad.rb

@@ -0,0 +1,5 @@
+require 'conrad/recorder'
+
+# :nodoc:
+module Conrad
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: conrad
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jonathon Anderson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.60.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.60.0
+description: 
+email:
+- jonathon.anderson@outreach.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/conrad.rb
+- lib/conrad/add_timestamp.rb
+- lib/conrad/add_uuid.rb
+- lib/conrad/errors.rb
+- lib/conrad/json_formatter.rb
+- lib/conrad/recorder.rb
+- lib/conrad/stdout_emitter.rb
+- lib/conrad/version.rb
+homepage: https://github.com/getoutreach/conrad
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Tool for auditing events.
+test_files: []