optiaudit-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ee00e821c324db9b3aba699c39e04eff9b471b1d1dfd5779deae13c6b2f293
-  data.tar.gz: cc49b0ca5595307c1461067dc06467a1f056c998b8e795a35beb29510aeb44d7
+  metadata.gz: 8ab9fc2af772216e10bb2376e7eb5c7dab31393f41500bf9375564b94c848128
+  data.tar.gz: ad4ba3df9b4b5b86cba423aaf50d2f9c87f832f78dde26873ecb3a4c2939f5f5
 SHA512:
-  metadata.gz: 3b50e99331b77e089addca33877bf5ba22c38b7f37f3303fb911593382c48200b74b36eaeb321ace3baa748e1a47ac9f5c7c622e98609656f6b067d54bb38e10
-  data.tar.gz: 8559093f201881f42ab2482949b5128c9778f095e0e394fa74187df8b1d6ff48120d8a0093b4032f03feefd47a24d3fbc76552a5bd103f839dac1f301cf032a9
+  metadata.gz: 454b2763272e3483aab0f1fb6f8c5dddf647e60dedda80929df8cdb30c0801810b52b146eed5bfea5794f337428e6429443d91c847470002cdfbca295a5e104f
+  data.tar.gz: e2f094abd10c8e528f7fcd316c1f9f208c6e53143c6316b57b223774e2cc507bddfa3e1a33211e05216947d290655fb90cf3506939ed53a39011f9b6bd588987

data/CHANGELOG.md

@@ -7,6 +7,41 @@ 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.
+
+### Fixed
+
+- **IP falsificada.** Cuando `Client-IP` y `X-Forwarded-For` no coinciden (`IpSpoofAttackError`), la 0.1.0 mandaba `request.ip`, que es el valor que eligió el cliente. Ahora el evento sale sin `ip_address`, con un warning.
+- **`ip_address` inválido** pasado a mano: OptiAudit lo acepta con 202 y después su worker pierde el evento sin avisar. Ahora la gema lo omite.
+- **`client_timestamp` que no es ISO 8601** pasado a mano: OptiAudit rechazaba el evento con 400. Ahora se reemplaza por la hora actual, con un warning.
+
+### Changed
+
+- README: con el adaptador `:thread`, OptiAudit pisa el `metadata.request_id` de cada evento con el id del POST del batch. El spoofing de IP ocurre en Rails 5.2 a 7.0, y en Rails 5.2 con log `info` es Rails, no la gema, el que responde 500.
+
 ## [0.1.0] - 2026-10-22
 
 Primera versión: el equivalente para Rails de `@theoptimalpartner/nestjs-optiaudit` 0.1.8 (SC25-2703).
