omni_events 0.1.1

data/db/migrate/20240101000003_create_omni_event_logs.rb

@@ -0,0 +1,14 @@
+class CreateOmniEventLogs < ActiveRecord::Migration[6.1]
+  def change
+    create_table :omni_event_logs do |t|
+      t.references :loggable, polymorphic: true, null: true
+      t.string :action_type, null: false, default: 'system_info'
+      t.text   :content
+      t.jsonb  :metadata, null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :omni_event_logs, :action_type
+    add_index :omni_event_logs, :created_at
+  end
+end

data/db/migrate/20240101000004_add_security_to_omni_event_notifiers.rb

@@ -0,0 +1,8 @@
+class AddSecurityToOmniEventNotifiers < ActiveRecord::Migration[6.1]
+  def change
+    add_column :omni_event_notifiers, :secret_key,          :string
+    add_column :omni_event_notifiers, :timestamp_tolerance, :integer, default: 300, null: false
+
+    add_index :omni_event_notifiers, :secret_key, unique: true, where: "secret_key IS NOT NULL"
+  end
+end

data/lib/generators/omni_event/install_generator.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'rails/generators/migration'
+
+module OmniEvent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_migrations
+        rake "omni_event:install:migrations"
+      end
+
+      def create_initializer
+        create_file "config/initializers/omni_event.rb", <<~RUBY
+          OmniEvent.configure do |config|
+            # ── Monitoring ────────────────────────────────────────────────────────────
+            config.new_relic_enabled    = false
+            config.new_relic_api_key    = ENV['NEW_RELIC_KEY']
+            config.new_relic_account_id = ENV['NEW_RELIC_ACCOUNT_ID']
+
+            # ── Processing ────────────────────────────────────────────────────────────
+            config.process_async  = true   # set false to process synchronously
+            config.retention_days = 30
+
+            # ── Custom log types ──────────────────────────────────────────────────────
+            # Define your domain-specific action types here.
+            config.custom_log_types = {
+              system_info:  0,
+              system_error: 1
+            }
+
+            # ── Processor registry ────────────────────────────────────────────────────
+            # Map each OmniEvent::Notifier name to its processor class.
+            #
+            #   config.processors = {
+            #     "Siscomex" => SiscomexProcessor,
+            #     "DHL"      => DHLWebhookProcessor
+            #   }
+            config.processors = {}
+          end
+        RUBY
+      end
+
+      def create_local_models
+        create_file "app/models/log.rb", <<~RUBY
+          class Log < OmniEvent::Log
+            # Add custom scopes, validations or methods here.
+          end
+        RUBY
+
+        create_file "app/models/webhook_event.rb", <<~RUBY
+          class WebhookEvent < OmniEvent::WebhookEvent
+          end
+        RUBY
+      end
+
+      def display_post_install_message
+        puts ""
+        puts "=" * 64
+        puts " OmniEvent #{OmniEvent::VERSION} installed successfully!"
+        puts ""
+        puts " Next steps:"
+        puts " 1. rails db:migrate"
+        puts " 2. Configure config/initializers/omni_event.rb"
+        puts " 3. Mount the engine in config/routes.rb:"
+        puts "      mount OmniEvent::Engine => '/omni_events'"
+        puts " 4. Create a Notifier:"
+        puts "      OmniEvent::Notifier.create!(name: 'My Partner')"
+        puts " 5. Register a processor in the initializer:"
+        puts "      config.processors = { 'My Partner' => MyProcessor }"
+        puts "=" * 64
+      end
+    end
+  end
+end

data/lib/omni_event/base_processor.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module OmniEvent
+  class BaseProcessor
+    attr_reader :event, :current_step
+
+    def self.steps(*method_names)
+      @steps_list = method_names
+    end
+
+    def self.steps_list
+      @steps_list || []
+    end
+
+    def initialize(event)
+      @event = event
+    end
+
+    def process!
+      self.class.steps_list.each do |method_name|
+        execute_step(method_name)
+      end
+    rescue => e
+      raise e
+    end
+
+    private
+
+    def execute_step(method_name)
+      @current_step = method_name.to_s.humanize
+
+      Rails.logger.info "[OmniEvent] Executing step: #{@current_step}"
+
+      send(method_name)
+
+    rescue => e
+      OmniEvent::Log.create!(
+        loggable: event,
+        action_type: :system_error,
+        content: "FAILURE in step [#{@current_step}]: #{e.message}",
+        metadata: {
+          error_class: e.class.name,
+          method: method_name,
+          backtrace: e.backtrace.first(3)
+        }
+      )
+      raise e
+    end
+  end
+end

