feat: Report handled errors to an external provider.

- Add the ErrorReporter seam and the ReportedError context every reporter
  reads, so a handled error reaches error tracking without the middleware
  knowing the provider.
- Add the SentryReporter adapter, which either boots the SDK from the
  deployment values or captures onto a hub the application already holds.
- Add ReportingFilter, so the consumer decides which handled errors reach the
  provider and a client error never spends quota.
- Add ReportingPriority and PrioritizedError, the four level urgency scale
  stated once in neutral terms and translated by each adapter.
- Add ReportingContext and ReportingTags, the exception side and request side
  supplements a report carries, which is how a value resolved below the
  middleware crosses the PSR-7 immutability gap.
- Add RouteMiddleware, so a report carries the route the request matched
  instead of the raw path that names one request rather than one endpoint.
- Add withMessage, which settles the message the response answers with before
  the body is built, so no layer above parses and re-encodes it.
- Validate the headers a mapping rule declares, so a malformed field fails
  while the table is declared rather than on the request that would return it.

Author: gustavofreze

README.md

@@ -28,7 +28,7 @@
         "psr/http-server-handler": "^1.0",
         "psr/http-server-middleware": "^1.0",
         "psr/log": "^3.0",
-        "tiny-blocks/http": "^7.0",
+        "tiny-blocks/http": "^7.1",
         "tiny-blocks/http-correlation-id": "^2.1"
     },
     "require-dev": {
@@ -37,10 +37,14 @@
         "infection/infection": "^0.34",
         "phpstan/phpstan": "^2.2",
         "phpunit/phpunit": "^13.2",
+        "sentry/sentry": "^4.0",
         "slevomat/coding-standard": "^8.31",
         "slim/slim": "^4.15",
         "squizlabs/php_codesniffer": "^4.0"
     },
+    "suggest": {
+        "sentry/sentry": "Required to use SentryReporter (^4.0)."
+    },
     "minimum-stability": "stable",
     "prefer-stable": true,
     "autoload": {

composer.json

@@ -8,18 +8,48 @@ parameters:
         # Constructor parameter holds the registered entries; PHPDoc is prohibited on constructors.
         - identifier: missingType.iterableValue
           path: src/ExceptionMappingTable.php
+        # Constructor parameter holds the response headers; PHPDoc is prohibited on constructors.
+        - identifier: missingType.iterableValue
+          path: src/MappedError.php
+        # Constructor parameter holds the accumulated tags; PHPDoc is prohibited on constructors.
+        - identifier: missingType.iterableValue
+          path: src/ReportedError.php
+        # Tag values reach the provider untyped, because ReportedError cannot annotate the array they come from.
+        - identifier: argument.type
+          path: src/Internal/Reporting/SentryTags.php
+        # Header values reach the response untyped; root cause is the same as the MappedError entry above.
+        - identifier: argument.type
+          path: src/Internal/Response/MappedResponse.php
         # Iteration over the constructor-typed array of entries; root cause is the same as above.
         - identifier: method.nonObject
           path: src/ExceptionMappingTable.php
         # The mapTo return type cannot be inferred without the constructor-level array shape.
         - identifier: return.type
           path: src/ExceptionMappingTable.php
+        # Constructor parameter holds the composed reporters; PHPDoc is prohibited inside src/Internal/.
+        - identifier: missingType.iterableValue
+          path: src/Internal/Reporting/CompositeErrorReporter.php
+        # Iteration over the constructor-typed array of reporters; root cause is the same as above.
+        - identifier: method.nonObject
+          path: src/Internal/Reporting/CompositeErrorReporter.php
+        # Trace lines and the assembled detail map; PHPDoc is prohibited inside src/Internal/.
+        - identifier: missingType.iterableValue
+          path: src/Internal/ExceptionDetails.php
+        # Header map arrives from the MappedError constructor; PHPDoc is prohibited inside src/Internal/.
+        - identifier: missingType.iterableValue
+          path: src/Internal/Response/ResponseHeaders.php
         # Internal matcher accepts a list of class-strings; PHPDoc is prohibited inside src/Internal/.
         - identifier: missingType.iterableValue
           path: src/Internal/Mapping/AnyExactClassMatcher.php
         # Closure invocation is opaque to PHPStan; PHPDoc is prohibited inside src/Internal/.
         - identifier: return.type
           path: src/Internal/Mapping/DynamicMappedErrorResolver.php
+        # Tag map the fake exception replays; PHPDoc is prohibited on constructors and inside tests/.
+        - identifier: missingType.iterableValue
+          path: tests/Unit/ContextualException.php
+        # The replayed map cannot be narrowed without the constructor tag; root cause is the same as above.
+        - identifier: return.type
+          path: tests/Unit/ContextualException.php
         # json_decode in test assertions yields mixed; PHPDoc is prohibited inside tests/.
         - identifier: offsetAccess.nonOffsetAccessible
           path: tests/Unit/ErrorMiddlewareTest.php

phpstan.neon.dist

@@ -17,20 +17,6 @@ private function __construct(
     ) {
     }
 
-    /**
-     * Creates an ErrorHandlingSettings with all flags disabled.
-     *
-     * @return ErrorHandlingSettings The default settings instance.
-     */
-    public static function default(): ErrorHandlingSettings
-    {
-        return ErrorHandlingSettings::from(
-            logErrors: false,
-            logErrorDetails: false,
-            displayErrorDetails: false
-        );
-    }
-
     /**
      * Creates an ErrorHandlingSettings from the given flags.
      *
@@ -50,4 +36,18 @@ public static function from(
             displayErrorDetails: $displayErrorDetails
         );
     }
+
+    /**
+     * Creates an ErrorHandlingSettings with all flags disabled.
+     *
+     * @return ErrorHandlingSettings The default settings instance.
+     */
+    public static function default(): ErrorHandlingSettings
+    {
+        return ErrorHandlingSettings::from(
+            logErrors: false,
+            logErrorDetails: false,
+            displayErrorDetails: false
+        );
+    }
 }

