package-updater/internal/master/model/job.go

package model

import (
	"errors"
	"time"
)

// Sentinel errors for jobs.
var (
	// ErrJobActive means the service already has a queued or running job.
	// CreateJob and jobs.Service.Trigger return it together with that job.
	ErrJobActive = errors.New("an update is already in progress for this service")
	// ErrAgentOffline means no connected agent can run the job.
	ErrAgentOffline = errors.New("agent offline")
	// ErrAgentTooOld means the only agent that could run the job speaks a
	// protocol version without jobs.
	ErrAgentTooOld = errors.New("agent too old for updates")
)

// NotUpdatableError says why a service cannot be updated. Reason is shown
// in the UI as is.
type NotUpdatableError struct {
	Reason string
}

func (e *NotUpdatableError) Error() string { return "not updatable: " + e.Reason }

// Reasons a service cannot be updated.
const (
	ReasonSelf      = "updated manually outside the system"
	ReasonContainer = "plain containers cannot be updated"
	ReasonNoTag     = "follows no tag"
	ReasonRemoved   = "service no longer exists"
	ReasonBuilt     = "built from source (build:)"
)

// JobStatus is the state of an update job.
type JobStatus string

// Job statuses. A job moves queued -> running -> succeeded|failed, or
// straight from queued to failed.
const (
	JobQueued    JobStatus = "queued"
	JobRunning   JobStatus = "running"
	JobSucceeded JobStatus = "succeeded"
	JobFailed    JobStatus = "failed"
)

// JobTrigger says what created a job. TriggerManual comes from the UI, TriggerWebhook from POST /update.
type JobTrigger string

// Job triggers.
const (
	TriggerManual  JobTrigger = "manual"
	TriggerWebhook JobTrigger = "webhook"
	TriggerPoll    JobTrigger = "poll"
)

// Job is one update of one service.
type Job struct {
	ID              int64
	ServiceID       int64
	ServiceName     string // Service.DisplayName() of the job's service
	AgentID         *int64 // agent the job was sent to; nil if it never was
	AgentName       string
	FromRef         string
	ToRef           string // "repo:tag" when created; "repo:tag@digest" after success
	Trigger         JobTrigger
	RequestedBy     string // OIDC subject for manual jobs
	Status          JobStatus
	Output          string // empty in ListJobs results
	OutputTruncated bool
	Error           string
	CreatedAt       time.Time
	StartedAt       *time.Time
	FinishedAt      *time.Time
}

// Active reports whether the job is queued or running.
func (j Job) Active() bool { return j.Status == JobQueued || j.Status == JobRunning }

// NewJob is what CreateJob needs to insert a queued job.
type NewJob struct {
	ServiceID   int64
	AgentID     *int64
	FromRef     string
	ToRef       string
	Trigger     JobTrigger
	RequestedBy string
	CreatedAt   time.Time
}

// JobFinish is a job's outcome as reported by the agent.
type JobFinish struct {
	Status          JobStatus // JobSucceeded or JobFailed
	Ref             string    // deployed "repo:tag@digest"; set on success
	Error           string
	Output          string
	OutputTruncated bool
	StartedAt       time.Time // agent clock
	FinishedAt      time.Time // agent clock
}

// JobFilter selects jobs for ListJobs. ServiceID 0 means all services.
// Limit 0 means 100.
type JobFilter struct {
	ServiceID int64
	Limit     int
}

// Route is the hub's choice of agent connection for a job. ConnID identifies
// the connection, so a job is never sent over a connection that replaced the
// one chosen.
type Route struct {
	AgentID int64
	ConnID  uint64
}