Dispatch AiExceptionEvent and allow subscribers to replace the response (graceful failover) (#3585233) · Issues · project / ai

Dispatch AiExceptionEvent and allow subscribers to replace the response (graceful failover)

>>> [!note] Migrated issue   Reported by: [marcus_johansson](https://www.drupal.org/user/385947) Related to !1514 >>> [Tracker] Update Summary: [One-line status update for stakeholders] Short Description: Dispatch a new AiExceptionEvent from ProviderProxy::wrapperCall() so subscribers can rewrite the exception message or substitute an OutputInterface, enabling third-party failover without patching core. Check-in Date: MM/DD/YYYY [/Tracker] <h3 id="summary-problem-motivation">Problem/Motivation</h3> Projects are shipping the AI module's features and third parties want to customise how failures surface. Two real needs today: <ul> <li>Customise the error message. When OpenAI reports a budget overrun, the raw exception surfaces as <code>Drupal\ai\Exception\AiRequestErrorException: Error invoking model response: Budget has been exceeded! Current cost: 1.133637, Max budget: 1.0</code> thrown from <code>ProviderProxy::wrapperCall()</code>. The floating-point precision and the raw "Budget has been exceeded" text leak implementation detail to the end user. Downstream modules currently have no extension point to rewrite this before it propagates.</li> <li>React to a failure without taking the caller down with it. When the primary provider exceeds quota or hits a rate limit, site owners want to transparently fall back to a secondary provider (or a cached response, or a canned apology) without the caller having to catch and retry. Right now <code>ProviderProxy::wrapperCall()</code> always rethrows and there is no way for a subscriber to substitute a valid <code>OutputInterface</code>.</li> </ul> Both <a href="https://www.drupal.org/project/ai/issues/3542496" title="Status: Needs work">#3542496: Dispatch AiExceptionEvent when a provider throws an exception</a> (dispatch an exception event) and a graceful-failover mechanism are being built or discussed in parallel. This issue does both in one patch because they share the dispatch site and the same event object. <h3 id="summary-proposed-resolution">Proposed resolution</h3> Three coordinated parts, all landing together because they touch the same three lines of <code>ProviderProxy::wrapperCall()</code> and the same event class. Part A — Dispatch <code>AiExceptionEvent</code> (from <a href="https://www.drupal.org/project/ai/issues/3542496" title="Status: Needs work">#3542496: Dispatch AiExceptionEvent when a provider throws an exception</a>). Add a new event class that carries the original exception and an overridable message, preserving the exception class when a subscriber rewrites the text so existing <code>catch (AiQuotaException $e)</code> blocks keep working: <pre><div class="codeblock"><code class="language-php">namespace Drupal\ai\Event; use Symfony\Contracts\EventDispatcher\Event; final class AiExceptionEvent extends Event {   private string $message;   public function __construct(     public readonly \Exception $exception,   ) {     $this->message = $exception->getMessage();   }   public function setMessage(string $message): void {     $this->message = $message;   }   /**    * Returns the exception that should be thrown by the proxy.    *    * The original exception type is preserved so callers keep their    * specific catch blocks (AiQuotaException, AiRateLimitException, ...).    * Only the message is swapped if a subscriber rewrote it.    */   public function getException(): \Exception {     if ($this->message === $this->exception->getMessage()) {       return $this->exception;     }     $class = get_class($this->exception);     return new $class($this->message, $this->exception->getCode(), $this->exception);   } }Dispatch it in <code>ProviderProxy::wrapperCall()</code>, inside the existing <code>try/catch</code> block, for every caught exception type. Dispatch by class (no event-name string), consistent with the MR !846 review discussion: <pre><div class="codeblock"><code class="language-php">catch (\Throwable $e) {   $event = new AiExceptionEvent($e);   $this->eventDispatcher->dispatch($event);   // Handled-response path - see Part B.   if ($forced = $event->getForcedOutputObject()) {     return $forced;   }   throw $event->getException(); }Move the existing per-type <code>$this->loggerFactory->get('ai')->error(...)</code> calls out of <code>ProviderProxy</code> and into an event subscriber on <code>AiExceptionEvent</code> so logging behaviour is extensible too. Part B — Allow subscribers to replace the response (failover). Add a forced-output slot on the event, mirroring <code>PreGenerateResponseEvent</code>: <pre><div class="codeblock"><code class="language-php">// On AiExceptionEvent. use Drupal\ai\OperationType\OutputInterface; protected ?OutputInterface $forcedOutputObject = NULL; public function getForcedOutputObject(): ?OutputInterface {   return $this->forcedOutputObject; } public function setForcedOutputObject(OutputInterface $output): void {   $this->forcedOutputObject = $output; }If a subscriber called <code>setForcedOutputObject()</code>, the proxy returns that output instead of throwing. If no subscriber sets one, behaviour is identical to Part A alone: rethrow with the (possibly rewritten) message. This is the minimum surface that lets a third-party module implement graceful failover - for example, a module that sees an <code>AiQuotaException</code> on <code>openai</code> can call a backup provider via <code>AiProviderPluginManager</code>, build an <code>OutputInterface</code> from the response, and set it on the event; the original caller receives a successful response and never sees an exception. Part C — Preserve the request context on the event. For failover to be useful, subscribers need to know which provider/model/input failed. Extend the constructor: <pre><div class="codeblock"><code class="language-php">public function __construct(   public readonly \Exception $exception,   public readonly ?string $requestThreadId = NULL,   public readonly ?string $providerId = NULL,   public readonly ?string $operationType = NULL,   public readonly ?string $modelId = NULL,   public readonly mixed $input = NULL,   public readonly array $configuration = [],   public readonly array $tags = [], ) { ... }<code>ProviderProxy::wrapperCall()</code> already has all of these in scope at the point of dispatch (it constructs <code>PreGenerateResponseEvent</code> from them a few lines earlier). All new arguments are nullable / defaulted so existing instantiations, including test fixtures, keep working. Example: a failover subscriber in a third-party module. With Parts A-C in place, a module can implement provider failover without patching AI core: <pre><div class="codeblock"><code class="language-php">namespace Drupal\my_failover\EventSubscriber; use Drupal\ai\AiProviderPluginManager; use Drupal\ai\Event\AiExceptionEvent; use Drupal\ai\Exception\AiQuotaException; use Drupal\ai\Exception\AiRateLimitException; use Drupal\ai\OperationType\Chat\ChatInput; use Symfony\Component\EventDispatcher\EventSubscriberInterface; final class FailoverSubscriber implements EventSubscriberInterface {   public function __construct(     private readonly AiProviderPluginManager $aiProvider,   ) {}   public static function getSubscribedEvents(): array {     return [AiExceptionEvent::class => 'onException'];   }   public function onException(AiExceptionEvent $event): void {     // Only failover on quota/rate-limit, and only for chat.     if (!($event->exception instanceof AiQuotaException         || $event->exception instanceof AiRateLimitException)) {       return;     }     if ($event->operationType !== 'chat' || !$event->input instanceof ChatInput) {       return;     }     // Avoid looping if the backup itself threw.     if ($event->providerId === 'anthropic') {       return;     }     $backup = $this->aiProvider->createInstance('anthropic');     $output = $backup->chat($event->input, 'claude-3-5-sonnet-latest', $event->tags);     $event->setForcedOutputObject($output);   } }The caller of the original <code>chat()</code> call receives the backup provider's response and is unaware anything failed. Backwards compatibility. Part A only changes the thrown exception when a subscriber rewrites the message; even then, the class is identical, so existing <code>catch (AiQuotaException $e)</code> keeps working. With no subscriber, behaviour is byte-for-byte identical to current code. Part B adds one optional behaviour (forced output) which is a no-op unless opted into. Part C adds constructor arguments that are all optional, so <code>new AiExceptionEvent($e)</code> remains a valid call. No existing callers of <code>ProviderProxy</code> need to change. Why one issue instead of two. Parts A and B touch the same three lines of <code>ProviderProxy::wrapperCall()</code> and the same event class. Splitting them means landing an event that has a known missing capability (no way to recover gracefully), then landing a follow-up that rewrites what just landed. Landing together also means the tests cover the interaction (subscriber rewrites the message and sets a forced output - the output wins, the message is irrelevant), which isn't exercised if the two land separately. Two MRs: 1.x preserves the original exception class, 2.0.x wraps in <code>AiResponseErrorException</code>. The rethrow behaviour is deliberately different on the two branches: <ul> <li>1.x MR - keep the exact current behaviour: the thrown exception is the same class as the original (<code>AiQuotaException</code>, <code>AiRateLimitException</code>, etc.), with only the message swapped when a subscriber rewrites it. This preserves byte-for-byte compatibility for every site currently using <code>catch (AiQuotaException $e)</code> and friends in 1.x.</li> <li>2.0.x MR - normalise the rethrow into a single <code>AiResponseErrorException</code> that wraps the original exception as its <code>$previous</code>. Callers that care about the specific cause use <code>$e->getPrevious()</code> to reach the original <code>AiQuotaException</code> / <code>AiRateLimitException</code> / etc. This lets callers write one <code>catch (AiResponseErrorException $e)</code> for all provider-side failures while still being able to branch on the underlying class when needed. It also means the rewritten-message path no longer has to reconstruct the original exception class by reflection - the wrapper is always the same type, and the original is available untouched via <code>getPrevious()</code>. This is a breaking change, which is why it ships in 2.0.x only.</li> </ul> Both MRs share the event class, forced-output slot, and context properties. The only divergence is in <code>ProviderProxy::wrapperCall()</code>'s rethrow statement and in <code>AiExceptionEvent::getException()</code>. Tests split accordingly: the 1.x MR asserts the caller sees the original class; the 2.0.x MR asserts the caller sees <code>AiResponseErrorException</code> with <code>getPrevious()</code> returning the original. Remaining tasks: <ul> <li>Implement <code>AiExceptionEvent</code> with message, forced-output, and context properties (Parts A + B + C).</li> <li>Update <code>ProviderProxy::wrapperCall()</code> to dispatch, honour forced output, and rethrow with the event's exception.</li> <li>Move per-type logging from <code>ProviderProxy</code> into <code>Drupal\ai\EventSubscriber\AiExceptionLoggingSubscriber</code> and register it in <code>ai.services.yml</code>.</li> <li>Unit test: subscriber that rewrites the message - assert the caller sees the rewritten text and the original exception class.</li> <li>Unit test: subscriber that sets a forced output - assert the caller receives the output and no exception is thrown.</li> <li>Unit test: no subscriber - assert current behaviour is unchanged (exception and message both untouched).</li> <li>Kernel test covering each exception type currently handled in <code>wrapperCall()</code>: <code>AiBadRequestException</code>, <code>AiResponseErrorException</code>, <code>AiMissingFeatureException</code>, <code>AiQuotaException</code>, <code>AiRateLimitException</code>, <code>AiUnsafePromptException</code>, <code>AiRequestErrorException</code>, plus the generic <code>\Exception</code> catch.</li> <li>Update <code>docs/developers/events.md</code> with an example of a failover subscriber.</li> <li>Close <a href="https://www.drupal.org/project/ai/issues/3542496" title="Status: Needs work">#3542496: Dispatch AiExceptionEvent when a provider throws an exception</a> as duplicate/supersede, link this issue from MR !846.</li> </ul> API changes: <ul> <li>New public class <code>Drupal\ai\Event\AiExceptionEvent</code> with the properties and methods above. Dispatched by class from <code>ProviderProxy::wrapperCall()</code>.</li> <li>Internal refactor: logging messages previously emitted directly from <code>ProviderProxy</code> move into an event subscriber. Text and log channel remain identical, so log parsers are unaffected.</li> <li>No UI change.</li> </ul> This issue supersedes / combines <a href="https://www.drupal.org/project/ai/issues/3542496" title="Status: Needs work">#3542496: Dispatch AiExceptionEvent when a provider throws an exception</a> with the extension needed for third-party modules to implement failover. <h3 id="summary-ai-usage">AI usage (if applicable)</h3> [x] AI Assisted Issue This issue was generated with AI assistance, but was reviewed and refined by the creator. [ ] AI Assisted Code [ ] AI Generated Code [ ] Vibe Coded - This issue was created with the help of AI </code></div></pre></code></div></pre></code></div></pre></code></div></pre></code></div></pre>

issue