Redactor refactor

Author: belisarh

README.md

@@ -110,13 +110,15 @@ class StripePaymentService
 
 **What it does:** Monitors critical operations with automatic start/end logging, exception-specific handling, DB transactions, circuit breakers, and true escalation for uncaught exceptions.
 
+**Note:** The second parameter `$origin` (usually `$this`) is optional and automatically provides origin context to the structured logger used by the controlled block, eliminating the need for a separate `->from()` call.
+
 #### **Factory & Execution**
 
 ```php
 use Kirschbaum\Monitor\Facades\Monitor;
 
 // Create and execute controlled block
-$result = Monitor::controlled('payment_processing')
+$result = Monitor::controlled('payment_processing', $this)
     ->run(function() {
         return processPayment($data);
     });
@@ -128,50 +130,54 @@ $result = Monitor::controlled('payment_processing')
 /*
  * Adds additional context to the structured logger.
  */
-->addContext([
-    'transaction_id' => 'txn_456',
-    'gateway' => 'stripe'
-]);
+Monitor::controlled('payment_processing', $this)
+    ->addContext([
+        'transaction_id' => 'txn_456',
+        'gateway' => 'stripe'
+    ]);
 
 /*
  * Will completely replace structured logger context.
  * ⚠️ Not recommended unless you have a good reason to do so.
  */
-->overrideContext([
-    'user_id' => 123,
-    'operation' => 'payment',
-    'amount' => 99.99
-]);
+Monitor::controlled('payment_processing', $this)
+    ->overrideContext([
+        'user_id' => 123,
+        'operation' => 'payment',
+        'amount' => 99.99
+    ]);
 ```
 
 #### **Exception Handling**
 
 **Exception-Specific Handlers (`catching`):**
 ```php
-->catching([
-    DatabaseException::class => function($exception, $meta) {
-        $cachedData = ExampleModel::getCachedData();
-        return $cachedData; // Recovery value
-    },
-    NetworkException::class => function($exception, $meta) {
-        $this->exampleRetryLater($meta);
-        // No return = just handle, don't recover
-    },
-    PaymentException::class => function($exception, $meta) {
-        $this->exampleNotifyFinanceTeam($exception, $meta);
-        throw $exception; // Re-throw if needed
-    },
-    // Other exception types remain uncaught.
-])
+Monitor::controlled('payment_processing', $this)
+    ->catching([
+        DatabaseException::class => function($exception, $meta) {
+            $cachedData = ExampleModel::getCachedData();
+            return $cachedData; // Recovery value
+        },
+        NetworkException::class => function($exception, $meta) {
+            $this->exampleRetryLater($meta);
+            // No return = just handle, don't recover
+        },
+        PaymentException::class => function($exception, $meta) {
+            $this->exampleNotifyFinanceTeam($exception, $meta);
+            throw $exception; // Re-throw if needed
+        },
+        // Other exception types remain uncaught.
+    ])
 ```
 
 **Uncaught Exception Handling (`onUncaughtException`):**
 ```php
-->onUncaughtException(function($exception, $meta) {
-    // Example actions, the exception will remain uncaught
-    $this->alertOpsTeam($exception, $meta);
-    $this->sendToErrorTracking($exception);
-})
+Monitor::controlled('payment_processing', $this)
+    ->onUncaughtException(function($exception, $meta) {
+        // Example actions, the exception will remain uncaught
+        $this->alertOpsTeam($exception, $meta);
+        $this->sendToErrorTracking($exception);
+    })
 ```
 
 **Key Behavior:**
@@ -182,16 +188,63 @@ $result = Monitor::controlled('payment_processing')
 
 #### **Circuit Breaker & Database Protection**
 
+**What are Circuit Breakers?**
+Circuit breakers prevent cascading failures by temporarily stopping requests to a failing service, allowing it time to recover. They automatically "open" after a threshold of failures and "close" once the service is healthy again, protecting your application from wasting resources on operations likely to fail.
+
 ```php
-->withCircuitBreaker('payment_gateway', 3, 60) // 3 failures, 60s timeout
-->withDatabaseTransaction(2, [DeadlockException::class], [ValidationException::class])
+Monitor::controlled('payment_processing', $this)
+    ->withCircuitBreaker('payment_gateway', 3, 60) // 3 failures, 60s timeout
+    ->withDatabaseTransaction(2, [DeadlockException::class], [ValidationException::class])
 ```
 
