mithril-go/internal/aggregator/client.go

// Package aggregator is a thin HTTP client for the Mithril aggregator REST API.
//
// Only the 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: 120 * time.Second},
	}
}

// CardanoDBSnapshot is the server shape for /artifact/cardano-database and its
// /{hash} detail endpoint. The list response omits {digests,immutables,ancillary};
// only the detail endpoint populates them.
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"`
	CardanoNodeVersion      string        `json:"cardano_node_version"`
	CreatedAt               time.Time     `json:"created_at"`
	Digests                 DigestsBlock  `json:"digests"`
	Immutables              ImmutsBlock   `json:"immutables"`
	Ancillary               AncillaryBlock `json:"ancillary"`
}

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

type DigestsBlock struct {
	SizeUncompressed uint64     `json:"size_uncompressed"`
	Locations        []Location `json:"locations"`
}

type ImmutsBlock struct {
	AverageSizeUncompressed uint64     `json:"average_size_uncompressed"`
	Locations               []Location `json:"locations"`
}

type AncillaryBlock struct {
	SizeUncompressed uint64     `json:"size_uncompressed"`
	Locations        []Location `json:"locations"`
}

// Location is a polymorphic URI holder. The Mithril API ships URI as either
// a plain string (for single artifacts) or as {"Template": "..."} for
// templated per-file URIs (immutables only).
type Location struct {
	Type                 string    `json:"type"`
	URI                  URIHolder `json:"uri"`
	CompressionAlgorithm string    `json:"compression_algorithm,omitempty"`
}

// URIHolder absorbs both string and templated-object URI shapes.
type URIHolder struct {
	Plain    string
	Template string
}

func (h *URIHolder) UnmarshalJSON(b []byte) error {
	// Try plain string first
	var s string
	if err := json.Unmarshal(b, &s); err == nil {
		h.Plain = s
		return nil
	}
	// Fall back to {"Template": "..."}
	var t struct {
		Template string `json:"Template"`
	}
	if err := json.Unmarshal(b, &t); err == nil {
		h.Template = t.Template
		return nil
	}
	return fmt.Errorf("unrecognized URI shape: %s", string(b))
}

// String returns whichever URI form is populated.
func (h URIHolder) String() string {
	if h.Template != "" {
		return h.Template
	}
	return h.Plain
}

// Certificate is the server-reported shape for /certificate/{hash}.
// Kept wide — STM verification consumes raw bytes separately from the decoded view.
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("GET %s: %w", path, err)
	}
	defer resp.Body.Close()
	if resp.StatusCode >= 400 {
		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
		return fmt.Errorf("GET %s: %d: %s", path, resp.StatusCode, string(body))
	}
	if out == nil {
		return nil
	}
	return json.NewDecoder(resp.Body).Decode(out)
}

func (c *Client) ListCardanoDBSnapshots(ctx context.Context) ([]CardanoDBSnapshot, error) {
	var out []CardanoDBSnapshot
	return out, c.get(ctx, "/artifact/cardano-database", &out)
}

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
}

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
}

// CertChain walks previous_hash backwards from headHash until it hits the
// first certificate that carries a genesis_signature. Returns the chain
// ordered head-first. Caller can invert if root-first is preferred.
//
// The chain length is usually 1-3 certs per epoch boundary; an unbounded
// walk would be a footgun so it caps at maxDepth.
func (c *Client) CertChain(ctx context.Context, headHash string, maxDepth int) ([]*Certificate, error) {
	if maxDepth <= 0 {
		maxDepth = 1024
	}
	var chain []*Certificate
	next := headHash
	for i := 0; i < maxDepth; i++ {
		if next == "" {
			return nil, fmt.Errorf("chain broke at depth %d: no previous_hash", i)
		}
		cert, err := c.GetCertificate(ctx, next)
		if err != nil {
			return nil, fmt.Errorf("depth %d (%s): %w", i, next, err)
		}
		chain = append(chain, cert)
		if cert.GenesisSignature != "" {
			return chain, nil
		}
		next = cert.PreviousHash
	}
	return nil, fmt.Errorf("cert chain exceeded max depth %d without reaching genesis", maxDepth)
}