Local Object Models

Overview

koji-habitude includes a complete set of local object models that represent koji objects defined in YAML configuration files. These models are validated, processed, and synchronized with remote Koji instances.

Local models are the primary interface for defining and managing koji objects through YAML files. They support dependency resolution, validation, and automatic synchronization with remote koji instances.

Architecture

Local Models

The following local model types are supported, each with detailed YAML schemas:

  • Tag - Build tags with inheritance chains and external repositories

  • Target - Build targets linking build and destination tags

  • User - Koji users with group membership and permissions

  • Group - Package groups and their memberships

  • Host - Build hosts and their configurations with architecture support

  • Channel - Build channels with host assignments

  • Permission - User permission definitions

  • ExternalRepo - External package repositories with URL validation

  • ContentGenerator - Content generators with user access control

  • BuildType - Build type definitions (rpm, maven, image, etc.)

  • ArchiveType - Archive type definitions with file extensions and compression

See YAML Format Specification for detailed schemas and field specifications for each type.

Loading from YAML

Local models are loaded from YAML files using the loader system:

---
type: tag
name: fedora-42-build
arches:
  - x86_64
  - aarch64
inheritance:
  - parent: fedora-42-base
    priority: 10

The loader system:

  1. Reads YAML documents from files

  2. Injects __file__ and __line__ metadata

  3. Validates structure using Pydantic models

  4. Creates CoreObject instances from validated data

Validation

All local models use Pydantic for validation with the following features:

  • Type Validation: Automatic type checking and conversion

  • Field Constraints: Min/max values, string patterns, list lengths

  • Required Fields: Automatic validation of required fields

  • Aliases: Support for field aliases (e.g., build-tag vs build_tag)

  • Custom Validators: Complex validation logic for koji-specific rules

Validation occurs during model instantiation, providing immediate feedback on configuration errors with detailed error messages including file and line number information.

Dependency Resolution

Local models declare dependencies through the dependency_keys() method, which returns a sequence of (typename, name) tuples. The resolver system:

  1. Collects all dependencies from local models

  2. Organizes dependencies into tiers based on dependency relationships

  3. Ensures objects are processed in the correct order

  4. Identifies missing dependencies (phantoms) and circular dependencies

This enables safe, ordered processing of koji objects where child objects are created before their parents.

Processing and Synchronization

Local models integrate with the workflow system for synchronization:

  1. Loading: YAML files are loaded and validated into local models

  2. Template Expansion: Templates are expanded, generating additional local models

  3. Resolution: Dependencies are resolved and objects are organized into tiers

  4. Comparison: Local models are compared with remote state to identify changes

  5. Application: Changes are applied to the Koji instance in dependency order

The change_report() method on each local model generates a ChangeReport describing what changes need to be made to synchronize with the remote instance.

Example Usage

Define objects in YAML:

---
type: tag
name: fedora-42-base
arches:
  - x86_64
  - aarch64

---
type: tag
name: fedora-42-build
arches:
  - x86_64
  - aarch64
inheritance:
  - parent: fedora-42-base
    priority: 10

---
type: target
name: fedora-42
build-tag: fedora-42-build
dest-tag: fedora-42-dest

Process with koji-habitude:

koji-habitude compare data/ --templates templates/
koji-habitude apply data/ --templates templates/

The system validates, resolves dependencies, compares with remote state, and applies changes in the correct order.

Technical Reference

For developers: Local models are implemented by classes inheriting from CoreObject in the koji_habitude.models package. Each model type has a corresponding class (e.g., Tag, Target, User) that combines a *Model class (shared with remote models) with CoreObject.

Local models use the same base classes as remote models (through CoreModel), ensuring consistency in data structures and validation rules across both representations.