pkg/blobstore: modernize the blobstore package.

pkg/blobstore/blobreader.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2011 The Grumble Authors
+// Copyright (c) 2011-2013 The Grumble Authors
 // The use of this source code is goverened by a BSD-style
 // license that can be found in the LICENSE-file.
 
@@ -8,46 +8,77 @@ import (
 	"bytes"
 	"crypto/sha1"
 	"encoding/hex"
-	"errors"
 	"hash"
 	"io"
 )
 
-// blobReader is based on the principles of the checksumReader from the archive/zip
-// package of the Go standard library.
+// EOFHashMismatchError signals that a blobReader reached EOF, but that
+// the calculated hash did not match the given blob key. This signals
+// a successful read of the blob, but that the on-disk content is
+// corrupted in some fashion.
+type EOFHashMismatchError struct {
+	// Sum represents that was calculated during the read operation.
+	Sum []byte
+}
 
-// ErrHashMismatch is returned if a blobReader has read a file whose computed hash
-// did not match its key.
-var ErrHashMismatch = errors.New("hash mismatch")
+func (hme EOFHashMismatchError) Error() string {
+	return "blobstore: EOF hash mismatch"
+}
 
-// blobReader reads a blob from disk, hashing all incoming data. On EOF, it checks
-// whether the read data matches the key.
+// blobReader implements an io.ReadCloser that reads a blob from disk
+// and hashes all incoming data to ensure integrity. On EOF, it matches
+// its calculated hash with the given blob key in order to detect data
+// corruption.
+//
+// If a mismatch is detected on EOF, the blobReader will return
+// the error ErrEOFHashMismatch instead of a regular io.EOF error.
 type blobReader struct {
 	rc   io.ReadCloser
 	sum  []byte
 	hash hash.Hash
 }
 
-func newBlobReader(rc io.ReadCloser, key string) (br *blobReader, err error) {
+// newBlobReader returns a new blobReader reading from rc.
+// The rc is expected to be a blobstore entry identified by
+// the given key. (The blobstore is content addressible, and
+// a blob's key represents the SHA1 of its content).
+func newBlobReader(rc io.ReadCloser, key string) (*blobReader, error) {
 	sum, err := hex.DecodeString(key)
 	if err != nil {
-		return
+		return nil, err
 	}
 	return &blobReader{rc, sum, sha1.New()}, nil
 }
 
-func (r *blobReader) Read(b []byte) (n int, err error) {
-	n, err = r.rc.Read(b)
-	r.hash.Write(b[:n])
+// Read implements the Read method of io.ReadCloser.
+// This Read implementation passes on read calls to the
+// wrapper io.ReadCloser and hashes all read content.
+// When EOF is reached, the sum of the streaming hash
+// hash is calculated and compared to the blob key given
+// in newBlobReader. If the calculated hash does not match
+// the blob key, the special error ErrEOFHashMismatch is
+// returned to signal EOF, while also signalling a hash
+// mismatch.
+func (r *blobReader) Read(b []byte) (int, error) {
+	n, err := r.rc.Read(b)
+ 	_, werr := r.hash.Write(b[:n])
+ 	if werr != nil {
+ 		return 0, werr
+ 	}
 	if err != io.EOF {
-		return
+		return n, err
 	}
-	if !bytes.Equal(r.sum, r.hash.Sum(nil)) {
-		err = ErrHashMismatch
+	// Match the calculated digest with the expected
+	// digest on EOF.
+	calcSum := r.hash.Sum(nil)
+	if !bytes.Equal(r.sum, calcSum) {
+		return 0, EOFHashMismatchError{Sum: calcSum}
 	}
-	return
+	return n, io.EOF
 }
 
+// Close implements the Close method of io.ReadCloser.
+// This Close method simply closes the wrapped io.ReadCloser.
 func (r *blobReader) Close() error {
 	return r.rc.Close()
-}
+}