<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for cleaning up orphaned streaming segment directories.
 *
 * Handles cleanup of HLS/DASH segment files and directories that remain
 * after failed or abandoned conversions.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface SegmentCleanupServiceInterface {

  /**
   * Default segment directory age threshold in seconds (24 hours).
   */
  public const int DEFAULT_SEGMENT_CLEANUP_AGE = 86400;

  /**
   * Default thumbnail/preview age threshold in seconds (6 hours).
   */
  public const int DEFAULT_THUMBNAIL_CLEANUP_AGE = 21600;

  /**
   * Cleans up orphaned segment directories for failed/abandoned conversions.
   *
   * Scans both legacy layout ({mediaId}/{format}/) and field-scoped layout
   * ({mediaId}/{fieldName}/{format}/) under the output directory. Removes
   * directories older than the configured age threshold when the associated
   * conversion is in a failed or abandoned state.
   *
   * @param int $maxAge
   *   Maximum age in seconds before orphaned segments are cleaned up.
   *
   * @return int
   *   Number of segment directories cleaned up.
   */
  public function cleanupOrphanedSegments(int $maxAge = self::DEFAULT_SEGMENT_CLEANUP_AGE): int;

  /**
   * Cleans up segment directories for a specific media entity.
   *
   * When a field name is provided, only that field's segment directories
   * are removed (preventing cross-field data loss). When empty, scans both
   * legacy layout ({mediaId}/{format}/) and all field-scoped layouts.
   *
   * @param int $mediaId
   *   The media entity ID.
   * @param string $fieldName
   *   Source field name. When non-empty, only cleans segments for that
   *   field. When empty, cleans all field and legacy segments.
   *
   * @return bool
   *   TRUE if any segments were cleaned up.
   */
  public function cleanupSegmentsForMedia(int $mediaId, string $fieldName = ''): bool;

  /**
   * Cleans up orphaned FFmpeg temporary working directories.
   *
   * FFmpeg creates temporary files (two-pass log files, intermediate
   * files) that can be left behind when a conversion crashes. This
   * method removes temp directories under the output directory that
   * are older than the specified age threshold.
   *
   * @param int $maxAge
   *   Maximum age in seconds before temp directories are cleaned up.
   *
   * @return int
   *   Number of temp directories cleaned up.
   */
  public function cleanupOrphanedTempFiles(int $maxAge = self::DEFAULT_SEGMENT_CLEANUP_AGE): int;

  /**
   * Cleans up orphaned thumbnail session directories.
   *
   * Scans both private://ffmpeg_media/thumbnails/ and
   * public://ffmpeg_media/thumbnails/ to handle the migration period where
   * files may exist in either location. Removes directories older than the
   * specified age threshold.
   *
   * @param int $maxAge
   *   Maximum age in seconds before orphaned thumbnails are cleaned up.
   *
   * @return int
   *   Number of thumbnail directories cleaned up.
   */
  public function cleanupOrphanedThumbnails(int $maxAge = self::DEFAULT_THUMBNAIL_CLEANUP_AGE): int;

  /**
   * Cleans up orphaned preview image files.
   *
   * Scans both private://ffmpeg_media/previews/ and
   * public://ffmpeg_media/previews/ to handle the migration period where
   * files may exist in either location. Removes files older than the
   * specified age threshold.
   *
   * @param int $maxAge
   *   Maximum age in seconds before orphaned previews are cleaned up.
   *
   * @return int
   *   Number of preview files cleaned up.
   */
  public function cleanupOrphanedPreviews(int $maxAge = self::DEFAULT_THUMBNAIL_CLEANUP_AGE): int;

}
