Documentation
¶
Overview ¶
Package fingerprint computes deterministic identity fingerprints for components. A fingerprint captures all resolved build inputs so that changes to any input (config fields, spec content, overlay files, distro context, upstream refs, or ManualBump) produce a different fingerprint.
The primary entry point is ComputeIdentity, which takes a resolved projectconfig.ComponentConfig and additional context, and returns a ComponentIdentity containing the overall fingerprint hash plus a breakdown of individual input hashes for debugging.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComputeResolutionHash ¶
func ComputeResolutionHash(inputs UpstreamCommitResolutionInputs) string
ComputeResolutionHash produces a deterministic hash of the effective inputs that affect upstream commit resolution. When this hash matches the stored value in a lock file, re-resolving the upstream commit can be skipped — the resolution inputs haven't changed so the same commit would be produced.
This prevents two classes of problems:
- Unnecessary re-resolution when only build inputs changed (e.g., overlay edit)
- Snapshot instability where upstream branches receive new commits (mass rebuilds, cherry-picks) that change what 'git rev-list --before' resolves to, even though the snapshot timestamp itself is unchanged
Callers must resolve distro inheritance/fallbacks before calling this — the hash must reflect the *actual* values used during resolution, not the raw per-component config which may be empty when defaults apply.
Types ¶
type ComponentIdentity ¶
type ComponentIdentity struct {
// Fingerprint is the overall SHA256 hash combining all inputs.
Fingerprint string `json:"fingerprint"`
// Inputs provides the individual input hashes that were combined.
Inputs ComponentInputs `json:"inputs"`
}
ComponentIdentity holds the computed fingerprint for a single component plus a breakdown of individual input hashes for debugging.
func ComputeIdentity ¶
func ComputeIdentity( fs opctx.FS, component projectconfig.ComponentConfig, releaseVer string, opts IdentityOptions, ) (*ComponentIdentity, error)
ComputeIdentity computes the fingerprint for a component from its resolved config and additional context. The fs parameter is used to read overlay source file contents for hashing; spec content identity is provided via IdentityOptions.SourceIdentity.
This function is a deterministic combiner: given the same resolved inputs it always produces the same fingerprint. It does not resolve source identity or count commits — those are expected to be pre-resolved by the caller and passed via opts.
type ComponentInputs ¶
type ComponentInputs struct {
// ConfigHash is the hash of the resolved component config fields (uint64 from hashstructure).
ConfigHash uint64 `json:"configHash"`
// SourceIdentity is the opaque identity string for the component's source.
// For local specs this is a content hash; for upstream specs this is a commit hash.
SourceIdentity string `json:"sourceIdentity,omitempty"`
// OverlayFileHashes maps overlay index (as string) to a combined hash of the
// source file's basename and content. Keyed by index rather than path to avoid
// checkout-location dependence.
OverlayFileHashes map[string]string `json:"overlayFileHashes,omitempty"`
// ManualBump is the manual rebuild counter from the lock file. Almost always 0;
// used for mass-rebuild scenarios.
ManualBump int `json:"manualBump"`
// ReleaseVer is the distro's formal releasever (e.g., "4.0"), which feeds into
// RPM macros like %{dist}. Different release versions produce different package
// NEVRAs even with identical specs.
ReleaseVer string `json:"releaseVer"`
}
ComponentInputs contains the individual input hashes that comprise a component's fingerprint.
type IdentityOptions ¶
type IdentityOptions struct {
// ManualBump is the manual rebuild counter from the component's lock file.
ManualBump int
// SourceIdentity is the opaque identity string from a [sourceproviders.SourceIdentityProvider].
// For upstream components this is the resolved commit hash; for local components this is a
// content hash of the spec directory.
//
// This is caller-provided because resolving it requires network access (upstream clone) or
// filesystem traversal (local content hash). [ComputeIdentity] is a pure combiner — it does
// not perform I/O beyond reading overlay files. Callers should resolve source identity via
// SourceManager.ResolveSourceIdentity before calling [ComputeIdentity].
SourceIdentity string
}
IdentityOptions holds additional inputs for computing a component's identity that are not part of the component config itself.
type UpstreamCommitResolutionInputs ¶
type UpstreamCommitResolutionInputs struct {
// Snapshot is the resolved snapshot timestamp.
Snapshot string
// DistroName is the resolved distro name.
DistroName string
// DistroVersion is the resolved distro version.
DistroVersion string
// DistGitBranch is the resolved dist-git branch (e.g., "f43").
DistGitBranch string
// DistGitBaseURI is the resolved dist-git base URI template.
DistGitBaseURI string
// UpstreamCommitPin is an explicit commit hash pin (overrides snapshot).
UpstreamCommitPin string
// UpstreamName is the upstream package name (if different from component).
UpstreamName string
}
UpstreamCommitResolutionInputs holds the effective inputs that determine which upstream commit gets resolved. These must be the *resolved* values after inheritance and fallback — not the raw component spec fields.
Source Files