12 type BlockWriter interface {
13 // WriteBlock reads all data from r, writes it to a backing
14 // store as "loc", and returns the number of bytes written.
15 WriteBlock(ctx context.Context, loc string, r io.Reader) error
18 type BlockReader interface {
19 // ReadBlock retrieves data previously stored as "loc" and
21 ReadBlock(ctx context.Context, loc string, w io.Writer) error
24 // A Volume is an interface representing a Keep back-end storage unit:
25 // for example, a single mounted disk, a RAID array, an Amazon S3 volume,
27 type Volume interface {
28 // Volume type as specified in config file. Examples: "S3",
32 // Do whatever private setup tasks and configuration checks
33 // are needed. Return non-nil if the volume is unusable (e.g.,
37 // Get a block: copy the block data into buf, and return the
38 // number of bytes copied.
40 // loc is guaranteed to consist of 32 or more lowercase hex
43 // Get should not verify the integrity of the data: it should
44 // just return whatever was found in its backing
45 // store. (Integrity checking is the caller's responsibility.)
47 // If an error is encountered that prevents it from
48 // retrieving the data, that error should be returned so the
49 // caller can log (and send to the client) a more useful
52 // If the error is "not found", and there's no particular
53 // reason to expect the block to be found (other than that a
54 // caller is asking for it), the returned error should satisfy
55 // os.IsNotExist(err): this is a normal condition and will not
56 // be logged as an error (except that a 404 will appear in the
57 // access log if the block is not found on any other volumes
60 // If the data in the backing store is bigger than len(buf),
61 // then Get is permitted to return an error without reading
64 // len(buf) will not exceed BlockSize.
65 Get(ctx context.Context, loc string, buf []byte) (int, error)
67 // Compare the given data with the stored data (i.e., what Get
68 // would return). If equal, return nil. If not, return
69 // CollisionError or DiskHashError (depending on whether the
70 // data on disk matches the expected hash), or whatever error
71 // was encountered opening/reading the stored data.
72 Compare(ctx context.Context, loc string, data []byte) error
74 // Put writes a block to an underlying storage device.
76 // loc is as described in Get.
78 // len(block) is guaranteed to be between 0 and BlockSize.
80 // If a block is already stored under the same name (loc) with
81 // different content, Put must either overwrite the existing
82 // data with the new data or return a non-nil error. When
83 // overwriting existing data, it must never leave the storage
84 // device in an inconsistent state: a subsequent call to Get
85 // must return either the entire old block, the entire new
86 // block, or an error. (An implementation that cannot peform
87 // atomic updates must leave the old data alone and return an
90 // Put also sets the timestamp for the given locator to the
93 // Put must return a non-nil error unless it can guarantee
94 // that the entire block has been written and flushed to
95 // persistent storage, and that its timestamp is current. Of
96 // course, this guarantee is only as good as the underlying
97 // storage device, but it is Put's responsibility to at least
98 // get whatever guarantee is offered by the storage device.
100 // Put should not verify that loc==hash(block): this is the
101 // caller's responsibility.
102 Put(ctx context.Context, loc string, block []byte) error
104 // Touch sets the timestamp for the given locator to the
107 // loc is as described in Get.
109 // If invoked at time t0, Touch must guarantee that a
110 // subsequent call to Mtime will return a timestamp no older
111 // than {t0 minus one second}. For example, if Touch is called
112 // at 2015-07-07T01:23:45.67890123Z, it is acceptable for a
113 // subsequent Mtime to return any of the following:
115 // - 2015-07-07T01:23:45.00000000Z
116 // - 2015-07-07T01:23:45.67890123Z
117 // - 2015-07-07T01:23:46.67890123Z
118 // - 2015-07-08T00:00:00.00000000Z
120 // It is not acceptable for a subsequente Mtime to return
121 // either of the following:
123 // - 2015-07-07T00:00:00.00000000Z -- ERROR
124 // - 2015-07-07T01:23:44.00000000Z -- ERROR
126 // Touch must return a non-nil error if the timestamp cannot
128 Touch(loc string) error
130 // Mtime returns the stored timestamp for the given locator.
132 // loc is as described in Get.
134 // Mtime must return a non-nil error if the given block is not
135 // found or the timestamp could not be retrieved.
136 Mtime(loc string) (time.Time, error)
138 // IndexTo writes a complete list of locators with the given
139 // prefix for which Get() can retrieve data.
141 // prefix consists of zero or more lowercase hexadecimal
144 // Each locator must be written to the given writer using the
147 // loc "+" size " " timestamp "\n"
151 // - size is the number of bytes of content, given as a
152 // decimal number with one or more digits
154 // - timestamp is the timestamp stored for the locator,
155 // given as a decimal number of seconds after January 1,
158 // IndexTo must not write any other data to writer: for
159 // example, it must not write any blank lines.
161 // If an error makes it impossible to provide a complete
162 // index, IndexTo must return a non-nil error. It is
163 // acceptable to return a non-nil error after writing a
164 // partial index to writer.
166 // The resulting index is not expected to be sorted in any
168 IndexTo(prefix string, writer io.Writer) error
170 // Trash moves the block data from the underlying storage
171 // device to trash area. The block then stays in trash for
172 // -trash-lifetime interval before it is actually deleted.
174 // loc is as described in Get.
176 // If the timestamp for the given locator is newer than
177 // BlobSignatureTTL, Trash must not trash the data.
179 // If a Trash operation overlaps with any Touch or Put
180 // operations on the same locator, the implementation must
181 // ensure one of the following outcomes:
183 // - Touch and Put return a non-nil error, or
184 // - Trash does not trash the block, or
185 // - Both of the above.
187 // If it is possible for the storage device to be accessed by
188 // a different process or host, the synchronization mechanism
189 // should also guard against races with other processes and
190 // hosts. If such a mechanism is not available, there must be
191 // a mechanism for detecting unsafe configurations, alerting
192 // the operator, and aborting or falling back to a read-only
193 // state. In other words, running multiple keepstore processes
194 // with the same underlying storage device must either work
195 // reliably or fail outright.
197 // Corollary: A successful Touch or Put guarantees a block
198 // will not be trashed for at least BlobSignatureTTL
200 Trash(loc string) error
202 // Untrash moves block from trash back into store
203 Untrash(loc string) error
205 // Status returns a *VolumeStatus representing the current
206 // in-use and available storage capacity and an
207 // implementation-specific volume identifier (e.g., "mount
208 // point" for a UnixVolume).
209 Status() *VolumeStatus
211 // String returns an identifying label for this volume,
212 // suitable for including in log messages. It should contain
213 // enough information to uniquely identify the underlying
214 // storage device, but should not contain any credentials or
218 // Writable returns false if all future Put, Mtime, and Delete
219 // calls are expected to fail.
221 // If the volume is only temporarily unwritable -- or if Put
222 // will fail because it is full, but Mtime or Delete can
223 // succeed -- then Writable should return false.
226 // Replication returns the storage redundancy of the
227 // underlying device. It will be passed on to clients in
228 // responses to PUT requests.
231 // EmptyTrash looks for trashed blocks that exceeded TrashLifetime
232 // and deletes them from the volume.
236 // A VolumeWithExamples provides example configs to display in the
238 type VolumeWithExamples interface {
243 // A VolumeManager tells callers which volumes can read, which volumes
244 // can write, and on which volume the next write should be attempted.
245 type VolumeManager interface {
246 // Mounts returns all mounts (volume attachments).
247 Mounts() []*VolumeMount
249 // Lookup returns the volume under the given mount
250 // UUID. Returns nil if the mount does not exist. If
251 // write==true, returns nil if the volume is not writable.
252 Lookup(uuid string, write bool) Volume
254 // AllReadable returns all volumes.
255 AllReadable() []Volume
257 // AllWritable returns all volumes that aren't known to be in
258 // a read-only state. (There is no guarantee that a write to
259 // one will succeed, though.)
260 AllWritable() []Volume
262 // NextWritable returns the volume where the next new block
263 // should be written. A VolumeManager can select a volume in
264 // order to distribute activity across spindles, fill up disks
265 // with more free space, etc.
266 NextWritable() Volume
268 // VolumeStats returns the ioStats used for tracking stats for
270 VolumeStats(Volume) *ioStats
272 // Close shuts down the volume manager cleanly.
276 // A VolumeMount is an attachment of a Volume to a VolumeManager.
277 type VolumeMount struct {
285 // Generate a UUID the way API server would for a "KeepVolumeMount"
287 func (*VolumeMount) generateUUID() string {
289 _, ok := max.SetString("zzzzzzzzzzzzzzz", 36)
291 panic("big.Int parse failed")
293 r, err := rand.Int(rand.Reader, &max)
297 return "zzzzz-ivpuk-" + r.Text(36)
300 // RRVolumeManager is a round-robin VolumeManager: the Nth call to
301 // NextWritable returns the (N % len(writables))th writable Volume
302 // (where writables are all Volumes v where v.Writable()==true).
303 type RRVolumeManager struct {
304 mounts []*VolumeMount
305 mountMap map[string]*VolumeMount
309 iostats map[Volume]*ioStats
312 // MakeRRVolumeManager initializes RRVolumeManager
313 func MakeRRVolumeManager(volumes []Volume) *RRVolumeManager {
314 vm := &RRVolumeManager{
315 iostats: make(map[Volume]*ioStats),
317 vm.mountMap = make(map[string]*VolumeMount)
318 for _, v := range volumes {
320 UUID: (*VolumeMount)(nil).generateUUID(),
322 ReadOnly: !v.Writable(),
326 if v, ok := v.(interface {
329 mnt.DeviceID = v.DeviceID()
331 vm.iostats[v] = &ioStats{}
332 vm.mounts = append(vm.mounts, mnt)
333 vm.mountMap[mnt.UUID] = mnt
334 vm.readables = append(vm.readables, v)
336 vm.writables = append(vm.writables, v)
342 func (vm *RRVolumeManager) Mounts() []*VolumeMount {
346 func (vm *RRVolumeManager) Lookup(uuid string, needWrite bool) Volume {
347 if mnt, ok := vm.mountMap[uuid]; ok && (!needWrite || !mnt.ReadOnly) {
354 // AllReadable returns an array of all readable volumes
355 func (vm *RRVolumeManager) AllReadable() []Volume {
359 // AllWritable returns an array of all writable volumes
360 func (vm *RRVolumeManager) AllWritable() []Volume {
364 // NextWritable returns the next writable
365 func (vm *RRVolumeManager) NextWritable() Volume {
366 if len(vm.writables) == 0 {
369 i := atomic.AddUint32(&vm.counter, 1)
370 return vm.writables[i%uint32(len(vm.writables))]
373 // VolumeStats returns an ioStats for the given volume.
374 func (vm *RRVolumeManager) VolumeStats(v Volume) *ioStats {
378 // Close the RRVolumeManager
379 func (vm *RRVolumeManager) Close() {
382 // VolumeStatus describes the current condition of a volume
383 type VolumeStatus struct {
390 // ioStats tracks I/O statistics for a volume or server
391 type ioStats struct {
402 type InternalStatser interface {
403 InternalStats() interface{}