src/ErrorHandlingSettings.php

@@ -4,15 +4,20 @@
 
 namespace TinyBlocks\Http\ErrorHandler;
 
+use Closure;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
 use Psr\Log\LoggerInterface;
 use Throwable;
+use TinyBlocks\Http\Code;
 use TinyBlocks\Http\ErrorHandler\Internal\DefaultErrorMiddlewareBuilder;
 use TinyBlocks\Http\ErrorHandler\Internal\ErrorLogger;
 use TinyBlocks\Http\ErrorHandler\Internal\ErrorOutcome;
+use TinyBlocks\Http\ErrorHandler\Internal\Reporting\CompositeErrorReporter;
+use TinyBlocks\Http\ErrorHandler\Internal\ResolvedRoute;
+use TinyBlocks\Http\ErrorHandler\Reporters\SilentErrorReporter;
 
 /**
  * PSR-15 middleware that captures exceptions thrown downstream, delegates to a consumer-provided
@@ -29,21 +34,33 @@ private function __construct(private ErrorOutcome $errorOutcome)
      * Builds an ErrorMiddleware from its configuration components.
      *
      * @param LoggerInterface|null $logger The logger to use for error logging, or <code>null</code> to disable logging.
+     * @param Closure(ErrorPayload, ServerRequestInterface): string $message The rule settling the message the
+     *                                                            response answers with.
      * @param ExceptionMappingTable $mappings The composed table that maps exceptions to error responses.
+     * @param Closure(?MappedError, Code): ReportingPriority $priority The rule deriving a priority from the rule
+     *                                                            that matched and the resolved status.
      * @param ErrorHandlingSettings $settings The settings controlling error display and logging behavior.
      * @param bool $fallbackOnUnmapped Whether to return a fallback response when no mapping matches.
+     * @param ErrorReporter $reporter The reporter notified after the response is produced and logged. Defaults to
+     *                                {@see SilentErrorReporter}, which forwards every report to no provider.
      * @return ErrorMiddleware The configured middleware instance.
      */
     public static function build(
         ?LoggerInterface $logger,
+        Closure $message,
         ExceptionMappingTable $mappings,
+        Closure $priority,
         ErrorHandlingSettings $settings,
-        bool $fallbackOnUnmapped
+        bool $fallbackOnUnmapped,
+        ErrorReporter $reporter = new SilentErrorReporter()
     ): ErrorMiddleware {
         $errorOutcome = new ErrorOutcome(
+            message: $message,
             mappings: $mappings,
+            priority: $priority,
             settings: $settings,
             errorLogger: ErrorLogger::from(logger: $logger, settings: $settings),
+            errorReporter: CompositeErrorReporter::create()->with(reporter: $reporter),
             fallbackOnUnmapped: $fallbackOnUnmapped
         );
 
@@ -62,10 +79,21 @@ public static function create(): ErrorMiddlewareBuilder
 
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
+        $tags = ReportingTags::pending();
+        $route = ResolvedRoute::pending();
+        $routed = $request
+            ->withAttribute(ResolvedRoute::ATTRIBUTE_NAME, $route)
+            ->withAttribute(ReportingTags::ATTRIBUTE_NAME, $tags);
+
         try {
-            return $handler->handle($request);
+            return $handler->handle($routed);
         } catch (Throwable $exception) {
-            return $this->errorOutcome->resolve(request: $request, exception: $exception);
+            return $this->errorOutcome->resolve(
+                tags: $tags,
+                route: $route,
+                request: $routed,
+                exception: $exception
+            );
         }
     }
 }

src/ErrorMiddleware.php

@@ -4,11 +4,15 @@
 
 namespace TinyBlocks\Http\ErrorHandler;
 
+use Closure;
+use Psr\Http\Message\ServerRequestInterface;
 use Psr\Log\LoggerInterface;
