export

package
v0.17.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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

View Source
const Version1 = 1

Variables

View Source
var ErrKindNotExported = errors.New("entity kind is not exported")

Functions

func EnsureMarker

func EnsureMarker(ctx context.Context, store entity.Store, id, marker entity.Id) (bool, error)

EnsureMarker adds marker to id, retrying if a concurrent writer changes the entity between the read and patch. It reports whether this call added it.

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

type BackfillStats struct {
	Scanned       int64
	Marked        int64
	AlreadyMarked int64
}

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

type Change struct {
	Severity  Severity
	Remedy    Remedy
	Kind      string
	Attribute string
	Detail    string
}

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

func Compare(known, next *Contract) ([]Change, error)

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.

func (Change) String added in v0.17.0

func (c Change) String() string

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 MustParse

func MustParse[T ~string | ~[]byte](data T) *Contract

func Parse

func Parse(data []byte) (*Contract, error)

Parse validates and compiles a generated contract.

func (*Contract) CanonicalJSON

func (c *Contract) CanonicalJSON() ([]byte, error)

CanonicalJSON returns the stable wire artifact. It deliberately ignores the compiled indexes and digest cached on Contract.

func (*Contract) Digest

func (c *Contract) Digest() string

func (*Contract) Filter

func (c *Contract) Filter(source *entity.Entity) (*entity.Entity, *Policy, error)

Filter returns a complete entity containing the source identity metadata and only business attributes admitted by the policy for its kind. A malformed allowed value is rejected rather than copied through under an unexpected shape.

func (*Contract) MarkerID

func (c *Contract) MarkerID() entity.Id

func (*Contract) Policy

func (c *Contract) Policy(kind entity.Id) (*Policy, bool)

func (*Contract) PolicyFor

func (c *Contract) PolicyFor(source entity.AttrGetter) (*Policy, bool)

type Kind

type Kind struct {
	ID         string      `json:"id"`
	Lifecycle  Lifecycle   `json:"lifecycle"`
	Attributes []Attribute `json:"attributes"`
}

type Lifecycle

type Lifecycle string
const (
	LifecycleMirror  Lifecycle = "mirror"
	LifecycleArchive Lifecycle = "archive"
)

type Policy

type Policy struct {
	Kind      entity.Id
	Lifecycle Lifecycle
	// contains filtered or unexported fields
}

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
)

func (Severity) String added in v0.17.0

func (s Severity) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL