fileservice

type Cache interface {
	Read(
		ctx context.Context,
		vector *IOVector,
	) error
	Update(
		ctx context.Context,
		vector *IOVector,
	) error
	Flush()
	CacheStats() *CacheStats
}

type CacheConfig struct {
	MemoryCapacity toml.ByteSize `toml:"memory-capacity"`
	DiskPath       string        `toml:"disk-path"`
	DiskCapacity   toml.ByteSize `toml:"disk-capacity"`
}

type CacheKey struct {
	Path   string
	Offset int64
	Size   int64
}

type CacheStats struct {
	NumRead int64
	NumHit  int64
}

type CachingFileService interface {
	FileService

	// FlushCache flushes cache
	FlushCache()

	// CacheStats returns cache statistics
	CacheStats() *CacheStats
}

type Config struct {
	// Name name of fileservice, describe what an instance of fileservice is used for
	Name string `toml:"name"`
	// Backend fileservice backend. [MEM|DISK|DISK-ETL|S3|MINIO]
	Backend string `toml:"backend"`
	// S3 used to create fileservice using s3 as the backend
	S3 S3Config `toml:"s3"`
	// Cache specifies configs for cache
	Cache CacheConfig `toml:"cache"`
	// DataDir used to create fileservice using DISK as the backend
	DataDir string `toml:"data-dir"`
}

type DirEntry struct {
	// file name, not full path
	Name  string
	IsDir bool
	Size  int64
}

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

type ETLFileService interface {
	FileService

	// ETLCompatible marks the implementation to be compatible to ETL operations
	// implementations must save file contents as-is
	ETLCompatible()
}

type FileLike interface {
	io.ReadWriteSeeker
	io.WriterAt
	io.ReaderAt
}

type FileService interface {
	// Name is file service's name
	// service name is case-insensitive
	Name() string

	// Write writes a new file
	// returns ErrFileExisted if file already existed
	// returns ErrSizeNotMatch if provided size does not match data
	// entries in vector should be written atomically. if write failed, following reads must not succeed.
	Write(ctx context.Context, vector IOVector) error

	// Read reads a file to fill IOEntries
	// returns ErrFileNotFound if requested file not found
	// returns ErrUnexpectedEOF if less data is read than requested size
	// returns ErrEmptyRange if no data at specified offset and size
	// returns ErrEmptyVector if no IOEntry is passed
	Read(ctx context.Context, vector *IOVector) error

	// List lists sub-entries in a dir
	List(ctx context.Context, dirPath string) ([]DirEntry, error)

	// Delete deletes multi file
	// returns ErrFileNotFound if requested file not found
	Delete(ctx context.Context, filePaths ...string) error

	// Stat returns infomations about a file
	// returns ErrFileNotFound if requested file not found
	StatFile(ctx context.Context, filePath string) (*DirEntry, error)
}

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

type FileWithChecksum[T FileLike] struct {
	// contains filtered or unexported fields
}

type IOEntry struct {
	// offset in file
	// when writing or mutating, offset can be arbitrary value, gaps between provided data are zero-filled
	// when reading, valid offsets are in range [0, len(file) - 1]
	Offset int64

	// number of bytes to read or write, [1, len(file)]
	// when reading, pass -1 to read to the end of file
	Size int64

	// raw content
	// when reading, if len(Data) < Size, a new Size-lengthed byte slice will be allocated
	Data []byte

	// when reading, if Writer is not nil, write data to it instead of setting Data field
	WriterForRead io.Writer

	// when reading, if ReadCloser is not nil, set an io.ReadCloser instead of setting Data field
	ReadCloserForRead *io.ReadCloser

	// when writing, if Reader is not nil, read data from it instead of reading Data field
	// number of bytes to be read is specified by Size field
	// if number of bytes is unknown, set Size field to -1
	ReaderForWrite io.Reader

	// when reading, if the ToObject field is not nil, the returning object will be set to this field
	// caches may choose to cache this object instead of caching []byte
	// Data, WriterForRead, ReadCloserForRead may be empty if Object is not null
	// if ToObject is provided, caller should always read Object instead of Data, WriterForRead or ReadCloserForRead
	Object any

	// ToObject constructs an object from entry contents
	// reader or data must not be retained after returns
	// reader always contains entry contents
	// data may contains entry contents if available
	// if data is empty, the io.Reader must be fully read before returning nil error
	// return an *RC value to make the object pinnable
	// cache implementations should not evict an *RC value with non-zero reference
	ToObject func(reader io.Reader, data []byte) (object any, objectSize int64, err error)

	// ObjectSize indicates the memory bytes to hold the object
	// set from ToObject returning value
	// used in capacity limited caches
	ObjectSize int64
	// contains filtered or unexported fields
}

type IOVector struct {
	// FilePath indicates where to find the file
	// a path has two parts, service name and file name, separated by ':'
	// service name is optional, if omitted, the receiver FileService will use the default name of the service
	// file name parts are separated by '/'
	// valid characters in file name: 0-9 a-z A-Z / ! - _ . * ' ( )
	// and all printable non-ASCII characters
	// example:
	// s3:a/b/c S3:a/b/c represents the same file 'a/b/c' located in 'S3' service
	FilePath string
	// io entries
	// empty Entries is not allowed
	// when writing, overlapping Entries is not allowed
	Entries []IOEntry
	// ExpireAt specifies the expire time of the file
	// implementations may or may not delete the file after this time
	// zero value means no expire
	ExpireAt time.Time
}

type LRU struct {
	sync.Mutex
	// contains filtered or unexported fields
}

type LocalETLFS struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

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

type LocalFS struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

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

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

type MemoryFS struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

type MutableFileService interface {
	FileService

	// NewMutator creates a new mutator
	NewMutator(filePath string) (Mutator, error)
}

type Mutator interface {

	// Mutate mutates file contents
	Mutate(ctx context.Context, entries ...IOEntry) error

	// Append appends data to file
	// all IOEntry.Offset is base on the end of file position
	// for example, passing IOEntry{Offset: 0, Len:1, Data: []byte("a")} will append "a" to the end of file
	Append(ctx context.Context, entries ...IOEntry) error

	// Close closes the mutator
	// Must be called after finishing mutation
	Close() error
}

type NewFileServicesFunc = func(defaultName string) (*FileServices, error)

type Path struct {
	Service          string
	ServiceArguments []string
	File             string
}

type RC[T any] struct {
	Value T
	// contains filtered or unexported fields
}

type ReplaceableFileService interface {
	FileService

	Replace(ctx context.Context, vector IOVector) error
}

type S3Config struct {
	SharedConfigProfile string `toml:"shared-config-profile"`
	Endpoint            string `toml:"endpoint"`
	Bucket              string `toml:"bucket"`
	// KeyPrefix enables multiple fs instances in one bucket
	KeyPrefix string `toml:"key-prefix"`
}

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