snapshots

type Accessor interface {
	MetadataStore

	Get(ctx context.Context, id string, opts ...RefOption) (ImmutableRef, error)
	GetBySnapshotID(ctx context.Context, snapshotID string, opts ...RefOption) (ImmutableRef, error)
	Scratch(ctx context.Context) (ImmutableRef, error)

	New(ctx context.Context, parent ImmutableRef, opts ...RefOption) (MutableRef, error)
	GetMutable(ctx context.Context, id string, opts ...RefOption) (MutableRef, error) // Rebase?
	GetMutableBySnapshotID(ctx context.Context, snapshotID string, opts ...RefOption) (MutableRef, error)
	ImportImage(ctx context.Context, img *ImportedImage, opts ImportImageOpts) (ImmutableRef, error)
	ImportChain(ctx context.Context, chain *ExportChain) (ImmutableRef, error)
	ApplySnapshotDiff(ctx context.Context, lower, upper ImmutableRef, opts ...RefOption) (ImmutableRef, error)
	Merge(ctx context.Context, parents []ImmutableRef, opts ...RefOption) (ImmutableRef, error)
}

type ChainContentError struct {
	Layer digest.Digest
	Stage string
	Err   error
}

type ChainWork struct {
	Begin func(ctx context.Context, i int) context.Context
	End   func(i int, blobBytes int64, err error)
}

type Diff struct {
	Lower      string
	Upper      string
	Comparison fsdiff.Comparison
}

type ExportChain struct {
	Layers []ExportLayer
	// Prefixes maps each snapshot the export walked, from the root to the
	// exported one, to the number of Layers that rebuild it: the layers
	// emitted up to and including it. A snapshot that added no layer maps to
	// the prefix before it, and a scratch root to none.
	Prefixes map[string]int
	Provider content.InfoReaderProvider
	// Await, when set, is how the blobs of ImportChain's layers arrive, with
	// no Provider: each layer the engine hasn't imported yet waits for Await
	// to return before taking its blob from the content store, and nothing
	// is downloaded ahead. Await returns once the blob is in the content
	// store. A layer that waits holds no import lock, and stops waiting, its
	// Await's context canceled, once another import has imported it.
	Await func(ctx context.Context, desc ocispecs.Descriptor) error
	// Timing, when set, receives where ImportChain's time went.
	Timing *ImportTiming
	// Applied, when set, is told of each layer ImportChain applies itself,
	// with the snapshot it committed, while it still holds the layer's
	// import lock: before any other import can reuse the snapshot.
	Applied func(ctx context.Context, desc ocispecs.Descriptor, snapshotID string)
	// Stats are what exporting the chain took.
	Stats ExportStats
	// contains filtered or unexported fields
}

type ExportLayer struct {
	Descriptor  ocispecs.Descriptor
	Description string
	CreatedAt   *time.Time
	// Computed is set when the export computed the layer's blob: it diffed
	// and compressed the layer's snapshot, or converted the snapshot's
	// stored blob to the export's compression. It is clear when the export
	// used a blob that already existed, such as a pulled image layer's or
	// one an earlier export computed.
	Computed bool
}

type ExportStats struct {
	// Layers counts the layers emitted.
	Layers int
	// LayersReused counts the layers whose blob already existed, and
	// LayersDiffed those whose blob was computed.
	LayersReused int
	LayersDiffed int
	// RawBytes is the on-disk usage of the diffed layers' snapshots, and
	// BlobBytes the size of the blobs computed from them.
	RawBytes  int64
	BlobBytes int64
	// DiffTime is computing the diffed layers' blobs: reading the mounts,
	// archiving, compressing and writing the content. Layers that build at
	// once each add their own, so it can exceed the export's wall time.
	DiffTime time.Duration
	// LockWait is the wait for the per-snapshot export lock, held by another
	// export of the same layer.
	LockWait time.Duration
	// BuildWait is the wait for a build slot, shared with other exports, to
	// build the diffed layers' blobs.
	BuildWait time.Duration
	// LayersMerged counts the diffed layers whose snapshot carries the
	// merge-usage label: a merge, a diff application, or a copy committed with
	// its usage (CommitWithUsage). The Merged sums are their share of
	// RawBytes, BlobBytes and DiffTime.
	LayersMerged    int
	MergedRawBytes  int64
	MergedBlobBytes int64
	MergedDiffTime  time.Duration
}

