<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for metrics collection service.
 *
 * Collects and exposes metrics in Prometheus format for monitoring
 * video conversion performance, queue status, and hardware utilization.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface MetricsServiceInterface {

  /**
   * Gets all metrics in Prometheus text format.
   *
   * @param array<string, string> $labels
   *   Additional labels to apply to all metrics.
   *
   * @return string
   *   Metrics in Prometheus exposition format.
   */
  #[\NoDiscard]
  public function getPrometheusMetrics(array $labels = []): string;

  /**
   * Gets conversion metrics.
   *
   * @return array<string, mixed>
   *   Conversion statistics.
   */
  #[\NoDiscard]
  public function getConversionMetrics(): array;

  /**
   * Gets queue metrics.
   *
   * @return array<string, mixed>
   *   Queue statistics.
   */
  #[\NoDiscard]
  public function getQueueMetrics(): array;

  /**
   * Gets hardware acceleration metrics.
   *
   * @return array<string, mixed>
   *   Hardware acceleration statistics.
   */
  #[\NoDiscard]
  public function getHardwareMetrics(): array;

  /**
   * Gets system resource metrics.
   *
   * @return array{
   *   concurrent_conversions: int,
   *   max_concurrent: int,
   *   locks_held: int,
   *   ffmpeg_processes: int,
   *   }
   *   System resource statistics.
   */
  #[\NoDiscard]
  public function getSystemMetrics(): array;

  /**
   * Records a conversion completion for metrics.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param bool $success
   *   Whether the conversion succeeded.
   * @param float $durationSeconds
   *   Conversion duration in seconds.
   * @param string|null $codec
   *   Codec used.
   * @param string|null $outputFormat
   *   Output format used.
   * @param bool $hardwareAccelerated
   *   Whether hardware acceleration was used.
   */
  public function recordConversion(
    int $mediaId,
    bool $success,
    float $durationSeconds,
    ?string $codec = NULL,
    ?string $outputFormat = NULL,
    bool $hardwareAccelerated = FALSE,
  ): void;

  /**
   * Records a queue wait time for metrics.
   *
   * @param float $waitTimeSeconds
   *   Time spent waiting in queue.
   */
  public function recordQueueWait(float $waitTimeSeconds): void;

  /**
   * Records a hardware fallback event.
   *
   * @param string $encoder
   *   The encoder that failed.
   * @param string $reason
   *   Reason for fallback.
   */
  public function recordHardwareFallback(string $encoder, string $reason): void;

}
