1 // Package storage provides types and functionality for abstracting storage systems 2 // (local, in memory, Google Cloud storage) into a common interface. 3 package storage 4 5 import ( 6 "context" 7 "io" 8 "time" 9 ) 10 11 // File contains the metadata required to define a file (for reading). 12 type File struct { 13 io.ReadCloser // Underlying data. 14 Attributes 15 } 16 17 // Attributes represents the metadata of a File 18 // Inspired from gocloud.dev/blob.Attributes 19 type Attributes struct { 20 // ContentType is the MIME type of the blob object. It will not be empty. 21 ContentType string 22 // ContentEncoding specifies the encoding used for the blob's content, if any. 23 ContentEncoding string 24 // Metadata holds key/value pairs associated with the blob. 25 // Keys are guaranteed to be in lowercase, even if the backend provider 26 // has case-sensitive keys (although note that Metadata written via 27 // this package will always be lowercased). If there are duplicate 28 // case-insensitive keys (e.g., "foo" and "FOO"), only one value 29 // will be kept, and it is undefined which one. 30 Metadata map[string]string 31 // ModTime is the time the blob object was last modified. 32 ModTime time.Time 33 // CreationTime is the time the blob object was created. 34 CreationTime time.Time 35 // Size is the size of the object in bytes. 36 Size int64 37 } 38 39 // ReaderOptions are used to modify the behaviour of read operations. 40 // Inspired from gocloud.dev/blob.ReaderOptions 41 // It is provided for future extensibility. 42 type ReaderOptions struct { 43 // ReadCompressed controls whether the file must be uncompressed based on Content-Encoding. 44 // Only respected by Google Cloud Storage: https://cloud.google.com/storage/docs/transcoding 45 // Common pitfall: https://github.com/googleapis/google-cloud-go/issues/1743 46 ReadCompressed bool 47 } 48 49 // WriterOptions are used to modify the behaviour of write operations. 50 // Inspired from gocloud.dev/blob.WriterOptions 51 // Not all options are supported by all FS 52 type WriterOptions struct { 53 Attributes Attributes 54 55 // BufferSize changes the default size in bytes of the chunks that 56 // Writer will upload in a single request; larger blobs will be split into 57 // multiple requests. 58 // 59 // This option may be ignored by some drivers. 60 // 61 // If 0, the driver will choose a reasonable default. 62 // 63 // If the Writer is used to do many small writes concurrently, using a 64 // smaller BufferSize may reduce memory usage. 65 BufferSize int 66 } 67 68 // DefaultSignedURLExpiry is the default duration for SignedURLOptions.Expiry. 69 const ( 70 DefaultSignedURLExpiry = 1 * time.Hour 71 DefaultSignedURLMethod = "GET" 72 ) 73 74 // SignedURLOptions are used to modify the behaviour of write operations. 75 // Inspired from gocloud.dev/blob.SignedURLOptions 76 // Not all options are supported by all FS 77 type SignedURLOptions struct { 78 // Expiry sets how long the returned URL is valid for. 79 // Defaults to DefaultSignedURLExpiry. 80 Expiry time.Duration 81 // Method is the HTTP method that can be used on the URL; one of "GET", "PUT", 82 // or "DELETE". Defaults to "GET". 83 Method string 84 } 85 86 func (o *SignedURLOptions) applyDefaults() { 87 if o.Expiry == 0 { 88 o.Expiry = DefaultSignedURLExpiry 89 } 90 if o.Method == "" { 91 o.Method = DefaultSignedURLMethod 92 } 93 } 94 95 // FS is an interface which defines a virtual filesystem. 96 type FS interface { 97 Walker 98 99 // Open opens an existing file at path in the filesystem. Callers must close the 100 // File when done to release all underlying resources. 101 Open(ctx context.Context, path string, options *ReaderOptions) (*File, error) 102 103 // Attributes returns attributes about a path 104 Attributes(ctx context.Context, path string, options *ReaderOptions) (*Attributes, error) 105 106 // Create makes a new file at path in the filesystem. Callers must close the 107 // returned WriteCloser and check the error to be sure that the file 108 // was successfully written. 109 Create(ctx context.Context, path string, options *WriterOptions) (io.WriteCloser, error) 110 111 // Delete removes a path from the filesystem. 112 Delete(ctx context.Context, path string) error 113 114 // URL resolves a path to an addressable URL 115 URL(ctx context.Context, path string, options *SignedURLOptions) (string, error) 116 } 117