Documentation
¶
Overview ¶
Package jobdef provides job definition utilities including collection and import of YAML manifests.
Index ¶
- Variables
- func CollectDefinitions(paths []string, validate bool) ([]schema.Definition, error)
- func ContractBreakResponse(err error) (any, bool)
- func IsYAML(path string) bool
- func ResolveYAMLFiles(paths []string) ([]string, error)
- func SetTriggerMutationHook(hook TriggerMutationHook)
- func ValidateAgentProfileRefs(ctx context.Context, conn *gorm.DB, defs []schema.Definition) error
- func ValidateDatasetGraph(ctx context.Context, conn *gorm.DB, defs []schema.Definition) error
- func ValidateTriggerChains(ctx context.Context, conn *gorm.DB, defs []schema.Definition) error
- type ApplyOptions
- type Importer
- func (i *Importer) Apply(ctx context.Context, def *schema.Definition) (*models.Job, error)
- func (i *Importer) ApplyWithOptions(ctx context.Context, def *schema.Definition, opts *ApplyOptions) (*models.Job, error)
- func (i *Importer) PruneMissing(ctx context.Context, desiredAliases []string, opts *PruneOptions) (int, error)
- func (i *Importer) ValidateBatch(ctx context.Context, defs []schema.Definition) error
- type Provenance
- type PruneOptions
- type SnapshotQuery
- func (q *SnapshotQuery) ByContentHash(jobID uuid.UUID, contentHash string) (*models.DagSnapshot, error)
- func (q *SnapshotQuery) ByGitCommit(jobID uuid.UUID, commit string) (*models.DagSnapshot, error)
- func (q *SnapshotQuery) Latest(jobID uuid.UUID) (*models.DagSnapshot, error)
- func (q *SnapshotQuery) List(jobID uuid.UUID) ([]models.DagSnapshot, error)
- type TriggerMutationHook
Constants ¶
This section is empty.
Variables ¶
var ( ErrDuplicateJob = errors.New("job alias already exists") ErrProvenanceConflict = errors.New("job definition provenance conflict") ErrJobRunning = errors.New("job has a running run") ErrContractBreak = contractenforce.ErrContractBreakBlocked ErrContractAck = contractenforce.ErrInvalidContractAck )
var ErrTriggerChainCycle = errors.New("trigger chain cycle detected")
Functions ¶
func CollectDefinitions ¶
func CollectDefinitions(paths []string, validate bool) ([]schema.Definition, error)
CollectDefinitions walks the given paths, reads YAML files, and returns all valid Caesium job definitions found. Non-Caesium YAML documents (e.g. Helm charts, Kubernetes manifests) are silently skipped. If validate is true, each definition is validated and errors are returned.
func ContractBreakResponse ¶
ContractBreakResponse returns the stable 409 payload for an apply-time contract enforcement error.
func ResolveYAMLFiles ¶
ResolveYAMLFiles returns all YAML file paths under the given paths.
func SetTriggerMutationHook ¶
func SetTriggerMutationHook(hook TriggerMutationHook)
func ValidateAgentProfileRefs ¶
ValidateAgentProfileRefs verifies that every server-side resource a metadata.remediation block references exists: the AgentProfile named by remediation.profile and the NotificationChannel named by remediation.escalation.channel. This is the server-side half of the lint split docs/design-agent-in-the-loop.md documents: pkg/jobdef's offline validation (which runs with conn == nil, e.g. `caesium job lint`) can only check the references are well-formed and emits a scope note, because these are server-side state. This function closes that gap and is invoked both from POST /v1/jobdefs/lint and from Importer.ValidateBatch inside the apply transaction, mirroring ValidateDatasetGraph's conn-may-be-nil posture.
The built-in models.DefaultTriageOnlyProfileName is treated as always resolvable regardless of DB state: it is the shipped default jobs are advertised to reference, seeded lazily/idempotently — so a job referencing it must never be rejected merely because the row has not been materialized on this particular server yet.
func ValidateDatasetGraph ¶
ValidateDatasetGraph runs the cross-job declared-graph lint over the incoming definitions PLUS the persisted declarations of jobs that are not being replaced: exactly one job produces a given dataset, every consumed dataset resolves to a produced dataset or a declared source across the whole set, and the declared graph is acyclic across jobs. It is the batch counterpart to the per-definition dataset validation in pkg/jobdef (which sees one job at a time and cannot prove a cross-job cycle or a duplicate producer).
conn may be nil (e.g. `caesium job lint` with no server), in which case only the incoming set is checked. The pure graph algorithm lives in internal/freshness so it is unit-testable without a database.
func ValidateTriggerChains ¶
Types ¶
type ApplyOptions ¶
type ApplyOptions struct {
Provenance *Provenance
Force bool
ContractAck *contractenforce.AllowBreaking
ContractWarnings *[]contractenforce.ContractWarning
}
ApplyOptions control optional behaviors for ApplyWithOptions.
type Importer ¶
type Importer struct {
// contains filtered or unexported fields
}
Importer coordinates persistence of job definitions.
func NewImporter ¶
NewImporter creates a new importer. The provided db connection must be non-nil.
func (*Importer) Apply ¶
Apply persists the provided definition and returns the reconciled job record.
func (*Importer) ApplyWithOptions ¶
func (i *Importer) ApplyWithOptions(ctx context.Context, def *schema.Definition, opts *ApplyOptions) (*models.Job, error)
ApplyWithOptions persists the provided definition using the supplied options. Existing jobs are reconciled in place so history remains attached to the same job ID.
func (*Importer) PruneMissing ¶
func (i *Importer) PruneMissing(ctx context.Context, desiredAliases []string, opts *PruneOptions) (int, error)
PruneMissing retires active jobs that are absent from the desired alias set. When opts.SourceID is set, pruning is scoped to jobs imported by that source.
func (*Importer) ValidateBatch ¶
type Provenance ¶
Provenance captures metadata describing the origin of a job definition.
type PruneOptions ¶
type PruneOptions struct {
SourceID string
}
PruneOptions scope the set of jobs that should be retired when pruning.
type SnapshotQuery ¶
type SnapshotQuery struct {
// contains filtered or unexported fields
}
SnapshotQuery provides read-only access to dag_snapshot rows. It does not touch the write path (writeSnapshotTx in importer.go). ctx is propagated to every query via db.WithContext so that request cancellation and deadlines are honoured — matching the house pattern used by other services (trigger, notification, etc.).
func NewSnapshotQuery ¶
func NewSnapshotQuery(ctx context.Context, conn *gorm.DB) *SnapshotQuery
NewSnapshotQuery returns a SnapshotQuery backed by conn.
func (*SnapshotQuery) ByContentHash ¶
func (q *SnapshotQuery) ByContentHash(jobID uuid.UUID, contentHash string) (*models.DagSnapshot, error)
ByContentHash returns the snapshot matching jobID + contentHash, or gorm.ErrRecordNotFound when none matches.
func (*SnapshotQuery) ByGitCommit ¶
func (q *SnapshotQuery) ByGitCommit(jobID uuid.UUID, commit string) (*models.DagSnapshot, error)
ByGitCommit returns the most-recent snapshot for jobID whose git_commit matches commit, or gorm.ErrRecordNotFound when none matches.
func (*SnapshotQuery) Latest ¶
func (q *SnapshotQuery) Latest(jobID uuid.UUID) (*models.DagSnapshot, error)
Latest returns the most-recently written snapshot for jobID, or gorm.ErrRecordNotFound when no snapshot exists.
func (*SnapshotQuery) List ¶
func (q *SnapshotQuery) List(jobID uuid.UUID) ([]models.DagSnapshot, error)
List returns all snapshots for jobID ordered by created_at descending (newest first).
Source Files
Directories