Documentation
¶
Overview ¶
Package advancedchangeset owns the immutable, owner-signed description of one already-rendered advanced change. It deliberately does not resolve, render, execute, or discover anything.
Index ¶
Constants ¶
const ( // SchemaVersion v2 adds the Terramate scope (affectedStacks and // terramateHostManifestSha256). The strict verifier rejects unknown // fields, so the version moved; v1 records expire within MaxLifetime. SchemaVersion = "stackkit.advanced-change-set/v2" MaxLifetime = 24 * time.Hour )
const ( StatusAdded = "added" StatusModified = "modified" StatusRemoved = "removed" )
const GenerationTargetTerramate = "terramate"
Variables ¶
This section is empty.
Functions ¶
func RenderSHA256 ¶
func RenderSHA256(result architecturev2renderer.RenderResult) (string, error)
RenderSHA256 exposes the exact canonical render identity used by Record. Apply uses it to prove that freshly rendered candidate bytes are the bytes the Owner approved, before any snapshot or runtime side effect is started.
Types ¶
type ArtifactChange ¶
type ArtifactChange struct {
Path string `json:"path"`
Status string `json:"status"`
BeforeSHA256 string `json:"beforeSha256,omitempty"`
AfterSHA256 string `json:"afterSha256,omitempty"`
MetadataChanged bool `json:"metadataChanged,omitempty"`
}
ArtifactChange is a deterministic path-keyed transition. Equal hashes with MetadataChanged=true represent a governed metadata-only modification.
type CreateRequest ¶
type CreateRequest struct {
Baseline architecturev2renderer.RenderResult
Candidate architecturev2renderer.RenderResult
CapabilityID string
CapabilitySHA256 string
KeyID string
StackID string
OwnerRef string
UIManagerRef string
RILRef string
BaselinePlanHash string
CandidatePlanHash string
// LocalSiteRef and LocalNodeRef select the host project of this
// execution channel. Both empty select the only host of a one-host graph.
LocalSiteRef string
LocalNodeRef string
CreatedAt time.Time
ExpiresAt time.Time
CapabilityExpiresAt time.Time
Sign OwnerSigner
VerifyOwnerSignature OwnerVerifier
}
type OwnerSignature ¶
type OwnerSignature struct {
OwnerRef string `json:"ownerRef"`
KeyID string `json:"keyId"`
Value string `json:"value"`
}
OwnerSignature is supplied by the local owner-custody composition seam. The private key and signing implementation never enter this package.
type OwnerSigner ¶
type OwnerSigner func(canonicalUnsigned []byte) (OwnerSignature, error)
OwnerSigner signs the canonical unsigned bytes using current local custody.
type OwnerVerifier ¶
type OwnerVerifier func(canonicalUnsigned []byte, signature OwnerSignature) error
OwnerVerifier verifies an owner signature and its binding to current local custody. Implementations are injected by the composition root.
type Record ¶
type Record struct {
SchemaVersion string `json:"schemaVersion"`
ChangeSetID string `json:"changeSetId"`
CapabilityID string `json:"capabilityId"`
CapabilitySHA256 string `json:"capabilitySha256"`
KeyID string `json:"keyId"`
StackID string `json:"stackId"`
OwnerRef string `json:"ownerRef"`
UIManagerRef string `json:"uiManagerRef"`
RILRef string `json:"rilRef"`
GenerationTarget string `json:"generationTarget"`
CreatedAt string `json:"createdAt"`
ExpiresAt string `json:"expiresAt"`
CapabilityExpiresAt string `json:"capabilityExpiresAt"`
BaselinePlanHash string `json:"baselinePlanHash"`
CandidatePlanHash string `json:"candidatePlanHash"`
BaselineRenderSHA256 string `json:"baselineRenderSha256"`
CandidateRenderSHA256 string `json:"candidateRenderSha256"`
Changes []ArtifactChange `json:"changes"`
// AffectedStacks are the Terramate stack IDs whose module owns a changed
// artifact, in the stack graph's global run order.
AffectedStacks []string `json:"affectedStacks"`
// TerramateHostManifestSHA256 is the digest of the local host project
// (stackkit.terramate-host-manifest/v1) the candidate materializes.
TerramateHostManifestSHA256 string `json:"terramateHostManifestSha256"`
OwnerSignature OwnerSignature `json:"ownerSignature"`
}
Record is content-addressed by all unsigned claims except ChangeSetID itself. OwnerSignature then authenticates the complete unsigned record, including that derived ID.
func Create ¶
func Create(request CreateRequest) (Record, error)
Create computes a pure diff from two already-authorized RenderResults and obtains an owner signature through the injected custody seam.
func Verify ¶
func Verify(raw []byte, request VerificationRequest) (Record, error)
Verify rejects non-canonical, malformed, stale, scope-substituted, or owner-signature-invalid records without performing side effects.
func (Record) MarshalCanonical ¶
MarshalCanonical returns the strict persisted representation.
func (Record) UnsignedCanonical ¶
UnsignedCanonical returns the exact bytes authenticated by OwnerSignature.
type Store ¶
type Store struct {
WorkspaceRoot string
}
type TerramateScope ¶ added in v0.46.5
TerramateScope is the Terramate part of a change set: the stacks the artifact diff touches, in graph run order, and the local host project the candidate materializes.
func DeriveTerramateScope ¶ added in v0.46.5
func DeriveTerramateScope( baseline, candidate []architecturev2renderer.Artifact, changes []ArtifactChange, siteRef, nodeRef string, ) (TerramateScope, error)
DeriveTerramateScope maps an artifact diff to Terramate stacks through the candidate's stack graph. Git-based `terramate list --changed` is not available in the runtime tree, so the graph is the only authority.
A changed artifact affects every stack whose module owns it: added and modified paths resolve their owner in the candidate, removed paths in the baseline. Plan-owned artifacts (the graph itself) and modules that are not stacks (host bootstrap, security baseline) affect no stack. A module rendered on several nodes affects each of its node stacks; stacks that exist only in the baseline (a removed workload) are not part of the candidate graph and are not listed.
Source Files