cmd, pkg/podman: Turn Image into an interface

In reaction to the conversation in PR #1707, I made suggested changes
to the implementation in terms of how Image information, received
from Podman, is represented and treated in the Toolbx code. I used
the same procedure as in the case of representing Containers:
 - Commit e611969
 - Commit ec7eb59

In short, the JSON from 'podman inspect --type image' and
'podman images' are different, so logically, there should be
different implementations of the JSON.Unmarshaler interface [1]
for them as well. The new Image interface provides access to the
values ​​parsed from the JSONs and two different concrete types,
which are implemented separately to handle the differences in
the JSONs.

GetImages() now returns an Images iterator-like structure that
handles image flattening and sorting internally. InspectImage()
returns an Image interface instead of map[string]interface{},
and the IsToolboxImage() function was replaced with the IsToolbx()
method on the Image interface.

Tested were results of Podman starting on version 1.1.2, which should be
sufficient since the minimum required Podman version is 1.6.4 (see
commit 8e80dd5). Covered are structures representing podman commands
'podman inspect --type image' and 'podman images'.

[1] https://pkg.go.dev/encoding/json#Unmarshaler

#1724

Signed-off-by: Dalibor Kricka <dalidalk@seznam.cz>

Author: DaliborKr

src/cmd/completion.go

