Merge pull request #5 from scunningham/refine_errors

Author: scunningham

internal/pkg/async/reader.go

@@ -237,7 +237,7 @@ func (r *asyncRdrT) NextBlock(prevBlk *blk.BlkT) (*blk.BlkT, int, error) {
 	case err != zerr.EndMark:
 	case r.hasher == nil:
 	case r.hasher.Done() != r.frameRdr.ContentChecksum():
-		err = zerr.ErrContentHash
+		err = zerr.WrapCorrupted(zerr.ErrContentHash)
 	}
 
 	return nextBlk, nRead, err

internal/pkg/sync/reader.go

@@ -64,7 +64,7 @@ func (r *syncReaderT) NextBlock(prevBlk *BlkT) (*BlkT, int, error) {
 	case zerr.EndMark:
 		if r.hasher != nil {
 			if r.hasher.Sum32() != r.frameRdr.ContentChecksum() {
-				err = zerr.ErrContentHash
+				err = zerr.WrapCorrupted(zerr.ErrContentHash)
 			}
 		}
 		fallthrough

internal/test/rd_test.go

@@ -720,11 +720,12 @@ func TestContentCRC(t *testing.T) {
 	}
 
 	tests := map[string]struct {
-		data  []byte
-		sha2  string
-		munge func([]byte) []byte
-		err   error
-		opts  []plz4.OptT
+		data    []byte
+		sha2    string
+		munge   func([]byte) []byte
+		err     error
+		corrupt bool
+		opts    []plz4.OptT
 	}{
 		"no_content_hash": {
 			data: oneFrameNoHash,
@@ -739,24 +740,27 @@ func TestContentCRC(t *testing.T) {
 			sha2: oneFrameSha2,
 		},
 		"munge_one_frame": {
-			data:  oneFrame,
-			munge: corruptCRC,
-			err:   plz4.ErrContentHash,
+			data:    oneFrame,
+			munge:   corruptCRC,
+			err:     plz4.ErrContentHash,
+			corrupt: true,
 		},
 		"clean_large": {
 			data: large,
 			sha2: lsha2,
 		},
 		"munged_large": {
-			data:  large,
-			munge: corruptCRC,
-			err:   plz4.ErrContentHash,
+			data:    large,
+			munge:   corruptCRC,
+			err:     plz4.ErrContentHash,
+			corrupt: true,
 		},
 		"munged_large_sync": {
-			data:  large,
-			munge: corruptCRC,
-			err:   plz4.ErrContentHash,
-			opts:  []Option{plz4.WithParallel(0)},
+			data:    large,
+			munge:   corruptCRC,
+			err:     plz4.ErrContentHash,
+			opts:    []Option{plz4.WithParallel(0)},
+			corrupt: true,
 		},
 		"large_clipped": {
 			data: large[:len(large)-4],
@@ -781,6 +785,11 @@ func TestContentCRC(t *testing.T) {
 			}
 
 			if tc.err != nil || err != nil {
+
+				if tc.corrupt != plz4.Lz4Corrupted(err) {
+					t.Errorf("Corrupt mismatch;  wanted: %v on '%v'", tc.corrupt, err)
+				}
+
 				if !errors.Is(err, tc.err) {
 					t.Fatalf("Expected error: %v got %v", tc.err, err)
 				}

plz4_err.go

@@ -35,6 +35,10 @@ const (
 )
 
 // Returns true if 'err' indicates that the read input is corrupted.
+//
+// Note that a short read is not considered corrupted. In that case
+// the returned error will be a join of the error context, and the
+// underlying error, either an io.EOF or io.ErrUnexpectedEOF.
 func Lz4Corrupted(err error) bool {
 	return errors.Is(err, ErrCorrupted)
 }

plz4_opts.go

@@ -8,13 +8,25 @@ import (
 	"github.com/prequel-dev/plz4/internal/pkg/opts"
 )
 
+// OptT is a function that sets an option on the processor.
 type OptT func(*opts.OptsT)
+
+// WorkerPool is an interface for a worker pool implementation.
 type WorkerPool = opts.WorkerPool
+
+// BlockIdxT is a type for block size index.
 type BlockIdxT = descriptor.BlockIdxT
+
+// LevelT is a type for compression level.
 type LevelT = compress.LevelT
 
+// Progress callback function type.
 type CbProgressT = opts.ProgressFuncT
+
+// Skip callback function type.
 type CbSkipT = opts.SkipCallbackT
+
+// Dictionary callback function type.
 type CbDictT = opts.DictCallbackT
 
 const (
@@ -73,7 +85,7 @@ func WithParallel(n int) OptT {
 // This option only applies to the asynchronous case.
 // It is ignored in the synchronous case.
 //
-// Setting the size to -1 forces auto mode, where the processor will automatically
+// Setting the pending size to -1 enables auto mode.  In auto mode, the processor will automatically
 // scale the pending size for maximum speed based on the block size and nParallel.
 func WithPendingSize(n int) OptT {
 	return func(o *opts.OptsT) {
@@ -91,15 +103,15 @@ func WithContentChecksum(enable bool) OptT {
 	}
 }
 
-// Optional worker pool for both compress and decompress mode.
+// Optional worker pool for both compress and decompress modes.
 func WithWorkerPool(wp WorkerPool) OptT {
 	return func(o *opts.OptsT) {
 		o.WorkerPool = wp
 	}
 }
 
 // Processor will emit tuple (src_block_offset, dst_blk_offset) on each
-// block boundary.  Applies to both compress and decompress mode.
+// block boundary.  Applies to both compress and decompress modes.
 //
 // Offsets are relative to the start of the frame.
 //
@@ -181,7 +193,7 @@ func WithDictionaryId(id uint32) OptT {
 
 // Read block starting at byte 'offset'.
 //
-// The offset is the first byte of the block relative to the start of the frame.
+// The offset is the first byte of the data block relative to the start of the frame.
 func WithReadOffset(offset int64) OptT {
 	return func(o *opts.OptsT) {
 		o.ReadOffset = offset

plz4_reader.go

@@ -6,6 +6,9 @@ import (
 	"github.com/prequel-dev/plz4/internal/pkg/rdr"
 )
 
+// Reader is an interface for reading LZ4 compressed data.
+//
+// It implements the io.ReadCloser and the io.WriterTo interfaces.
 type Reader interface {
 	// Read decompressed data into 'dst'.  Return number bytes read.
 	Read(dst []byte) (n int, err error)
@@ -19,7 +22,7 @@ type Reader interface {
 	Close() error
 }
 
-// Construct a Reader to decompress the LZ4 frame from 'rdr'.
+// Construct a Reader to decompress the LZ4 frame from 'rd'.
 //
 // Specify optional parameters in 'opts'.
 func NewReader(rd io.Reader, opts ...OptT) Reader {

plz4_writer.go

@@ -8,6 +8,9 @@ import (
 	"github.com/prequel-dev/plz4/internal/pkg/sync"
 )
 
+// Writer is an interface for compressing data into an LZ4 frame.
+//
+// It implements the io.WriteCloser and the io.ReaderFrom interfaces.
 type Writer interface {
 	// Compress 'src' data; return number of bytes written.
 	// May be used in sequence with ReadFrom.
@@ -31,7 +34,7 @@ type Writer interface {
 	Close() error
 }
 
-// Construct a Writer to compress an LZ4 frame into 'wr'.
+// Construct a Writer to compress data into an LZ4 frame written to 'wr'.
 //
 // Specify optional parameters in 'opts'.
 func NewWriter(wr io.Writer, opts ...OptT) Writer {