<?php

declare(strict_types=1);

namespace Drupal\native_observability_spans\Service;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

/**
 * Provides optional request summary enrichment payloads for synthetic spans.
 *
 * Implementations are expected to be lightweight and fail-safe.
 * The returned payload is merged into the synthetic request summary span.
 */
interface RequestSummaryEnrichmentProviderInterface {

  /**
   * Builds additional request summary payload data.
   *
   * @param \Symfony\Component\HttpFoundation\Request $request
   *   The current main request.
   * @param \Symfony\Component\HttpFoundation\Response $response
   *   The final response for the current request.
   *
   * @return array
   *   A structured payload fragment to merge into the synthetic request span.
   *   Implementations should return an empty array when no enrichment is
   *   available for the current request.
   */
  public function buildRequestSummaryPayload(Request $request, Response $response): array;

}
