Help us shape the future of Go! Take the 2026 Go Developer Survey

image

package
v2.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 25, 2026 License: BSD-3-Clause Imports: 64 Imported by: 0

Documentation

Overview

Package image owns Docker image operations, metadata, attestations, patching, and routes.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildVolumeUsageMap 

func BuildVolumeUsageMap(containers []container.Summary, projectIDByName map[string]string) map[string][]imagetypes.UsedBy

func MapDockerImagesToDTOs 

func MapDockerImagesToDTOs(
	dockerImages []image.Summary,
	containers []container.Summary,
	usageMap map[string][]imagetypes.UsedBy,
	updateMap map[string]*imageupdate.ImageUpdateRecord,
	vulnerabilityMap map[string]*vulnerabilitytypes.ScanSummary,
) []imagetypes.Summary

func RegisterImages 

func RegisterImages(
	api huma.API,
	dockerService *docker.DockerClientService,
	imageService *ImageService,
	imageUpdateService *imageupdate.ImageUpdateService,
	settingsService *settings.SettingsService,
	buildService *build.BuildService,
	activityService *activity.ActivityService,
	uploadService *upload.UploadService,
	appCtx handlerutil.ActivityAppContext,
)

RegisterImages registers image management routes using Huma.

func ShouldRetryAnonymousPull 

func ShouldRetryAnonymousPull(pullOptions client.ImagePullOptions, pullErr error) bool

Types

type BuildImageInput 

type BuildImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Body          types.BuildRequest
}

type ExportImageInput 

type ExportImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	ImageName     string `path:"name" doc:"Image ID or image reference"`
}

type GetImageBuildInput 

type GetImageBuildInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	BuildID       string `path:"buildId" doc:"Build ID"`
}

type GetImageHistoryInput 

type GetImageHistoryInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	ImageName     string `path:"name" doc:"Image ID or image reference"`
}

type GetImageInput 

type GetImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	ImageID       string `path:"imageId" doc:"Image ID"`
}

type GetImageUsageCountsInput 

type GetImageUsageCountsInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
}

type ImageHandler 

type ImageHandler struct {
	// contains filtered or unexported fields
}

ImageHandler provides Huma-based image management endpoints.

func (*ImageHandler) BuildImage 

func (h *ImageHandler) BuildImage(ctx context.Context, input *BuildImageInput) (*huma.StreamResponse, error)

BuildImage builds a Docker image with streaming progress.

func (*ImageHandler) ExportImage 

func (h *ImageHandler) ExportImage(ctx context.Context, input *ExportImageInput) (*huma.StreamResponse, error)

ExportImage streams a Docker image tar archive.

func (*ImageHandler) GetImage 

func (h *ImageHandler) GetImage(ctx context.Context, input *GetImageInput) (*handlerutil.Out[image.DetailSummary], error)

GetImage returns an image by ID.

func (*ImageHandler) GetImageBuild 

func (h *ImageHandler) GetImageBuild(ctx context.Context, input *GetImageBuildInput) (*handlerutil.Out[image.BuildRecord], error)

GetImageBuild returns a single build history entry.

func (*ImageHandler) GetImageHistory 

func (h *ImageHandler) GetImageHistory(ctx context.Context, input *GetImageHistoryInput) (*handlerutil.Out[[]image.HistoryItem], error)

GetImageHistory returns Docker image layer history.

func (*ImageHandler) GetImageUsageCounts 

func (h *ImageHandler) GetImageUsageCounts(ctx context.Context, input *GetImageUsageCountsInput) (*handlerutil.Out[image.UsageCounts], error)

GetImageUsageCounts returns counts of images by usage status.

func (*ImageHandler) ListImageBuilds 

func (h *ImageHandler) ListImageBuilds(ctx context.Context, input *ListImageBuildsInput) (*handlerutil.Page[image.BuildRecord], error)

ListImageBuilds returns a paginated list of image build history entries.

func (*ImageHandler) ListImages 

func (h *ImageHandler) ListImages(ctx context.Context, input *ListImagesInput) (*ListImagesOutput, error)

ListImages returns a paginated list of images.

func (*ImageHandler) PruneImages 

func (h *ImageHandler) PruneImages(ctx context.Context, input *PruneImagesInput) (*handlerutil.Out[image.PruneReport], error)

PruneImages removes unused Docker images.

func (*ImageHandler) PullImage 

func (h *ImageHandler) PullImage(ctx context.Context, input *PullImageInput) (*huma.StreamResponse, error)

PullImage pulls a Docker image with streaming progress.

func (*ImageHandler) RemoveImage 

func (h *ImageHandler) RemoveImage(ctx context.Context, input *RemoveImageInput) (*handlerutil.Out[base.MessageResponse], error)

RemoveImage removes a Docker image.

func (*ImageHandler) SearchImages 

func (h *ImageHandler) SearchImages(ctx context.Context, input *SearchImagesInput) (*handlerutil.Out[[]image.SearchResult], error)

SearchImages searches Docker Hub images.

func (*ImageHandler) TagImage 