+**Circuit Breaker HTTP Middleware**
+
+You can also protect entire routes or route groups using the `CheckCircuitBreakers` middleware:
+
+```php
+// bootstrap/app.php or register as route middleware
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->alias([
+        'circuit' => \Kirschbaum\Monitor\Http\Middleware\CheckCircuitBreakers::class,
+    ]);
+})
+
+// In your routes
+Route::middleware(['circuit:payment_gateway,external_api'])
+    ->group(function () {
+        Route::post('/payments', [PaymentController::class, 'store']);
+        Route::get('/external-data', [DataController::class, 'fetch']);
+    });
+
+// Or on individual routes
+Route::get('/api/data')
+    ->middleware('circuit:slow_service')
+    ->name('data.fetch');
+```
+
+**Circuit Breaker Middleware Features:**
+- **Multiple Breakers**: Check multiple circuit breakers with `circuit:breaker1,breaker2,breaker3`
+- **Graceful Degradation**: Returns HTTP 503 (Service Unavailable) when circuit is open
+- **Standard Headers**: Includes `Retry-After`, `X-Circuit-Breaker`, and `X-Circuit-Breaker-Status` headers
+- **Jitter Protection**: Built-in randomized retry delays prevent thundering herd effects
+- **Auto-Recovery**: Circuits automatically close when services recover
+
+**Response Headers When Circuit is Open:**
+```
+HTTP/1.1 503 Service Unavailable
+Retry-After: 45
+X-Circuit-Breaker: payment_gateway
+X-Circuit-Breaker-Status: open
+```
+
+The `Retry-After` header includes intelligent jitter - instead of all clients retrying at the exact same time, it provides a random delay between 0 and the remaining decay time, preventing overwhelming the recovering service.
+
 #### **Tracing & Logging**
 
 ```php
-->overrideTraceId('custom-trace-12345')
-->from('PaymentService') // Custom logger origin
+Monitor::controlled('payment_processing', $this)
+    ->overrideTraceId('custom-trace-12345')
+    // Origin is automatically set from the second parameter ($this)
 ```
 
 #### **Complete Example**
@@ -225,7 +278,7 @@ class PaymentService
 }
 ```
 
-#### **📊 What it logs:**
+#### **What it logs:**
 
 **Success:**
 ```json
