// Package ipfs is the abstraction anchorage uses to reach its paired IPFS
// backend (currently Kubo over HTTP RPC; potentially embedded Kubo or
// ipfs-cluster later). Everything above this layer works in terms of the
// Backend interface so swapping implementations needs no touch anywhere
// else.
package ipfs

import (
	"context"
	"errors"
)

// ErrNotFound is the canonical "CID isn't pinned / doesn't exist" sentinel.
var ErrNotFound = errors.New("ipfs: not found")

// PinStatus reports the backend's view of a single CID.
type PinStatus struct {
	CID    string
	Pinned bool
	// Type is the backend-reported pin kind ("recursive" for full DAG
	// pins, "direct" for shallow, "indirect" for transitive children).
	Type string
}

// Backend is the operation surface anchorage uses against its paired
// IPFS daemon. Implementations must be safe for concurrent use.
type Backend interface {
	// Pin instructs the backend to hold the given CID. Idempotent.
	// Origins may be passed as peer multiaddrs the backend should try
	// first for bitswap (spec: PinAddRequest.origins).
	Pin(ctx context.Context, cid string, origins []string) error

	// Unpin instructs the backend to drop the pin. Idempotent.
	Unpin(ctx context.Context, cid string) error

	// Status reports whether the CID is locally pinned and how.
	Status(ctx context.Context, cid string) (*PinStatus, error)

	// List returns every CID currently pinned locally. Used by the
	// reconciler to diff against Postgres.
	List(ctx context.Context) ([]string, error)

	// ID returns the backend's libp2p peer info, notably its multiaddrs.
	// anchorage uses this to populate the nodes.multiaddrs column if
	// the operator didn't pre-fill it in config.
	ID(ctx context.Context) (*IDInfo, error)
}

// IDInfo is the minimal view of /api/v0/id anchorage needs.
type IDInfo struct {
	PeerID    string
	Addresses []string
}