<?php

declare(strict_types=1);

namespace Drupal\native_observability\Service;

/**
 * Defines a cleanup handler for observability data retention.
 */
interface ObservabilityCleanupHandlerInterface {

  /**
   * Returns the unique cleanup handler identifier.
   *
   * @return string
   *   The cleanup handler identifier.
   */
  public function id(): string;

  /**
   * Indicates whether the cleanup handler is currently available.
   *
   * A handler may be unavailable when the related submodule is disabled or
   * when the underlying storage table does not exist.
   *
   * @return bool
   *   TRUE when cleanup can be executed safely, FALSE otherwise.
   */
  public function isAvailable(): bool;

  /**
   * Executes cleanup logic and returns the number of deleted records.
   *
   * @param array $settings
   *   Cleanup settings relevant to the handler.
   *
   * @return int
   *   Number of deleted records.
   */
  public function cleanup(array $settings): int;

  /**
   * Executes a full forced cleanup.
   *
   * @return int
   *   Number of deleted records.
   */
  public function cleanupAll(): int;

}
