session

package
v1.21.1 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package session manages container states and reporting during a Watchtower update session. It tracks container progress, categorizes outcomes, and generates reports for scanned, updated, failed, skipped, stale, fresh, and restarted containers.

Key components:

  • State: Enum for container states (e.g., Updated, Failed).
  • ContainerStatus: Tracks individual container details and state.
  • Progress: Maps container statuses during a session.
  • Report: Categorizes and sorts container outcomes.

Usage example: 

progress := session.Progress{}
progress.AddScanned(container, newImageID)
progress.MarkForUpdate(container.ID())
report := progress.Report()
scanned := report.Scanned()

The package integrates with types.Container and uses zerolog for logging session events.

Index

Constants

View Source 
const (
	UnknownStateString   = "Unknown"
	SkippedStateString   = "Skipped"
	ScannedStateString   = "Scanned"
	UpdatedStateString   = "Updated"
	FailedStateString    = "Failed"
	FreshStateString     = "Fresh"
	StaleStateString     = "Stale"
	RestartedStateString = "Restarted"
)

State string constants.

Variables

This section is empty.

Functions

func NewReport 

func NewReport(log *zerolog.Logger, progress Progress) types.Report

NewReport creates a report from progress data.

Parameters:

  • progress: Progress map to process.

Returns:

  • types.Report: Categorized and sorted report.

Types

type ContainerStatus 

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

ContainerStatus holds a container's state during a session.

func UpdateFromContainer 

func UpdateFromContainer(log *zerolog.Logger,
	container types.Container,
	newImage types.ImageID,
	state State,
	params types.UpdateParams,
) *ContainerStatus

UpdateFromContainer creates a status from container data.

Parameters:

  • container: Container to update from.
  • newImage: Latest image ID.
  • state: Container state.
  • params: Update parameters for monitor-only check.

Returns:

  • *ContainerStatus: Updated status.

func (*ContainerStatus) CooldownAge 

func (u *ContainerStatus) CooldownAge() string

CooldownAge returns the human-readable image age.

func (*ContainerStatus) CooldownDelay 

func (u *ContainerStatus) CooldownDelay() string

CooldownDelay returns the human-readable cooldown duration.

func (*ContainerStatus) CooldownEligibleAt 

func (u *ContainerStatus) CooldownEligibleAt() time.Time

CooldownEligibleAt returns the time when the container becomes eligible for update.

Returns:

  • time.Time: The eligible-at timestamp (zero if not set).

func (*ContainerStatus) CooldownPassed 

func (u *ContainerStatus) CooldownPassed() bool

CooldownPassed returns whether the image passed the cooldown check.

func (*ContainerStatus) CooldownRemaining 

func (u *ContainerStatus) CooldownRemaining() string

CooldownRemaining returns the human-readable remaining cooldown time.

func (*ContainerStatus) CurrentImageID 

func (u *ContainerStatus) CurrentImageID() types.ImageID

CurrentImageID returns the original image ID.

Returns:

  • types.ImageID: Image ID at session start.

func (*ContainerStatus) Error 

func (u *ContainerStatus) Error() string

Error returns the session error, if any.

Returns:

  • string: Error message or empty if none.

func (*ContainerStatus) ID 

func (u *ContainerStatus) ID() types.ContainerID

ID returns the container ID.

Returns:

  • types.ContainerID: Container's unique identifier.

func (*ContainerStatus) ImageName 

func (u *ContainerStatus) ImageName() string

ImageName returns the image name with tag.

Returns:

  • string: Image name (e.g., "nginx:latest").

func (*ContainerStatus) IsMonitorOnly 

func (u *ContainerStatus) IsMonitorOnly() bool

IsMonitorOnly returns whether the container is in monitor-only mode.

Returns:

  • bool: True if monitor-only, false otherwise.

func (*ContainerStatus) LatestImageID 

func (u *ContainerStatus) LatestImageID() types.ImageID

LatestImageID returns the latest image ID.

Returns:

  • types.ImageID: Newest image ID from session.

func (*ContainerStatus) Name 

func (u *ContainerStatus) Name() string

Name returns the container name.

Returns:

  • string: Container's name.

func (*ContainerStatus) NewContainerID 

func (u *ContainerStatus) NewContainerID() types.ContainerID

NewContainerID returns the new container ID after update.

Returns:

  • types.ContainerID: New container ID or empty if not updated.

func (*ContainerStatus) SetCooldownInfo 

func (u *ContainerStatus) SetCooldownInfo(
	age,
	delay,
	remaining string,
	eligibleAt time.Time,
	passed bool,
)

SetCooldownInfo sets cooldown metadata for this container.

Parameters:

  • age: Human-readable image age (e.g., "47 days, 11 hours").
  • delay: Human-readable cooldown duration (e.g., "24 hours").
  • remaining: Human-readable remaining time (empty if passed).
  • eligibleAt: Time when the container becomes eligible for update.
  • passed: True if the image passed the cooldown check.

func (*ContainerStatus) SetNewContainerID 

func (u *ContainerStatus) SetNewContainerID(newID types.ContainerID)

SetNewContainerID sets the new container ID after update.

Parameters:

  • newID: The new container ID.

func (*ContainerStatus) State 

func (u *ContainerStatus) State() string

State returns the human-readable state name.

Returns:

  • string: State as a string (e.g., "Updated").

type Progress 

type Progress map[types.ContainerID]*ContainerStatus

Progress tracks container statuses during a session.

func (Progress) Add 

func (m Progress) Add(log *zerolog.Logger, update *ContainerStatus)

Add inserts a container status into the progress map.

Parameters:

  • update: Status to add.

func (Progress) AddScanned 