data/lib/omni_event/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OmniEvent
+  class Configuration
+    attr_accessor :new_relic_enabled,
+                  :new_relic_api_key,
+                  :new_relic_account_id,
+                  :retention_days,
+                  :process_async,
+                  :custom_log_types,
+                  :processors
+
+    def initialize
+      @new_relic_enabled    = false
+      @new_relic_api_key    = nil
+      @new_relic_account_id = nil
+      @retention_days       = 30
+      @process_async        = true
+      @custom_log_types     = { system_info: 0, system_error: 1 }
+      @processors           = {}
+    end
+  end
+end

data/lib/omni_event/engine.rb

@@ -0,0 +1,5 @@
+module OmniEvent
+  class Engine < ::Rails::Engine
+    isolate_namespace OmniEvent
+  end
+end

data/lib/omni_event/process_dispatcher.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OmniEvent
+  # Finds the registered processor for a given WebhookEvent and runs it.
+  #
+  # Register processors in your initializer:
+  #
+  #   OmniEvent.configure do |config|
+  #     config.processors = {
+  #       "Siscomex" => SiscomexProcessor,
+  #       "DHL"      => DHLProcessor
+  #     }
+  #   end
+  #
+  class ProcessDispatcher
+    def self.call(event)
+      processor_class = resolve(event)
+
+      unless processor_class
+        Rails.logger.warn "[OmniEvent] No processor registered for notifier '#{event.webhook_notifier.name}'. Marking as processed."
+        event.update!(status: :processed)
+        return
+      end
+
+      processor_class.new(event).process!
+      event.update!(status: :processed)
+    rescue => e
+      event.update!(status: :failed)
+      raise e
+    end
+
+    private_class_method def self.resolve(event)
+      notifier_name = event.webhook_notifier.name
+      config = OmniEvent.configuration.processors
+
+      config[notifier_name] ||
+        config[notifier_name.to_sym] ||
+        config[notifier_name.downcase] ||
+        config[notifier_name.downcase.to_sym]
+    end
+  end
+end

data/lib/omni_event/signature_verifier.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module OmniEvent
+  # Verifies the authenticity and freshness of an incoming webhook request.
+  #
+  # Two independent checks (both only active when secret_key is set):
+  #
+  #   1. Timestamp — rejects requests outside the tolerance window (replay attack protection).
+  #      Header: X-OmniEvent-Timestamp  (Unix timestamp, e.g. 1711800000)
+  #
+  #   2. HMAC Signature — verifies the payload was signed with the shared secret.
+  #      Header: X-OmniEvent-Signature  (e.g. "sha256=abc123...")
+  #      Algorithm: HMAC-SHA256(secret_key, raw_body)
+  #
+  # If the Notifier has no secret_key, all checks are skipped (backward compatible).
+  #
+  # Usage:
+  #   result = OmniEvent::SignatureVerifier.call(notifier, request)
+  #   result.success? # => true / false
+  #   result.error    # => "Invalid signature — payload may have been tampered"
+  #
+  class SignatureVerifier
+    Result = Struct.new(:success?, :error)
+
+    TIMESTAMP_HEADER = 'X-OmniEvent-Timestamp'
+    SIGNATURE_HEADER = 'X-OmniEvent-Signature'
+
+    def self.call(notifier, request)
+      new(notifier, request).verify
+    end
+
+    def initialize(notifier, request)
+      @notifier = notifier
+      @request  = request
+    end
+
+    def verify
+      # No secret configured — skip all checks (opt-in security)
+      return success unless @notifier.secret_key.present?
+
+      result = verify_timestamp
+      return result unless result.success?
+
+      verify_signature
+    end
+
+    private
+
+    # ── Timestamp check ────────────────────────────────────────────────────────
+    def verify_timestamp
+      tolerance = @notifier.timestamp_tolerance.to_i
+      return success if tolerance.zero?
+
+      header = @request.headers[TIMESTAMP_HEADER]
+      return failure("Missing #{TIMESTAMP_HEADER} header") if header.blank?
+
+      request_time = Time.at(header.to_i)
+      elapsed = (Time.current - request_time).abs
+
+      if elapsed > tolerance
+        failure("Request timestamp is #{elapsed.to_i}s old — outside the #{tolerance}s window (possible replay attack)")
+      else
+        success
+      end
+    end
+
+    # ── HMAC signature check ───────────────────────────────────────────────────
+    def verify_signature
+      header = @request.headers[SIGNATURE_HEADER]
+      return failure("Missing #{SIGNATURE_HEADER} header") if header.blank?
+
+      raw_body = @request.raw_post
+      expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', @notifier.secret_key, raw_body)}"
+
+      unless ActiveSupport::SecurityUtils.secure_compare(expected, header)
+        failure("Invalid signature — payload may have been tampered or secret_key is wrong")
+      else
+        success
+      end
+    end
+
+    def success        = Result.new(true,  nil)
+    def failure(msg)   = Result.new(false, msg)
+  end
+end

