git.stella-ops.org/src/BinaryIndex/__Libraries/StellaOps.Symbols.Client/ISymbolsClient.cs

using StellaOps.Symbols.Core.Models;

namespace StellaOps.Symbols.Client;

/// <summary>
/// Client interface for the Symbols service.
/// </summary>
public interface ISymbolsClient
{
    /// <summary>
    /// Uploads a symbol manifest to the server.
    /// </summary>
    Task<SymbolManifestUploadResult> UploadManifestAsync(
        SymbolManifest manifest,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a manifest by ID.
    /// </summary>
    Task<SymbolManifest?> GetManifestAsync(
        string manifestId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets manifests by debug ID.
    /// </summary>
    Task<IReadOnlyList<SymbolManifest>> GetManifestsByDebugIdAsync(
        string debugId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Resolves addresses to symbols.
    /// </summary>
    Task<IReadOnlyList<SymbolResolutionResult>> ResolveAsync(
        string debugId,
        IEnumerable<ulong> addresses,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Resolves a single address to a symbol.
    /// </summary>
    Task<SymbolResolutionResult?> ResolveAddressAsync(
        string debugId,
        ulong address,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Queries manifests with filters.
    /// </summary>
    Task<SymbolManifestQueryResult> QueryManifestsAsync(
        SymbolManifestQuery query,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets service health status.
    /// </summary>
    Task<SymbolsHealthStatus> GetHealthAsync(CancellationToken cancellationToken = default);
}

/// <summary>
/// Result of manifest upload.
/// </summary>
public sealed record SymbolManifestUploadResult
{
    public required string ManifestId { get; init; }
    public required string DebugId { get; init; }
    public required string BinaryName { get; init; }
    public string? BlobUri { get; init; }
    public required int SymbolCount { get; init; }
    public required DateTimeOffset CreatedAt { get; init; }
}

/// <summary>
/// Result of symbol resolution.
/// </summary>
public sealed record SymbolResolutionResult
{
    public required ulong Address { get; init; }
    public required bool Found { get; init; }
    public string? MangledName { get; init; }
    public string? DemangledName { get; init; }
    public ulong Offset { get; init; }
    public string? SourceFile { get; init; }
    public int? SourceLine { get; init; }
    public double Confidence { get; init; }
}

/// <summary>
/// Query parameters for manifest search.
/// </summary>
public sealed record SymbolManifestQuery
{
    public string? DebugId { get; init; }
    public string? CodeId { get; init; }
    public string? BinaryName { get; init; }
    public string? Platform { get; init; }
    public BinaryFormat? Format { get; init; }
    public DateTimeOffset? CreatedAfter { get; init; }
    public DateTimeOffset? CreatedBefore { get; init; }
    public bool? HasDsse { get; init; }
    public int Offset { get; init; }
    public int Limit { get; init; } = 50;
}

/// <summary>
/// Result of manifest query.
/// </summary>
public sealed record SymbolManifestQueryResult
{
    public required IReadOnlyList<SymbolManifestSummary> Manifests { get; init; }
    public required int TotalCount { get; init; }
    public required int Offset { get; init; }
    public required int Limit { get; init; }
}

/// <summary>
/// Summary of a symbol manifest.
/// </summary>
public sealed record SymbolManifestSummary
{
    public required string ManifestId { get; init; }
    public required string DebugId { get; init; }
    public string? CodeId { get; init; }
    public required string BinaryName { get; init; }
    public string? Platform { get; init; }
    public required BinaryFormat Format { get; init; }
    public required int SymbolCount { get; init; }
    public required bool HasDsse { get; init; }
    public required DateTimeOffset CreatedAt { get; init; }
}

/// <summary>
/// Symbols service health status.
/// </summary>
public sealed record SymbolsHealthStatus
{
    public required string Status { get; init; }
    public required string Version { get; init; }
    public required DateTimeOffset Timestamp { get; init; }
    public long? TotalManifests { get; init; }
    public long? TotalSymbols { get; init; }
}