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 ¶
const ( MissedFiresOne = "one" MissedFiresSkip = "skip" ConcurrencyForbid = "forbid" ConcurrencyQueue = "queue" )
The schedule policies of the Compose specification.
Variables ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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.