@@ -138,12 +138,13 @@ func completionImageNames(cmd *cobra.Command, _ []string, _ string) ([]string, c
 	if images, err := podman.GetImages(true); err != nil {
 		logrus.Debugf("Getting all images failed: %s", err)
 	} else {
-		for _, image := range images {
-			if len(image.Names) != 1 {
+		for images.Next() {
+			image := images.Get()
+			if len(image.Names()) != 1 {
 				panic("cannot complete unflattened Image")
 			}
 
-			imageNames = append(imageNames, image.Names[0])
+			imageNames = append(imageNames, image.Names()[0])
 		}
 	}
 
@@ -158,15 +159,16 @@ func completionImageNamesFiltered(_ *cobra.Command, args []string, _ string) ([]
 	if images, err := podman.GetImages(true); err != nil {
 		logrus.Debugf("Getting all images failed: %s", err)
 	} else {
-		for _, image := range images {
+		for images.Next() {
 			skip := false
 
-			if len(image.Names) != 1 {
+			image := images.Get()
+			if len(image.Names()) != 1 {
 				panic("cannot complete unflattened Image")
 			}
 
 			for _, arg := range args {
-				if arg == image.Names[0] {
+				if arg == image.Names()[0] {
 					skip = true
 					break
 				}
@@ -176,7 +178,7 @@ func completionImageNamesFiltered(_ *cobra.Command, args []string, _ string) ([]
 				continue
 			}
 
-			imageNames = append(imageNames, image.Names[0])
+			imageNames = append(imageNames, image.Names()[0])
 		}
 	}
 

src/cmd/list.go

@@ -81,7 +81,7 @@ func list(cmd *cobra.Command, args []string) error {
 		lsImages = false
 	}
 
-	var images []podman.Image
+	var images *podman.Images
 	var containers []podman.Container
 	var err error
 
@@ -147,26 +147,27 @@ func listHelp(cmd *cobra.Command, args []string) {
 	}
 }
 
-func listOutput(images []podman.Image, containers []podman.Container) {
-	if len(images) != 0 {
+func listOutput(images *podman.Images, containers []podman.Container) {
+	if images.Len() != 0 {
 		writer := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
 		fmt.Fprintf(writer, "%s\t%s\t%s\n", "IMAGE ID", "IMAGE NAME", "CREATED")
 
-		for _, image := range images {
-			if len(image.Names) != 1 {
+		for images.Next() {
+			image := images.Get()
+			if len(image.Names()) != 1 {
 				panic("cannot list unflattened Image")
 			}
 
 			fmt.Fprintf(writer, "%s\t%s\t%s\n",
-				utils.ShortID(image.ID),
-				image.Names[0],
-				image.Created)
+				utils.ShortID(image.ID()),
+				image.Names()[0],
+				image.Created())
 		}
 
 		writer.Flush()
 	}
 
-	if len(images) != 0 && len(containers) != 0 {
+	if images.Len() != 0 && len(containers) != 0 {
 		fmt.Println()
 	}
 

src/cmd/rmi.go

@@ -76,8 +76,9 @@ func rmi(cmd *cobra.Command, args []string) error {
 			return errors.New("failed to get images")
 		}
 
-		for _, image := range toolboxImages {
-			imageID := image.ID
+		for toolboxImages.Next() {
+			image := toolboxImages.Get()
+			imageID := image.ID()
 			if err := podman.RemoveImage(imageID, rmiFlags.forceDelete); err != nil {
 				fmt.Fprintf(os.Stderr, "Error: %s\n", err)
 				continue
@@ -94,8 +95,14 @@ func rmi(cmd *cobra.Command, args []string) error {
 		}
 
 		for _, image := range args {
-			if _, err := podman.IsToolboxImage(image); err != nil {
-				fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+			imageObj, err := podman.InspectImage(image)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "Error: failed to inspect image %s\n", image)
+				continue
+			}
+
+			if !imageObj.IsToolbx() {
+				fmt.Fprintf(os.Stderr, "Error: %s is not a Toolbx image\n", image)
 				continue
 			}
 

src/meson.build

@@ -23,6 +23,7 @@ sources = files(
   'pkg/nvidia/nvidia.go',
   'pkg/podman/container.go',
   'pkg/podman/errors.go',
+  'pkg/podman/image.go',
   'pkg/podman/podman.go',
   'pkg/podman/containerInspect_test.go',
   'pkg/shell/shell.go',

src/pkg/podman/image.go

@@ -0,0 +1,254 @@
+/*
+ * Copyright © 2025 – 2026 Red Hat Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package podman
+
+import (
+	"encoding/json"
+
+	"github.com/containers/toolbox/pkg/utils"
+)
+
+type Image interface {
+	Created() string
+	ID() string
+	IsToolbx() bool
+	Labels() map[string]string
+	Names() []string
+	RepoTags() []string
+}
+
+type Images struct {
+	data []imageImages
+	i    int
+}
+
+type imageImages struct {
+	created  string
+	id       string
+	labels   map[string]string
+	names    []string
+	repoTags []string
+}
+
+type imageInspect struct {
+	created      string
+	entrypoint   []string
+	envVars      []string
+	id           string
+	labels       map[string]string
+	namesHistory []string
+	repoTags     []string
+}
+
+type imageSlice []imageImages
+
+func (images *Images) Get() Image {
+	if images.i < 1 {
+		panic("called Images.Get() without calling Images.Next()")
+	}
+
+	image := images.data[images.i-1]
+	return &image
+}
+
+func (images *Images) Len() int {
+	return len(images.data)
+}
+
+func (images *Images) Next() bool {
+	available := images.i < len(images.data)
+	if available {
+		images.i++
+	}
+
+	return available
+}
+
+func (images *Images) Reset() {
+	images.i = 0
+}
+
+func (image *imageImages) Created() string {
+	return image.created
+}
+
+func (image *imageImages) flattenNames(fillNameWithID bool) []imageImages {
+	var ret []imageImages
+
+	if len(image.Names()) == 0 {
+		flattenedImage := *image
+
+		if fillNameWithID {
+			shortID := utils.ShortID(image.ID())
+			flattenedImage.setNames([]string{shortID})
+		} else {
+			flattenedImage.setNames([]string{"<none>"})
+		}
+
+		ret = []imageImages{flattenedImage}
+		return ret
+	}
+
+	ret = make([]imageImages, 0, len(image.Names()))
+
+	for _, name := range image.Names() {
+		flattenedImage := *image
+		flattenedImage.setNames([]string{name})
+		ret = append(ret, flattenedImage)
+	}
+
+	return ret
+}
+
+func (image *imageImages) ID() string {
+	return image.id
+}
+
+func (image *imageImages) IsToolbx() bool {
+	return isToolbx(image.labels)
+}
+
+func (image *imageImages) Labels() map[string]string {
+	return image.labels
+}
+
+func (image *imageImages) Names() []string {
+	return image.names
+}
+
+func (image *imageImages) setNames(names []string) {
+	image.names = names
+}
+
+func (image *imageImages) RepoTags() []string {
+	return image.repoTags
+}
+
+func (image *imageImages) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Created  interface{}
+		ID       string
+		Labels   map[string]string
+		Names    []string
+		RepoTags []string
+	}
+
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+
+	// Until Podman 2.0.x the field 'Created' held a human-readable string in
+	// format "5 minutes ago". Since Podman 2.1 the field holds an integer with
+	// Unix time. Go interprets numbers in JSON as float64.
+	switch value := raw.Created.(type) {
+	case string:
+		image.created = value
+	case float64:
+		image.created = utils.HumanDuration(int64(value))
+	}
+
+	image.id = raw.ID
+	image.labels = raw.Labels
+	image.names = raw.Names
+	image.repoTags = raw.RepoTags
+	return nil
+}
+
+func (image *imageInspect) Created() string {
+	return image.created
+}
+
+func (image *imageInspect) Entrypoint() []string {
+	return image.entrypoint
+}
+
+func (image *imageInspect) EnvVars() []string {
+	return image.envVars
+}
+
+func (image *imageInspect) ID() string {
+	return image.id
+}
+
+func (image *imageInspect) IsToolbx() bool {
+	return isToolbx(image.labels)
+}
+
+func (image *imageInspect) Labels() map[string]string {
+	return image.labels
+}
+
+func (image *imageInspect) Names() []string {
+	return image.namesHistory
+}
+
+func (image *imageInspect) RepoTags() []string {
+	return image.repoTags
+}
+
+func (image *imageInspect) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Created interface{}
+		ID      string
+		Config  struct {
+			Labels     map[string]string
+			Env        []string
+			Entrypoint []string
+		}
+		NamesHistory []string
+		RepoTags     []string
+	}
+
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+
+	switch value := raw.Created.(type) {
+	case string:
+		image.created = value
+	case float64:
+		image.created = utils.HumanDuration(int64(value))
+	}
+
+	image.id = raw.ID
+	image.labels = raw.Config.Labels
+	image.envVars = raw.Config.Env
+	image.namesHistory = raw.NamesHistory
+	image.repoTags = raw.RepoTags
+	image.entrypoint = raw.Config.Entrypoint
+	return nil
+}
+
+func (images imageSlice) Len() int {
+	return len(images)
+}
+
+func (images imageSlice) Less(i, j int) bool {
+	if len(images[i].Names()) != 1 {
+		panic("cannot sort unflattened Images")
+	}
+
+	if len(images[j].Names()) != 1 {
+		panic("cannot sort unflattened Images")
+	}
+
+	return images[i].Names()[0] < images[j].Names()[0]
+}
+
+func (images imageSlice) Swap(i, j int) {
+	images[i], images[j] = images[j], images[i]
+}