Documentation
¶
Overview ¶
Package importer implements the configuration import flow defined in Spec 021. An ImportBundle is the versioned interchange format between source workspaces (or external bootstrap scripts) and target Conflow workspaces.
Index ¶
- Constants
- Variables
- func GenerateToken(draftRevision uint64) string
- func ValidateToken(token string, currentRevision uint64) error
- type ApplyInput
- type ApplyResult
- type BundleEntity
- type ConflictMode
- type DecisionRequired
- type EntityAction
- type EntityPlan
- type ImportBundle
- type ImportDecision
- type PreviewResult
Constants ¶
const FormatVersion = 1
FormatVersion is the only format version currently supported.
Variables ¶
var ( // ErrTokenExpired is returned when the preview token has expired or is invalid. ErrTokenExpired = errors.New("preview token expired") // ErrRevisionChanged is returned when the draft revision has changed since // the token was generated. ErrRevisionChanged = errors.New("draft revision changed since preview") )
Functions ¶
func GenerateToken ¶
GenerateToken creates a preview token that encodes the current draft revision and an expiry time 15 minutes in the future.
func ValidateToken ¶
ValidateToken checks that the token is syntactically valid, not expired, and that the draft revision matches the one encoded in the token. Returns ErrTokenExpired for invalid or expired tokens, ErrRevisionChanged if the revision has advanced since the token was issued.
Types ¶
type ApplyInput ¶
type ApplyInput struct {
Bundle ImportBundle
PreviewToken string
Decisions []ImportDecision
ConflictMode ConflictMode
DraftRevision uint64
}
ApplyInput is the input to Apply.
type ApplyResult ¶
type ApplyResult struct {
AppliedCount int
SkippedCount int
// PreparedEntities holds the bundle entities after decisions have been merged
// in, keyed by entity type. unit_binding is always excluded.
PreparedEntities map[string][]BundleEntity
}
ApplyResult is returned by Apply. The service layer uses PreparedEntities to perform the actual draft write.
func Apply ¶
func Apply(input ApplyInput) (ApplyResult, error)
Apply validates the previewToken against the current draft revision, verifies that every DecisionRequired item has a corresponding operator-supplied decision, and merges decisions into the bundle entities.
Apply does not modify the draft; the service layer applies PreparedEntities using draft.Mutation.
type BundleEntity ¶
BundleEntity is a single entity record inside an ImportBundle.
type ConflictMode ¶
type ConflictMode string
ConflictMode controls how entity ID collisions are handled during import.
const ( // ConflictReplace overwrites existing entities with the same ID (default). ConflictReplace ConflictMode = "replace" // ConflictMerge only imports entities whose ID does not already exist in the draft. ConflictMerge ConflictMode = "merge" // ConflictSkip skips all conflicting entities; only adds entities of types // that are completely absent from the draft. ConflictSkip ConflictMode = "skip" )
type DecisionRequired ¶
type DecisionRequired struct {
// Key uses the format "<entity_type>.<entity_id>.<field_name>".
Key string `json:"key"`
Reason string `json:"reason"`
Hint string `json:"hint,omitempty"`
}
DecisionRequired describes one field that the operator must supply before apply.
type EntityAction ¶
type EntityAction struct {
EntityType string `json:"entity_type"`
ID string `json:"id"`
Diff interface{} `json:"diff,omitempty"`
}
EntityAction describes what will happen to one entity during apply.
type EntityPlan ¶
type EntityPlan struct {
ToAdd []EntityAction `json:"to_add"`
ToReplace []EntityAction `json:"to_replace"`
ToSkip []EntityAction `json:"to_skip"`
ToKeep []EntityAction `json:"to_keep"`
}
EntityPlan breaks down the full set of changes that apply would make.
type ImportBundle ¶
type ImportBundle struct {
FormatVersion int `json:"format_version"`
PackRef string `json:"pack_ref"`
SchemaVersion uint64 `json:"schema_version"`
CreatedAt time.Time `json:"created_at"`
SourceID string `json:"source_id,omitempty"`
SourceRevision string `json:"source_revision,omitempty"`
SourceDigest string `json:"source_digest,omitempty"`
Entities map[string][]BundleEntity `json:"entities"`
// DecisionsRequired lists fields that cannot be inferred from the source and must
// be supplied by the operator in the apply call.
DecisionsRequired []DecisionRequired `json:"decisions_required,omitempty"`
}
ImportBundle is the versioned interchange format produced by export and consumed by preview/apply. It must not contain Firebase credentials, access tokens, private keys, or unit_binding entities.
func Export ¶
func Export(packRef string, schemaVersion uint64, sourceID string, draftEntities map[string][]BundleEntity) (ImportBundle, error)
Export reads all non-unit_binding entities from draftEntities and produces an ImportBundle. Credentials and Provider config are never included; they must not appear in draftEntities.
packRef is the Pack reference string (e.g. "mobile-ad-monetization/v2"). schemaVersion is the current Pack schema version. sourceID is an opaque identifier for the source workspace (used for tracing).
type ImportDecision ¶
type ImportDecision struct {
// Key matches DecisionRequired.Key.
Key string `json:"key"`
Value interface{} `json:"value"`
}
ImportDecision is the operator-supplied value for one DecisionRequired item.
type PreviewResult ¶
type PreviewResult struct {
PreviewToken string `json:"preview_token"`
ExpiresAt time.Time `json:"expires_at"`
PackRef string `json:"pack_ref"`
ConflictMode ConflictMode `json:"conflict_mode"`
EntityPlan EntityPlan `json:"entity_plan"`
DecisionsRequired []DecisionRequired `json:"decisions_required"`
Risks []string `json:"risks,omitempty"`
}
PreviewResult is returned by PreviewImport. The PreviewToken must be supplied to ApplyImport via If-Match; it expires after 15 minutes or when the draft revision changes.
func Preview ¶
func Preview(bundle ImportBundle, draftEntities map[string][]string, draftRevision uint64, conflictMode ConflictMode) (PreviewResult, error)
Preview generates an EntityPlan for importing bundle into the current draft without modifying it. conflictMode controls how entity ID collisions are handled.
draftEntities is a map of entity type name → slice of entity IDs currently present in the draft (excluding unit_binding).
Source Files