FIXME: Document/consolidate layer identification

- Ensure layers have an ID on every path (FIXME)
- Remove possibly misleading "for completeness" comments, ensuring identification
  is a basic responsibility.

Signed-off-by: Miloslav Trmač <[email protected]>

storage/storage_dest.go

@@ -84,8 +84,11 @@ type storageImageDestinationLockProtected struct {
 	// When creating a layer, the c/storage layer metadata and image IDs must _only_ be based on trusted values
 	// we have computed ourselves. (Layer reuse can then look up against such trusted values, but it might not
 	// recompute those values for incomding layers — the point of the reuse is that we don’t need to consume the incoming layer.)
-	blobDiffIDs           map[digest.Digest]digest.Digest             // Mapping from layer blobsums to their corresponding DiffIDs
-	indexToTOCDigest      map[int]digest.Digest                       // Mapping from layer index to a TOC Digest, IFF the layer was created/found/reused by TOC digest
+
+	// Layer identification: For a layer, at least one of indexToTOCDigest and blobDiffIDs must be available before commitLayer is called.
+	blobDiffIDs      map[digest.Digest]digest.Digest // Mapping from layer blobsums to their corresponding DiffIDs
+	indexToTOCDigest map[int]digest.Digest           // Mapping from layer index to a TOC Digest, IFF the layer was created/found/reused by TOC digest
+
 	fileSizes             map[digest.Digest]int64                     // Mapping from layer blobsums to their sizes
 	filenames             map[digest.Digest]string                    // Mapping from layer blobsums to names of files we used to hold them
 	currentIndex          int                                         // The index of the layer to be committed (i.e., lower indices have already been committed)
@@ -360,7 +363,6 @@ func (s *storageImageDestination) tryReusingBlobAsPending(blobDigest digest.Dige
 		if err != nil && !errors.Is(err, storage.ErrLayerUnknown) {
 			return false, private.ReusedBlob{}, fmt.Errorf(`looking for compressed layers with digest %q and labels: %w`, blobDigest, err)
 		} else if err == nil {
-			// Record the uncompressed value so that we can use it to calculate layer IDs.
 			s.lockProtected.blobDiffIDs[blobDigest] = aLayer.UncompressedDigest()
 			s.lockProtected.blobAdditionalLayer[blobDigest] = aLayer
 			return true, private.ReusedBlob{
@@ -397,7 +399,6 @@ func (s *storageImageDestination) tryReusingBlobAsPending(blobDigest digest.Dige
 		return false, private.ReusedBlob{}, fmt.Errorf(`looking for layers with digest %q: %w`, blobDigest, err)
 	}
 	if len(layers) > 0 {
-		// Save this for completeness.
 		s.lockProtected.blobDiffIDs[blobDigest] = layers[0].UncompressedDigest
 		return true, private.ReusedBlob{
 			Digest: blobDigest,
@@ -411,7 +412,6 @@ func (s *storageImageDestination) tryReusingBlobAsPending(blobDigest digest.Dige
 		return false, private.ReusedBlob{}, fmt.Errorf(`looking for compressed layers with digest %q: %w`, blobDigest, err)
 	}
 	if len(layers) > 0 {
-		// Record the uncompressed value so that we can use it to calculate layer IDs.
 		s.lockProtected.blobDiffIDs[blobDigest] = layers[0].UncompressedDigest
 		return true, private.ReusedBlob{
 			Digest: blobDigest,
@@ -456,7 +456,6 @@ func (s *storageImageDestination) tryReusingBlobAsPending(blobDigest digest.Dige
 			return false, private.ReusedBlob{}, fmt.Errorf(`looking for layers with TOC digest %q: %w`, options.TOCDigest, err)
 		}
 		if len(layers) > 0 {
-			// Save this for completeness.
 			s.lockProtected.indexToTOCDigest[*options.LayerIndex] = options.TOCDigest
 			return true, private.ReusedBlob{
 				Digest:             blobDigest,