1 package driver 2 3 import ( 4 "context" 5 "fmt" 6 "io" 7 "regexp" 8 "strconv" 9 "strings" 10 ) 11 12 // Version is a string representing the storage driver version, of the form 13 // Major.Minor. 14 // The registry must accept storage drivers with equal major version and greater 15 // minor version, but may not be compatible with older storage driver versions. 16 type Version string 17 18 // Major returns the major (primary) component of a version. 19 func (version Version) Major() uint { 20 majorPart := strings.Split(string(version), ".")[0] 21 major, _ := strconv.ParseUint(majorPart, 10, 0) 22 return uint(major) 23 } 24 25 // Minor returns the minor (secondary) component of a version. 26 func (version Version) Minor() uint { 27 minorPart := strings.Split(string(version), ".")[1] 28 minor, _ := strconv.ParseUint(minorPart, 10, 0) 29 return uint(minor) 30 } 31 32 // CurrentVersion is the current storage driver Version. 33 const CurrentVersion Version = "0.1" 34 35 // StorageDriver defines methods that a Storage Driver must implement for a 36 // filesystem-like key/value object storage. Storage Drivers are automatically 37 // registered via an internal registration mechanism, and generally created 38 // via the StorageDriverFactory interface (https://godoc.org/github.com/docker/distribution/registry/storage/driver/factory). 39 // Please see the aforementioned factory package for example code showing how to get an instance 40 // of a StorageDriver 41 type StorageDriver interface { 42 // Name returns the human-readable "name" of the driver, useful in error 43 // messages and logging. By convention, this will just be the registration 44 // name, but drivers may provide other information here. 45 Name() string 46 47 // GetContent retrieves the content stored at "path" as a []byte. 48 // This should primarily be used for small objects. 49 GetContent(ctx context.Context, path string) ([]byte, error) 50 51 // PutContent stores the []byte content at a location designated by "path". 52 // This should primarily be used for small objects. 53 PutContent(ctx context.Context, path string, content []byte) error 54 55 // Reader retrieves an io.ReadCloser for the content stored at "path" 56 // with a given byte offset. 57 // May be used to resume reading a stream by providing a nonzero offset. 58 Reader(ctx context.Context, path string, offset int64) (io.ReadCloser, error) 59 60 // Writer returns a FileWriter which will store the content written to it 61 // at the location designated by "path" after the call to Commit. 62 Writer(ctx context.Context, path string, append bool) (FileWriter, error) 63 64 // Stat retrieves the FileInfo for the given path, including the current 65 // size in bytes and the creation time. 66 Stat(ctx context.Context, path string) (FileInfo, error) 67 68 // List returns a list of the objects that are direct descendants of the 69 //given path. 70 List(ctx context.Context, path string) ([]string, error) 71 72 // Move moves an object stored at sourcePath to destPath, removing the 73 // original object. 74 // Note: This may be no more efficient than a copy followed by a delete for 75 // many implementations. 76 Move(ctx context.Context, sourcePath string, destPath string) error 77 78 // Delete recursively deletes all objects stored at "path" and its subpaths. 79 Delete(ctx context.Context, path string) error 80 81 // URLFor returns a URL which may be used to retrieve the content stored at 82 // the given path, possibly using the given options. 83 // May return an ErrUnsupportedMethod in certain StorageDriver 84 // implementations. 85 URLFor(ctx context.Context, path string, options map[string]interface{}) (string, error) 86 87 // Walk traverses a filesystem defined within driver, starting 88 // from the given path, calling f on each file. 89 // If the returned error from the WalkFn is ErrSkipDir and fileInfo refers 90 // to a directory, the directory will not be entered and Walk 91 // will continue the traversal. If fileInfo refers to a normal file, processing stops 92 Walk(ctx context.Context, path string, f WalkFn) error 93 } 94 95 // FileWriter provides an abstraction for an opened writable file-like object in 96 // the storage backend. The FileWriter must flush all content written to it on 97 // the call to Close, but is only required to make its content readable on a 98 // call to Commit. 99 type FileWriter interface { 100 io.WriteCloser 101 102 // Size returns the number of bytes written to this FileWriter. 103 Size() int64 104 105 // Cancel removes any written content from this FileWriter. 106 Cancel() error 107 108 // Commit flushes all content written to this FileWriter and makes it 109 // available for future calls to StorageDriver.GetContent and 110 // StorageDriver.Reader. 111 Commit() error 112 } 113 114 // PathRegexp is the regular expression which each file path must match. A 115 // file path is absolute, beginning with a slash and containing a positive 116 // number of path components separated by slashes, where each component is 117 // restricted to alphanumeric characters or a period, underscore, or 118 // hyphen. 119 var PathRegexp = regexp.MustCompile(`^(/[A-Za-z0-9._-]+)+$`) 120 121 // ErrUnsupportedMethod may be returned in the case where a StorageDriver implementation does not support an optional method. 122 type ErrUnsupportedMethod struct { 123 DriverName string 124 } 125 126 func (err ErrUnsupportedMethod) Error() string { 127 return fmt.Sprintf("%s: unsupported method", err.DriverName) 128 } 129 130 // PathNotFoundError is returned when operating on a nonexistent path. 131 type PathNotFoundError struct { 132 Path string 133 DriverName string 134 } 135 136 func (err PathNotFoundError) Error() string { 137 return fmt.Sprintf("%s: Path not found: %s", err.DriverName, err.Path) 138 } 139 140 // InvalidPathError is returned when the provided path is malformed. 141 type InvalidPathError struct { 142 Path string 143 DriverName string 144 } 145 146 func (err InvalidPathError) Error() string { 147 return fmt.Sprintf("%s: invalid path: %s", err.DriverName, err.Path) 148 } 149 150 // InvalidOffsetError is returned when attempting to read or write from an 151 // invalid offset. 152 type InvalidOffsetError struct { 153 Path string 154 Offset int64 155 DriverName string 156 } 157 158 func (err InvalidOffsetError) Error() string { 159 return fmt.Sprintf("%s: invalid offset: %d for path: %s", err.DriverName, err.Offset, err.Path) 160 } 161 162 // Error is a catch-all error type which captures an error string and 163 // the driver type on which it occurred. 164 type Error struct { 165 DriverName string 166 Enclosed error 167 } 168 169 func (err Error) Error() string { 170 return fmt.Sprintf("%s: %s", err.DriverName, err.Enclosed) 171 } 172