Document integration stages and optimize spoof checks

Author: ndbroadbent

INTEGRATIONS.md

@@ -5,7 +5,7 @@
 **High‑Level Flow**
 
 - Add a typed log structure under `lib/log_struct/log/` (so the docs generator picks it up).
-- Add a configuration toggle in `ConfigStruct::Integrations` and wire it into `Integrations.setup_integrations`.
+- Add a configuration toggle in `ConfigStruct::Integrations` and wire it into `Integrations.setup_integrations` via the appropriate stage (`:non_middleware` for instrumentation hooks, `:middleware` when the integration inserts Rack middleware).
 - Implement the integration under `lib/log_struct/integrations/…` to produce that log type.
 - Add the dev dependency for the third‑party gem and generate RBIs with Tapioca.
 - Add tests (unit + behavior) under `test/log_struct/integrations` and (if needed) `test/log_struct/log`.
@@ -74,7 +74,7 @@
      - `prop :enable_<name>, T::Boolean, default: true`
    - In `lib/log_struct/integrations.rb`:
      - `require_relative "integrations/<name>"`
-     - Call `Integrations::<Name>.setup(config)` inside `setup_integrations` behind the toggle.
+     - Call `Integrations::<Name>.setup(config)` inside `setup_integrations`, selecting the stage that matches your integration (`:non_middleware` for subscribers/hooks, `:middleware` for Rack additions). Most integrations belong in the default `:non_middleware` stage; only code that mutates the middleware stack should go in `:middleware`.
 
 4. Implement the integration
    - File: `lib/log_struct/integrations/<name>.rb`

docs/README.md

@@ -14,20 +14,20 @@ This is the documentation website for the LogStruct gem, built with Next.js and
 ### Prerequisites
 
 - Node.js (version 18 or higher)
-- npm (version 8 or higher)
+- pnpm (version 9 or higher)
 
 ### Getting Started
 
 1. Install dependencies:
 
 ```bash
-npm install
+pnpm install
 ```
 
 2. Start the development server:
 
 ```bash
-npm run dev
+pnpm dev
 ```
 
 3. Open [http://localhost:3001](http://localhost:3001) to view the docs in your browser.
@@ -37,7 +37,7 @@ npm run dev
 To build the static docs for production:
 
 ```bash
-npm run build
+pnpm build
 ```
 
 This will generate static HTML files in the `out` directory that can be deployed to any static web hosting service.
@@ -51,7 +51,7 @@ To manually deploy:
 1. Build the docs:
 
 ```bash
-npm run build
+pnpm build
 ```
 
 2. The static files will be in the `out` directory, which can be deployed to any static hosting service.

docs/biome.json

@@ -8,8 +8,8 @@
   "files": {
     "ignoreUnknown": false,
     "includes": [
-      "**/*.{js,ts,jsx,tsx}",
-      "*.{js,ts,jsx,tsx}",
+      "**/*.{js,ts,jsx,tsx,json}",
+      "*.{js,ts,jsx,tsx,json}",
       "!generated/**/*.ts",
       "!scripts/**/*.js",
       "!public/coverage/**/*"

docs/package.json

@@ -13,8 +13,8 @@
     "format": "biome format --write .",
     "test": "jest",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check": "npm run typecheck && npm run lint && npm run build && npm run test:integration && npm run e2e",
-    "test:integration": "node scripts/prepare-integration-fixtures.js && npm run build && jest -c jest.integration.config.ts",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run build && pnpm run test:integration && pnpm run e2e",
+    "test:integration": "node scripts/prepare-integration-fixtures.js && pnpm run build && jest -c jest.integration.config.ts",
     "e2e": "playwright test",
     "test:watch": "jest --watch",
     "generate-favicons": "node scripts/generate-favicons.js"

lib/log_struct/integrations/rack_error_handler/middleware.rb

@@ -83,7 +83,6 @@ def call(env)
             [FORBIDDEN_STATUS, IP_SPOOF_HEADERS.dup, [IP_SPOOF_HTML]]
           rescue ::ActionController::InvalidAuthenticityToken => invalid_auth_token_error
             # Create a security log for CSRF error
-            request = ::ActionDispatch::Request.new(env)
             security_log = Log::Security::CSRFViolation.new(
               path: request.path,
               http_method: request.method,
@@ -97,15 +96,15 @@ def call(env)
             LogStruct.error(security_log)
 
             # Report to error reporting service and/or re-raise
-            context = extract_request_context(env)
+            context = extract_request_context(env, request)
             LogStruct.handle_exception(invalid_auth_token_error, source: Source::Security, context: context)
 
             # If handle_exception raised an exception then Rails will deal with it (e.g. config.exceptions_app)
             # If we are only logging or reporting these security errors, then return a default response
             [FORBIDDEN_STATUS, CSRF_HEADERS.dup, [CSRF_HTML]]
           rescue => error
             # Extract request context for error reporting
-            context = extract_request_context(env)
+            context = extract_request_context(env, request)
 
             # Create and log a structured exception with request context
             exception_log = Log.from_exception(Source::Rails, error, context)
@@ -122,23 +121,19 @@ def call(env)
         sig { params(request: ::ActionDispatch::Request).void }
         def perform_remote_ip_check!(request)
           action_dispatch_config = ::Rails.application.config.action_dispatch
+          check_ip = action_dispatch_config.ip_spoofing_check
+          return unless check_ip
 
-          remote_ip_middleware = ::ActionDispatch::RemoteIp.new(
-            ->(_env) { [200, {}, []] },
-            action_dispatch_config.ip_spoofing_check,
-            action_dispatch_config.trusted_proxies
-          )
-
-          return unless remote_ip_middleware.check_ip
+          proxies = normalized_trusted_proxies(action_dispatch_config.trusted_proxies)
 
           ::ActionDispatch::RemoteIp::GetIp
-            .new(request, remote_ip_middleware.check_ip, remote_ip_middleware.proxies)
+            .new(request, check_ip, proxies)
             .to_s
         end
 
-        sig { params(env: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
-        def extract_request_context(env)
-          request = ::ActionDispatch::Request.new(env)
+        sig { params(env: T::Hash[String, T.untyped], request: T.nilable(::ActionDispatch::Request)).returns(T::Hash[Symbol, T.untyped]) }
+        def extract_request_context(env, request = nil)
+          request ||= ::ActionDispatch::Request.new(env)
           {
             request_id: request.request_id,
             path: request.path,
@@ -150,6 +145,32 @@ def extract_request_context(env)
           # If we can't extract request context, return minimal info
           {error_extracting_context: error.message}
         end
+
+        sig { params(configured_proxies: T.untyped).returns(T.untyped) }
+        def normalized_trusted_proxies(configured_proxies)
+          if configured_proxies.nil? || (configured_proxies.respond_to?(:empty?) && configured_proxies.empty?)
+            return ::ActionDispatch::RemoteIp::TRUSTED_PROXIES
+          end
+
+          return configured_proxies if configured_proxies.respond_to?(:any?)
+
+          raise(
+            ArgumentError,
+            <<~EOM
+              Setting config.action_dispatch.trusted_proxies to a single value isn't
+              supported. Please set this to an enumerable instead. For
+              example, instead of:
+
+              config.action_dispatch.trusted_proxies = IPAddr.new("10.0.0.0/8")
+
+              Wrap the value in an Array:
+
+              config.action_dispatch.trusted_proxies = [IPAddr.new("10.0.0.0/8")]
+
+              Note that passing an enumerable will *replace* the default set of trusted proxies.
+            EOM
+          )
+        end
       end
     end
   end