data/lib/omni_event/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OmniEvent
+  VERSION = "0.1.1"
+end

data/lib/omni_event.rb

@@ -0,0 +1,17 @@
+require "omni_event/version"
+require "omni_event/engine"
+require "omni_event/configuration"
+require "omni_event/base_processor"
+require "omni_event/process_dispatcher"
+require "omni_event/signature_verifier"
+
+module OmniEvent
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+end

data/lib/tasks/omni_event_tasks.rake

@@ -0,0 +1,12 @@
+namespace :omni_event do
+  desc "Delete logs and webhook events older than the configured retention_days"
+  task cleanup: :environment do
+    retention_days = OmniEvent.configuration.retention_days
+    cutoff         = retention_days.days.ago
+
+    deleted_logs   = OmniEvent::Log.where("created_at < ?", cutoff).delete_all
+    deleted_events = OmniEvent::WebhookEvent.where("created_at < ?", cutoff).delete_all
+
+    puts "[OmniEvent] Cleanup complete: #{deleted_logs} logs and #{deleted_events} webhook events deleted (older than #{retention_days} days)."
+  end
+end

data/sig/omni_event.rbs

@@ -0,0 +1,4 @@
+module OmniEvent
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: omni_events
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Antonio Neto
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+description: OmniEvent unifies external event ingestion with detailed internal auditing
+  via a step-based pipeline and asynchronous monitoring.
+email:
+- antoniocneto.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/controllers/omni_event/receiver_controller.rb
+- app/jobs/omni_event/new_relic_job.rb
+- app/jobs/omni_event/process_webhook_job.rb
+- app/models/omni_event/application_record.rb
+- app/models/omni_event/log.rb
+- app/models/omni_event/notifier.rb
+- app/models/omni_event/webhook_event.rb
+- config/routes.rb
+- db/migrate/20240101000001_create_omni_event_notifiers.rb
+- db/migrate/20240101000002_create_omni_event_webhook_events.rb
+- db/migrate/20240101000003_create_omni_event_logs.rb
+- db/migrate/20240101000004_add_security_to_omni_event_notifiers.rb
+- lib/generators/omni_event/install_generator.rb
+- lib/omni_event.rb
+- lib/omni_event/base_processor.rb
+- lib/omni_event/configuration.rb
+- lib/omni_event/engine.rb
+- lib/omni_event/process_dispatcher.rb
+- lib/omni_event/signature_verifier.rb
+- lib/omni_event/version.rb
+- lib/tasks/omni_event_tasks.rake
+- sig/omni_event.rbs
+homepage: https://github.com/antoniocneto/omni_event
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/antoniocneto/omni_event
+  source_code_uri: https://github.com/antoniocneto/omni_event
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Rails Engine for unified Webhook ingestion, Polymorphic Logging, and Process
+  Traceability.
+test_files: []