optiaudit-rails 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2da47ba93a09717845045e65800eebf3f280a2261402a2bb7f7bf7a2db72a7a2
-  data.tar.gz: a5c6b63dfdba71cfaf7843f3ba0daedffbd1e5d76834cb4a74bb4174ace02ac7
+  metadata.gz: 8ab9fc2af772216e10bb2376e7eb5c7dab31393f41500bf9375564b94c848128
+  data.tar.gz: ad4ba3df9b4b5b86cba423aaf50d2f9c87f832f78dde26873ecb3a4c2939f5f5
 SHA512:
-  metadata.gz: 6578b9531cbdefe3dcb5c05268d6ebaf9c6bc45c6d7773df090cd2822f325d910f76edad3b5b367752845439b1cb924a3c5f6a0546c8ec41076c7cccb2e1709b
-  data.tar.gz: eae50f9a7632ca5a6087292e9b3d2e3c99faffa37619a3e1d86dff713c027ae22243b71de72d6ba18e05689ded14c5ca380ddfe86e85c8433ce72960628a37b3
+  metadata.gz: 454b2763272e3483aab0f1fb6f8c5dddf647e60dedda80929df8cdb30c0801810b52b146eed5bfea5794f337428e6429443d91c847470002cdfbca295a5e104f
+  data.tar.gz: e2f094abd10c8e528f7fcd316c1f9f208c6e53143c6316b57b223774e2cc507bddfa3e1a33211e05216947d290655fb90cf3506939ed53a39011f9b6bd588987

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-23
+
+### Added
+
+- **Registro central de acciones auditadas** en `config/optiaudit.rb`, que la gema carga sola al arrancar:
+  `Optiaudit.audit { page_view "o/pax/itineraries#index", module: :itineraries, formats: :html, if: ... }` y
+  `event :create, "controller#action", module: ...`. Auditar una pantalla nueva es una línea en ese archivo, sin tocar
+  controllers. Las macros siguen funcionando.
+- **Validación al arrancar**: cada entrada se compara con las rutas de la app, cuando Rails termina de dibujarlas
+  (un bloque `routes.append`, que corre en `RouteSet#finalize!`): sin reordenar initializers ni cargar las rutas dos
+  veces, y con los initializers de la app ya aplicados. En development y test una entrada sin
+  ruta detiene el arranque (`Optiaudit::InvalidRegistry`); en production se registra un warning y la app arranca.
+  `Optiaudit::Testing.verify_registry!` para tenerlo como test.
+- Opción `formats:` (por ejemplo, solo `:html`).
+
+### Performance
+
+Un único `after_action` global busca la acción en un hash de dos niveles congelado. Para acciones que no están en el
+registro suma entre 0,6 y 3,7 µs por request (300 entradas, Ruby 2.7.5 + Rails 5.2.8, benchmark intercalado con y sin
+el hook, GC desactivado). La búsqueda en sí son ~117 ns.
+
 ## [0.1.1] - 2026-10-22
 
 Correcciones de la verificación del README contra OptiAudit real, con la 0.1.0 publicada.
