snapshot

type CocoonRunner interface {
	// Export runs `cocoon snapshot export <name> -o -` and returns a reader
	// for the resulting tar stream plus a wait function the caller invokes
	// once the stream is fully consumed.
	Export(ctx context.Context, name string) (io.ReadCloser, func() error, error)

	// Import runs `cocoon snapshot import <name>` (with optional --description)
	// and returns a writer for the tar stream plus a wait function. The caller
	// closes the writer to signal end-of-stream and then calls wait.
	Import(ctx context.Context, opts ImportOptions) (io.WriteCloser, func() error, error)
}

type Downloader interface {
	GetManifest(ctx context.Context, name, tag string) ([]byte, string, error)
	GetBlob(ctx context.Context, name, digest string) (io.ReadCloser, error)
}

type ExecCocoon struct {
	// Binary is the resolved cocoon binary path. Use [ResolveCocoonBinary]
	// to populate it from $EPOCH_COCOON_BINARY or $PATH.
	Binary string
	// Stderr receives the cocoon subprocess stderr. Defaults to os.Stderr
	// when nil.
	Stderr io.Writer
}

type ImportOptions struct {
	Name        string
	Description string
}

type PullOptions struct {
	// Name is the OCI repository name. Required.
	Name string
	// Tag is the OCI tag. Defaults to "latest".
	Tag string
	// LocalName overrides the cocoon-side snapshot name on import.
	// Empty means reuse Name.
	LocalName string
	// Description is forwarded to `cocoon snapshot import --description`.
	Description string
	// Progress receives one-line status updates. May be nil.
	Progress func(string)
}

type Puller struct {
	Downloader Downloader
	Cocoon     CocoonRunner
}

type PushOptions struct {
	// Name is the OCI repository name. Required.
	Name string
	// Tag is the OCI tag. Defaults to "latest".
	Tag string
	// BaseImage is the optional cocoonstack.snapshot.baseimage annotation
	// value (an OCI ref like "ghcr.io/cocoonstack/cocoon/ubuntu:24.04").
	// When empty the annotation is omitted.
	BaseImage string
	// Source identifies the producer in the manifest annotations
	// (org.opencontainers.image.source). Optional.
	Source string
	// Revision is the org.opencontainers.image.revision annotation. Optional.
	Revision string
	// Progress receives one-line status updates. May be nil.
	Progress func(string)
}

type PushResult struct {
	Name           string
	Tag            string
	ManifestDigest string // sha256:<hex>
	ManifestBytes  []byte
	TotalSize      int64
	LayerCount     int
}

type Pusher struct {
	Uploader Uploader
	Cocoon   CocoonRunner
}

type StreamOptions struct {
	// Name is the OCI repository name used to fetch layer blobs. Required.
	Name string
	// LocalName overrides the snapshot name written into the rebuilt
	// snapshot.json envelope. Empty falls back to Name so the importer
	// reuses the registry repository name.
	LocalName string
	// Writer is the destination for the cocoon-import-shaped tar stream.
	// Required.
	Writer io.Writer
	// Progress receives one-line status updates per layer. May be nil.
	Progress func(string)
}

type Uploader interface {
	BlobExists(ctx context.Context, name, digest string) (bool, error)
	PutBlob(ctx context.Context, name, digest string, body io.Reader, size int64) error
	PutManifest(ctx context.Context, name, tag string, data []byte, contentType string) error
}