+use TinyBlocks\Http\Code;
 use TinyBlocks\Http\ErrorHandler\Exceptions\MappingNotConfigured;
 
 /**
- * Fluent builder that assembles an {@see ErrorMiddleware} from a logger, exception mappings, and settings.
+ * Fluent builder that assembles an {@see ErrorMiddleware} from a logger, exception mappings, error reporters,
+ * settings, and the rules deciding the message a response answers with and the priority an error carries.
  */
 interface ErrorMiddlewareBuilder
 {
@@ -36,6 +40,19 @@ public function withLogger(?LoggerInterface $logger): ErrorMiddlewareBuilder;
      */
     public function withMapping(ExceptionMapping $mapping): ErrorMiddlewareBuilder;
 
+    /**
+     * Registers the rule that settles the message the response answers with.
+     *
+     * <p>Without this rule the response answers what the mapping or the fallback already said. An
+     * application that speaks to people replaces it, and decides from the resolved code and the request,
+     * so the message is settled once and never parsed back out of a rendered body.</p>
+     *
+     * @param Closure(ErrorPayload, ServerRequestInterface): string $resolver The rule naming the message to answer
+     *                                                                       with.
+     * @return ErrorMiddlewareBuilder The configured builder.
+     */
+    public function withMessage(Closure $resolver): ErrorMiddlewareBuilder;
+
     /**
      * Returns a builder with the given exception mappings registered.
      *
@@ -44,6 +61,32 @@ public function withMapping(ExceptionMapping $mapping): ErrorMiddlewareBuilder;
      */
     public function withMappings(ExceptionMapping ...$mappings): ErrorMiddlewareBuilder;
 
+    /**
+     * Registers the rule that derives a priority from the status the middleware resolved.
+     *
+     * <p>The default is {@see ReportingPriority::from}, which every consumer is free to replace. What an
+     * exception declares through {@see PrioritizedError} still wins over whatever this rule answers.</p>
+     *
+     * @param Closure(?MappedError, Code): ReportingPriority $resolver The rule naming the priority an error
+     *                                                              justifies.
+     * @return ErrorMiddlewareBuilder The configured builder.
+     */
+    public function withPriority(Closure $resolver): ErrorMiddlewareBuilder;
+
+    /**
+     * Returns a builder with the given error reporter registered.
+     *
+     * <p>Reporters are optional, and the method may be called more than once to register several of
+     * them, so one application can report to an error tracking service, a metrics backend, and an
+     * audit trail at once. Each one is notified after the response has been produced and the log
+     * entry emitted, and a failure thrown by one of them is discarded, so it can never affect the
+     * response.</p>
+     *
+     * @param ErrorReporter $reporter The reporter notified when an error is handled.
+     * @return ErrorMiddlewareBuilder The configured builder.
+     */
+    public function withReporter(ErrorReporter $reporter): ErrorMiddlewareBuilder;
+
     /**
      * Returns a builder configured with the given error handling settings.
      *

src/ErrorMiddlewareBuilder.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Http\ErrorHandler;
+
+use TinyBlocks\Http\Code;
+
+/**
+ * Body the middleware is about to answer with, before the message is final.
+ *
+ * <p>An application that speaks to people rather than to machines rewrites the message, and the
+ * rest of the answer stays as the middleware resolved it. Handing it this, rather than the rendered
+ * response, is what keeps the rewrite from being a parse and a re-encode of what was just built.</p>
+ */
+final readonly class ErrorPayload
+{
+    public function __construct(
+        public string $code,
+        public Code $status,
+        public string $message,
+        public bool $wasMapped
+    ) {
+    }
+}

src/ErrorPayload.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Http\ErrorHandler;
+
+/**
+ * Consumer-provided sink that forwards a handled error to an external observability provider.
+ *
+ * <p>One implementation adapts one provider, and the middleware accepts any number of them, so a
+ * single application can report to an error tracking service, a metrics backend, and an audit trail
+ * without any of them knowing about the others.</p>
+ *
+ * <p>Reporting is the best effort. Reporters run synchronously, after the response has been produced
+ * and after the log entry has been emitted, and any failure thrown by an implementation is
+ * discarded, so a provider that fails never fails the response. A slow one still adds its own
+ * duration to it.</p>
+ */
+interface ErrorReporter
+{
+    /**
+     * Reports the error to the provider this reporter adapts.
+     *
+     * <p>Implementations are free to throw. The middleware discards whatever comes out, so an
+     * implementation never needs to defend itself for the sake of the request.</p>
+     *
+     * @param ReportedError $error The resolved error context to forward.
+     */
+    public function report(ReportedError $error): void;
+}

src/ErrorReporter.php

@@ -25,7 +25,7 @@ public function __construct(private ExceptionMappingTable $table, private Except
      * Closes the rule with a fixed MappedError produced from the given fields.
      *
      * @param string $code Machine-readable error code.
-     * @param int $status HTTP response status code (400-599).
+     * @param int $status HTTP response status code, one of the known HTTP error statuses.
      * @param string $message Human-readable error description.
      * @param array<string, string|string[]> $headers Optional HTTP response headers.
      * @return ExceptionMappingTable The table with the new rule appended.

src/ExceptionMappingRule.php

@@ -53,7 +53,7 @@ public function when(string $exceptionClass): ExceptionMappingRule
     public function mapTo(Throwable $exception): ?MappedError
     {
         foreach ($this->entries as $entry) {
-            $mappedError = $entry->resolve(exception: $exception);
+            $mappedError = $entry->resolve($exception);
 
             if (!is_null($mappedError)) {
                 return $mappedError;