*/ private $stopped = array(); /** * Failures shared with the later runs of this process, keyed by provider * id, or provider id and model for a model failure. * * @var array */ private static $shared = array(); /** * The provider a request without an explicit provider resolved to (the * site default), so a later run can check it before its first call. * * @var string */ private static $defaultProvider = ''; /** * The model a request without an explicit model resolved to, per provider. * * @var array */ private static $defaultModels = array(); /** * Test seam: fn(): float, unix time with sub-second precision. * * @var callable|null */ private static $clock = null; /** * @param StructuredCallerInterface $inner The caller that reaches the provider. */ public function __construct( StructuredCallerInterface $inner ) { $this->inner = $inner; } /** * @param array $request See StructuredCallerInterface::call(). * @return array See StructuredCallerInterface::call(). */ public function call( array $request ): array { $requested = (string) ( $request['provider'] ?? '' ); $requested_model = (string) ( $request['model'] ?? '' ); $provider = '' !== $requested ? $requested : self::$defaultProvider; if ( '' !== $provider ) { $model = '' !== $requested_model ? $requested_model : ( self::$defaultModels[ $provider ] ?? '' ); $blocked = $this->stopped[ $provider ] ?? self::sharedFailure( $provider, $model ); if ( null !== $blocked ) { return array_merge( $blocked, array( 'calls' => 0, 'durationMs' => 0, ) ); } } $result = $this->inner->call( $request ); $resolved = (string) ( $result['provider'] ?? '' ); if ( '' !== $resolved ) { if ( '' === $requested ) { self::$defaultProvider = $resolved; } if ( '' === $requested_model && '' !== (string) ( $result['model'] ?? '' ) ) { self::$defaultModels[ $resolved ] = (string) $result['model']; } } $reason = is_array( $result['error'] ?? null ) ? (string) ( $result['error']['reason'] ?? '' ) : ''; if ( empty( $result['ok'] ) && '' !== $resolved && ProviderCallException::isRunWideReason( $reason ) ) { $this->stopped[ $resolved ] = $result; self::share( $resolved, (string) ( $result['model'] ?? '' ), $reason, $result ); } return $result; } /** * Forget every shared failure and learned default (tests, or a process * that starts over). Mirrors {@see \AIPT\Api\ProviderCircuit::reset()}. * * @return void */ public static function reset(): void { self::$shared = array(); self::$defaultProvider = ''; self::$defaultModels = array(); } /** * Test seam for the clock. * * @param callable|null $clock fn(): float, or null for the real clock. * @return void */ public static function useClock( ?callable $clock ): void { self::$clock = $clock; } /** * The shared failure that still blocks this provider and model, if any. * * @param string $provider Provider id. * @param string $model Model id ('' when unknown). * @return array|null The failed result, or null when a call may go out. */ private static function sharedFailure( string $provider, string $model ): ?array { foreach ( array( $provider, $provider . '|' . $model ) as $key ) { if ( ! isset( self::$shared[ $key ] ) ) { continue; } $until = self::$shared[ $key ]['until']; if ( null !== $until && self::now() >= $until ) { unset( self::$shared[ $key ] ); continue; } return self::$shared[ $key ]['result']; } return null; } /** * Remember a run-wide failure for the later runs of this process. * * @param string $provider Provider id. * @param string $model Model id the call used. * @param string $reason ProviderCallException reason. * @param array $result The failed result. * @return void */ private static function share( string $provider, string $model, string $reason, array $result ): void { $key = in_array( $reason, self::MODEL_REASONS, true ) ? $provider . '|' . $model : $provider; $until = in_array( $reason, self::TRANSIENT_REASONS, true ) ? self::now() + self::coolDownSeconds( is_array( $result['error'] ?? null ) ? $result['error']['retryAfter'] ?? null : null ) : null; self::$shared[ $key ] = array( 'result' => $result, 'until' => $until, ); } /** * The cool-down for a transient failure: the provider's own retry hint * when it gave one, else {@see self::COOL_DOWN_DEFAULT_SECONDS}, always * clamped between {@see self::COOL_DOWN_MIN_SECONDS} and * {@see self::COOL_DOWN_MAX_SECONDS} - a hint longer than the fixed 30 * seconds this used to always use must still be honored, and a shorter * one must not be stretched back out to 30. * * @param int|null $retry_after The provider's Retry-After hint, in seconds. * @return int */ private static function coolDownSeconds( ?int $retry_after ): int { $seconds = ( null !== $retry_after && $retry_after > 0 ) ? $retry_after : self::COOL_DOWN_DEFAULT_SECONDS; return max( self::COOL_DOWN_MIN_SECONDS, min( self::COOL_DOWN_MAX_SECONDS, $seconds ) ); } private static function now(): float { return null !== self::$clock ? (float) call_user_func( self::$clock ) : microtime( true ); } }