<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media_image\Service;

/**
 * Tracks temporary private image URIs that need entity-based download access.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface TemporaryFileAccessManagerInterface {

  /**
   * Registers a temporary private URI for entity-scoped download access.
   *
   * Re-registering the same URI merges media IDs so shared thumbnail caches can
   * still be served to users who can view any related media entity.
   *
   * @param string $uri
   *   The temporary file URI.
   * @param int $mediaId
   *   The related media entity ID.
   * @param string $fileMime
   *   The file MIME type.
   * @param int $ttl
   *   Time to live in seconds.
   */
  public function registerUri(
    string $uri,
    int $mediaId,
    string $fileMime = 'image/jpeg',
    int $ttl = 3600,
  ): void;

  /**
   * Returns access metadata for a registered temporary URI.
   *
   * @param string $uri
   *   The temporary file URI.
   *
   * @return array{media_ids: list<int>, filemime: string}|null
   *   Access metadata, or NULL when the URI is not registered.
   */
  #[\NoDiscard]
  public function getAccessRecord(string $uri): ?array;

}
