Add code comments to functions

This commit adds comments to better explain the purpose of the
`Compressed()` and `Uncompressed()` functions in the
`internal/utils/oci/safe_cache.go` file.

Ref: #1109
Ref: EC-1669
Signed-off-by: Rob Nester <rnester@redhat.com>

Author: robnester-rh

internal/utils/oci/safe_cache.go

@@ -124,6 +124,12 @@ func (l *safeLayer) DiffID() (v1.Hash, error)            { return l.inner.DiffID
 func (l *safeLayer) Size() (int64, error)                { return l.inner.Size() }
 func (l *safeLayer) MediaType() (types.MediaType, error) { return l.inner.MediaType() }
 
+// Compressed returns a reader for the layer's compressed bytes. If the layer is
+// already cached on disk (by digest), it opens and returns that file. Otherwise
+// it uses singleflight so only one goroutine calls the inner Compressed() and
+// drains the stream (allowing the inner cache to write the file); all callers
+// then wait for the file to be ready and open it. This avoids races when
+// multiple goroutines request the same layer.
 func (l *safeLayer) Compressed() (io.ReadCloser, error) {
 	digest, err := l.inner.Digest()
 	if err != nil {
@@ -133,12 +139,15 @@ func (l *safeLayer) Compressed() (io.ReadCloser, error) {
 	if _, err := os.Stat(path); err == nil {
 		return os.Open(path)
 	}
+	// Only one goroutine runs the inner work; others block on the same key.
 	key := "compressed:" + digest.String()
 	v, err, _ := l.flight.Do(key, func() (any, error) {
 		rc, err := l.inner.Compressed()
 		if err != nil {
 			return nil, err
 		}
+		// Drain the stream in a goroutine so the inner cache can write the file.
+		// We signal when done so callers can open the file instead of the stream.
 		ready := make(chan struct{})
 		go func() {
 			_, _ = io.Copy(io.Discard, rc)
@@ -154,6 +163,9 @@ func (l *safeLayer) Compressed() (io.ReadCloser, error) {
 	return os.Open(path)
 }
 
+// Uncompressed returns a reader for the layer's uncompressed bytes. Same pattern
+// as Compressed but uses diffID for the cache path and singleflight key, since
+// uncompressed content is keyed by diffID rather than digest.
 func (l *safeLayer) Uncompressed() (io.ReadCloser, error) {
 	diffID, err := l.inner.DiffID()
 	if err != nil {
@@ -163,12 +175,14 @@ func (l *safeLayer) Uncompressed() (io.ReadCloser, error) {
 	if _, err := os.Stat(path); err == nil {
 		return os.Open(path)
 	}
+	// Only one goroutine runs the inner work; others block on the same key.
 	key := "uncompressed:" + diffID.String()
 	v, err, _ := l.flight.Do(key, func() (any, error) {
 		rc, err := l.inner.Uncompressed()
 		if err != nil {
 			return nil, err
 		}
+		// Drain the stream in a goroutine so the inner cache can write the file.
 		ready := make(chan struct{})
 		go func() {
 			_, _ = io.Copy(io.Discard, rc)