type Attr struct {
	// Size, for regular files, is the logical size of the file.
	Size int64

	// ModTime is the modification time of the node.
	ModTime time.Time

	// LinkName, for symlinks, is the link target.
	LinkName string

	// Mode is the permission and mode bits.
	Mode os.FileMode

	// UID is the user ID of the owner.
	UID int

	// GID is the group ID of the owner.
	GID int

	// DevMajor is the major device number for device.
	DevMajor int

	// DevMinor is the major device number for device.
	DevMinor int

	// Xattrs are the extended attribute for the node.
	Xattrs map[string][]byte

	// NumLink is the number of names pointing to this node.
	NumLink int
}

type Decompressor interface {
	estargz.Decompressor

	// DecompressTOC decompresses the passed blob and returns a reader of TOC JSON.
	//
	// If tocOffset returned by ParseFooter is < 0, we assume that TOC isn't contained in the blob.
	// Pass nil reader to DecompressTOC then we expect that DecompressTOC acquire TOC from the external
	// location and return it.
	DecompressTOC(io.Reader) (tocJSON io.ReadCloser, err error)
}

type File interface {
	ChunkEntryForOffset(offset int64) (off int64, size int64, dgst string, ok bool)
	ReadAt(p []byte, off int64) (n int, err error)
}

type MeasureLatencyHook func(time.Time)

type Option func(o *Options) error

type Options struct {
	TOCOffset     int64
	Telemetry     *Telemetry
	Decompressors []Decompressor
}

type Reader interface {
	RootID() uint32
	TOCDigest() digest.Digest

	GetOffset(id uint32) (offset int64, err error)
	GetAttr(id uint32) (attr Attr, err error)
	GetChild(pid uint32, base string) (id uint32, attr Attr, err error)
	ForeachChild(id uint32, f func(name string, id uint32, mode os.FileMode) bool) error
	OpenFile(id uint32) (File, error)
	OpenFileWithPreReader(id uint32, preRead func(id uint32, chunkOffset, chunkSize int64, chunkDigest string, r io.Reader) error) (File, error)

	Clone(sr *io.SectionReader) (Reader, error)
	Close() error
}

type Store func(sr *io.SectionReader, opts ...Option) (Reader, error)

type Telemetry struct {
	GetFooterLatency      MeasureLatencyHook // measure time to get stargz footer (in milliseconds)
	GetTocLatency         MeasureLatencyHook // measure time to GET TOC JSON (in milliseconds)
	DeserializeTocLatency MeasureLatencyHook // measure time to deserialize TOC JSON (in milliseconds)
}