fileio

type Chunk struct {
	Offset int64  // Offset into the file.
	Data   []byte // Data slab.
}

type CreateMode int

type Files interface {
	// Open a file for writing.
	OpenWriter(context.Context, string, WriteOptions) (Writer, error)

	// Write to a file.
	WriteFile(context.Context, string, []byte, WriteOptions) error

	// Append data to a file.
	AppendFile(context.Context, string, io.Reader, WriteOptions) (int64, error)

	// Remove a file.
	Remove(string) error

	// Rename a file.
	Rename(string, string) error

	// Create directory.
	//
	// If any directory in the path does not exist, then it will be
	// created.
	MkdirAll(string, os.FileMode) error
}

type FsyncPolicy int

type ReadOptions struct {
	// Maximum number of bytes to read.
	//
	// If this value is set to a negative number then it is interpreted
	// as "read an unlimited number of bytes".
	//
	// However "unlimited", in this case, equates to `math.MaxInt` bytes.
	//
	// The reason for this is that we return a slice of bytes, and the
	// maximum number of elements in a Go slice is `math.MaxInt`.
	//
	// The default value is 0.
	MaxReadBytes int64

	// Should symbolic links be followed?
	//
	// If false, then symbolic links are not followed.
	//
	// The default value is false.
	FollowSymlinks bool
}

type Reader interface {
	// The file name that we wish to load.
	Filename() string

	// Check whether the file exists.
	//
	// If the file exists, then `true` is returned along with no error.
	//
	// If the file does not exist, then `false` is returned along with
	// no error.
	//
	// If the file exists but is not a regular file, then false is
	// returned along with `ErrNotRegular`.
	//
	// If we are following symbolic links and the file exists and is
	// a symbolic link then it is resolved to the symbolic link's target
	// and, if that exists, `true` is returned along with no error.
	Exists() (bool, error)

	// Check if the file is a symbolic link.
	IsSymlink() (bool, error)

	// Read the file and return a byte array of its content.
	//
	// If `MaxReadBytes` in the options is zero then the number of bytes
	// read will be at most `math.MaxInt`.
	//
	// If `MaxReadBytes` in the options is higher than zero then the
	// number of bytes read will be at most `MaxReadBytes`.
	//
	// `MaxReadBytes` can never be negative and can never exceed
	// `math.MaxInt`.
	Load() ([]byte, error)

	// Open the file and return an `io.ReadCloser`.
	//
	// `MaxReadBytes` is ignored.
	Open() (io.ReadCloser, error)

	// Open the file and stream its contents to the specified writer.
	//
	// If `limit` is zero then the entire contents shall be copied.
	//
	// If `limit` is greater than zero, then at most `limit` bytes will
	// be copied.
	CopyTo(writer io.Writer, limit int64) (int64, error)

	// Stream chunks of up to `chunkSize` bytes.
	//
	// `bufSize` will utilise a readahead buffer of the given size.
	//
	// If `limit` is zero then the entirety of the content will be
	// streamed.
	//
	// if `chunkSize` is zero or lower then a default chunk size of
	// 64 * 1024 shall be used.
	Stream(ctx context.Context, chunkSize, bufSize int, limit int64) StreamResult
}

type StreamResult struct {
	ChunkCh <-chan Chunk // Channel for chunks.
	ErrorCh <-chan error // Channel for errors.
	Close   func()       // Cancel the stream.
	Wait    func() error // Wait for completion.
}

type WriteOptions struct {
	// File mode.
	//
	// Default is 0o644.
	Mode os.FileMode

	// File creation mode.
	//
	// Can be one of "truncate" or "append".
	CreateMode CreateMode

	// Create directories should they not exist?
	CreateDirs bool

	// Buffer size.
	//
	// If the value is zero, the value in`DefaultWriteBufferSize` shall
	// be used.
	BufferSize int

	// File sync policy.
	Fsync FsyncPolicy

	// Synchronise file every n writes.
	//
	// If zero, no syncs will be performed.
	FsyncEveryN int64

	// Context deadline.
	Timeout time.Duration
}

type Writer interface {
	io.WriteCloser

	// Perform a synchronisation.
	Sync() error

	// Number of bytes written.
	BytesWritten() int64

	// Name of the file to which we are writing.
	Name() string

	// Abort file writing.
	Abort() error
}