shared-libraries

Shared Libraries (pkg/lib)

Analyzed from commit: 412c71822 on 2026-05-04

All Forklift controllers share a common set of library packages under pkg/lib/. Understanding these is essential because they define the patterns every controller follows.

---

1. Condition Framework (pkg/lib/condition) — CRITICAL

The condition framework is the core abstraction for resource status. Every CRD's .status.conditions field uses it.

1.1 Condition Struct

type Condition struct {
    Type               string   // e.g. "Ready", "ReconcileFailed", "ConnectionTestFailed"
    Status             string   // "True" or "False"
    Category           string   // severity: Critical, Error, Warn, Required, Advisory
    Reason             string   // machine-readable reason
    Message            string   // human-readable description
    Suggestion         string   // suggested resolution
    LastTransitionTime Time     // when status last changed
    Durable            bool     // if true, survives staging sweeps
    Items              []string // referenced items in Message
    staged             bool     // internal: was this set in current cycle?
}

1.2 Categories (Severity Levels)

Category	Constant	Effect
Critical	Blocks Reconcile() AND blocks Ready
Error	Blocks Ready only
Warn	Does NOT block Ready — advisory warning
Required	Required for Ready to be true
Advisory	Purely informational

Special categories for pending states: ValidatingVDDK, VMMissingGuestIPs, VMMissingChangedBlockTracking, SharedDisks.

1.3 Conditions Collection — The Staging Pattern

Conditions is a managed slice embedded in every resource's Status:

type Conditions struct {
    List    []Condition // serialized to JSON
    staging bool        // internal staging state
}

The staging lifecycle (used in every controller's Reconcile):

// 1. Begin staging — marks all non-Durable conditions as un-staged
resource.Status.BeginStagingConditions()

// 2. Set conditions for current reconcile cycle
//    Each SetCondition call marks that condition as staged
resource.Status.SetCondition(Condition{
    Type:     "SomeValidation",
    Status:   True,
    Category: Error,
    Message:  "Something is wrong",
})

// 3. End staging — deletes any conditions NOT set/staged this cycle
//    Durable conditions always survive
resource.Status.EndStagingConditions()

// 4. Derive the Ready condition from blocker status
resource.Status.SetCondition(Condition{
    Type:     Ready,
    Status:   boolToStatus(!resource.Status.HasBlockerCondition()),
    Category: Required,
    Message:  "Resource is ready.",
})