composeproject

package
v1.2.1 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package composeproject loads a Compose project and turns the scheduled entries of its top-level `jobs:` into job definitions Ofelia can schedule, following ADR-004 (docs/adr/ADR-004-compose-jobs-as-job-source.md).

Loading uses compose-go, the reference implementation of the Compose specification. Execution is not part of this package: the jobs it returns are run through the `docker compose` CLI by core.ComposeJob.

Only a documented subset of the trigger model is accepted. Everything else is rejected at load time with an error that names the job and the setting, because mapping a setting silently to a different behavior would be a compatibility bug.

Index

Constants

View Source
const (
	MissedFiresOne    = "one"
	MissedFiresSkip   = "skip"
	ConcurrencyForbid = "forbid"
	ConcurrencyQueue  = "queue"
)

The schedule policies of the Compose specification.

Variables

View Source
var (
	ErrUnsupportedTrigger = errors.New("unsupported compose job trigger")
	ErrInvalidSpec        = errors.New("invalid compose project")
)

Errors returned for job definitions outside the supported subset. Each returned error wraps one of them and names the project, job and setting.

Functions

func Revision

func Revision(project *types.Project) (string, error)

Revision returns a short hash of the loaded, normalized model.

Types

type ComposeGoLoader

type ComposeGoLoader struct{}

ComposeGoLoader loads projects with compose-go, using Ofelia's own process environment for interpolation, as the docker CLI does.

func (ComposeGoLoader) Load

func (ComposeGoLoader) Load(ctx context.Context, spec Spec) (*Project, error)

Load reads, merges and interpolates the project, then extracts its jobs.

type Job

type Job struct {
	// Name is the job name in the Compose file.
	Name string
	// Schedule is the cron expression for Ofelia's scheduler, prefixed with
	// CRON_TZ=<zone> when the job names a time zone.
	Schedule string
	// TimeZone is the zone the schedule is evaluated in: the job's timezone,
	// or a description of the scheduler's local zone when the job has none.
	TimeZone string
	// Revision identifies the job's own definition in the loaded model. It
	// changes only when this job changes, so a reload replaces only the jobs
	// whose definition changed.
	Revision string
	// MissedFires is the schedule's missed_fires policy, MissedFiresOne or
	// MissedFiresSkip; unset in the file means one.
	MissedFires string
	// Concurrency is the schedule's concurrency policy, ConcurrencyForbid or
	// ConcurrencyQueue; unset in the file means forbid.
	Concurrency string
}

Job is one scheduled Compose job.

func (Job) NeedsScheduleState

func (j Job) NeedsScheduleState() bool

NeedsScheduleState reports whether the job's schedule needs Ofelia's durable schedule state (ADR-005): a catch-up for a missed fire, or a queue slot.

type Loader

type Loader interface {
	Load(ctx context.Context, spec Spec) (*Project, error)
}

Loader loads a Compose project. It exists so that the cli package does not depend on compose-go directly and tests can substitute a fixture.

type Project

type Project struct {
	// Name is the resolved Compose project name.
	Name string
	// WorkingDir is the resolved, absolute project directory.
	WorkingDir string
	// Profiles are the active profiles the project was loaded with, from the
	// registration or, when it names none, from COMPOSE_PROFILES. A run passes
	// them explicitly, so it uses exactly the loaded selection.
	Profiles []string
	// Revision identifies the loaded model; it changes when the merged,
	// interpolated configuration changes.
	Revision string
	// Jobs are the scheduled jobs, sorted by name.
	Jobs []Job
	// Unscheduled names the active jobs without a schedule; they stay
	// manual-only and are not scheduled by Ofelia.
	Unscheduled []string
	// Snapshot is the resolved execution model. It and SnapshotFiles may
	// contain secrets; callers must never expose them in logs or API output.
	Snapshot string
	// SnapshotFiles captures configs and secrets backed by a file or an
	// environment variable, keyed by resource kind and name.
	SnapshotFiles map[string]domain.ComposeSnapshotFile
	// SnapshotEnvironment preserves environment-backed config/secret inputs
	// on Compose's native upload path rather than turning them into bind mounts.
	SnapshotEnvironment map[string]string
}

Project is a loaded Compose project with the jobs Ofelia schedules.

func Extract

func Extract(registration string, project *types.Project) (*Project, error)

Extract applies the supported trigger subset to a loaded project. Jobs behind an inactive profile are ignored, active jobs without a schedule are listed as unscheduled, and every unsupported setting is reported. When any job is rejected, Extract returns all rejections joined and no project.

type Spec

type Spec struct {
	// Name is the registration name, the prefix of every job name.
	Name string
	// Files are the Compose files, merged in this order.
	Files []string
	// Profiles are activated while loading; jobs behind other profiles stay
	// unarmed, as the specification defines.
	Profiles []string
	// EnvFiles replace the default .env file for interpolation.
	EnvFiles []string
	// ProjectName overrides the project name compose-go would derive.
	ProjectName string
	// ProjectDirectory overrides the working directory of the project.
	ProjectDirectory string
}

Spec is what an operator registers: the files, profiles and environment that select one Compose project. It never configures containers; the workload stays defined in the Compose files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL