top: add support for --layers

Get top files for one or more layers specified via digest, partial or
complete. Errors out if the passed layers don't match any layer in the
image, or it matches more than one layers. Merges the output when more
than one layer is passed.

* add unit tests

Signed-off-by: Danish Prakash <[email protected]>

Author: danishprakash

.github/workflows/ci.yaml

@@ -44,3 +44,7 @@ jobs:
       - name: build
         run: make binaries
         working-directory: .
+
+      - name: test
+        run: make unit-tests
+        working-directory: .

Makefile

@@ -1,9 +1,13 @@
-.PHONY: binaries, vendor
+.PHONY: binaries, vendor, unit-tests
 
 # Build the binaries
 binaries:
 	go build -o bin/skiff ./cmd/skiff
 
+# Run tests
+unit-tests:
+	go test -v ./cmd/skiff/...
+
 vendor:
 	go mod tidy
 	go mod vendor

cmd/skiff/layers.go

@@ -22,7 +22,7 @@ func ShowLayerUsage(ctx context.Context, sysCtx *types.SystemContext, uri string
 	}
 
 	res := ""
-	if layers != nil && len(layers) > 0 {
+	if len(layers) > 0 {
 		if len(inspect.LayersData) != len(layers) {
 			return "", fmt.Errorf(
 				"internal error: image inspect returned %d layers, storage returned %d layers",

cmd/skiff/top.go

@@ -6,10 +6,12 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"os"
 	"path/filepath"
 	"slices"
 	"strconv"
 	"strings"
+	"text/tabwriter"
 
 	"github.com/containers/image/v5/pkg/blobinfocache/none"
 	"github.com/containers/image/v5/pkg/compression"
@@ -25,6 +27,16 @@ var topCommand = cli.Command{
 	Flags: []cli.Flag{
 		&cli.BoolFlag{Name: "include-pseudo", Usage: "Include pseudo-filesystems (/dev, /proc, /sys)"},
 		&cli.BoolFlag{Name: "follow-symlinks", Usage: "Follow symbolic links"},
+		&cli.BoolFlag{
+			Name:    "human-readable",
+			Usage:   "Show file sizes in human readable format",
+			Aliases: []string{"h"},
+		},
+		&cli.StringSliceFlag{
+			Name:    "layer",
+			Usage:   "Filter results to specific layer(s) by SHA256 digest. If not specified, all layers are included (not an empty result).",
+			Aliases: []string{"l"},
+		},
 	},
 	Arguments: []cli.Argument{
 		&cli.StringArg{Name: "image", UsageText: "Container image ref"},
@@ -35,17 +47,25 @@ var topCommand = cli.Command{
 			return fmt.Errorf("image URL is required")
 		}
 
+		humanReadable := c.Bool("human-readable")
+		layers := c.StringSlice("layer")
+		if c.IsSet("layer") && len(layers) == 0 {
+			return fmt.Errorf("--layer flag provided but no layer digest specified; please provide at least one layer digest")
+		}
+
 		sysCtx := types.SystemContext{}
-		return analyzeLayers(image, ctx, &sysCtx)
+
+		return analyzeLayers(ctx, &sysCtx, image, layers, humanReadable)
 	},
 }
 
 const defaultFileLimit = 10
 
 type FileInfo struct {
-	Path  string
-	Size  int64
-	Layer string // layer ID this file belongs to
+	Path              string
+	Size              int64
+	HumanReadableSize string
+	Layer             string // layer ID this file belongs to
 }
 
 type FileHeap []FileInfo
@@ -66,9 +86,73 @@ func (h *FileHeap) Pop() interface{} {
 	return item
 }
 
+// HumanReadableSize converts a byte count to a human readable string
+// From https://yourbasic.org/golang/formatting-byte-size-to-human-readable-format/
+func HumanReadableSize(b int64) string {
+	const unit = 1000
+	if b < unit {
+		return fmt.Sprintf("%d B", b)
+	}
+	div, exp := int64(unit), 0
+	for n := b / unit; n >= unit; n /= unit {
+		div *= unit
+		exp++
+	}
+	return fmt.Sprintf("%.1f %cB",
+		float64(b)/float64(div), "kMGTPE"[exp])
+}
+
+// getFilteredLayers returns only the layers that needs to be
+// processed/extracted e.g. after user specifies specific layer(s)
+// using --layer, we shouldn't be processing all the layers.
+// If layers is empty, returns all layers in the image.
+func getFilteredLayers(img types.Image, layers []string) ([]types.BlobInfo, error) {
+	allLayers := img.LayerInfos()
+
+	if len(layers) == 0 {
+		return allLayers, nil // No filtering needed
+	}
+
+	// Build a map for efficient layer lookup
+	layerMap := make(map[string]types.BlobInfo)
+	for _, layer := range allLayers {
+		layerMap[layer.Digest.Encoded()] = layer
+	}
+
+	var filteredLayers []types.BlobInfo
+	seenLayers := make(map[string]bool) // Track which layers we've already added
+
+	for _, filter := range layers {
+		var matchedLayersDigests []string
+		for layerDigest := range layerMap {
+			if layerDigest == filter || strings.HasPrefix(layerDigest, filter) {
+				matchedLayersDigests = append(matchedLayersDigests, layerDigest)
+			}
+		}
+
+		if len(matchedLayersDigests) == 0 {
+			return nil, fmt.Errorf("layer %s not found in image", filter)
+		}
+		if len(matchedLayersDigests) > 1 {
+			return nil, fmt.Errorf("multiple layers match shortened digest %s", filter)
+		}
+
+		matchedLayerDigest := matchedLayersDigests[0]
+		layer := layerMap[matchedLayerDigest]
+
+		// Only add if we haven't seen this layer before
+		if !seenLayers[layer.Digest.String()] {
+			filteredLayers = append(filteredLayers, layer)
+			seenLayers[layer.Digest.String()] = true
+		}
+	}
+
+	return filteredLayers, nil
+}
+
 // analyzeLayers fetches layers for a given image reference
 // reads the associated layer archives and lists file info
-func analyzeLayers(uri string, ctx context.Context, sysCtx *types.SystemContext) error {
+func analyzeLayers(ctx context.Context, sysCtx *types.SystemContext, uri string, layers []string, humanReadable bool) error {
 	img, _, err := skiff.ImageAndLayersFromURI(ctx, sysCtx, uri)
 	if err != nil {
 		return err
@@ -83,9 +167,7 @@ func analyzeLayers(uri string, ctx context.Context, sysCtx *types.SystemContext)
 	h := &FileHeap{}
 	heap.Init(h)
 
-	files := make([]FileInfo, h.Len())
-
-	layerInfos, err := skiff.BlobInfoFromImage(img, ctx, sysCtx)
+	layerInfos, err := getFilteredLayers(img, layers)
 	if err != nil {
 		return err
 	}
@@ -113,48 +195,49 @@ func analyzeLayers(uri string, ctx context.Context, sysCtx *types.SystemContext)
 				return fmt.Errorf("failed to read tar header: %w", err)
 			}
 
-			// TODO: follow symlinks
+			// TODO(danishprakash): follow symlinks
 			// if hdr.Typeflag == tar.TypeSymlink
 
 			path, err := filepath.Abs(filepath.Join("/", hdr.Name))
 			if err != nil {
-				// TODO: perhaps just log and not error out
-				return fmt.Errorf("error generating absolute representation of path: %w", err)
+				// Log the error but continue processing other files
+				fmt.Fprintf(os.Stderr, "warning: error generating absolute representation of path %s: %v\n", hdr.Name, err)
+				continue
 			}
 
 			if hdr.Typeflag == tar.TypeReg {
-				heap.Push(h, FileInfo{Path: path, Size: hdr.Size, Layer: layer.Digest.Encoded()})
+				heap.Push(h, FileInfo{
+					Path:              path,
+					Size:              hdr.Size,
+					HumanReadableSize: HumanReadableSize(hdr.Size),
+					Layer:             layer.Digest.Encoded(),
+				})
 				if h.Len() > defaultFileLimit {
 					heap.Pop(h)
 				}
 			}
 		}
-
 	}
 
-	for i := 0; h.Len() > 0; i++ {
+	// Extract files from heap in reverse order (largest first)
+	var files []FileInfo
+	for h.Len() > 0 {
 		files = append(files, heap.Pop(h).(FileInfo))
 	}
 
-	maxPathLen, maxSizeLen, maxLayerLen := 0, 0, 12
-	for _, f := range files {
-		if len(f.Path) > maxPathLen {
-			maxPathLen = len(f.Path)
-		}
-		sizeStr := strconv.FormatInt(f.Size, 10)
-		if len(sizeStr) > maxSizeLen {
-			maxSizeLen = len(sizeStr)
-		}
-	}
-
-	fmt.Printf("%-*s	%*s	%-*s\n", maxPathLen, "File Path", maxSizeLen, "Size", maxLayerLen, "Layer ID")
-	fmt.Println(strings.Repeat("-", maxPathLen+maxSizeLen+maxLayerLen+15)) // also consider two tab chars
+	w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', tabwriter.TabIndent)
+	defer w.Flush()
+	fmt.Fprintln(w, "FILE PATH\tSIZE\tLAYER ID")
 
 	slices.Reverse(files)
 	for _, f := range files {
-		sizeStr := strconv.FormatInt(f.Size, 10)
-		fmt.Printf("%-*s	%*s	%-*s\n", maxPathLen, f.Path, maxSizeLen, sizeStr, maxLayerLen, f.Layer[:12])
+		var size string
+		if humanReadable {
+			size = f.HumanReadableSize
+		} else {
+			size = strconv.FormatInt(f.Size, 10)
+		}
+		fmt.Fprintf(w, "%s\t%s\t%s\n", f.Path, size, f.Layer[:12])
 	}
-
 	return nil
 }