@@ -23,5 +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.0
+[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
@@ -166,7 +204,7 @@ Request data, also filled in by `optiaudit_track`:
 | `ip_address` | `request.remote_ip` (see below) |
 | `user_agent` | `request.user_agent` |
 | `session_id` | SHA-256 of the session id. The raw id is a credential and never leaves the app. Only sent when the action already loaded the session. |
-| `metadata.request_id` | `request.request_id` (`X-Request-ID`), also sent as the `X-Request-ID` header to OptiAudit |
+| `metadata.request_id` | `request.request_id` (`X-Request-ID`), also sent as the `X-Request-ID` header to OptiAudit. With the `:thread` adapter OptiAudit replaces it with the id of the batch request (see [Delivery](#delivery)). |
 | `metadata.module` | the module given to the macro |
 
 ## Client IP Resolution
@@ -179,15 +217,18 @@ rule as the NestJS package since `v0.1.8`: values a client injects on the left a
 If your proxies use public addresses (a CDN in front of the load balancer), add them to
 `config.action_dispatch.trusted_proxies`, or `remote_ip` will return the proxy.
 
-In Rails 5.2, `remote_ip` raises `IpSpoofAttackError` when `Client-IP` and `X-Forwarded-For` disagree.
-The gem then logs a warning and uses `request.ip`, so the event is still sent and the request is not affected.
+When `Client-IP` and `X-Forwarded-For` disagree, `remote_ip` raises `IpSpoofAttackError` (Rails 5.2 to 7.0).
+The gem logs a warning and sends the event without `ip_address`: the other sources of the IP, like
+`request.ip`, return a value the client chose. The gem never raises, but Rails itself may: in Rails 5.2
+the request logger calls `remote_ip` at log level `info`, so with those headers the request fails with
+500 before reaching the controller, with or without this gem.
 
 ## Delivery
 
 | Adapter | When | How |
 |---------|------|-----|
 | `:sidekiq` | Default when Sidekiq is loaded | One job per event in the `optiaudit` queue. Survives deploys. Retried with Sidekiq's backoff (5 times by default) on 5xx, 429, timeouts and connection errors. Other 4xx are dropped with a warning: retrying would not fix them. |
-| `:thread` | Default without Sidekiq | In-memory buffer sent to `POST /events/batch` (up to 100 events) every 5 seconds or when full, from a background thread. Works with forking servers (Puma, Unicorn): each process starts its own thread. Pending events are flushed at exit. Events still in memory are lost if the process is killed, and failed batches are not retried. |
+| `:thread` | Default without Sidekiq | In-memory buffer sent to `POST /events/batch` (up to 100 events) every 5 seconds or when full, from a background thread. Works with forking servers (Puma, Unicorn): each process starts its own thread. Pending events are flushed at exit. Events still in memory are lost if the process is killed, and failed batches are not retried. OptiAudit sets `metadata.request_id` of every event in a batch to the id of the batch request, so the request id of each event is lost. |
 | `:inline` | Console, scripts, debugging | Synchronous `POST /events` in the caller's thread. Adds up to `timeout` seconds to a request. |
 
 Sidekiq jobs receive the event as a hash of string keys and JSON values, so they work with Sidekiq 7's
@@ -255,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
@@ -271,11 +315,11 @@ Fields accepted by `Optiaudit.track` and `optiaudit_track`, with the limits of O
 | `resource_type` | string | Truncated to 100. |
 | `resource_id` | string | Truncated to 100. |
 | `resource_path` | string | Truncated to 500. |
-| `ip_address` | string | Truncated to 45. |
+| `ip_address` | string | IPv4 or IPv6. Omitted if it is not an IP (OptiAudit would accept it and then lose the event). |
 | `user_agent` | string | |
 | `session_id` | string | Truncated to 255. `optiaudit_track` sends a SHA-256. |
 | `metadata` | hash | Free-form. Converted to JSON types. |
-| `client_timestamp` | Time or ISO 8601 string | Default: when `track` is called, not when the event is sent. |
+| `client_timestamp` | Time or ISO 8601 string | Default: when `track` is called, not when the event is sent. A string that is not ISO 8601 is replaced by the current time, with a warning. |
 
 OptiAudit rejects the whole event when one field is invalid, and in a batch, the whole batch. That is why
 the gem truncates or omits fields instead of sending them as they are.
@@ -289,11 +333,15 @@ the gem truncates or omits fields instead of sending them as they are.
 | No actor | Event not sent |
 | Action raised or response 4xx/5xx | Event not sent |
 | Unknown `event_type` | Event not sent, logs warning |
-| Invalid `actor_email` / `organization_id` | Field omitted, event sent |
+| Invalid `actor_email` / `organization_id` / `ip_address` | Field omitted, event sent |
+| Invalid `client_timestamp` | Replaced by the current time, logs warning, event sent |
+| `Client-IP` and `X-Forwarded-For` disagree (IP spoofing) | Event sent without `ip_address`, logs warning |
 | HTTP 5xx, 429, timeout (3s), connection error | Logs warning, doesn't raise. Sidekiq retries. |
 | 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
 
@@ -312,7 +360,18 @@ To try the gem end to end against a real OptiAudit (e.g. development), `examples
 OPTIAUDIT_URL=https://... OPTIAUDIT_WRITE_KEY=oat-... bundle exec ruby examples/smoke.rb
 ```
 
-Releases are published to rubygems.org from Bitbucket Pipelines with the manual `custom: publish` pipeline.
+## Releasing
+
+The gem is owned by the `routinguc` account on rubygems.org and requires MFA (`rubygems_mfa_required`),
+so every push asks for a one-time password and releases are published by hand, not from CI:
+
+1. Update `lib/optiaudit/version.rb` and `CHANGELOG.md`, commit and wait for the CI matrix to pass.
+2. Tag the release: `git tag v<version> && git push origin v<version>`.
+3. Build and push with an API key that has the "Push rubygem" scope (rubygems.org → Settings → API keys):
+   ```bash
+   gem build optiaudit-rails.gemspec
+   GEM_HOST_API_KEY=<api-key> gem push optiaudit-rails-<version>.gem   # asks for the OTP
+   ```
 
 ## License
 

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/event.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ipaddr"
 require "json"
 require "time"
 
@@ -9,8 +10,9 @@ module Optiaudit
   # OptiAudit validates every field and rejects the whole event (and, in a batch,
   # the whole batch) when one is invalid. So instead of sending something that
   # will come back as 400/422, fields are fixed here: strings are truncated to
-  # the API limits, an invalid actor_email is omitted and a non-integer
-  # organization_id is omitted.
+  # the API limits; an invalid actor_email or ip_address and a non-integer
+  # organization_id are omitted; an invalid client_timestamp becomes the
+  # current time.
   module Event
     # Limits from OptiAudit's CreateEventDto.
     MAX_LENGTHS = {
@@ -59,6 +61,7 @@ module Optiaudit
       end
       event["actor_type"] ||= DEFAULT_ACTOR_TYPE
       event.delete("actor_email") unless email?(event["actor_email"])
+      event.delete("ip_address") unless ip?(event["ip_address"])
 
       organization_id = integer(params["organization_id"])
       event["organization_id"] = organization_id if organization_id
@@ -99,6 +102,17 @@ module Optiaudit
       labels.size >= 2 && labels.all? { |label| label.match?(DOMAIN_LABEL) } && labels.last.match?(TOP_LEVEL_DOMAIN)
     end
 
+    # OptiAudit stores it in an INET column: anything else is accepted by the
+    # API and then lost by its worker.
+    def ip?(value)
+      return false if value.nil?
+
+      IPAddr.new(value)
+      true
+    rescue IPAddr::Error
+      false
+    end
+
     def integer(value)
       return value if value.is_a?(Integer)
 
@@ -107,10 +121,25 @@ module Optiaudit
 
     def timestamp(value)
       case value
-      when nil then Time.now.utc.iso8601(3)
+      when nil then current_timestamp
       when Time, DateTime then value.to_time.utc.iso8601(3)
-      else value.to_s
+      else
+        return value.to_s if iso8601?(value.to_s)
+
+        Optiaudit.log_warning("client_timestamp #{value.to_s.inspect} is not ISO 8601, using the current time")
+        current_timestamp
       end
     end
+
+    def iso8601?(value)
+      Time.iso8601(value)
+      true
+    rescue ArgumentError
+      false
+    end
+
+    def current_timestamp
+      Time.now.utc.iso8601(3)
+    end
   end
 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/request_data.rb

@@ -17,13 +17,14 @@ module Optiaudit
     end
 
     # remote_ip skips trusted proxies (private ranges by default), so behind a
-    # load balancer it returns the client's public IP. In Rails 5.2 it raises
-    # when Client-IP and X-Forwarded-For disagree.
+    # load balancer it returns the client's public IP. It raises when
+    # Client-IP and X-Forwarded-For disagree; then the IP is omitted: the
+    # alternatives (request.ip) return a value the client chose.
     def client_ip(request)
       request.remote_ip
     rescue ActionDispatch::RemoteIp::IpSpoofAttackError => e
-      Optiaudit.log_warning("remote_ip rejected (#{e.message}), using request.ip")
-      request.ip
+      Optiaudit.log_warning("remote_ip rejected (#{e.message}), event sent without ip_address")
+      nil
     end
 
     # Hashed: the raw session id is a credential and never leaves the app.

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.0"
+  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.0
+  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