<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;

/**
 * Resolves effective access policy for public health probe endpoints.
 *
 * @internal
 */
interface HealthProbeAccessManagerInterface {

  /**
   * Determines whether the current or provided probe request is authorized.
   *
   * @param \Symfony\Component\HttpFoundation\Request|null $request
   *   The request to authorize. When omitted, the current request is used.
   *
   * @return bool
   *   TRUE when probe access is authorized, FALSE otherwise.
   */
  public function isAccessAuthorized(?Request $request = NULL): bool;

  /**
   * Builds the standardized JSON response for denied probe access.
   *
   * @param \Symfony\Component\HttpFoundation\Request|null $request
   *   The denied request. When omitted, the current request is used.
   *
   * @return \Symfony\Component\HttpFoundation\JsonResponse
   *   The denied response payload.
   */
  public function buildAccessDeniedResponse(?Request $request = NULL): JsonResponse;

}
