file

type Closer = ioctx.Closer

type ETagged interface {
	// ETag is an identifier assigned to a specific version of the file.
	ETag() string
}

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

type File interface {
	// String returns a diagnostic string.
	String() string

	// Name returns the path name given to file.Open or file.Create when this
	// object was created.
	Name() string

	// Stat returns file metadata.
	//
	// REQUIRES: Close has not been called
	Stat(ctx context.Context) (Info, error)

	// Reader creates an io.ReadSeeker object that operates on the file.  If
	// Reader() is called multiple times, they share the seek pointer.
	//
	// For emphasis: these share state, which is different from OffsetReader!
	//
	// REQUIRES: Close has not been called
	Reader(ctx context.Context) io.ReadSeeker

	// OffsetReader creates a new, independent ioctx.ReadCloser, starting at
	// offset. Unlike Reader, its position in the file is only modified by Read
	// on this object. The returned object is not thread-safe, and callers are
	// responsible for serializing all of their calls, including calling Close
	// after all Reads are done. Of course, callers can use separate
	// OffsetReaders in parallel.
	//
	// Background: This API reflects S3's performance characteristics, where
	// initiating a new read position is relatively expensive, but then
	// streaming data is fast (including in parallel with multiple readers).
	//
	// REQUIRES: Close has not been called
	OffsetReader(offset int64) ioctx.ReadCloser

	// Writer creates a writes that to the file. If Writer() is called multiple
	// times, they share the seek pointer.
	//
	// REQUIRES: Close has not been called
	Writer(ctx context.Context) io.Writer

	// Discard discards a file before it is closed, relinquishing any
	// temporary resources implied by pending writes. This should be
	// used if the caller decides not to complete writing the file.
	// Discard is a best-effort operation. Discard is not defined for
	// files opened for reading. Exactly one of Discard or Close should
	// be called. No other File, io.ReadSeeker, or io.Writer methods
	// shall be called after Discard.
	Discard(ctx context.Context)

	// Closer commits the contents of a written file, invalidating the
	// File and all Readers and Writers created from the file. Exactly
	// one of Discard or Close should be called. No other File or
	// io.ReadSeeker, io.Writer methods shall be called after Close.
	Closer
}

type Implementation interface {
	// String returns a diagnostic string.
	String() string

	// Open opens a file for reading. The pathname given to file.Open() is passed
	// here unchanged. Thus, it contains the URL prefix such as "s3://".
	//
	// Open returns an error of kind errors.NotExist if there is
	// no file at the provided path.
	Open(ctx context.Context, path string, opts ...Opts) (File, error)

	// Create opens a file for writing. If "path" already exists, the old contents
	// will be destroyed. If "path" does not exist already, the file will be newly
	// created. The pathname given to file.Create() is passed here unchanged.
	// Thus, it contains the URL prefix such as "s3://".
	//
	// Creating a file with the same name as an existing directory is unspecified
	// behavior and varies by implementation. Users are thus advised to avoid
	// this if possible.
	//
	// For filesystem based storage engines (e.g. localfile), if the directory
	// part of the path does not exist already, it will be created. If the path
	// is a directory, an error will be returned.
	//
	// For key based storage engines (e.g. S3), it is OK to create a file that
	// already exists as a common prefix for other objects, assuming a pseudo
	// path separator. So both "foo" and "foo/bar" can be used as paths for
	// creating regular files in the same storage. See List() for more context.
	Create(ctx context.Context, path string, opts ...Opts) (File, error)

	// List finds files and directories. If "path" points to a regular file, the
	// lister will return information about the file itself and finishes.
	//
	// If "path" is a directory, the lister will list file and directory under the
	// given path.  When "recursive" is set to false, List finds files "one level"
	// below dir.  Dir may end in /, but need not.  All the files and directories
	// returned by the lister will have pathnames of the form dir/something.
	//
	// For key based storage engines (e.g. S3), a dir prefix not ending in "/" must
	// be followed immediately by "/" in some object keys, and only such keys
	// will be returned.
	// With "recursive=true" List finds all files whose pathnames under "dir" or its
	// subdirectories.  All the files returned by the lister will have pathnames of
	// the form dir/something.  Directories will not be returned as separate entities.
	// For example List(ctx, "foo",true) will yield "foo/bar/bat.txt", but not "foo.txt"
	// or "foo/bar/", while List(ctx, "foo", false) will yield "foo/bar", and
	// "foo/bat.txt", but not "foo.txt" or "foo/bar/bat.txt".  There is no difference
	// in the return value of List(ctx, "foo", ...) and List(ctx, "foo/", ...)
	List(ctx context.Context, path string, recursive bool) Lister

	// Stat returns the file metadata.  It returns nil if path is
	// a directory. (There is no direct test for existence of a
	// directory.)
	//
	// Stat returns an error of kind errors.NotExist if there is
	// no file at the provided path.
	Stat(ctx context.Context, path string, opts ...Opts) (Info, error)

	// Remove removes the file. The path passed to file.Remove() is passed here
	// unchanged.
	Remove(ctx context.Context, path string) error

	// Presign returns a URL that can be used to perform the given HTTP method,
	// usually one of "GET", "PUT" or "DELETE", on the path for the duration
	// specified in expiry.
	//
	// It returns an error of kind errors.NotSupported for implementations that
	// do not support signed URLs, or that do not support the given HTTP method.
	//
	// Unlike Open and Stat, this method does not return an error of kind
	// errors.NotExist if there is no file at the provided path.
	Presign(ctx context.Context, path, method string, expiry time.Duration) (url string, err error)
}

