9 // A Volume is an interface representing a Keep back-end storage unit:
10 // for example, a single mounted disk, a RAID array, an Amazon S3 volume,
12 type Volume interface {
13 // Volume type as specified in config file. Examples: "S3",
17 // Do whatever private setup tasks and configuration checks
18 // are needed. Return non-nil if the volume is unusable (e.g.,
22 // Get a block: copy the block data into buf, and return the
23 // number of bytes copied.
25 // loc is guaranteed to consist of 32 or more lowercase hex
28 // Get should not verify the integrity of the data: it should
29 // just return whatever was found in its backing
30 // store. (Integrity checking is the caller's responsibility.)
32 // If an error is encountered that prevents it from
33 // retrieving the data, that error should be returned so the
34 // caller can log (and send to the client) a more useful
37 // If the error is "not found", and there's no particular
38 // reason to expect the block to be found (other than that a
39 // caller is asking for it), the returned error should satisfy
40 // os.IsNotExist(err): this is a normal condition and will not
41 // be logged as an error (except that a 404 will appear in the
42 // access log if the block is not found on any other volumes
45 // If the data in the backing store is bigger than len(buf),
46 // then Get is permitted to return an error without reading
49 // len(buf) will not exceed BlockSize.
50 Get(loc string, buf []byte) (int, error)
52 // Compare the given data with the stored data (i.e., what Get
53 // would return). If equal, return nil. If not, return
54 // CollisionError or DiskHashError (depending on whether the
55 // data on disk matches the expected hash), or whatever error
56 // was encountered opening/reading the stored data.
57 Compare(loc string, data []byte) error
59 // Put writes a block to an underlying storage device.
61 // loc is as described in Get.
63 // len(block) is guaranteed to be between 0 and BlockSize.
65 // If a block is already stored under the same name (loc) with
66 // different content, Put must either overwrite the existing
67 // data with the new data or return a non-nil error. When
68 // overwriting existing data, it must never leave the storage
69 // device in an inconsistent state: a subsequent call to Get
70 // must return either the entire old block, the entire new
71 // block, or an error. (An implementation that cannot peform
72 // atomic updates must leave the old data alone and return an
75 // Put also sets the timestamp for the given locator to the
78 // Put must return a non-nil error unless it can guarantee
79 // that the entire block has been written and flushed to
80 // persistent storage, and that its timestamp is current. Of
81 // course, this guarantee is only as good as the underlying
82 // storage device, but it is Put's responsibility to at least
83 // get whatever guarantee is offered by the storage device.
85 // Put should not verify that loc==hash(block): this is the
86 // caller's responsibility.
87 Put(loc string, block []byte) error
89 // Touch sets the timestamp for the given locator to the
92 // loc is as described in Get.
94 // If invoked at time t0, Touch must guarantee that a
95 // subsequent call to Mtime will return a timestamp no older
96 // than {t0 minus one second}. For example, if Touch is called
97 // at 2015-07-07T01:23:45.67890123Z, it is acceptable for a
98 // subsequent Mtime to return any of the following:
100 // - 2015-07-07T01:23:45.00000000Z
101 // - 2015-07-07T01:23:45.67890123Z
102 // - 2015-07-07T01:23:46.67890123Z
103 // - 2015-07-08T00:00:00.00000000Z
105 // It is not acceptable for a subsequente Mtime to return
106 // either of the following:
108 // - 2015-07-07T00:00:00.00000000Z -- ERROR
109 // - 2015-07-07T01:23:44.00000000Z -- ERROR
111 // Touch must return a non-nil error if the timestamp cannot
113 Touch(loc string) error
115 // Mtime returns the stored timestamp for the given locator.
117 // loc is as described in Get.
119 // Mtime must return a non-nil error if the given block is not
120 // found or the timestamp could not be retrieved.
121 Mtime(loc string) (time.Time, error)
123 // IndexTo writes a complete list of locators with the given
124 // prefix for which Get() can retrieve data.
126 // prefix consists of zero or more lowercase hexadecimal
129 // Each locator must be written to the given writer using the
132 // loc "+" size " " timestamp "\n"
136 // - size is the number of bytes of content, given as a
137 // decimal number with one or more digits
139 // - timestamp is the timestamp stored for the locator,
140 // given as a decimal number of seconds after January 1,
143 // IndexTo must not write any other data to writer: for
144 // example, it must not write any blank lines.
146 // If an error makes it impossible to provide a complete
147 // index, IndexTo must return a non-nil error. It is
148 // acceptable to return a non-nil error after writing a
149 // partial index to writer.
151 // The resulting index is not expected to be sorted in any
153 IndexTo(prefix string, writer io.Writer) error
155 // Trash moves the block data from the underlying storage
156 // device to trash area. The block then stays in trash for
157 // -trash-lifetime interval before it is actually deleted.
159 // loc is as described in Get.
161 // If the timestamp for the given locator is newer than
162 // BlobSignatureTTL, Trash must not trash the data.
164 // If a Trash operation overlaps with any Touch or Put
165 // operations on the same locator, the implementation must
166 // ensure one of the following outcomes:
168 // - Touch and Put return a non-nil error, or
169 // - Trash does not trash the block, or
170 // - Both of the above.
172 // If it is possible for the storage device to be accessed by
173 // a different process or host, the synchronization mechanism
174 // should also guard against races with other processes and
175 // hosts. If such a mechanism is not available, there must be
176 // a mechanism for detecting unsafe configurations, alerting
177 // the operator, and aborting or falling back to a read-only
178 // state. In other words, running multiple keepstore processes
179 // with the same underlying storage device must either work
180 // reliably or fail outright.
182 // Corollary: A successful Touch or Put guarantees a block
183 // will not be trashed for at least BlobSignatureTTL
185 Trash(loc string) error
187 // Untrash moves block from trash back into store
188 Untrash(loc string) error
190 // Status returns a *VolumeStatus representing the current
191 // in-use and available storage capacity and an
192 // implementation-specific volume identifier (e.g., "mount
193 // point" for a UnixVolume).
194 Status() *VolumeStatus
196 // String returns an identifying label for this volume,
197 // suitable for including in log messages. It should contain
198 // enough information to uniquely identify the underlying
199 // storage device, but should not contain any credentials or
203 // Writable returns false if all future Put, Mtime, and Delete
204 // calls are expected to fail.
206 // If the volume is only temporarily unwritable -- or if Put
207 // will fail because it is full, but Mtime or Delete can
208 // succeed -- then Writable should return false.
211 // Replication returns the storage redundancy of the
212 // underlying device. It will be passed on to clients in
213 // responses to PUT requests.
216 // EmptyTrash looks for trashed blocks that exceeded TrashLifetime
217 // and deletes them from the volume.
221 // A VolumeWithExamples provides example configs to display in the
223 type VolumeWithExamples interface {
228 // A VolumeManager tells callers which volumes can read, which volumes
229 // can write, and on which volume the next write should be attempted.
230 type VolumeManager interface {
231 // AllReadable returns all volumes.
232 AllReadable() []Volume
234 // AllWritable returns all volumes that aren't known to be in
235 // a read-only state. (There is no guarantee that a write to
236 // one will succeed, though.)
237 AllWritable() []Volume
239 // NextWritable returns the volume where the next new block
240 // should be written. A VolumeManager can select a volume in
241 // order to distribute activity across spindles, fill up disks
242 // with more free space, etc.
243 NextWritable() Volume
245 // Close shuts down the volume manager cleanly.
249 // RRVolumeManager is a round-robin VolumeManager: the Nth call to
250 // NextWritable returns the (N % len(writables))th writable Volume
251 // (where writables are all Volumes v where v.Writable()==true).
252 type RRVolumeManager struct {
258 // MakeRRVolumeManager initializes RRVolumeManager
259 func MakeRRVolumeManager(volumes []Volume) *RRVolumeManager {
260 vm := &RRVolumeManager{}
261 for _, v := range volumes {
262 vm.readables = append(vm.readables, v)
264 vm.writables = append(vm.writables, v)
270 // AllReadable returns an array of all readable volumes
271 func (vm *RRVolumeManager) AllReadable() []Volume {
275 // AllWritable returns an array of all writable volumes
276 func (vm *RRVolumeManager) AllWritable() []Volume {
280 // NextWritable returns the next writable
281 func (vm *RRVolumeManager) NextWritable() Volume {
282 if len(vm.writables) == 0 {
285 i := atomic.AddUint32(&vm.counter, 1)
286 return vm.writables[i%uint32(len(vm.writables))]
289 // Close the RRVolumeManager
290 func (vm *RRVolumeManager) Close() {
293 // VolumeStatus provides status information of the volume consisting of:
295 // * device_num (an integer identifying the underlying storage system)
298 type VolumeStatus struct {
299 MountPoint string `json:"mount_point"`
300 DeviceNum uint64 `json:"device_num"`
301 BytesFree uint64 `json:"bytes_free"`
302 BytesUsed uint64 `json:"bytes_used"`