disko

type BootCodeImplementer interface {
	// SetBootCode sets the machine code that is executed on startup if the disk
	// image is used as a boot volume. If the code provided is too short then
	// the implementation should pad it with bytes to fit. This is guaranteed to
	// be at most [FSFeatures.MaxBootCodeSize] bytes.
	SetBootCode(code []byte) DriverError

	// GetBootCode returns the machine code that is executed on startup.
	GetBootCode(buffer []byte) (int, DriverError)
}

type DirectoryEntry interface {
	os.DirEntry
	Stat() FileStat
}

type Driver interface {
	// NormalizePath converts a path from the user's native file system syntax
	// to an absolute normalized path using forward slashes (/) as the component
	// separator. The return value is always an absolute path. If the argument
	// is a relative path, it's computed relative to the working directory as
	// returned by [Driver.Getwd].
	NormalizePath(path string) string

	// GetFSFeatures returns a struct that gives the various features the file
	// system supports, regardless of whether the driver implements these
	// features or not.
	GetFSFeatures() FSFeatures

	Chdir(path string) error
	Chmod(name string, mode os.FileMode) error
	Chown(name string, uid, gid int) error
	Chtimes(name string, atime time.Time, mtime time.Time) error
	Create(path string) (File, error)
	Getwd() (string, error)
	Lchown(name string, uid, gid int) error
	Link(oldname, newname string) error
	Lstat(path string) (FileStat, error)
	Mkdir(path string, perm os.FileMode) error
	MkdirAll(path string, perm os.FileMode) error
	Open(path string) (File, error)
	OpenFile(path string, flags IOFlags, perm os.FileMode) (File, error)
	ReadDir(path string) ([]DirectoryEntry, error)
	ReadFile(path string) ([]byte, error)
	Readlink(path string) (string, error)
	Remove(path string) error
	RemoveAll(path string) error
	Rename(old string, new string) error
	SameFile(fi1, fi2 os.FileInfo) bool
	Stat(path string) (FileStat, error)
	Symlink(oldname, newname string) error
	Truncate(path string) error
	Unmount() error
	WriteFile(path string, data []byte, perm os.FileMode) error
}

type DriverError interface {
	error
	WithMessage(message string) DriverError
	Wrap(err error) DriverError
}

type FSFeatures struct {
	// DoesNotRequireFormatting is true if and only if a driver doesn't need to
	// format an image before use. This is mostly only used for archive formats.
	DoesNotRequireFormatting bool

	// HasDirectories indicates if the file system supports directories, but
	// makes no assertion as to whether any nesting is supported.
	HasDirectories   bool
	HasSymbolicLinks bool
	HasHardLinks     bool
	HasCreatedTime   bool
	HasAccessedTime  bool
	HasModifiedTime  bool
	HasChangedTime   bool
	HasDeletedTime   bool

	// HasUnixPermissions is true if the file system supports a permissions model
	// similar to user/group/other, read/write/execute model that Unix uses. The
	// file system does not need to support group permissions to set this.
	HasUnixPermissions bool

	HasUserPermissions  bool
	HasGroupPermissions bool
	HasUserID           bool
	HasGroupID          bool

	// TimestampEpoch returns the earliest representable timestamp on this file
	// system. File systems that don't support timestamps of any kind must set
	// this to [UndefinedTimestamp].
	TimestampEpoch time.Time

	// DefaultNameEncoding gives the name of the text encoding natively used by
	// the file system for directory and file names (not file contents!).
	//
	// This must be lowercase with no symbols (e.g. "utf8" not "UTF-8"). For
	// systems this old it will most likely be either "ascii" or "ebcdic".
	DefaultNameEncoding string
	SupportsBootCode    bool

	// MaxBootCodeSize gives the maximum number of bytes that can be stored as
	// boot code in the file system. File systems that don't support boot code
	// must return 0. File systems that don't have a theoretical upper limit
	// should set this to [math.MaxInt].
	MaxBootCodeSize int

	// DefaultBlockSize gives the default size of a single block in the file
	// system, in bytes. File systems that don't have fixed block sizes (such as
	// certain types of archives) must set this to 0.
	DefaultBlockSize int

	// MinTotalBlocks is the smallest possible size of the file system, in blocks.
	MinTotalBlocks int64

	// MaxTotalBlocks is the largest possible size of the file system, in blocks.
	MaxTotalBlocks int64

	// MaxVolumeLabelSize gives the maximum size of the volume label for the
	// file system, in bytes. If volume labels are not supported by the file
	// system, this should be 0. If there's no length limit, this should be
	// [math.MaxInt].
	MaxVolumeLabelSize int
}