type ImmutableRef interface {
	Ref
	ExportChain(ctx context.Context, cfg config.RefConfig) (*ExportChain, error)
	// ExportFileChain exports the file at filePath in the ref's filesystem
	// as a chain of its own content.
	ExportFileChain(ctx context.Context, cfg config.RefConfig, filePath string) (*ExportChain, error)
}

type ImportImageOpts struct {
	ImageRef   string
	RecordType client.UsageRecordType
}

type ImportTiming struct {
	// LayerWait is the wait for the per-layer import lock, held by another
	// import of the same layer onto the same parent, or of the same layers.
	LayerWait time.Duration
	// Fetch is getting blobs into the content store: reading them, writing
	// and verifying them, and committing them. A reused layer adds nothing.
	Fetch time.Duration
	// Apply is applying the fetched blobs to their snapshots.
	Apply time.Duration
	// Ahead counts the blobs whose download started early, while the layer
	// before them applied, and Joined the layers whose blob came from a
	// download another import had in progress.
	Ahead  int
	Joined int
	// Packed counts the layers whose blob the import got with its pack's:
	// read, joined, or held from an earlier read.
	Packed int
}

type ImportedImage struct {
	Ref          string
	ManifestDesc ocispecs.Descriptor
	ConfigDesc   ocispecs.Descriptor
	Layers       []ocispecs.Descriptor
	Nonlayers    []ocispecs.Descriptor
}

type ImportedLayerBlobKey struct {
	ParentSnapshotID string
	BlobDigest       digest.Digest
}

type ImportedLayerBlobRow struct {
	ParentSnapshotID string
	BlobDigest       digest.Digest
	SnapshotID       string
}

type ImportedLayerDiffKey struct {
	ParentSnapshotID string
	DiffID           digest.Digest
}

type ImportedLayerDiffRow struct {
	ParentSnapshotID string
	DiffID           digest.Digest
	SnapshotID       string
}

type LeaseManager struct {
	// contains filtered or unexported fields
}

type LeaseRef struct {
	// contains filtered or unexported fields
}

type LocalMounterOpt func(*localMounter)

type MergeSnapshotter interface {
	Snapshotter
	Merge(ctx context.Context, key string, diffs []Diff, opts ...snapshots.Opt) error
}

type MetadataStore interface {
	Search(context.Context, string, bool) ([]RefMetadata, error)
}

type Mountable interface {
	Mount(ctx context.Context, readonly bool) (MountableRef, error)
}

type MountableRef = executor.MountableRef

type Mounter interface {
	Mount() (string, error)
	Unmount() error
}

type MutableRef interface {
	Ref
	Commit(context.Context) (ImmutableRef, error)
	CommitWithUsage(context.Context, snapshots.Usage) (ImmutableRef, error)
	InvalidateSize(context.Context) error
}

type PackProvider interface {
	// PackOf returns the ID of the pack that holds blob, if one does.
	PackOf(blob digest.Digest) (digest.Digest, bool)
	// OpenPack opens the whole pack that holds blob.
	OpenPack(ctx context.Context, blob digest.Digest) (io.ReadCloser, error)
}

type PersistentMetadataRows struct {
	SnapshotContent []SnapshotContentRow
	ImportedByBlob  []ImportedLayerBlobRow
	ImportedByDiff  []ImportedLayerDiffRow
	ContentHashes   []SnapshotContentHashRow
}

type ProgressTracker struct {
	// contains filtered or unexported fields
}

type ReadOnlyMountReleaser interface {
	// ReleaseIdleSharedMounts releases the shared read-only mounts nobody is
	// using, so that garbage collection can reclaim the snapshots their
	// views held. It returns once they are released.
	ReleaseIdleSharedMounts() error
	// WaitForBackgroundReleases releases the shared read-only mounts nobody
	// is using and waits for the releases running in the background, such
	// as before the metadata DBs close. Mounts released later are released
	// on their callers' paths, and are no longer shared.
	WaitForBackgroundReleases()
}

type Ref interface {
	Mountable
	ID() string
	SnapshotID() string
	Release(context.Context) error
	Size(context.Context) (int64, error)
}

type RefMetadata interface {
	ID() string
	SnapshotID() string

	GetDescription() string
	SetDescription(string) error

	GetCreatedAt() time.Time
	SetCreatedAt(time.Time) error

	GetLayerType() string
	SetLayerType(string) error

	GetRecordType() client.UsageRecordType
	SetRecordType(client.UsageRecordType) error

	// generic getters/setters for external packages
	GetString(string) string
	Get(string) *Value
	SetString(key, val, index string) error

	GetExternal(string) ([]byte, error)
	SetExternal(string, []byte) error

	ClearValueAndIndex(string, string) error
}

