contract

package
v0.36.1 Latest Latest
Warning

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

Go to latest
Published: Apr 2, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Index

Constants

View Source
const (
	InterfaceTypeHTTP  = "http"
	InterfaceTypeGRPC  = "grpc"
	InterfaceTypeEvent = "event"
)

InterfaceType constants.

View Source
const (
	VisibilityPublic   = "public"
	VisibilityInternal = "internal"
)

Visibility constants.

View Source
const (
	WorkloadTypeService   = "service"
	WorkloadTypeJob       = "job"
	WorkloadTypeScheduled = "scheduled"
)

WorkloadType constants.

View Source
const (
	StateStateless = "stateless"
	StateStateful  = "stateful"
	StateHybrid    = "hybrid"
)

StateType constants.

View Source
const (
	DataCriticalityLow    = "low"
	DataCriticalityMedium = "medium"
	DataCriticalityHigh   = "high"
)

DataCriticality constants.

View Source
const (
	ScopeLocal  = "local"
	ScopeShared = "shared"
)

Scope constants.

View Source
const (
	DurabilityEphemeral  = "ephemeral"
	DurabilityPersistent = "persistent"
)

Durability constants.

View Source
const (
	UpgradeStrategyRolling  = "rolling"
	UpgradeStrategyRecreate = "recreate"
	UpgradeStrategyOrdered  = "ordered"
)

UpgradeStrategy constants.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bundle

type Bundle struct {
	Contract *Contract
	RawYAML  []byte // Original YAML bytes; populated for local reads.
	FS       fs.FS
}

Bundle represents a contract bundled with its referenced files.

type Chart added in v0.18.0

type Chart struct {
	Ref     string `yaml:"ref" json:"ref"`
	Version string `yaml:"version" json:"version"`
}

Chart describes the Helm chart for the service.

type Configuration

type Configuration struct {
	Schema  string                 `yaml:"schema,omitempty" json:"schema,omitempty"`
	Ref     string                 `yaml:"ref,omitempty" json:"ref,omitempty"`
	Values  map[string]interface{} `yaml:"values,omitempty" json:"values,omitempty"`
	Configs []NamedConfigSource    `yaml:"configs,omitempty" json:"configs,omitempty"`
}

Configuration holds the configuration section of a contract. It supports two forms:

  • Legacy: top-level Schema/Ref/Values fields (single configuration source)
  • New: a Configs array of named configuration sources (multiple independent scopes)

When both forms are present, Configs takes precedence. Internally, use EffectiveConfigs() to normalize both forms into a uniform slice.

func (*Configuration) EffectiveConfigs added in v0.35.0

func (c *Configuration) EffectiveConfigs() []EffectiveConfigSource

EffectiveConfigs normalizes both configuration forms into a uniform slice. If Configs is non-empty, each named entry is returned directly. Otherwise, if legacy fields (Schema or Ref) are set, a single entry is returned. Returns nil if the Configuration is nil or has no effective sources.

type Contract

type Contract struct {
	PactoVersion  string                 `yaml:"pactoVersion" json:"pactoVersion"`
	Service       ServiceIdentity        `yaml:"service" json:"service"`
	Interfaces    []Interface            `yaml:"interfaces,omitempty" json:"interfaces,omitempty"`
	Configuration *Configuration         `yaml:"configuration,omitempty" json:"configuration,omitempty"`
	Policies      []PolicySource         `yaml:"policies,omitempty" json:"policies,omitempty"`
	Dependencies  []Dependency           `yaml:"dependencies,omitempty" json:"dependencies,omitempty"`
	Runtime       *Runtime               `yaml:"runtime,omitempty" json:"runtime,omitempty"`
	Scaling       *Scaling               `yaml:"scaling,omitempty" json:"scaling,omitempty"`
	Metadata      map[string]interface{} `yaml:"metadata,omitempty" json:"metadata,omitempty"`
}

Contract is the root aggregate — the parsed in-memory representation of a pacto.yaml.

func Parse

func Parse(r io.Reader) (*Contract, error)

Parse deserializes a pacto.yaml from the given reader into a Contract. It handles syntactic correctness only (field types, required top-level structure). Semantic validation is a separate concern handled by the validation engine.

type Dependency

type Dependency struct {
	Ref           string `yaml:"ref" json:"ref"`
	Required      bool   `yaml:"required,omitempty" json:"required,omitempty"`
	Compatibility string `yaml:"compatibility" json:"compatibility"`
}

Dependency represents a dependency on another service.

type EffectiveConfigSource added in v0.35.0

type EffectiveConfigSource struct {
	Name   string
	Schema string
	Ref    string
	Values map[string]interface{}
}

EffectiveConfigSource is the normalized internal representation of a single configuration source, regardless of whether it came from the legacy form or the new configuration.configs[] form.

