export

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
  • func ExcludingKinds(kinds ...entity.Id) BackfillOption
• type BackfillStats
  • func BackfillMarker(ctx context.Context, log *slog.Logger, store entity.Store, contract *Contract, ...) (BackfillStats, error)
• type Contract
  • func MustParse[T ~string | ~[]byte](data T) *Contract
  • func Parse(data []byte) (*Contract, error)
  • 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

Constants

const Version1 = 1

Variables

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 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
}