func (h *ImageHandler) TagImage(ctx context.Context, input *TagImageInput) (*handlerutil.Out[base.MessageResponse], error)

TagImage adds a repository tag to an image.

func (*ImageHandler) UploadImage 

func (h *ImageHandler) UploadImage(ctx context.Context, input *UploadImageInput) (*handlerutil.Out[image.LoadResult], error)

UploadImage uploads a Docker image from a tar archive.

type ImageService 

type ImageService struct {
	// contains filtered or unexported fields
}

func NewImageService 

func NewImageService(
	db *database.DB,
	dockerService *dockerInternal.DockerClientService,
	registryService *registry.ContainerRegistryService,
	imageUpdateService *imageupdate.ImageUpdateService,
	vulnerabilityService *vulnerability.VulnerabilityService,
	eventService *event.EventService,
	settingsService *settings.SettingsService,
	activityService *activity.ActivityService,
) *ImageService

func (*ImageService) AggregateImageCounts added in v2.16.1 

func (s *ImageService) AggregateImageCounts(ctx context.Context) (base.ApiResponse[imagetypes.UsageCounts], error)

func (*ImageService) AggregateImages added in v2.16.1 

func (s *ImageService) AggregateImages(ctx context.Context, params pagination.QueryParams) (imagetypes.ListResponse, error)

func (*ImageService) BuildProjectIDMap 

func (s *ImageService) BuildProjectIDMap(ctx context.Context, containers []container.Summary) map[string]string

BuildProjectIDMap returns a map of compose project name → project ID for any containers that carry the com.docker.compose.project label. The lookup uses a short-TTL cache shared across all callers of this ImageService instance.

func (*ImageService) ExportImage 

func (s *ImageService) ExportImage(ctx context.Context, imageName string) (io.ReadCloser, error)

ExportImage returns a tar stream for one Docker image.

func (*ImageService) GetImageDetail 

func (s *ImageService) GetImageDetail(ctx context.Context, id string) (*imagetypes.DetailSummary, error)

GetImageDetail returns a DetailSummary for the given image ID. It fetches ImageInspect and ImageList concurrently so the size field reflects the same metric shown in the image table (docker image ls / docker system df).

func (*ImageService) GetImageHistory 

func (s *ImageService) GetImageHistory(ctx context.Context, imageName string) ([]imagetypes.HistoryItem, error)

GetImageHistory returns layer history for an image.

func (*ImageService) GetUpdateInfoByContainers added in v2.11.0 

func (s *ImageService) GetUpdateInfoByContainers(ctx context.Context, containers []container.Summary) (map[string]*imagetypes.UpdateInfo, error)

GetUpdateInfoByContainers returns the stored check matching each container's current policy, keyed by container ID. Digest policies read the image-level record for the container's runtime image ID, so a check recorded under another local tag of the same image still applies. Tag policies read the container's own record and require an exact policy key. Containers that opted out of update checks are omitted; disabling automatic installation does not hide results.

func (*ImageService) GetUpdateInfoByImageIDs 

func (s *ImageService) GetUpdateInfoByImageIDs(ctx context.Context, imageIDs []string) (map[string]*imagetypes.UpdateInfo, error)

GetUpdateInfoByImageIDs returns a map of image ID to UpdateInfo for the given image IDs. This is used by the container service to populate update info for containers.

func (*ImageService) GetUpdateInfoByImageRefs 

func (s *ImageService) GetUpdateInfoByImageRefs(ctx context.Context, imageRefs []string) (map[string]*imagetypes.UpdateInfo, error)

GetUpdateInfoByImageRefs returns persisted update information keyed by the original image reference string.

func (*ImageService) ImageExistsLocally 

func (s *ImageService) ImageExistsLocally(ctx context.Context, imageName string) (bool, error)

func (*ImageService) ImageLastTagTime added in v2.8.1 

func (s *ImageService) ImageLastTagTime(ctx context.Context, imageName string) (time.Time, error)

ImageLastTagTime returns when the local image was last tagged, zero when the engine doesn't report it. Pull-policy refresh windows compare against this timestamp, the same clock compose v5.5.0 uses.

func (*ImageService) ListImagesPaginated 

func (s *ImageService) ListImagesPaginated(ctx context.Context, params pagination.QueryParams) ([]imagetypes.Summary, pagination.Response, error)

func (*ImageService) LoadImageFromReader 

func (s *ImageService) LoadImageFromReader(ctx context.Context, reader io.Reader, fileName string, user usertypes.Actor, maxSizeBytes int64) (*imagetypes.LoadResult, error)

func (*ImageService) PatchWorkflow added in v2.16.0 

func (s *ImageService) PatchWorkflow() *flow.Workflow

PatchWorkflow is the scheduled auto-patch workflow.

func (*ImageService) PruneImages 

func (s *ImageService) PruneImages(ctx context.Context, options system.PruneImagesOptions) (*image.PruneReport, error)

func (*ImageService) Pull added in v2.17.0 

func (s *ImageService) Pull(ctx context.Context, req PullRequest) error

Pull pulls req.Ref within the dockerImagePullTimeout setting and reconciles the pulled reference's update state.