type FSStat struct {
	// BlockSize is the size of a logical block on the file system, in bytes.
	BlockSize uint

	// TotalBlocks is the total number of blocks on the disk image.
	TotalBlocks uint64

	// BlocksFree is the number of unallocated blocks on the image.
	BlocksFree uint64

	// BlocksAvailable is the number of blocks available for use by user data.
	// This should always be less than or equal to [FSStat.BlocksFree].
	BlocksAvailable uint64

	// Files is the total number of used directory entries on the file system.
	// Implementations should return 0 if the information is not available.
	Files uint64

	// FilesFree is the number of remaining directory entries available for use.
	// Implementations should return [math.MaxUint64] for file systems that have
	// no limit on the maximum number of directory entries.
	FilesFree uint64

	// FileSystemID is the serial number for the disk image, if available.
	FileSystemID string

	// MaxNameLength is the longest possible name for a directory entry, in
	// bytes. Implementations should return [math.MaxUint] if there is no limit.
	MaxNameLength uint

	// Label is the volume label, if available.
	Label string
}

type File interface {
	io.ReadWriteCloser
	io.Seeker
	io.ReaderAt
	io.ReaderFrom
	io.WriterAt
	io.StringWriter
	common.Truncator

	Chdir() error
	Chmod(mode os.FileMode) error
	Chown(uid, gid int) error
	Name() string
	ReadDir(n int) ([]os.DirEntry, error)
	Readdir(n int) ([]os.FileInfo, error)
	Readdirnames(n int) ([]string, error)
	Stat() (os.FileInfo, error)
	Sync() error
}

type FileStat struct {
	DeviceID     uint64
	InodeNumber  uint64
	Nlinks       uint64
	ModeFlags    os.FileMode
	Uid          uint32
	Gid          uint32
	Rdev         uint64
	Size         int64
	BlockSize    int64
	NumBlocks    int64
	CreatedAt    time.Time
	LastChanged  time.Time
	LastAccessed time.Time
	LastModified time.Time
	DeletedAt    time.Time
}

type FileSystemImplementer interface {
	// Mount initializes the file system implementation with access settings.
	Mount(flags MountFlags) DriverError

	// Flush writes out all pending changes to the disk image. The file system
	// must be left in a valid state once this is finished. Files and file
	// handles *may* be open when this is called, so implementations must
	// ensure these remain in a usable state.
	//
	// This will only be called if [Mount] returned successfully.
	Flush() DriverError

	// Unmount writes out all pending changes to the disk image and releases any
	// resources the implementation may be holding.
	//
	// The following guarantees apply when this function is called:
	//
	//  - [Flush] will already have been called.
	//	- There will be no open files or other handles (directory traversers, etc.)
	//	  when this is called.
	Unmount() DriverError

	// CreateObject creates an object on the file system, such as a file or
	// directory. You can tell what it is based on the [os.FileMode] flags.
	//
	// The following guarantees apply when this function is called:
	//
	// 	- This will never be called for an object that already exists.
	//  - `parent` will always be a valid object handle.
	CreateObject(
		name string,
		parent ObjectHandle,
		perm os.FileMode,
	) (ObjectHandle, DriverError)

	// GetObject returns a handle to an object with the given name in a directory
	// specified by `parent`.
	//
	// The following guarantees apply when this function is called:
	//
	// 	- This will never be called for a nonexistent object.
	//	- `parent` will always be a valid object handle.
	GetObject(name string, parent ObjectHandle) (ObjectHandle, DriverError)

	// GetRootDirectory returns a handle to the root directory of the disk image.
	// This must always be a valid object handle, even if directories are not
	// supported by the file system (e.g. FAT8).
	GetRootDirectory() ObjectHandle

	// FSStat returns information about the file system. Multiple calls to this
	// function must return identical data if no modifications have been made
	// to the file system.
	FSStat() FSStat

	// GetFSFeatures returns a struct that gives the various features the file
	// system specification supports, regardless of whether this driver
	// implementation supports these features or not.
	//
	// The results are independent of the volume's contents, so this must always
	// return a valid value even if the volume isn't mounted or is corrupted.
	GetFSFeatures() FSFeatures
}

