libpod: add pullprogress to /libpod/images/pull

Following PR attempts to expose `pull progress` of images while a user
attempts to pull image using `libpod`'s API endpoint `/images/pull`
using a newly introduced flag called `pullprogress`.

Output is similar to `compatMode` but not exactly same. Idea is to
maintain a new endpoint which does not have to adhere with `docker`
compatibility and can be extended for new features easily.

Following flag will expose some new fields to pullprogress and will be
slowly extended with more features.

Signed-off-by: flouthoc <[email protected]>

Author: flouthoc

pkg/api/handlers/libpod/images_pull.go

@@ -31,14 +31,15 @@ func ImagesPull(w http.ResponseWriter, r *http.Request) {
 	runtime := r.Context().Value(api.RuntimeKey).(*libpod.Runtime)
 	decoder := r.Context().Value(api.DecoderKey).(*schema.Decoder)
 	query := struct {
-		AllTags    bool   `schema:"allTags"`
-		CompatMode bool   `schema:"compatMode"`
-		PullPolicy string `schema:"policy"`
-		Quiet      bool   `schema:"quiet"`
-		Reference  string `schema:"reference"`
-		Retry      uint   `schema:"retry"`
-		RetryDelay string `schema:"retrydelay"`
-		TLSVerify  bool   `schema:"tlsVerify"`
+		AllTags      bool   `schema:"allTags"`
+		CompatMode   bool   `schema:"compatMode"`
+		PullProgress bool   `schema:"pullProgress"`
+		PullPolicy   string `schema:"policy"`
+		Quiet        bool   `schema:"quiet"`
+		Reference    string `schema:"reference"`
+		Retry        uint   `schema:"retry"`
+		RetryDelay   string `schema:"retrydelay"`
+		TLSVerify    bool   `schema:"tlsVerify"`
 		// Platform fields below:
 		Arch    string `schema:"Arch"`
 		OS      string `schema:"OS"`
@@ -129,6 +130,10 @@ func ImagesPull(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	if query.PullProgress {
+		utils.PullProgress(r.Context(), w, runtime, query.Reference, pullPolicy, pullOptions)
+		return
+	}
 	if query.CompatMode {
 		utils.CompatPull(r.Context(), w, runtime, query.Reference, pullPolicy, pullOptions)
 		return

pkg/api/handlers/utils/images.go

@@ -18,6 +18,7 @@ import (
 	"github.com/containers/image/v5/types"
 	"github.com/containers/podman/v5/libpod"
 	api "github.com/containers/podman/v5/pkg/api/types"
+	entities "github.com/containers/podman/v5/pkg/domain/entities/types"
 	"github.com/containers/podman/v5/pkg/errorhandling"
 	"github.com/containers/storage"
 	"github.com/docker/distribution/registry/api/errcode"
@@ -124,6 +125,100 @@ type pullResult struct {
 	err    error
 }
 
+func PullProgress(ctx context.Context, w http.ResponseWriter, runtime *libpod.Runtime, reference string, pullPolicy config.PullPolicy, pullOptions *libimage.PullOptions) {
+	progress := make(chan types.ProgressProperties)
+	pullOptions.Progress = progress
+
+	pullResChan := make(chan pullResult)
+	go func() {
+		pulledImages, err := runtime.LibimageRuntime().Pull(ctx, reference, pullPolicy, pullOptions)
+		pullResChan <- pullResult{images: pulledImages, err: err}
+	}()
+
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(true)
+
+	flush := func() {
+		if flusher, ok := w.(http.Flusher); ok {
+			flusher.Flush()
+		}
+	}
+
+	statusWritten := false
+	writeStatusCode := func(code int) {
+		if !statusWritten {
+			w.WriteHeader(code)
+			w.Header().Set("Content-Type", "application/json")
+			flush()
+			statusWritten = true
+		}
+	}
+
+	report := entities.ImagePullReportV2{}
+	report.Status = "pulling"
+	report.Stream = "Pulling image"
+
+	writeStatusCode(http.StatusOK)
+	if err := enc.Encode(report); err != nil {
+		logrus.Errorf("Error encoding pull report: %v", err)
+		return
+	}
+	flush()
+
+	for {
+		select {
+		case e := <-progress:
+			report.Status = "pulling"
+			switch e.Event {
+			case types.ProgressEventNewArtifact:
+				report.Stream = "Pulling fs layer"
+			case types.ProgressEventRead:
+				report.Stream = "Downloading"
+				report.Progress = &entities.ImagePullProgress{
+					Current: e.Offset,
+					Total:   e.Artifact.Size,
+				}
+			case types.ProgressEventSkipped:
+				report.Stream = "Layer already exists"
+			case types.ProgressEventDone:
+				report.Stream = "Pull complete"
+			}
+			if err := enc.Encode(report); err != nil {
+				logrus.Errorf("Error encoding pull report: %v", err)
+				return
+			}
+			flush()
+
+		case result := <-pullResChan:
+			if result.err != nil {
+				report.Status = "error"
+				report.Stream = result.err.Error()
+				writeStatusCode(http.StatusInternalServerError)
+				if err := enc.Encode(report); err != nil {
+					logrus.Errorf("Error encoding pull report: %v", err)
+				}
+				flush()
+				return
+			}
+
+			report.Status = "success"
+			report.Stream = "Pull complete"
+			images := []string{}
+			for _, img := range result.images {
+				images = append(images, img.ID())
+			}
+
+			report.Images = images
+			if err := enc.Encode(report); err != nil {
+				logrus.Errorf("Error encoding pull report: %v", err)
+				return
+			}
+			flush()
+			return
+		}
+	}
+}
+
 func CompatPull(ctx context.Context, w http.ResponseWriter, runtime *libpod.Runtime, reference string, pullPolicy config.PullPolicy, pullOptions *libimage.PullOptions) {
 	progress := make(chan types.ProgressProperties)
 	pullOptions.Progress = progress

pkg/domain/entities/types/images.go

@@ -147,6 +147,53 @@ type ImagePullReport struct {
 	ID string `json:"id,omitempty"`
 }
 
+// ImagePullReportV2 provides a detailed status of a container image pull operation.
+type ImagePullReportV2 struct {
+	// Status indicates the current state of the image pull operation.
+	// Possible values are:
+	// - "error":   An error occurred during the pull.
+	// - "pulling": The image pull is in progress.
+	// - "success": The image pull completed successfully.
+	Status string `json:"status,omitempty"`
+
+	// Images contains the unique identifiers of the successfully pulled images.
+	// This field is only populated when the Status is "success".
+	Images []string `json:"images,omitempty"`
+
+	// Stream provides a human-readable stream of events from the containers/image
+	// library. This data is intended for display purposes and should not be parsed
+	// by software.
+	Stream string `json:"logStream,omitempty"`
+
+	// Progress provides detailed information about the download progress of an
+	// image layer. This field is only populated when the Status is "pulling".
+	Progress *ImagePullProgress `json:"progress,omitempty"`
+}
+
+// ImagePullProgress details the download progress of a single image layer.
+type ImagePullProgress struct {
+	// Current is the number of bytes of the current artifact that have been
+	// downloaded so far.
+	Current uint64 `json:"current,omitempty"`
+
+	// Total is the total size of the artifact in bytes. A value of -1
+	// indicates that the total size is unknown.
+	Total int64 `json:"total,omitempty"`
+
+	// Completed indicates whether the pull of the associated layer has finished.
+	// This is particularly useful for tracking the status of "partial pulls"
+	// where only a portion of the layers may be downloaded.
+	Completed bool `json:"completed,omitempty"`
+
+	// LayerID is the unique identifier for the image layer being downloaded.
+	LayerID string `json:"layerID,omitempty"`
+
+	// ProgressText is a human-readable string that represents the current
+	// progress, often as a progress bar or status message. This text is for
+	// display purposes only and should not be parsed.
+	ProgressText string `json:"progressText,omitempty"`
+}
+
 type ImagePushStream struct {
 	// ManifestDigest is the digest of the manifest of the pushed image.
 	ManifestDigest string `json:"manifestdigest,omitempty"`

test/apiv2/10-images.at

@@ -440,4 +440,22 @@ t GET "libpod/events?stream=false&since=$START"  200  \
   .Actor.Attributes.name="localhost:5000/idonotexist" \
   .Actor.Attributes.error~".*connection refused"
 
+# Test pullProgress parameter on /libpod/images/pull endpoint
+# Remove the image first to ensure we actually pull it
+podman rmi -f quay.io/libpod/alpine:latest >/dev/null 2>&1 || true
+
+# Test pullProgress=true - should return ImagePullReportV2 format with progress info
+t POST "libpod/images/pull?reference=quay.io/libpod/alpine:latest&pullProgress=true" 200 \
+  .status~".*success.*" \
+  .logStream~".*Pull complete.*"
+
+
+# Test pullProgress=true with invalid image - should return error status
+t POST "libpod/images/pull?reference=localhost:5000/idonotexist:latest&pullProgress=true" 200 \
+  .status~".*error.*" \
+  .logStream~".*"
+
+# Clean up
+podman rmi -f quay.io/libpod/alpine:latest >/dev/null 2>&1 || true
+
 # vim: filetype=sh