type Info interface {
	// Size returns the length of the file in bytes for regular files; system-dependent for others
	Size() int64
	// ModTime returns modification time for regular files; system-dependent for others
	ModTime() time.Time
}

type Lister interface {
	// Scan advances the lister to the next entry.  It returns
	// false either when the scan stops because we have reached the end of the input
	// or else because there was error.  After Scan returns, the Err method returns
	// any error that occurred during scanning.
	Scan() bool

	// Err returns the first error that occurred while scanning.
	Err() error

	// Path returns the last path that was scanned. The path always starts with
	// the directory path given to the List method.
	//
	// REQUIRES: Last call to Scan returned true.
	Path() string

	// IsDir() returns true if Path() refers to a directory in a file system
	// or a common prefix ending in "/" in S3.
	//
	// REQUIRES: Last call to Scan returned true.
	IsDir() bool

	// Info returns metadata of the file that was scanned.
	//
	// REQUIRES: Last call to Scan returned true.
	Info() Info
}

type Opts struct {
	// When set, this flag causes the file package to keep retrying when the file
	// is reported as not found. This flag should be set when:
	//
	// 1. you are accessing a file on S3, and
	//
	// 2. an application may have attempted to GET the same file in recent past
	// (~5 minutes). The said application may be on a different machine.
	//
	// This flag is honored only by S3 to work around the problem where s3 may
	// report spurious KeyNotFound error after a GET request to the same file.
	// For more details, see
	// https://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#CoreConcepts,
	// section "S3 Data Consistency Model". In particular:
	//
	//   The caveat is that if you make a HEAD or GET request to the key
	//   name (to find if the object exists) before creating the object, Amazon S3
	//   provides eventual consistency for read-after-write.
	RetryWhenNotFound bool

	// When set, Close will ignore NoSuchUpload error from S3
	// CompleteMultiPartUpload and silently returns OK.
	//
	// This is to work around a bug where concurrent uploads to one file sometimes
	// causes an upload request to be lost on the server side.
	// https://console.aws.amazon.com/support/cases?region=us-west-2#/6299905521/en
	// https://github.com/yasushi-saito/s3uploaderror
	//
	// Set this flag only if:
	//
	//  1. you are writing to a file on S3, and
	//
	//  2. possible concurrent writes to the same file produce the same
	//  contents, so you are ok with taking any of them.
	//
	// If you don't set this flag, then concurrent writes to the same file may
	// fail with a NoSuchUpload error, and it is up to you to retry.
	//
	// On non-S3 file systems, this flag is ignored.
	IgnoreNoSuchUpload bool
}