blob: 39ec375156d8f74690160be8a7d14c5e82ced82f [file] [log] [blame]
package gcs
import (
"context"
"io"
"cloud.google.com/go/storage"
)
// GCSClient is an interface for interacting with Google Cloud Storage (GCS). Introducing
// the interface allows for easier mocking and testing for unit (small) tests. GCSClient
// should have common, general functionality. Users should feel free to create a
// instance-specific GCSClient that creates an abstraction for more instance-specific method calls.
// One intentional thing missing from these method calls is bucket name. The bucket name
// is given at creation time, so as to simplify the method signatures.
// In all methods, context.Background() is a safe value for ctx if you don't want to use
// the context of the web request, for example.
// See also test_gcsclient.NewMockClient() for mocking this for unit tests.
// See also mem_gcsclient.New() for an alternative.
type GCSClient interface {
// FileReader returns an io.ReadCloser pointing to path on GCS, using the provided
// context. storage.ErrObjectNotExist will be returned if the file is not found.
// The caller must call Close on the returned Reader when done reading.
// Note that per https://cloud.google.com/storage/docs/transcoding, a file that is gzip encoded
// will be automatically uncompressed.
FileReader(ctx context.Context, path string) (io.ReadCloser, error)
// FileWriter returns an io.WriteCloser that writes to the GCS file given by path
// using the provided context. A new GCS file will be created if it doesn't already exist.
// Otherwise, the existing file will be overwritten. The caller must call Close on
// the returned Writer to flush the writes.
FileWriter(ctx context.Context, path string, opts FileWriteOptions) io.WriteCloser
// DoesFileExist returns true if the specified path exists and false if it does not.
// This is a convenience wrapper around
// https://godoc.org/cloud.google.com/go/storage#ObjectHandle.Attrs
// If any error, other than storage.ErrObjectNotExist, is encountered then it will be
// returned.
DoesFileExist(ctx context.Context, path string) (bool, error)
// GetFileContents returns the []byte represented by the GCS file at path. This is a
// convenience wrapper around FileReader. storage.ErrObjectNotExist will be returned
// if the file is not found.
// Note that per https://cloud.google.com/storage/docs/transcoding, a file that is gzip encoded
// will be automatically uncompressed.
GetFileContents(ctx context.Context, path string) ([]byte, error)
// SetFileContents writes the []byte to the GCS file at path. This is a
// convenience wrapper around FileWriter. The GCS file will be created if it doesn't exist.
SetFileContents(ctx context.Context, path string, opts FileWriteOptions, contents []byte) error
// GetFileObjectAttrs returns the storage.ObjectAttrs associated with the given
// path.
GetFileObjectAttrs(ctx context.Context, path string) (*storage.ObjectAttrs, error)
// AllFilesInDirectory executes the callback on all GCS files with the given prefix,
// i.e. in the directory prefix. It returns an error if it fails to read any of the
// ObjectAttrs belonging to files. If the callback returns an error, iteration stops
// and the error is returned without modification.
AllFilesInDirectory(ctx context.Context, prefix string, callback func(item *storage.ObjectAttrs) error) error
// DeleteFile deletes the given file, returning any error.
DeleteFile(ctx context.Context, path string) error
// Bucket returns the bucket name of this client
Bucket() string
}
// FileWriteOptions represents the metadata for a GCS file. See storage.ObjectAttrs
// for a more detailed description of what these are.
type FileWriteOptions struct {
ContentEncoding string
ContentType string
ContentLanguage string
ContentDisposition string
Metadata map[string]string
}
// FILE_WRITE_OPTS_TEXT are default options for writing a text file.
var FILE_WRITE_OPTS_TEXT = FileWriteOptions{ContentType: "text/plain"}