<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\file\FileInterface;
use Drupal\media\MediaInterface;

/**
 * Determines which queue a media item should be assigned to.
 *
 * Encapsulates queue routing by file size, max-size guards, legacy
 * dedup-marker checks, and source-field resolution. Internal to the
 * ffmpeg_media module.
 *
 * @internal
 */
interface QueueAssignmentServiceInterface {

  /**
   * Returns the queue name to use for the given file size.
   *
   * @param int $fileSize
   *   File size in bytes.
   *
   * @return string
   *   Queue name.
   */
  #[\NoDiscard]
  public function getQueueNameForSize(int $fileSize): string;

  /**
   * Returns the queue name to use for the given file entity.
   *
   * @param \Drupal\file\FileInterface $file
   *   The file entity.
   *
   * @return string
   *   Queue name.
   */
  #[\NoDiscard]
  public function getQueueForFile(FileInterface $file): string;

  /**
   * Returns the large-file threshold in bytes from config.
   *
   * @return int
   *   Threshold in bytes.
   */
  #[\NoDiscard]
  public function getLargeFileThreshold(): int;

  /**
   * Resolves the conversion context for the given media entity.
   *
   * Validates multi-formatter contexts and auto-detects the source field from
   * the media type when not explicitly provided. Returns the resolved media ID,
   * field name, and source file entity, or NULL if the media cannot be queued.
   *
   * @param \Drupal\media\MediaInterface $media
   *   The media entity.
   * @param string $fieldName
   *   The field name (empty string for auto-detection).
   *
   * @return array{media_id: int, field_name: string, source_file: \Drupal\file\FileInterface}|null
   *   The resolved context, or NULL if resolution failed.
   */
  #[\NoDiscard]
  public function resolveConversionContext(MediaInterface $media, string $fieldName): ?array;

  /**
   * Resolves the target queue for a file and validates preconditions.
   *
   * Checks that the file size does not exceed the configured maximum, that no
   * legacy media-wide dedup marker conflicts with a field-scoped insertion,
   * and returns the resolved queue name together with the file size.
   *
   * @param \Drupal\file\FileInterface $sourceFile
   *   The source file entity.
   * @param int $mediaId
   *   The media entity ID.
   * @param string $fieldName
   *   The resolved field name (empty string for legacy media-wide scope).
   *
   * @return array{queue_name: string, file_size: int}|null
   *   Resolved queue target, or NULL when the file cannot be queued.
   */
  #[\NoDiscard]
  public function resolveQueueTarget(FileInterface $sourceFile, int $mediaId, string $fieldName): ?array;

}