@@ -37,6 +58,7 @@ Primera versión: el equivalente para Rails de `@theoptimalpartner/nestjs-optiau
 - **`Optiaudit::Testing`** para que las apps verifiquen sus eventos en tests sin HTTP.
 - Compatibilidad probada en CI: Ruby 2.7 + Rails 5.2 + Sidekiq 6.3, Ruby 3.0 + Rails 6.1 + Sidekiq 6.5 y Ruby 3.2 + Rails 7.0 + Sidekiq 7.2.
 
-[Unreleased]: https://bitbucket.org/RoutingUC/optiaudit-rails/branches/compare/main%0Dv0.1.1
+[Unreleased]: https://bitbucket.org/RoutingUC/optiaudit-rails/branches/compare/main%0Dv0.2.0
+[0.2.0]: https://bitbucket.org/RoutingUC/optiaudit-rails/src/v0.2.0/
 [0.1.1]: https://bitbucket.org/RoutingUC/optiaudit-rails/src/v0.1.1/
 [0.1.0]: https://bitbucket.org/RoutingUC/optiaudit-rails/src/v0.1.0/

data/README.md

@@ -9,6 +9,7 @@ Integrating an app is adding the gem, two environment variables and one line per
 ## Features
 
 - **Zero-config**: Reads `OPTIAUDIT_URL` and `OPTIAUDIT_WRITE_KEY` from the environment
+- **One list of audited actions**: `config/optiaudit.rb` declares what the app audits, without touching controllers, checked against the routes at boot
 - **Controller macros**: `optiaudit_page_view` and `optiaudit_event`, the equivalent of `@TrackPageView()` and `@TrackEvent()`
 - **Auto context extraction**: actor from `current_user`, client IP, user agent, path, request id and a hashed session id
 - **Never breaks the request**: delivery runs in Sidekiq or a background thread, and every error is logged as a warning
@@ -56,7 +57,44 @@ If the app runs Sidekiq, events go through the `optiaudit` queue. Add it to the
 
 Apps without Sidekiq need nothing: the gem uses a background thread (see [Delivery](#delivery)).
 
-### 3. Use the Macros
+### 3. Declare what to audit
+
+List the audited actions in `config/optiaudit.rb`. The gem loads it at boot: auditing a new screen is
+one line in this file, and no controller changes.
+
+```ruby
+# config/optiaudit.rb
+Optiaudit.audit do
+  page_view "routes#index", module: :routes, formats: :html
+  page_view "routes#show",  module: :routes, formats: :html
+  event :update, "routes#update",  module: :routes
+  event :delete, "routes#destroy", module: :routes,
+                 metadata: ->(controller) { { action: "delete_route", route_id: controller.params[:id] } }
+end
+```
+
+- **Key:** `"<controller_path>#<action>"` of the controller that serves the request (`Admin::RoutesController`
+  is `"admin/routes"`). A parent controller does not cover its subclasses: an action served by two
+  controllers needs two lines.
+- **Options:** `module:` (required), `formats:` (one or more, e.g. `:html`; default all), `if:` / `unless:`
+  (a controller method name or a lambda that receives the controller) and `metadata:` (a hash or a lambda
+  that receives the controller).
+- **Checked at boot:** an entry without a route (a renamed controller, a typo) stops the boot in
+  development and test, so it never reaches production unnoticed. In production it is logged
+  (`<key> has no route: that action is not being audited`) and the app boots.
+- The same rules as the macros apply: only 2xx and 3xx, only with an actor, never raises.
+- **Cost:** one global `after_action` looks the action up in a frozen hash. For actions not in the list
+  it adds about 1–4 µs per request (measured with 300 entries on Ruby 2.7 / Rails 5.2).
+- **Keep metadata in memory:** lambdas run inside the request; use params and instance variables the
+  action already loaded, never database queries.
+
+Changes to this file go through code review and a deploy, so the audit trail of what is audited is the
+repository history.
+
+### Or use the Macros
+
+The registry is the recommended way. The macros remain for apps that prefer to declare tracking in
+the controller:
 
 ```ruby
 class RoutesController < ApplicationController
@@ -258,6 +296,9 @@ it "audits the update" do
     "metadata" => include("module" => "routes")
   )
 end
