<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\Enum\HardwareType;
use Drupal\ffmpeg_media\ValueObject\ConversionOptions;
use Drupal\ffmpeg_media\ValueObject\ConversionResult;
use Drupal\ffmpeg_media\ValueObject\ConversionContext;
use Drupal\file\FileInterface;
use Drupal\media\MediaInterface;

/**
 * Handles conversion lifecycle events (start, success, failure).
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface ConversionLifecycleHandlerInterface {

  /**
   * Dispatches the conversion started event and initializes progress.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionOptions $conversionOptions
   *   Conversion options.
   * @param string $sourcePath
   *   Source file path.
   * @param array<int, string> $outputFormats
   *   List of output format names.
   */
  public function dispatchStarted(
    MediaInterface $media,
    ConversionOptions $conversionOptions,
    string $sourcePath,
    array $outputFormats,
  ): void;

  /**
   * Dispatches the conversion completed event.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionResult $result
   *   Conversion result.
   */
  public function dispatchCompleted(
    MediaInterface $media,
    ConversionResult $result,
  ): void;

  /**
   * Handles successful conversion completion.
   *
   * Records hardware encoding success and schedules original file retention.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionResult $result
   *   Conversion result.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionContext $context
   *   Conversion context.
   * @param \Drupal\file\FileInterface|null $sourceFile
   *   Original source file, if available.
   * @param \Drupal\ffmpeg_media\Enum\HardwareType|null $hwType
   *   Current hardware type for circuit breaker recording.
   */
  public function handleSuccess(
    MediaInterface $media,
    ConversionResult $result,
    ConversionContext $context,
    ?FileInterface $sourceFile,
    ?HardwareType $hwType = NULL,
  ): void;

  /**
   * Finalizes a successful conversion.
   *
   * Combines dispatchCompleted() and handleSuccess() into a single call to
   * eliminate temporal coupling at the call site.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionResult $result
   *   Conversion result.
   * @param \Drupal\ffmpeg_media\ValueObject\ConversionContext $context
   *   Conversion context.
   * @param \Drupal\file\FileInterface|null $sourceFile
   *   Original source file, if available.
   * @param \Drupal\ffmpeg_media\Enum\HardwareType|null $hwType
   *   Current hardware type for circuit breaker recording.
   */
  public function finalizeSuccess(
    MediaInterface $media,
    ConversionResult $result,
    ConversionContext $context,
    ?FileInterface $sourceFile,
    ?HardwareType $hwType = NULL,
  ): void;

  /**
   * Handles conversion failure.
   *
   * Records hardware encoding failure, updates progress, removes from queue,
   * logs the error, and dispatches failure event.
   *
   * @param \Drupal\media\MediaInterface $media
   *   Media entity.
   * @param string $error
   *   Error message.
   * @param \Throwable|null $exception
   *   Exception if any.
   * @param \Drupal\ffmpeg_media\Enum\HardwareType|null $hwType
   *   Current hardware type for circuit breaker recording.
   * @param string $fieldName
   *   Conversion source field name.
   */
  public function handleFailure(
    MediaInterface $media,
    string $error,
    ?\Throwable $exception = NULL,
    ?HardwareType $hwType = NULL,
    string $fieldName = '',
  ): void;

}