type Health

type Health struct {
	Interface           string `yaml:"interface" json:"interface"`
	Path                string `yaml:"path,omitempty" json:"path,omitempty"`
	InitialDelaySeconds *int   `yaml:"initialDelaySeconds,omitempty" json:"initialDelaySeconds,omitempty"`
}

Health describes the health check configuration.

type Image

type Image struct {
	Ref     string `yaml:"ref" json:"ref"`
	Private bool   `yaml:"private,omitempty" json:"private,omitempty"`
}

Image describes the container image for the service.

type Interface

type Interface struct {
	Name       string `yaml:"name" json:"name"`
	Type       string `yaml:"type" json:"type"`
	Port       *int   `yaml:"port,omitempty" json:"port,omitempty"`
	Visibility string `yaml:"visibility,omitempty" json:"visibility,omitempty"`
	Contract   string `yaml:"contract,omitempty" json:"contract,omitempty"`
}

Interface describes a service interface declaration.

type Lifecycle

type Lifecycle struct {
	UpgradeStrategy         string `yaml:"upgradeStrategy,omitempty" json:"upgradeStrategy,omitempty"`
	GracefulShutdownSeconds *int   `yaml:"gracefulShutdownSeconds,omitempty" json:"gracefulShutdownSeconds,omitempty"`
}

Lifecycle describes lifecycle behavior.

type Metrics added in v0.19.0

type Metrics struct {
	Interface string `yaml:"interface" json:"interface"`
	Path      string `yaml:"path,omitempty" json:"path,omitempty"`
}

Metrics describes the metrics endpoint configuration.

type NamedConfigSource added in v0.35.0

type NamedConfigSource struct {
	Name   string                 `yaml:"name" json:"name"`
	Schema string                 `yaml:"schema,omitempty" json:"schema,omitempty"`
	Ref    string                 `yaml:"ref,omitempty" json:"ref,omitempty"`
	Values map[string]interface{} `yaml:"values,omitempty" json:"values,omitempty"`
}

NamedConfigSource declares a named configuration source within the configuration.configs[] array. Name is required and each entry is an independent named scope with no implicit merge semantics.

type OCIReference

type OCIReference struct {
	Registry   string
	Repository string
	Tag        string
	Digest     string
}

OCIReference represents a parsed OCI artifact reference.

func ParseOCIReference

func ParseOCIReference(s string) (OCIReference, error)

ParseOCIReference parses an OCI reference string into its components. Accepted formats:

registry/repo
registry/repo:tag
registry/repo@sha256:hex
registry/repo:tag@sha256:hex

func (OCIReference) String

func (r OCIReference) String() string

String returns the full OCI reference string.

type Owner added in v0.34.0

type Owner struct {
	// contains filtered or unexported fields
}

Owner represents ownership information for a service. It supports two forms for backward compatibility:

  • Legacy string: "team/payments"
  • Structured object: { team: "foundations", dri: "eduardo.diaz", contacts: [...] }

func NewOwnerFromInfo added in v0.34.0

func NewOwnerFromInfo(info OwnerInfo) Owner

NewOwnerFromInfo creates an Owner from structured ownership metadata.

func NewOwnerFromString added in v0.34.0

func NewOwnerFromString(s string) Owner

NewOwnerFromString creates an Owner from a legacy string value.

func (Owner) Contacts added in v0.34.0

func (o Owner) Contacts() []OwnerContact

Contacts returns the contacts list. Nil for legacy string owners.

func (Owner) DRI added in v0.34.0

func (o Owner) DRI() string

DRI returns the DRI. Empty for legacy string owners.

func (Owner) DisplayString added in v0.34.0

func (o Owner) DisplayString() string

DisplayString returns a human-readable representation of the owner. For legacy strings, returns the string as-is. For structured owners, returns the team name (or DRI if no team).

func (Owner) Equal added in v0.34.0

func (o Owner) Equal(other Owner) bool

Equal reports whether two Owner values are semantically equal.

func (Owner) Info added in v0.34.0

func (o Owner) Info() *OwnerInfo

Info returns the structured ownership info, or nil if legacy string form.

func (Owner) IsEmpty added in v0.34.0

func (o Owner) IsEmpty() bool

IsEmpty returns true if no ownership information is set.

func (Owner) IsStructured added in v0.34.0

func (o Owner) IsStructured() bool

IsStructured returns true if the owner uses the structured object form.

func (Owner) MarshalJSON added in v0.34.0

func (o Owner) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (Owner) MarshalYAML added in v0.34.0

func (o Owner) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler.

func (Owner) MatchesFilter added in v0.34.0

func (o Owner) MatchesFilter(query string) bool

