Add Hash method to Reader for computing archive checksums (#9)

* Add Hash method to Reader for computing archive checksums from buffered raw bytes

* Make OpenBytes zero-copy by dispatching directly on the caller's slice

* Add OpenBytesWithPrefix for zero-copy prefix-stripped opens

Author: andrew

README.md

@@ -46,6 +46,26 @@ func main() {
 }
 ```
 
+### Hashing
+
+`Open` buffers the raw archive bytes in memory, so the reader can compute checksums of the original artifact without re-reading from the source. This is useful for verifying a downloaded package against the digest published by its registry.
+
+```go
+reader, _ := archives.Open("rails-7.1.0.gem", f)
+defer reader.Close()
+
+sha, _ := reader.Hash(archives.SHA256)
+fmt.Println(sha) // hex-encoded sha256 of the .gem file
+
+// also available: archives.SHA512, archives.SHA1, archives.MD5
+```
+
+The hash is computed over the archive as it was passed to `Open`, not the decompressed contents. For nested formats like gems this means the outer `.gem` file, which is what rubygems.org publishes. If you already have the bytes in hand, `OpenBytes` skips the extra read:
+
+```go
+reader, _ := archives.OpenBytes("pkg.tgz", data)
+```
+
 ### Prefix stripping
 
 Some package formats wrap content in a directory (npm uses `package/`). `OpenWithPrefix` strips a path prefix from all entries:

archives.go

@@ -19,13 +19,13 @@ import (
 
 // FileInfo represents metadata about a file in an archive.
 type FileInfo struct {
-	Path         string    // Full path within archive
-	Name         string    // Base name
-	Size         int64     // Uncompressed size in bytes
-	ModTime      time.Time // Modification time
-	IsDir        bool      // Whether this is a directory
-	Mode         uint32    // File mode/permissions
-	CompressedSize int64   // Compressed size (if available)
+	Path           string    // Full path within archive
+	Name           string    // Base name
+	Size           int64     // Uncompressed size in bytes
+	ModTime        time.Time // Modification time
+	IsDir          bool      // Whether this is a directory
+	Mode           uint32    // File mode/permissions
+	CompressedSize int64     // Compressed size (if available)
 }
 
 // Reader provides methods to browse and extract files from archives.
@@ -41,60 +41,100 @@ type Reader interface {
 	// Returns io.ReadCloser for the file content.
 	Extract(filePath string) (io.ReadCloser, error)
 
+	// Hash returns the hex-encoded digest of the raw archive bytes using
+	// the named algorithm. Supported algorithms are SHA256, SHA512, SHA1
+	// and MD5. The hash is computed over the original archive as passed
+	// to Open, not the decompressed contents.
+	Hash(algo string) (string, error)
+
 	// Close releases resources associated with the reader.
 	Close() error
 }
 
 // Open creates an archive reader for the given content.
 // The filename is used to detect the archive format.
 // The content reader will be read entirely into memory.
+//
 //nolint:ireturn // factory function returning interface by design
 func Open(filename string, content io.Reader) (Reader, error) {
 	format := detectFormat(filename)
 	if format == "" {
 		return nil, fmt.Errorf("unsupported archive format: %s", filename)
 	}
 
-	var reader Reader
-	var err error
+	raw, err := io.ReadAll(content)
+	if err != nil {
+		return nil, fmt.Errorf("reading archive content: %w", err)
+	}
+
+	return openRaw(format, raw)
+}
+
+// OpenBytes is like Open but accepts the archive content as a byte slice.
+// The slice is retained (not copied) for the lifetime of the Reader and
+// must not be modified by the caller after this call.
+//
+//nolint:ireturn // factory function returning interface by design
+func OpenBytes(filename string, content []byte) (Reader, error) {
+	format := detectFormat(filename)
+	if format == "" {
+		return nil, fmt.Errorf("unsupported archive format: %s", filename)
+	}
+
+	return openRaw(format, content)
+}
 
+//nolint:ireturn
+func openRaw(format string, raw []byte) (Reader, error) {
 	switch format {
 	case "zip":
-		reader, err = openZip(content)
+		return openZip(raw)
 	case "tar":
-		reader, err = openTar(content, "")
+		return openTar(raw, "")
 	case "tar.gz", "tgz":
-		reader, err = openTar(content, "gzip")
+		return openTar(raw, "gzip")
 	case "tar.bz2":
-		reader, err = openTar(content, "bzip2")
+		return openTar(raw, "bzip2")
 	case "tar.xz":
-		reader, err = openTar(content, "xz")
+		return openTar(raw, "xz")
 	case "gem":
-		reader, err = openGem(content)
+		return openGem(raw)
 	default:
 		return nil, fmt.Errorf("unsupported format: %s", format)
 	}
-
-	return reader, err
 }
 
 // OpenWithPrefix opens an archive and strips the given prefix from all paths.
 // This is useful for npm packages which wrap content in a "package/" directory.
+//
 //nolint:ireturn // factory function returning interface by design
 func OpenWithPrefix(filename string, content io.Reader, stripPrefix string) (Reader, error) {
 	reader, err := Open(filename, content)
 	if err != nil {
 		return nil, err
 	}
+	return wrapPrefix(reader, stripPrefix), nil
+}
 
-	if stripPrefix == "" {
-		return reader, nil
+// OpenBytesWithPrefix is like OpenWithPrefix but accepts the archive content as
+// a byte slice. The slice is retained (not copied) for the lifetime of the
+// Reader and must not be modified by the caller after this call.
+//
+//nolint:ireturn // factory function returning interface by design
+func OpenBytesWithPrefix(filename string, content []byte, stripPrefix string) (Reader, error) {
+	reader, err := OpenBytes(filename, content)
+	if err != nil {
+		return nil, err
 	}
+	return wrapPrefix(reader, stripPrefix), nil
+}
 
-	return &prefixStripper{
-		reader: reader,
-		prefix: stripPrefix,
-	}, nil
+//nolint:ireturn
+func wrapPrefix(reader Reader, stripPrefix string) Reader {
+	if stripPrefix == "" {
+		return reader
+	}
+	return &prefixStripper{reader: reader, prefix: stripPrefix}
 }
 
 // detectFormat determines archive format from filename extension.

archives_test.go

@@ -140,7 +140,7 @@ func createTestZip() []byte {
 
 func TestZipReader(t *testing.T) {
 	data := createTestZip()
-	reader, err := openZip(bytes.NewReader(data))
+	reader, err := openZip(data)
 	if err != nil {
 		t.Fatalf("openZip failed: %v", err)
 	}
@@ -216,7 +216,7 @@ func createTestTarGz() []byte {
 
 func TestTarReader(t *testing.T) {
 	data := createTestTarGz()
-	reader, err := openTar(bytes.NewReader(data), "gzip")
+	reader, err := openTar(data, "gzip")
 	if err != nil {
 		t.Fatalf("openTar failed: %v", err)
 	}
@@ -279,7 +279,7 @@ func TestOpen(t *testing.T) {
 
 func TestZipListDir(t *testing.T) {
 	data := createTestZip()
-	reader, err := openZip(bytes.NewReader(data))
+	reader, err := openZip(data)
 	if err != nil {
 		t.Fatalf("openZip failed: %v", err)
 	}
@@ -484,7 +484,7 @@ func assertNoDuplicates(t *testing.T, label string, files []FileInfo) {
 
 func TestZipListDirNoDuplicatesWithExplicitDirEntries(t *testing.T) {
 	data := createTestZipWithDirEntries()
-	reader, err := openZip(bytes.NewReader(data))
+	reader, err := openZip(data)
 	if err != nil {
 		t.Fatalf("openZip failed: %v", err)
 	}
@@ -505,7 +505,7 @@ func TestZipListDirNoDuplicatesWithExplicitDirEntries(t *testing.T) {
 
 func TestTarListDirNoDuplicatesWithExplicitDirEntries(t *testing.T) {
 	data := createTestTarGzWithDirEntries()
-	reader, err := openTar(bytes.NewReader(data), "gzip")
+	reader, err := openTar(data, "gzip")
 	if err != nil {
 		t.Fatalf("openTar failed: %v", err)
 	}
@@ -591,7 +591,7 @@ func TestOpenTarRejectsDecompressBomb(t *testing.T) {
 	_ = tw.Close()
 	_ = gw.Close()
 
-	_, err := openTar(bytes.NewReader(buf.Bytes()), "gzip")
+	_, err := openTar(buf.Bytes(), "gzip")
 	if err == nil {
 		t.Fatal("expected error for oversized decompressed content")
 	}
@@ -619,7 +619,7 @@ func TestOpenTarAcceptsWithinLimit(t *testing.T) {
 	_ = tw.Close()
 	_ = gw.Close()
 
-	reader, err := openTar(bytes.NewReader(buf.Bytes()), "gzip")
+	reader, err := openTar(buf.Bytes(), "gzip")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -654,7 +654,7 @@ func TestOpenTarRejectsCumulativeOverflow(t *testing.T) {
 	_ = tw.Close()
 	_ = gw.Close()
 
-	_, err := openTar(bytes.NewReader(buf.Bytes()), "gzip")
+	_, err := openTar(buf.Bytes(), "gzip")
 	if err == nil {
 		t.Fatal("expected error when cumulative size exceeds limit")
 	}
@@ -695,7 +695,7 @@ func TestOpenGemRejectsOversizedData(t *testing.T) {
 	_, _ = outerTw.Write(dataTarGz)
 	_ = outerTw.Close()
 
-	_, err := openGem(bytes.NewReader(gemBuf.Bytes()))
+	_, err := openGem(gemBuf.Bytes())
 	if err == nil {
 		t.Fatal("expected error for oversized gem data")
 	}

diff/diff.go

@@ -25,13 +25,13 @@ const (
 
 // FileDiff represents the diff for a single file.
 type FileDiff struct {
-	Path      string `json:"path"`
-	Type      string `json:"type"` // "modified", "added", "deleted", "renamed"
-	OldPath   string `json:"old_path,omitempty"`
-	Diff      string `json:"diff,omitempty"`
-	IsBinary  bool   `json:"is_binary,omitempty"`
-	LinesAdded int   `json:"lines_added"`
-	LinesDeleted int `json:"lines_deleted"`
+	Path         string `json:"path"`
+	Type         string `json:"type"` // "modified", "added", "deleted", "renamed"
+	OldPath      string `json:"old_path,omitempty"`
+	Diff         string `json:"diff,omitempty"`
+	IsBinary     bool   `json:"is_binary,omitempty"`
+	LinesAdded   int    `json:"lines_added"`
+	LinesDeleted int    `json:"lines_deleted"`
 }
 
 // CompareResult contains the complete comparison between two versions.
@@ -231,9 +231,9 @@ func generateSimpleDiff(path string, oldContent, newContent []byte) (string, int
 	oldEnd := len(oldLines) - 1
 	newEnd := len(newLines) - 1
 	for commonSuffix < maxCommon-commonPrefix &&
-	      oldEnd-commonSuffix >= commonPrefix &&
-	      newEnd-commonSuffix >= commonPrefix &&
-	      oldLines[oldEnd-commonSuffix] == newLines[newEnd-commonSuffix] {
+		oldEnd-commonSuffix >= commonPrefix &&
+		newEnd-commonSuffix >= commonPrefix &&
+		oldLines[oldEnd-commonSuffix] == newLines[newEnd-commonSuffix] {
 		commonSuffix++
 	}
 

diff/diff_test.go

@@ -33,15 +33,15 @@ func createTestArchiveWithFiles(files map[string]string) []byte {
 func TestCompare(t *testing.T) {
 	// Create two test archives
 	oldFiles := map[string]string{
-		"README.md":    "# Old Version\n",
-		"src/main.go":  "package main\n\nfunc main() {\n\tprintln(\"old\")\n}\n",
-		"deleted.txt":  "this will be deleted",
+		"README.md":   "# Old Version\n",
+		"src/main.go": "package main\n\nfunc main() {\n\tprintln(\"old\")\n}\n",
+		"deleted.txt": "this will be deleted",
 	}
 
 	newFiles := map[string]string{
-		"README.md":    "# New Version\n\nWith more content\n",
-		"src/main.go":  "package main\n\nfunc main() {\n\tprintln(\"new\")\n}\n",
-		"added.txt":    "this is new",
+		"README.md":   "# New Version\n\nWith more content\n",
+		"src/main.go": "package main\n\nfunc main() {\n\tprintln(\"new\")\n}\n",
+		"added.txt":   "this is new",
 	}
 
 	oldArchive, err := archives.Open("old.tar.gz", bytes.NewReader(createTestArchiveWithFiles(oldFiles)))

gem.go

@@ -2,6 +2,7 @@ package archives
 
 import (
 	"archive/tar"
+	"bytes"
 	"fmt"
 	"io"
 )
@@ -10,12 +11,12 @@ import (
 // - gem file is a tar archive containing metadata.gz and data.tar.gz
 // - data.tar.gz contains the actual source code
 type gemReader struct {
-	dataReader Reader // The inner data.tar.gz reader
+	raw        []byte
+	dataReader Reader
 }
 
-func openGem(content io.Reader) (*gemReader, error) {
-	// Read the gem file as a tar archive
-	tr := tar.NewReader(content)
+func openGem(raw []byte) (*gemReader, error) {
+	tr := tar.NewReader(bytes.NewReader(raw))
 
 	// Find data.tar.gz in the gem
 	for {
@@ -37,13 +38,12 @@ func openGem(content io.Reader) (*gemReader, error) {
 				return nil, fmt.Errorf("%w: data.tar.gz exceeds %d bytes", ErrDecompressLimit, maxDecompressedSize)
 			}
 
-			// Open the inner tar.gz
-			dataReader, err := openTar(io.NopCloser(newBytesReader(dataContent)), "gzip")
+			dataReader, err := openTar(dataContent, "gzip")
 			if err != nil {
 				return nil, fmt.Errorf("opening data.tar.gz: %w", err)
 			}
 
-			return &gemReader{dataReader: dataReader}, nil
+			return &gemReader{raw: raw, dataReader: dataReader}, nil
 		}
 	}
 }
@@ -60,32 +60,14 @@ func (g *gemReader) Extract(filePath string) (io.ReadCloser, error) {
 	return g.dataReader.Extract(filePath)
 }
 
+func (g *gemReader) Hash(algo string) (string, error) {
+	return hashRaw(g.raw, algo)
+}
+
 func (g *gemReader) Close() error {
+	g.raw = nil
 	if g.dataReader != nil {
 		return g.dataReader.Close()
 	}
 	return nil
 }
-
-// bytesReader implements io.Reader from a byte slice
-type bytesReader struct {
-	data []byte
-	pos  int
-}
-
-func newBytesReader(data []byte) *bytesReader {
-	return &bytesReader{data: data}
-}
-
-func (b *bytesReader) Read(p []byte) (n int, err error) {
-	if b.pos >= len(b.data) {
-		return 0, io.EOF
-	}
-	n = copy(p, b.data[b.pos:])
-	b.pos += n
-	return n, nil
-}
-
-func (b *bytesReader) Close() error {
-	return nil
-}