<?php

declare(strict_types=1);

namespace Drupal\native_observability\Service;

/**
 * Defines storage operations for request traces.
 *
 * We keep a small interface to:
 * - Support alternative backends later (e.g. syslog, file, external DB).
 * - Keep controllers/subscriber decoupled from the implementation details.
 */
interface TraceStorageInterface {

  /**
   * Inserts a trace record into storage.
   *
   * @param array $trace
   *   Normalized trace data ready to be persisted.
   *
   * @return int
   *   The primary key ID of the inserted trace record.
   */
  public function insert(array $trace): int;

  /**
   * Loads a trace by primary key.
   *
   * @param int $id
   *   Trace storage primary key.
   *
   * @return array|null
   *   The trace record as associative array, or NULL if not found.
   */
  public function load(int $id): ?array;

  /**
   * Searches traces using filter conditions (MVP set).
   *
   * Supported filters:
   * - status_code (int)
   * - path (string, contains match)
   * - min_duration_ms (int)
   * - max_duration_ms (int)
   *
   * @param array $filters
   *   Filters array.
   * @param int $limit
   *   Max results per page.
   * @param int $offset
   *   Offset for pagination.
   *
   * @return array
   *   List of trace rows.
   */
  public function search(array $filters, int $limit = 50, int $offset = 0): array;

  /**
   * Counts the total number of traces matching filters.
   *
   * @param array $filters
   *   Same filter format as ::search().
   *
   * @return int
   *   Total count.
   */
  public function count(array $filters): int;

  /**
   * Deletes all stored traces.
   *
   * @return int
   *   Number of deleted rows.
   */
  public function deleteAll(): int;

  /**
   * Loads a trace record by its request correlation id.
   *
   * @param string $request_id
   *   The correlation request id (e.g., ULID).
   *
   * @return array|null
   *   The trace record array, or NULL if not found.
   */
  public function loadByRequestId(string $request_id): ?array;

  /**
   * Loads the most recent trace row for the given request_id.
   *
   * @param string $request_id
   *   Correlation identifier (ULID/UUID).
   *
   * @return array|null
   *   The trace row as an associative array, or NULL if not found.
   */
  public function loadLatestByRequestId(string $request_id): ?array;

}