type FormatImageImplementer interface {
	// FormatImage creates a new blank file system on the image this was created
	// with, using characteristics defined in `options`.
	//
	// The following guarantees apply when this function is called:
	//
	//  - The image will already be correctly sized according to `options`.
	//  - It will consist entirely of null bytes.
	FormatImage(options disks.BasicFormatterOptions) DriverError
}

type HardLinkImplementer interface {
	// CreateHardLink creates a new file system object that is a hard link from
	// the source to the target.
	//
	// The following guarantees apply when this function is called:
	//
	//	- The target will not already exist.
	//	- `source` will never be a directory.
	//	- `targetParentDir` will always be an existing directory.
	//
	// A thoroug explanation for why hard links are disallowed for directories
	// can be found here: https://askubuntu.com/a/525129
	CreateHardLink(
		source ObjectHandle,
		targetParentDir ObjectHandle,
		targetName string,
	) (ObjectHandle, DriverError)
}

type IOFlags int

type ImplementerConstructor func(stream io.ReadWriteSeeker) (FileSystemImplementer, DriverError)

type MountFlags int

type ObjectHandle interface {
	// Stat returns information on the status of the file as it appears on disk.
	Stat() FileStat

	// Resize changes the size of the object, in bytes. Drivers are responsible
	// for ensuring the needed number of blocks are allocated or freed.
	Resize(newSize uint64) DriverError

	// ReadBlocks fills `buffer` with data from a sequence of logical blocks
	// beginning at `index`. The following guarantees apply when this function
	// is called:
	//
	//   - `buffer` is a nonzero multiple of the size of a block.
	//   - The read range will always be within the current boundaries of the
	//     object.
	ReadBlocks(index common.LogicalBlock, buffer []byte) DriverError

	// WriteBlocks writes bytes from `buffer` into a sequence of logical blocks
	// beginning at `index`. The following guarantees apply when this function
	// is called:
	//
	//   - `buffer` is a nonzero multiple of the size of a block.
	//   - The write range will always be within the current boundaries of the
	//     object.
	WriteBlocks(index common.LogicalBlock, data []byte) DriverError

	// ZeroOutBlocks tells the implementation to treat `count` logical blocks
	// beginning at `startIndex` as consisting entirely of null bytes (0). It
	// does not change the size of the object.
	//
	// Functionally, it's equivalent to:
	//
	//		buffer := make([]byte, BlockSize * NUM_BLOCKS)
	//		WriteBlocks(START_BLOCK, buffer)
	//
	// The following guarantees apply when this function is called:
	//
	//   - `count` is nonzero.
	//   - `[startIndex, startIndex + count)` will always be within the current
	//     boundaries of the object.
	//
	// Some file systems have optimizations for such "holes" that can save disk
	// space. It's up to the file system implementation to handle this case, as
	// well as consolidating holes where possible. The driver doesn't care what
	// the implementation does as long as a subsequent call to [ReadBlocks] on
	// this range returns all null bytes.
	ZeroOutBlocks(startIndex common.LogicalBlock, count uint) DriverError

	// Unlink deletes the file system object. For directories, this is guaranteed
	// to not be called unless [ListDir] returns an empty slice (aside from "."
	// and ".." if present, as the driver cannot assume these exist).
	Unlink() DriverError

	// Name returns the name of the object itself without any path component.
	// The root directory, which technically has no name, must return "/".
	Name() string

	// SameAs returns a boolean indicating if this object handle refers to the
	// same on-disk object as the given handle. A few rules:
	//
	//   - Attributes such as size, timestamps, number of links, etc. should be
	//     ignored. This is only comparing identity, not properties.
	//   - Symbolic links should not be dereferenced, so X and Y are not the same
	//     even if X is a symbolic link to Y.
	//   - Hard links are considered the same as the files they refer to.
	//
	// For a UNIX-like file system, this is equivalent to comparing the inumbers.
	SameAs(other ObjectHandle) bool

	// Close frees any resources associated with the handle, such as open file
	// descriptors or temporary directories. The handle cannot be used after
	// calling this method.
	//
	// 	- Closing a handle on a deleted object must not return an error.
	//	- Subsequent calls should return [disko.ErrFileDescriptorBadState].
	Close() error
}