func (*ImageService) PullImage 

func (s *ImageService) PullImage(ctx context.Context, imageName string, progressWriter io.Writer, user usertypes.Actor, externalCreds []containerregistry.Credential) error

func (*ImageService) PullOptionsWithAuth 

func (s *ImageService) PullOptionsWithAuth(ctx context.Context, imageRef string, externalCreds []containerregistry.Credential) (client.ImagePullOptions, error)

func (*ImageService) RecoverInterruptedPatches added in v2.17.0 

func (s *ImageService) RecoverInterruptedPatches(ctx context.Context) error

func (*ImageService) RegisterWorkflows added in v2.16.0 

func (s *ImageService) RegisterWorkflows(engine *flow.Engine) error

RegisterWorkflows defines the scheduled auto-patch: find images with fixable findings, patch each one in turn, then report. Call it before the host starts.

func (*ImageService) RemoteDigest added in v2.17.0 

func (s *ImageService) RemoteDigest(ctx context.Context, imageRef string, credentials []containerregistry.Credential) (string, error)

RemoteDigest resolves imageRef's registry digest within the registry timeout setting.

func (*ImageService) RemoveImage 

func (s *ImageService) RemoveImage(ctx context.Context, id string, force bool, user usertypes.Actor) error

func (*ImageService) SearchImages 

func (s *ImageService) SearchImages(ctx context.Context, term string) ([]imagetypes.SearchResult, error)

SearchImages searches the configured Docker registry for images.

func (*ImageService) TagImage 

func (s *ImageService) TagImage(ctx context.Context, source string, req imagetypes.TagRequest, user usertypes.Actor) error

TagImage adds a repository tag to an existing image.

type ListImageBuildsInput 

type ListImageBuildsInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Search        string `query:"search" doc:"Search query"`
	Sort          string `query:"sort" doc:"Column to sort by"`
	Order         string `query:"order" default:"desc" doc:"Sort direction (asc or desc)"`
	Start         int    `query:"start" default:"0" doc:"Start index for pagination"`
	Limit         int    `query:"limit" default:"20" doc:"Number of items per page"`
	Status        string `query:"status" doc:"Filter by status"`
	Provider      string `query:"provider" doc:"Filter by provider"`
}

type ListImagesInput 

type ListImagesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Search        string `query:"search" doc:"Search query"`
	Sort          string `query:"sort" doc:"Column to sort by"`
	Order         string `query:"order" default:"asc" doc:"Sort direction (asc or desc)"`
	Start         int    `query:"start" default:"0" doc:"Start index for pagination"`
	Limit         int    `query:"limit" default:"20" doc:"Number of items per page"`
	InUse         string `query:"inUse" doc:"Filter by in-use status (true/false)"`
	Updates       string `query:"updates" doc:"Filter by update availability (true/false)"`
}

type ListImagesOutput 

type ListImagesOutput struct {
	Body image.ListResponse
}

ListImagesOutput is the image list response including the upload limit.

type Module 

type Module struct {
	// contains filtered or unexported fields
}

func New 

func New(
	service *ImageService,
	dockerService *docker.DockerClientService,
	imageUpdate *imageupdate.ImageUpdateService,
	settingsService *settings.SettingsService,
	buildService *build.BuildService,
	activityService *activity.ActivityService,
	uploadService *upload.UploadService,
) *Module

func (*Module) RegisterRoutes 

func (m *Module) RegisterRoutes(api huma.API, appCtx handlerutil.ActivityAppContext)

func (*Module) Service 

func (m *Module) Service() *ImageService

type PruneImagesInput 

type PruneImagesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Dangling      bool   `query:"dangling" doc:"Only remove dangling images"`
	Body          *struct {
		Mode     *string             `json:"mode,omitempty"`
		Until    *string             `json:"until,omitempty"`
		Dangling *bool               `json:"dangling,omitempty"`
		Filters  map[string][]string `json:"filters,omitempty"`
	}
}

type PullImageInput 

type PullImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Body          image.PullOptions
}

type PullRequest added in v2.17.0 

type PullRequest struct {
	// Ref is the reference pulled from the registry.
	Ref string
	// Tag, when set, is the reference Ref is tagged as after the pull; it is the one reconciled.
	Tag         string
	Progress    io.Writer
	User        usertypes.Actor
	Credentials []containerregistry.Credential
}

PullRequest describes one pull through Pull.

type RemoveImageInput 

type RemoveImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	ImageID       string `path:"imageId" doc:"Image ID"`
	Force         bool   `query:"force" doc:"Force removal"`
}

type SearchImagesInput 

type SearchImagesInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Term          string `query:"term" doc:"Search term"`
}

type TagImageInput 

type TagImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	ImageName     string `path:"name" doc:"Image ID or image reference"`
	Body          image.TagRequest
}

type UploadImageInput 

type UploadImageInput struct {
	EnvironmentID string `path:"id" doc:"Environment ID"`
	Body          uploadtypes.ConsumeRequest
}

Source Files

View all Source files

Directories

Path Synopsis
children
attestations
patch

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.