MatchesFilter returns true if the owner matches a search query. Matches against team, dri, and contact values (case-insensitive).

func (Owner) String added in v0.34.0

func (o Owner) String() string

String returns the legacy string value. Empty if structured form.

func (Owner) Team added in v0.34.0

func (o Owner) Team() string

Team returns the team name. For legacy strings, returns the full string. For structured owners, returns the Team field.

func (*Owner) UnmarshalJSON added in v0.34.0

func (o *Owner) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*Owner) UnmarshalYAML added in v0.34.0

func (o *Owner) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler.

type OwnerContact added in v0.34.0

type OwnerContact struct {
	Type    string `yaml:"type" json:"type"`
	Value   string `yaml:"value" json:"value"`
	Purpose string `yaml:"purpose,omitempty" json:"purpose,omitempty"`
}

OwnerContact is a provider-neutral contact point.

type OwnerInfo added in v0.34.0

type OwnerInfo struct {
	Team     string         `yaml:"team,omitempty" json:"team,omitempty"`
	DRI      string         `yaml:"dri,omitempty" json:"dri,omitempty"`
	Contacts []OwnerContact `yaml:"contacts,omitempty" json:"contacts,omitempty"`
}

OwnerInfo is the structured ownership metadata.

type ParseError

type ParseError struct {
	Path    string
	Message string
	Err     error // underlying cause, if any
}

ParseError represents an error encountered during YAML parsing.

func (*ParseError) Error

func (e *ParseError) Error() string

func (*ParseError) Unwrap added in v0.2.1

func (e *ParseError) Unwrap() error

type Persistence

type Persistence struct {
	Scope      string `yaml:"scope" json:"scope"`
	Durability string `yaml:"durability" json:"durability"`
}

Persistence represents the persistence requirements.

type PolicySource added in v0.35.0

type PolicySource struct {
	Schema string `yaml:"schema,omitempty" json:"schema,omitempty"`
	Ref    string `yaml:"ref,omitempty" json:"ref,omitempty"`
}

PolicySource declares a policy constraint source. Each entry provides either a local JSON Schema file or a reference to an external contract whose bundle contains the policy schema at policy/schema.json. A policy schema validates the contract itself, enabling platform teams to enforce organizational standards. Schema and Ref are mutually exclusive.

type Range

type Range struct {
	// contains filtered or unexported fields
}

Range represents a parsed semver constraint range.

func ParseRange

func ParseRange(s string) (Range, error)

ParseRange parses a semver range string (npm-style: ^, ~, exact, range).

func (Range) Contains

func (r Range) Contains(version string) bool

Contains returns true if the given version string satisfies this range.

func (Range) String

func (r Range) String() string

String returns the original range string.

type Runtime

type Runtime struct {
	Workload  string     `yaml:"workload" json:"workload"`
	State     State      `yaml:"state" json:"state"`
	Lifecycle *Lifecycle `yaml:"lifecycle,omitempty" json:"lifecycle,omitempty"`
	Health    *Health    `yaml:"health,omitempty" json:"health,omitempty"`
	Metrics   *Metrics   `yaml:"metrics,omitempty" json:"metrics,omitempty"`
}

Runtime describes how the service behaves at runtime.

type Scaling

type Scaling struct {
	Replicas *int `yaml:"replicas,omitempty" json:"replicas,omitempty"`
	Min      int  `yaml:"min,omitempty" json:"min,omitempty"`
	Max      int  `yaml:"max,omitempty" json:"max,omitempty"`
}

Scaling describes scaling parameters. Either Replicas (exact count) or Min/Max (range) is set.

type ServiceIdentity

type ServiceIdentity struct {
	Name    string `yaml:"name" json:"name"`
	Version string `yaml:"version" json:"version"`
	Owner   Owner  `yaml:"owner,omitempty" json:"owner,omitempty"`
	Image   *Image `yaml:"image,omitempty" json:"image,omitempty"`
	Chart   *Chart `yaml:"chart,omitempty" json:"chart,omitempty"`
}

ServiceIdentity holds service identification fields.

type State

type State struct {
	Type            string      `yaml:"type" json:"type"`
	Persistence     Persistence `yaml:"persistence" json:"persistence"`
	DataCriticality string      `yaml:"dataCriticality" json:"dataCriticality"`
}

State describes the state semantics of the service.

type ValidationError

type ValidationError struct {
	Path    string
	Code    string
	Message string
}

ValidationError represents a validation failure that makes a contract invalid.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type ValidationWarning

type ValidationWarning struct {
	Path    string
	Code    string
	Message string
}

ValidationWarning represents a validation concern that does not invalidate the contract.

func (*ValidationWarning) String

func (w *ValidationWarning) String() string

Jump to

Keyboard shortcuts

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