// -----------------------------------------------------------------------------
// RuntimeTracesEndpoints.cs
// Sprint: SPRINT_20260107_006_002_FE_diff_runtime_tabs
// Task: DR-014 — Runtime traces API endpoints
// -----------------------------------------------------------------------------

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;
using StellaOps.Findings.Ledger.WebService.Contracts;

namespace StellaOps.Findings.Ledger.WebService.Endpoints;

/// <summary>
/// API endpoints for runtime traces evidence.
/// </summary>
public static class RuntimeTracesEndpoints
{
    /// <summary>
    /// Maps runtime traces endpoints to the application.
    /// </summary>
    public static void MapRuntimeTracesEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/api/v1/findings")
            .WithTags("Runtime Evidence")
            .RequireAuthorization();

        // GET /api/v1/findings/{findingId}/runtime/traces
        group.MapGet("/{findingId:guid}/runtime/traces", GetRuntimeTraces)
            .WithName("GetRuntimeTraces")
            .WithDescription("Get runtime function traces for a finding")
            .Produces<RuntimeTracesResponse>(200)
            .Produces(404);

        // GET /api/v1/findings/{findingId}/runtime/score
        group.MapGet("/{findingId:guid}/runtime/score", GetRtsScore)
            .WithName("GetRtsScore")
            .WithDescription("Get Runtime Trustworthiness Score for a finding")
            .Produces<RtsScoreResponse>(200)
            .Produces(404);
    }

    /// <summary>
    /// Gets runtime function traces for a finding.
    /// </summary>
    private static async Task<Results<Ok<RuntimeTracesResponse>, NotFound>> GetRuntimeTraces(
        Guid findingId,
        IRuntimeTracesService service,
        CancellationToken ct,
        [FromQuery] int? limit = null,
        [FromQuery] string? sortBy = null)
    {
        var options = new RuntimeTracesQueryOptions
        {
            Limit = limit ?? 50,
            SortBy = sortBy ?? "hits"
        };

        var traces = await service.GetTracesAsync(findingId, options, ct);

        return traces is not null
            ? TypedResults.Ok(traces)
            : TypedResults.NotFound();
    }

    /// <summary>
    /// Gets the RTS score for a finding.
    /// </summary>
    private static async Task<Results<Ok<RtsScoreResponse>, NotFound>> GetRtsScore(
        Guid findingId,
        IRuntimeTracesService service,
        CancellationToken ct)
    {
        var score = await service.GetRtsScoreAsync(findingId, ct);

        return score is not null
            ? TypedResults.Ok(score)
            : TypedResults.NotFound();
    }
}

/// <summary>
/// Query options for runtime traces.
/// </summary>
public sealed record RuntimeTracesQueryOptions
{
    /// <summary>
    /// Maximum number of traces to return.
    /// </summary>
    public int Limit { get; init; } = 50;

    /// <summary>
    /// Sort by field (hits, recent).
    /// </summary>
    public string SortBy { get; init; } = "hits";
}

/// <summary>
/// Service for retrieving runtime traces.
/// </summary>
public interface IRuntimeTracesService
{
    /// <summary>
    /// Gets runtime traces for a finding.
    /// </summary>
    /// <param name="findingId">Finding identifier.</param>
    /// <param name="options">Query options.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>Runtime traces response or null if not found.</returns>
    Task<RuntimeTracesResponse?> GetTracesAsync(
        Guid findingId,
        RuntimeTracesQueryOptions options,
        CancellationToken ct);

    /// <summary>
    /// Gets RTS score for a finding.
    /// </summary>
    /// <param name="findingId">Finding identifier.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>RTS score response or null if not found.</returns>
    Task<RtsScoreResponse?> GetRtsScoreAsync(Guid findingId, CancellationToken ct);
}