<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Drupal\ffmpeg_media\ValueObject\VideoInfo;

/**
 * Interface for caching FFprobe results.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface FFprobeCacheServiceInterface {

  /**
   * Default cache TTL in seconds (1 hour).
   */
  public const int DEFAULT_TTL = 3600;

  /**
   * Cache bin name.
   */
  public const string CACHE_BIN = 'ffmpeg_media_ffprobe';

  /**
   * Gets cached video info for a file URI.
   *
   * @param string $uri
   *   The file URI (e.g., 'public://videos/example.mp4').
   *
   * @return \Drupal\ffmpeg_media\ValueObject\VideoInfo|null
   *   Cached VideoInfo or NULL if not cached.
   */
  #[\NoDiscard]
  public function get(string $uri): ?VideoInfo;

  /**
   * Caches video info for a file URI.
   *
   * @param string $uri
   *   The file URI.
   * @param \Drupal\ffmpeg_media\ValueObject\VideoInfo $info
   *   The video info to cache.
   * @param int|null $ttl
   *   Optional TTL in seconds. Uses default if NULL.
   */
  public function set(string $uri, VideoInfo $info, ?int $ttl = NULL): void;

  /**
   * Invalidates cached video info for a file URI.
   *
   * @param string $uri
   *   The file URI.
   */
  public function invalidate(string $uri): void;

  /**
   * Invalidates all cached FFprobe results.
   */
  public function invalidateAll(): void;

  /**
   * Gets or computes video info, using cache when available.
   *
   * @param string $uri
   *   The file URI.
   * @param callable $callback
   *   Callback that computes VideoInfo if not cached.
   *   Signature: fn(string $uri): ?VideoInfo.
   *
   * @return \Drupal\ffmpeg_media\ValueObject\VideoInfo|null
   *   VideoInfo from cache or computed result.
   */
  #[\NoDiscard]
  public function getOrCompute(string $uri, callable $callback): ?VideoInfo;

  /**
   * Gets cached video info by file hash.
   *
   * Useful when the same file exists at different URIs.
   *
   * @param string $hash
   *   The file hash (e.g., MD5 or SHA256).
   *
   * @return \Drupal\ffmpeg_media\ValueObject\VideoInfo|null
   *   Cached VideoInfo or NULL if not cached.
   */
  #[\NoDiscard]
  public function getByHash(string $hash): ?VideoInfo;

  /**
   * Caches video info by file hash.
   *
   * @param string $hash
   *   The file hash.
   * @param \Drupal\ffmpeg_media\ValueObject\VideoInfo $info
   *   The video info to cache.
   * @param int|null $ttl
   *   Optional TTL in seconds.
   */
  public function setByHash(string $hash, VideoInfo $info, ?int $ttl = NULL): void;

}