type SupportsChmodHandle interface {
	// Chmod changes the permission bits of this file system object. Only the
	// permissions bits will be set in `mode`.
	//
	// File systems that support access controls but not all aspects (e.g. no
	// executable bit, or no group permissions) must silently ignore flags they
	// don't recognize.
	Chmod(mode os.FileMode) DriverError
}

type SupportsChownHandle interface {
	// Chown sets the ID of the owning user and group for this object. If the
	// file system doesn't support group IDs, implementations must silently
	// ignore `gid`, whatever its value.
	Chown(uid, gid int) DriverError
}

type SupportsChtimesHandle interface {
	// Chtimes changes various timestamps associated with an object. The driver
	// will do its best to ensure that unsupported timestamps are equal to
	// [UndefinedTimestamp], but the implementation must ignore timestamps it
	// doesn't support.
	//
	// The following guarantees apply when this function is called:
	//
	//  - Timestamps known to be unsupported (i.e. the corresponding feature in
	//    [FSFeatures] is false) will always be [UndefinedTimestamp].
	//  - `deletedAt` will only be set if the object has been deleted and the
	//    flag is supported by the file system.
	//
	// If a supported timestamp is passed in as [UndefinedTimestamp],
	// implementations should not modify the existing timestamp for the object.
	Chtimes(
		createdAt,
		lastAccessed,
		lastModified,
		lastChanged,
		deletedAt time.Time,
	) DriverError
}

type SupportsListDirHandle interface {
	// ListDir returns a list of the directory entries this object contains. "."
	// and ".." are ignored if present.
	ListDir() ([]string, DriverError)
}

type VolumeLabelImplementer interface {
	// SetVolumeLabel sets the volume label on the file system.
	//
	// `label` is guaranteed to be UTF-8 encoded. Implementations should convert
	// the string to the native character set if needed.
	//
	// To avoid nasty surprises, callers should try to stick to printable ASCII
	// characters and avoid non-punctuation symbols. This is because pre-1977
	// versions of the ASCII standard allowed some variance in how the same
	// character code could be depicted, e.g. `!` could also render as `|`.
	// (This is why on old keyboards the pipe character looks like `╎` to avoid
	// confusion.)
	// Thus, if you set the volume label to "(^_^)" you may get "(¬_¬)" when you
	// read it back -- a very different sentiment.
	SetVolumeLabel(label string) DriverError

	// GetVolumeLabel gets the volume label from the file system.
	//
	// The return value is guaranteed to be UTF-8 encoded. Implementations must
	// remove any padding from the return value, if applicable (and possible).
	GetVolumeLabel() (string, DriverError)
}