+
+# Fails when an entry of config/optiaudit.rb has no route
+it("audits only routed actions") { Optiaudit::Testing.verify_registry! }
 ```
 
 ## Track Params
@@ -299,6 +340,8 @@ the gem truncates or omits fields instead of sending them as they are.
 | HTTP 4xx (other) | Logs warning, doesn't raise, no retry |
 | HTTP 207 on a batch | Logs warning with the rejected events |
 | Redis down when enqueueing | Logs warning, doesn't raise |
+| `config/optiaudit.rb` entry without a route | Raises at boot in development and test; logs a warning in production |
+| `if:` / `metadata:` lambda raises | Event not sent, logs warning, doesn't raise |
 
 ## Contributing
 

data/lib/optiaudit/controller.rb

@@ -33,6 +33,31 @@ module Optiaudit
 
     private
 
+    # Global after_action (added by the Railtie): tracks the action if it is in
+    # the registry. Unregistered actions cost one hash lookup.
+    def optiaudit_track_registered
+      entry = Optiaudit.registry.lookup(controller_path, action_name)
+      return unless entry && optiaudit_trackable_response?
+      return unless entry.formats.nil? || entry.formats.include?(request.format.to_sym)
+      return unless optiaudit_condition(entry.if, true) && !optiaudit_condition(entry.unless, false)
+
+      optiaudit_track(entry.event_type, entry.module_name, metadata: entry.metadata)
+    rescue StandardError => e
+      Optiaudit.log_warning("could not track #{entry&.key}: #{e.class}: #{e.message}")
+    end
+
+    def optiaudit_condition(condition, default)
+      case condition
+      when nil then default
+      when Symbol, String then send(condition)
+      else condition.call(self)
+      end
+    end
+
+    def optiaudit_trackable_response?
+      response.status >= 200 && response.status < 400
+    end
+
     # Tracks an event with the actor and request data of this controller.
     # `params` accepts every field of Optiaudit.track and overrides the defaults;
     # `metadata` may also be a lambda that receives the controller.
@@ -55,7 +80,7 @@ module Optiaudit
     end
 
     def optiaudit_track_action(event_type, module_name, metadata)
-      return unless response.status >= 200 && response.status < 400
+      return unless optiaudit_trackable_response?
 
       optiaudit_track(event_type, module_name, metadata: metadata)
     end

data/lib/optiaudit/railtie.rb

@@ -8,6 +8,7 @@ module Optiaudit
       ActiveSupport.on_load(:action_controller) do
         require "optiaudit/controller"
         include Optiaudit::Controller
+        after_action :optiaudit_track_registered
       end
     end
 
@@ -16,5 +17,21 @@ module Optiaudit
     config.after_initialize do
       require "optiaudit/sidekiq_job" if defined?(::Sidekiq)
     end
+
+    # The app's list of audited actions (config/optiaudit.rb), loaded and
+    # verified against the routes when Rails finishes drawing them: an entry
+    # without a route stops the boot in development and test, and is logged in
+    # production. A routes.append block runs at that point (RouteSet#finalize!)
+    # in every supported Rails, without reordering initializers or loading the
+    # routes twice. By then the app initializers ran, so its config applies.
+    initializer "optiaudit.registry" do |app|
+      path = app.root.join("config", "optiaudit.rb")
+      next unless File.exist?(path)
+
+      app.routes.append do
+        Optiaudit::Registry.load_file(path)
+        Optiaudit.registry.verify!(app.routes, strict: !::Rails.env.production?)
+      end
+    end
   end
 end

data/lib/optiaudit/registry.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Optiaudit
+  # Raised by Registry#verify! in strict mode when entries have no route.
+  class InvalidRegistry < StandardError; end
+
+  # The actions an app audits, declared in one place (config/optiaudit.rb)
+  # instead of with macros in each controller:
+  #
+  #   Optiaudit.audit do
+  #     page_view "o/pax/itineraries#index", module: :itineraries, formats: :html, if: :sky?
+  #     event :create, "o/sky/demand_set_imports#confirm", module: :demand_sets,
+  #                    metadata: ->(controller) { { import_id: controller.params[:id] } }
+  #   end
+  #
+  # Keys are "<controller_path>#<action>" of the controller that serves the
+  # request: a parent controller does not cover its subclasses.
+  #
+  # Every request looks itself up here, so the registry is a frozen two-level
+  # hash ({ "o/pax/itineraries" => { "index" => entry } }) and the lookup
+  # allocates nothing.
+  class Registry
+    Entry = Struct.new(:key, :event_type, :module_name, :formats, :if, :unless, :metadata, keyword_init: true)
+
+    # The DSL of Optiaudit.audit.
+    class Builder
+      def initialize(config)
+        @config = config
+        @entries = {}
+      end
+
+      def page_view(key, **options)
+        event(:page_view, key, **options)
+      end
+
+      # Options: module (required), formats, if, unless, metadata. if/unless
+      # take a controller method name or a lambda that receives the controller.
+      def event(event_type, key, module: nil, formats: nil, if: nil, unless: nil, metadata: nil)
+        module_name = binding.local_variable_get(:module)
+        controller_path, action = parse_key(key)
+        validate!(key, event_type.to_s, module_name)
+
+        actions = (@entries[controller_path] ||= {})
+        raise ArgumentError, "#{key} declared twice in the Optiaudit registry" if actions.key?(action)
+
+        actions[action] = Entry.new(
+          key: key, event_type: event_type.to_s, module_name: module_name.to_s,
+          formats: formats && Array(formats).map(&:to_sym).freeze,
+          if: binding.local_variable_get(:if), unless: binding.local_variable_get(:unless), metadata: metadata
+        ).freeze
+      end
+
+      def build
+        Registry.new(@entries.transform_values(&:freeze).freeze)
+      end
+
+      private
+
+      def parse_key(key)
+        controller_path, action = key.to_s.split("#", 2)
+        if Util.blank?(controller_path) || Util.blank?(action)
+          raise ArgumentError, %(#{key.inspect} is not "controller_path#action")
+        end
+
+        [controller_path.freeze, action.freeze]
+      end
+
+      def validate!(key, event_type, module_name)
+        raise ArgumentError, "#{key}: module is required" if Util.blank?(module_name)
+        return if @config.event_types.map(&:to_s).include?(event_type)
+
+        raise ArgumentError, "#{key}: unknown event_type #{event_type.inspect}"
+      end
+    end
+
+    # Loads the app's list (config/optiaudit.rb). Returns false when there is none.
+    def self.load_file(path)
+      return false unless File.exist?(path)
+
+      load path.to_s
+      true
+    end
+
+    def initialize(entries)
+      @entries = entries
+      freeze
+    end
+
+    def lookup(controller_path, action_name)
+      actions = @entries[controller_path]
+      actions && actions[action_name]
+    end
+
+    def empty?
+      @entries.empty?
+    end
+
+    def keys
+      @entries.flat_map { |_, actions| actions.values.map(&:key) }.sort
+    end
+
+    # Checks every entry against the app routes, so that renaming a controller
+    # does not silently stop auditing it. Strict mode raises; otherwise each
+    # missing action is logged. Returns the keys without a route.
+    def verify!(routes, strict:)
+      routed = routes.routes.each_with_object({}) do |route, set|
+        controller, action = route.defaults.values_at(:controller, :action)
+        set["#{controller}##{action}"] = true if controller && action
+      end
+      missing = keys.reject { |key| routed.key?(key) }
+      return missing if missing.empty?
+
+      raise InvalidRegistry, "Optiaudit registry entries without a route: #{missing.join(', ')}" if strict
+
+      missing.each { |key| Optiaudit.log_warning("#{key} has no route: that action is not being audited") }
+      missing
+    end
+
+    EMPTY = new({}.freeze)
+  end
+end

data/lib/optiaudit/testing.rb

@@ -49,5 +49,13 @@ module Optiaudit
     def clear!
       events.clear
     end
+
+    # For the app's test suite: fails when an entry of config/optiaudit.rb has
+    # no route.
+    #
+    #   it("audits only routed actions") { Optiaudit::Testing.verify_registry! }
+    def verify_registry!
+      Optiaudit.registry.verify!(::Rails.application.routes, strict: true)
+    end
   end
 end

data/lib/optiaudit/version.rb

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

data/lib/optiaudit.rb

@@ -9,6 +9,7 @@ require "optiaudit/event"
 require "optiaudit/client"
 require "optiaudit/actor"
 require "optiaudit/request_data"
+require "optiaudit/registry"
 require "optiaudit/testing"
 
 # Sends audit events to OptiAudit. See README.md.
@@ -35,6 +36,19 @@ module Optiaudit
       Testing.fake? || configuration.enabled?
     end
 
+    # Declares the actions the app audits (see Optiaudit::Registry). Called from
+    # config/optiaudit.rb, which the Railtie loads at boot. Replaces any previous
+    # declaration.
+    def audit(&block)
+      builder = Registry::Builder.new(configuration)
+      builder.instance_exec(&block)
+      @registry = builder.build
+    end
+
+    def registry
+      @registry || Registry::EMPTY
+    end
+
     # Tracks an event. Returns true when it was handed to the adapter, false when
     # it was skipped (disabled, invalid) or failed. Never raises.
     #
@@ -80,6 +94,7 @@ module Optiaudit
     def reset!
       discard_adapter
       @configuration = nil
+      @registry = nil
     end
 
     private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: optiaudit-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - The Optimal Partner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-22 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -50,6 +50,7 @@ files:
 - lib/optiaudit/event.rb
 - lib/optiaudit/rails.rb
 - lib/optiaudit/railtie.rb
+- lib/optiaudit/registry.rb
 - lib/optiaudit/request_data.rb
 - lib/optiaudit/sidekiq_job.rb
 - lib/optiaudit/testing.rb