@@ -246,19 +299,18 @@ class PaymentService
 {"message": "[PaymentProcessor] UNCAUGHT", "exception": "RuntimeException", "uncaught": true, "duration_ms": 300}
 ```
 
-#### **🎯 API Reference**
+#### **API Reference**
 
 | Method | Purpose | Returns |
 |--------|---------|---------|
-| `Controlled::for(string $name)` | Create controlled block | `self` |
+| `Monitor::controlled(string $name, string\|object $origin = null)` | Create controlled block with optional origin | `self` |
 | `->overrideContext(array $context)` | Replace entire context | `self` |
 | `->addContext(array $context)` | Merge additional context | `self` |
 | `->catching(array $handlers)` | Define exception-specific handlers | `self` |
 | `->onUncaughtException(Closure $callback)` | Handle uncaught exceptions only | `self` |
 | `->withCircuitBreaker(string $name, int $threshold, int $decay)` | Configure circuit breaker | `self` |
 | `->withDatabaseTransaction(int $retries, array $only, array $exclude)` | Wrap in DB transaction with retry | `self` |
 | `->overrideTraceId(string $traceId)` | Set custom trace ID | `self` |
-| `->from(string\|object $origin)` | Set logger origin | `self` |
 | `->run(Closure $callback)` | Execute the controlled block | `mixed` |
 
 ### Distributed Tracing

composer.json

@@ -29,7 +29,8 @@
         "laravel/pint": "^1.22",
         "larastan/larastan": "^3.4",
         "orchestra/testbench": "^10.3",
-        "pestphp/pest-plugin-laravel": "^3.1"
+        "pestphp/pest-plugin-laravel": "^3.1",
+        "timacdonald/log-fake": "^2.4"
     },
     "config": {
         "allow-plugins": {

config/monitor.php

@@ -417,6 +417,37 @@
 
         'mark_redacted' => env('MONITOR_LOG_REDACTOR_MARK_REDACTED', true),
 
+        /*
+        |----------------------------------------------------------------------
+        | Track Redacted Keys
+        |----------------------------------------------------------------------
+        |
+        | When enabled, adds a '_redacted_keys' array to the context listing
+        | which keys were redacted. Useful for debugging and auditing.
+        | Only applies when mark_redacted is also enabled.
+        |
+        */
+
+        'track_redacted_keys' => env('MONITOR_LOG_REDACTOR_TRACK_KEYS', false),
+
+        /*
+        |----------------------------------------------------------------------
+        | Non-Redactable Object Behavior
+        |----------------------------------------------------------------------
+        |
+        | Defines how to handle objects that cannot be safely redacted due to
+        | circular references, resources, or other serialization issues.
+        |
+        | Available options:
+        |   - 'preserve': Return the original object unchanged (default, safest)
+        |   - 'remove': Remove the object entirely from context
+        |   - 'empty_array': Replace with an empty array []
+        |   - 'redact': Replace with redaction placeholder text
+        |
+        */
+
+        'non_redactable_object_behavior' => env('MONITOR_LOG_REDACTOR_OBJECT_BEHAVIOR', 'preserve'),
+
         /*
         |----------------------------------------------------------------------
         | Maximum Value Length
@@ -431,7 +462,7 @@
         |
         */
 
-        'max_value_length' => env('MONITOR_LOG_REDACTOR_MAX_VALUE_LENGTH', 20000),
+        'max_value_length' => env('MONITOR_LOG_REDACTOR_MAX_VALUE_LENGTH', 5000),
 
         /*
         |----------------------------------------------------------------------
@@ -494,6 +525,29 @@
             | 30: Higher performance, may miss some short tokens
             */
             'min_length' => env('MONITOR_LOG_REDACTOR_SHANNON_MIN_LENGTH', 25),
+
+            /*
+            |----------------------------------------------------------------------
+            | Exclusion Patterns
+            |----------------------------------------------------------------------
+            |
+            | Regex patterns for strings that should NOT be redacted despite having
+            | high entropy. These patterns identify common safe formats like URLs,
+            | file paths, UUIDs, etc. that naturally have high entropy but are not
+            | sensitive data.
+            |
+            */
+            'exclusion_patterns' => [
+                '/^https?:\/\//',                                                           // URLs
+                '/^[\/\\\\].+[\/\\\\]/',                                                   // File paths
+                '/^\d{4}-\d{2}-\d{2}/',                                                    // Date formats
+                '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i',     // UUIDs
+                '/^[0-9a-f]+$/i',                                                          // Hex strings (short ones < 32 chars)
+                '/^\s*$/',                                                                 // Whitespace strings
+                '/^Mozilla\/\d\.\d|^[A-Za-z]+\/\d+\.\d+|AppleWebKit|Chrome|Safari|Firefox|Opera|Edge/', // User agents
+                '/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/',                                // IPv4 addresses
+                '/^[0-9a-f]{2}:[0-9a-f]{2}:[0-9a-f]{2}:[0-9a-f]{2}:[0-9a-f]{2}:[0-9a-f]{2}$/i', // MAC addresses
+            ],
         ],
     ],
 ];

src/Controlled.php

@@ -14,7 +14,7 @@
 
 final class Controlled
 {
-    protected ?string $name = null;
+    protected string $name;
 
     /** @var array<class-string<\Throwable>, \Closure> */
     protected array $exceptionHandlers = [];
@@ -46,12 +46,18 @@ final class Controlled
 
     protected ?StructuredLogger $logger = null;
 
-    public static function for(string $name): self
+    public function __construct(string $name, string|object|null $origin = null)
     {
-        $instance = new self;
-        $instance->name = $name;
+        $this->name = $name;
 
-        return $instance;
+        if ($origin !== null) {
+            $this->withStructuredLogger(StructuredLogger::from($origin));
+        }
+    }
+
+    public static function for(string $name, string|object|null $origin = null): self
+    {
+        return new self($name, $origin);
     }
 
     /**
@@ -127,9 +133,9 @@ public function overrideTraceId(string $traceId): self
         return $this;
     }
 
-    public function from(string|object $origin): self
+    public function withStructuredLogger(StructuredLogger $logger): self
     {
-        $this->logger = StructuredLogger::from($origin);
+        $this->logger = $logger;
 
         return $this;
     }
@@ -141,10 +147,6 @@ public function run(Closure $callback): mixed
 
     protected function execute(Closure $callback): mixed
     {
-        if (! $this->name) {
-            throw new \InvalidArgumentException('Controlled block name is required');
-        }
-
         if ($this->traceIdOverride) {
             Monitor::trace()->override($this->traceIdOverride);
         }
@@ -266,7 +268,7 @@ protected function handleCaughtException(Throwable $e, string $blockId, string $
         foreach ($this->exceptionHandlers as $exceptionClass => $handler) {
             if ($e instanceof $exceptionClass) {
                 $meta = new ControlledFailureMeta(
-                    name: $this->name ?? 'unknown',
+                    name: $this->name,
                     id: $blockId,
                     traceId: $traceId,
                     attempt: $this->attempt,
@@ -316,7 +318,7 @@ protected function handleCaughtException(Throwable $e, string $blockId, string $
     protected function handleUncaughtException(Throwable $e, string $blockId, string $traceId, float $durationMs): void
     {
         $meta = new ControlledFailureMeta(
-            name: $this->name ?? 'unknown',
+            name: $this->name,
             id: $blockId,
             traceId: $traceId,
             attempt: $this->attempt,

src/Facades/Monitor.php

@@ -11,9 +11,8 @@
  * @method static \Kirschbaum\Monitor\StructuredLogger log(string|object $origin = 'Monitor')
  * @method static \Kirschbaum\Monitor\LogTimer time()
  * @method static \Kirschbaum\Monitor\CircuitBreaker breaker()
- * @method static \Kirschbaum\Monitor\MonitorWithOrigin from(string|object $origin)
- * @method static mixed controlled(string $name, \Closure|null $callback = null, array<string, mixed> $context = [], \Closure|null $onFail = null)
- * @method static \Kirschbaum\Monitor\Controlled controlled()
+ * @method static \Kirschbaum\Monitor\Controlled controlled(string $name, string|object|null $origin = null)
+ * @method static \Kirschbaum\Monitor\Support\LogRedactor redactor()
  */
 class Monitor extends Facade
 {