<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for circuit breaker pattern implementation.
 *
 * The circuit breaker prevents repeated failures from overwhelming the system
 * by temporarily blocking requests to a failing service
 * (e.g., hardware encoder).
 *
 * States:
 * - CLOSED: Normal operation, requests pass through.
 * - OPEN: Too many failures, requests fail fast (skip hardware).
 * - HALF_OPEN: After timeout, allow one test request.
 *
 * @internal
 */
interface CircuitBreakerInterface {

  /**
   * Circuit state: Closed (normal operation).
   */
  public const string STATE_CLOSED = 'closed';

  /**
   * Circuit state: Open (failing fast).
   */
  public const string STATE_OPEN = 'open';

  /**
   * Circuit state: Half-open (testing recovery).
   */
  public const string STATE_HALF_OPEN = 'half-open';

  /**
   * Checks if the circuit is open for a service.
   *
   * When the circuit is open, callers should skip the operation
   * and use a fallback (e.g., software encoding instead of hardware).
   *
   * @param string $service
   *   Service identifier (e.g., 'nvenc', 'vaapi', 'qsv').
   *
   * @return bool
   *   TRUE if circuit is open (should skip), FALSE if requests should proceed.
   */
  #[\NoDiscard]
  public function isOpen(string $service): bool;

  /**
   * Records a successful operation for a service.
   *
   * In half-open state, successful operations help close the circuit.
   * In closed state, this resets the failure counter.
   *
   * @param string $service
   *   Service identifier.
   */
  public function recordSuccess(string $service): void;

  /**
   * Records a failed operation for a service.
   *
   * Increments the failure counter. When threshold is reached,
   * the circuit opens.
   *
   * @param string $service
   *   Service identifier.
   */
  public function recordFailure(string $service): void;

  /**
   * Gets the current state of the circuit for a service.
   *
   * @param string $service
   *   Service identifier.
   *
   * @return string
   *   One of STATE_CLOSED, STATE_OPEN, or STATE_HALF_OPEN.
   */
  #[\NoDiscard]
  public function getState(string $service): string;

  /**
   * Resets the circuit for a service to closed state.
   *
   * This clears all failure history and allows requests to proceed.
   *
   * @param string $service
   *   Service identifier.
   */
  public function reset(string $service): void;

  /**
   * Gets the failure count for a service.
   *
   * @param string $service
   *   Service identifier.
   *
   * @return int
   *   Number of consecutive failures.
   */
  #[\NoDiscard]
  public function getFailureCount(string $service): int;

  /**
   * Gets the time until circuit transitions from open to half-open.
   *
   * @param string $service
   *   Service identifier.
   *
   * @return int
   *   Seconds remaining, or 0 if not in open state.
   */
  #[\NoDiscard]
  public function getTimeUntilHalfOpen(string $service): int;

}