func (m Progress) AddScanned(log *zerolog.Logger,
	container types.Container,
	newImage types.ImageID,
	params types.UpdateParams,
)

AddScanned adds a container as scanned with a new image.

Parameters:

  • container: Container to add.
  • newImage: Latest image ID.
  • params: Update parameters for monitor-only check.

func (Progress) AddSkipped 

func (m Progress) AddSkipped(log *zerolog.Logger, container types.Container, err error, params types.UpdateParams)

AddSkipped adds a container as skipped with an error.

Parameters:

  • container: Container to add.
  • err: Skip reason error.
  • params: Update parameters for monitor-only check.

func (Progress) MarkForUpdate 

func (m Progress) MarkForUpdate(log *zerolog.Logger, containerID types.ContainerID)

MarkForUpdate sets a container's state to updated.

Parameters:

  • containerID: ID of container to mark.

func (Progress) MarkRestarted 

func (m Progress) MarkRestarted(log *zerolog.Logger, containerID types.ContainerID)

MarkRestarted sets a container's state to restarted.

Parameters:

  • containerID: ID of container to mark.

func (Progress) Report 

func (m Progress) Report(log *zerolog.Logger) types.Report

Report generates a report from the progress data.

Returns:

  • types.Report: New report instance.

func (Progress) Restarted 

func (m Progress) Restarted(log *zerolog.Logger) []types.ContainerReport

Restarted returns all containers marked as restarted.

Returns:

  • []types.ContainerReport: List of restarted containers.

func (Progress) SetCooldownInfo 

func (m Progress) SetCooldownInfo(log *zerolog.Logger,
	containerID types.ContainerID,
	age,
	delay,
	remaining string,
	eligibleAt time.Time,
	passed bool,
)

SetCooldownInfo sets cooldown metadata on a container's status.

Parameters:

  • containerID: Container ID.
  • age: Human-readable image age.
  • delay: Human-readable cooldown duration.
  • remaining: Human-readable remaining time (empty if passed).
  • eligibleAt: Time when the container becomes eligible for update.
  • passed: True if the image passed the cooldown check.

func (Progress) UpdateFailed 

func (m Progress) UpdateFailed(log *zerolog.Logger, failures map[types.ContainerID]error)

UpdateFailed marks containers as failed with errors.

Parameters:

  • failures: Map of container IDs to errors.

type SingleContainerReport 

type SingleContainerReport struct {
	UpdatedReports   []types.ContainerReport // Primary container(s) that were updated in this notification
	RestartedReports []types.ContainerReport // Primary container(s) that were restarted in this notification
	ScannedReports   []types.ContainerReport // All containers scanned during the session (for context)
	FailedReports    []types.ContainerReport // All containers that failed to update (for context)
	SkippedReports   []types.ContainerReport // All containers that were skipped (for context)
	StaleReports     []types.ContainerReport // All containers with stale images (for context)
	FreshReports     []types.ContainerReport // All containers with fresh images (for context)
}

SingleContainerReport implements types.Report for individual container notifications.

This struct is used when notification splitting by container is enabled (--notification-split-by-container). Unlike the standard report which groups all containers from a session, SingleContainerReport focuses on a specific container while providing context from all other containers in the session. This allows notifications to be sent separately for each updated or restarted container while maintaining awareness of the overall session state (failed, skipped, stale, fresh containers).

func (*SingleContainerReport) All 

func (r *SingleContainerReport) All() []types.ContainerReport

All returns deduplicated containers, prioritized by state.

Returns:

  • []types.ContainerReport: Sorted, unique list.

func (*SingleContainerReport) Failed 

func (r *SingleContainerReport) Failed() []types.ContainerReport

Failed returns failed containers.

func (*SingleContainerReport) Fresh 

func (r *SingleContainerReport) Fresh() []types.ContainerReport

Fresh returns fresh containers.

func (*SingleContainerReport) Restarted 

func (r *SingleContainerReport) Restarted() []types.ContainerReport

Restarted returns restarted containers.

func (*SingleContainerReport) Scanned 

func (r *SingleContainerReport) Scanned() []types.ContainerReport

Scanned returns scanned containers.

func (*SingleContainerReport) Skipped 

func (r *SingleContainerReport) Skipped() []types.ContainerReport

Skipped returns skipped containers.

func (*SingleContainerReport) Stale 

func (r *SingleContainerReport) Stale() []types.ContainerReport

Stale returns stale containers.

func (*SingleContainerReport) Updated 

func (r *SingleContainerReport) Updated() []types.ContainerReport

Updated returns updated containers (only one for split notifications).

type SortableContainers 

type SortableContainers []types.ContainerReport

SortableContainers implements sort.Interface for reports.

func (SortableContainers) Len 

func (s SortableContainers) Len() int

Len returns the slice length.

Returns:

  • int: Number of reports.

func (SortableContainers) Less 

func (s SortableContainers) Less(i, j int) bool

Less compares container IDs.

Parameters:

  • i, j: Indices to compare.

Returns:

  • bool: True if i's ID is less than j's.

func (SortableContainers) Swap 

func (s SortableContainers) Swap(i, j int)

Swap exchanges two reports.

Parameters:

  • i, j: Indices to swap.

type State 

type State int

State indicates what the current state is of the container. 

const (
	UnknownState   State = iota // Uninitialized state.
	SkippedState                // Container skipped.
	ScannedState                // Container scanned.
	UpdatedState                // Container updated.
	FailedState                 // Container update failed.
	FreshState                  // Container is fresh.
	StaleState                  // Container is stale.
	RestartedState              // Container restarted (linked dependency).
)

State enum values.

Source Files

View all Source files

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.