Documentation
¶
Overview ¶
Package export defines the generated contract for entities that may leave the runtime. The source schema owns the contract; this package provides the small runtime needed to identify and filter an entity against it.
Index ¶
- Constants
- Variables
- func EnsureMarker(ctx context.Context, store entity.Store, id, marker entity.Id) (bool, error)
- type Attribute
- type BackfillOption
- type BackfillStats
- type Change
- type Contract
- func (c *Contract) CanonicalJSON() ([]byte, error)
- func (c *Contract) Digest() string
- func (c *Contract) Filter(source *entity.Entity) (*entity.Entity, *Policy, error)
- func (c *Contract) MarkerID() entity.Id
- func (c *Contract) Policy(kind entity.Id) (*Policy, bool)
- func (c *Contract) PolicyFor(source entity.AttrGetter) (*Policy, bool)
- type Kind
- type Lifecycle
- type Policy
- type Remedy
- type Severity
Constants ¶
const Version1 = 1
Variables ¶
var ErrKindNotExported = errors.New("entity kind is not exported")
Functions ¶
Types ¶
type Attribute ¶
type Attribute struct {
ID string `json:"id"`
Type string `json:"type"`
Parent string `json:"parent,omitempty"`
Many bool `json:"many,omitempty"`
EnumValues []string `json:"enum_values,omitempty"`
}
Attribute describes one allowed value. Parent is set for fields nested in a component. Ancestor component attributes are included automatically by the generator, so a validator can reconstruct the allowed tree without knowing the runtime's source schema.
type BackfillOption ¶
type BackfillOption func(*backfillConfig)
func ExcludingKinds ¶
func ExcludingKinds(kinds ...entity.Id) BackfillOption
ExcludingKinds leaves marker ownership for the named kinds to a more specialized migration. This is how deployment attempts stay unselectable until their canonical migration has validated each individual record.
type BackfillStats ¶
func BackfillMarker ¶
func BackfillMarker( ctx context.Context, log *slog.Logger, store entity.Store, contract *Contract, pageSize int64, options ...BackfillOption, ) (BackfillStats, error)
BackfillMarker makes existing entities selectable through the contract's one indexed marker. Generated encoders mark new writes; this pass is the additive upgrade path for records created by older runtimes.
type Change ¶ added in v0.17.0
Change is one difference between a known contract and its successor. Attribute is empty when the change is to the kind itself. Remedy is set only on breaking changes.
func Compare ¶ added in v0.17.0
Compare reports how next differs from known, from the point of view of a consumer that validates against known the way cloud does: an attribute it knows must keep its wire kind, parent and cardinality, while anything it does not know is accepted as an addition. Additions are therefore not reported at all.
type Contract ¶
type Contract struct {
Version int `json:"version"`
Target string `json:"target"`
Marker string `json:"marker"`
Kinds []Kind `json:"kinds"`
// contains filtered or unexported fields
}
Contract is the language-neutral description generated from schema.yml. Kinds and attributes are slices rather than maps so its JSON encoding is a stable, reviewable artifact and therefore a suitable digest input.
func (*Contract) CanonicalJSON ¶
CanonicalJSON returns the stable wire artifact. It deliberately ignores the compiled indexes and digest cached on Contract.
type Remedy ¶ added in v0.17.0
type Remedy int
Remedy says how a breaking change can land without breaking sync.
const ( // ShipCloudFirst works when runtimes still sending the old shape satisfy // the new contract too, so the consumer can adopt it before any runtime // release does. ShipCloudFirst Remedy = iota + 1 // Replace is for changes no ordering makes safe: whichever shape the // consumer expects, it rejects runtimes still sending the other. The new // shape needs a new attribute, and the old one retires once nothing reads // it. Replace )
type Severity ¶ added in v0.17.0
type Severity int
Severity says what a contract change does to a consumer that already knows the old contract.
const ( // Breaking changes either make the consumer reject sync or quietly // diverge from what it projects. The quiet ones matter most here, since // nothing at sync time will notice them. Breaking Severity = iota // Advisory changes alter the contract without changing anything the // consumer sees or projects, so they deserve a look but not a failure. Advisory )