type RefOption interface{}

type SharedMounter interface {
	// MountShared returns the root of the snapshot's shared read-only mount
	// and the mount it came from. release ends this reader's use of it; it
	// must be called once.
	MountShared(ctx context.Context) (root string, m mount.Mount, release func(), err error)
	// SharedMountTopLayer returns the directory of the snapshot's topmost
	// layer, if a shared mount of the snapshot has been made and that is still
	// remembered. A regular file there is the file the snapshot shows, whatever
	// the layers below hold, so a reader of it needs no mount. The directory
	// may be gone by the time it is read, if the snapshot is; a reader that
	// doesn't find its file there has learned nothing and uses MountShared.
	SharedMountTopLayer() (dir string, ok bool)
}

type SnapshotContentHashRow struct {
	SnapshotID string
	Data       []byte
}

type SnapshotContentRow struct {
	SnapshotID string
	Digest     digest.Digest
}

type SnapshotManager interface {
	Accessor
	PinSnapshot(context.Context, string) (ImmutableRef, error)
	LeaseExistingSnapshot(context.Context, string) (ImmutableRef, error)
	SnapshotSize(ctx context.Context, snapshotID string) (int64, error)
	// SnapshotParent returns the snapshot's parent ID, or "" for a base
	// snapshot. Owner leases retain the whole parent chain.
	SnapshotParent(ctx context.Context, snapshotID string) (string, error)
	SnapshotRecordMetadata(ctx context.Context, snapshotID string) (SnapshotRecordMetadata, bool, error)
	AttachLease(ctx context.Context, leaseID, snapshotID string) error
	RemoveLease(ctx context.Context, leaseID string) error
	PinContent(ctx context.Context, leaseID string, descs []ocispecs.Descriptor) error
	// LoadPersistentMetadata takes ownership of the content-hash data buffers.
	// Callers must not modify them after loading.
	LoadPersistentMetadata(rows PersistentMetadataRows) error
	PersistentMetadataRows() PersistentMetadataRows
	DeleteStaleDaggerOwnerLeases(ctx context.Context, keep map[string]struct{}) error
	Close() error
}

type SnapshotManagerOpt struct {
	Snapshotter  Snapshotter
	ContentStore content.Store
	LeaseManager leases.Manager
	Applier      diff.Applier
	// ApplyFrom, when set, returns an applier like Applier that reads blobs
	// from provider instead of the content store. A chain import uses it to
	// apply a layer from its blob decompressed ahead; nil applies the stored
	// blob with Applier.
	ApplyFrom     func(provider content.Provider) diff.Applier
	Differ        diff.Comparer
	MountPoolRoot string
	// BuiltinContent is the engine's builtin image store, consulted by
	// chain imports for a layer blob before the chain's provider. Nil means
	// no such store.
	BuiltinContent content.InfoReaderProvider
	// MetadataDB is the containerd metadata database behind LeaseManager.
	// When set, AttachLease makes its lease writes in one transaction.
	MetadataDB metadata.Transactor
	// LocalMounter mounts a snapshot's mounts on a local directory for
	// shared read-only mounts; nil means LocalMounterWithMounts. Tests use
	// one that needs no privileges.
	LocalMounter func([]mount.Mount) Mounter
	// SharedMountLinger and MaxIdleSharedMounts bound the shared read-only
	// mounts nobody is using that are kept; zero means
	// DefaultSharedMountLinger and DefaultMaxIdleSharedMounts.
	SharedMountLinger   time.Duration
	MaxIdleSharedMounts int
}

type SnapshotRecordMetadata struct {
	RecordType  client.UsageRecordType
	Description string
}

type Snapshotter interface {
	Name() string
	Mounts(ctx context.Context, key string) (MountableRef, error)
	Prepare(ctx context.Context, key, parent string, opts ...snapshots.Opt) error
	View(ctx context.Context, key, parent string, opts ...snapshots.Opt) (MountableRef, error)

	Stat(ctx context.Context, key string) (snapshots.Info, error)
	Update(ctx context.Context, info snapshots.Info, fieldpaths ...string) (snapshots.Info, error)
	Usage(ctx context.Context, key string) (snapshots.Usage, error)
	Commit(ctx context.Context, name, key string, opts ...snapshots.Opt) error
	Remove(ctx context.Context, key string) error
	Walk(ctx context.Context, fn snapshots.WalkFunc, filters ...string) error
	Close() error
}

type Value struct {
	Value json.RawMessage `json:"value,omitempty"`
	Index string          `json:"index,omitempty"`
}