mithril-go/internal/aggregator/client.go

// Package aggregator is a thin HTTP client for the Mithril aggregator REST API.
//
// Only the handful of endpoints needed for client-side snapshot workflows are
// exposed. Authentication is not required for the read paths used here.
package aggregator

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strings"
	"time"
)

type Client struct {
	baseURL string
	http    *http.Client
}

func New(baseURL string) *Client {
	return &Client{
		baseURL: strings.TrimRight(baseURL, "/"),
		http:    &http.Client{Timeout: 60 * time.Second},
	}
}

// CardanoDBSnapshot is the server-reported shape for /artifact/cardano-database/{hash}.
// Field set is trimmed to what the client actually consumes — full schema documented
// at https://mithril.network/doc/aggregator-api/.
type CardanoDBSnapshot struct {
	Hash                  string                   `json:"hash"`
	MerkleRoot            string                   `json:"merkle_root"`
	Network               string                   `json:"network"`
	Beacon                Beacon                   `json:"beacon"`
	CertificateHash       string                   `json:"certificate_hash"`
	TotalDBSizeUncompressed uint64                 `json:"total_db_size_uncompressed"`
	Digests               LocationList             `json:"digests"`
	ImmutablesAncillary   LocationList             `json:"immutables"`
	ImmutablesIncremental *IncrementalImmutables   `json:"immutables_incremental,omitempty"`
	CreatedAt             time.Time                `json:"created_at"`
}

type Beacon struct {
	Epoch           uint64 `json:"epoch"`
	ImmutableFileNumber uint64 `json:"immutable_file_number"`
}

type LocationList struct {
	Size      uint64       `json:"size"`
	Locations []LocationAlt `json:"locations"`
}

// LocationAlt is a best-of alternative; Mithril returns a typed-discriminated object.
type LocationAlt struct {
	Type string `json:"type"` // e.g. "cloud_storage", "ipfs"
	URI  string `json:"uri"`
}

type IncrementalImmutables struct {
	AverageSize uint64       `json:"average_size"`
	Locations   []LocationAlt `json:"locations"`
}

// Certificate is the server-reported shape for /certificate/{hash}.
// Kept minimal; STM verification reads what it needs from the raw JSON later.
type Certificate struct {
	Hash            string          `json:"hash"`
	PreviousHash    string          `json:"previous_hash"`
	Epoch           uint64          `json:"epoch"`
	SignedMessage   string          `json:"signed_message"`
	ProtocolMessage json.RawMessage `json:"protocol_message"`
	Multisignature  json.RawMessage `json:"multi_signature"`
	GenesisSignature string         `json:"genesis_signature,omitempty"`
}

func (c *Client) get(ctx context.Context, path string, out any) error {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+path, nil)
	if err != nil {
		return err
	}
	req.Header.Set("Accept", "application/json")
	resp, err := c.http.Do(req)
	if err != nil {
		return fmt.Errorf("aggregator GET %s: %w", path, err)
	}
	defer resp.Body.Close()
	if resp.StatusCode >= 400 {
		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
		return fmt.Errorf("aggregator GET %s: status %d: %s", path, resp.StatusCode, string(body))
	}
	if out == nil {
		return nil
	}
	return json.NewDecoder(resp.Body).Decode(out)
}

// ListCardanoDBSnapshots returns the sorted-newest-first list of cardano-database snapshots.
func (c *Client) ListCardanoDBSnapshots(ctx context.Context) ([]CardanoDBSnapshot, error) {
	var out []CardanoDBSnapshot
	if err := c.get(ctx, "/artifact/cardano-database", &out); err != nil {
		return nil, err
	}
	return out, nil
}

// GetCardanoDBSnapshot fetches details for a single snapshot by hash (or "latest").
func (c *Client) GetCardanoDBSnapshot(ctx context.Context, hash string) (*CardanoDBSnapshot, error) {
	var out CardanoDBSnapshot
	if err := c.get(ctx, "/artifact/cardano-database/"+url.PathEscape(hash), &out); err != nil {
		return nil, err
	}
	return &out, nil
}

// GetCertificate fetches a certificate by hash for signature verification.
func (c *Client) GetCertificate(ctx context.Context, hash string) (*Certificate, error) {
	var out Certificate
	if err := c.get(ctx, "/certificate/"+url.PathEscape(hash), &out); err != nil {
		return nil, err
	}
	return &out, nil
}