api

package
v1.30.0 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2024 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

See MutableResource.ImpliedVersion() for resource version conversion semantics. 

// Manipulate the fields in Address.
addr.Access(func(x *compute.Address) {
  x.Name = "my-addr"
  x.Description = ...
  x.Network = ...
  // Meta-fields are handled as well:
  x.ForceSendFields = []string{"Region"}
})

// Edit fields that are present in Beta. Fields that common with the
// compute.Address be propagated to all associated types, e.g. a field
// like "Name" will be set in all versions of the resource.
addr.AccessBeta(func(x *beta.Address) {
 x.Name = "different-name"
 x.Labels = ...
})

// Fetch the required API object. The code should handle
// checking for missing fields that may have been dropped as
// part of version translation.
betaObj, err := addr.ToBeta()
  if err != nil {
    var objErrors *Errors
    if errors.As(err, &objErrors) { /* handle MissingFields, etc. */ }
}

Checking type assumptions with unit tests

Resource.CheckSchema() can be used to check if the types referenced meet the above criteria. 

type Address = NewResource[compute.Address, alpha.Address, beta.Address](...)
addr := Address{}
if err := addr.CheckSchema(); err != nil { /* unsupported type schema */ }

Customizing resource behavior

Resource conversion behavior can be customized using TypeTraits. TypeTraits give hooks to the Resource implementation on version conversion and diff'ing. 

type myTypeTrait struct { BaseTypeTrait[myTypeGA, myTypeAlpha, myTypeBeta] }

// CopyHelpers are called after the generic value-wise copy is
// finished. This allows for any additional fixup of the fields after
// conversion.
func (*myTypeTrait) CopyHelperGAtoAlpha(...) { ... }

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckStructuralSubset added in v1.26.0 

func CheckStructuralSubset(from, to reflect.Type) error

CheckStructuralSubset checks if type From is the subset of To type. Type is a subset of another if it contains fields with the same type and name. This function is not symmetric.

func Fill 

func Fill(obj any, options ...FillOption) error

Fill obj with dummy values for testing. Slices and maps will have one element in them so the linked objects will have non-zero values.

func NewResource 

func NewResource[GA any, Alpha any, Beta any](
	resourceID *cloud.ResourceID,
	typeTrait TypeTrait[GA, Alpha, Beta],
) *mutableResource[GA, Alpha, Beta]

NewResource constructs a new Resource.

If typeTrait is nil, then it will be set to BaseTypeTrait.

Types

type BaseTypeTrait 

type BaseTypeTrait[GA any, Alpha any, Beta any] struct{}

BaseTypeTrait is a TypeTrait that has no effect. This can be embedded to reduce verbosity when creating a custom TypeTrait.

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperAlphaToBeta 

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperAlphaToBeta(dest *Beta, src *Alpha) error

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperAlphaToGA 

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperAlphaToGA(dest *GA, src *Alpha) error

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperBetaToAlpha 

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperBetaToAlpha(dest *Alpha, src *Beta) error

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperBetaToGA 

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperBetaToGA(dest *GA, src *Beta) error

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperGAtoAlpha 

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperGAtoAlpha(dest *Alpha, src *GA) error

Implements TypeTrait.

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperGAtoBeta 

func (*BaseTypeTrait[GA, Alpha, Beta]) CopyHelperGAtoBeta(dest *Beta, src *GA) error

func (*BaseTypeTrait[GA, Alpha, Beta]) FieldTraits 

func (*BaseTypeTrait[GA, Alpha, Beta]) FieldTraits(meta.Version) *FieldTraits

type ConversionContext 

type ConversionContext int

ConversionContext gives which version => version the error occurred on. 

const (
	GAToAlphaConversion ConversionContext = iota
	GAToBetaConversion
	AlphaToGAConversion
	AlphaToBetaConversion
	BetaToGAConversion
	BetaToAlphaConversion
)

type ConversionError 

type ConversionError struct {
	// MissingFields is a list of field values that were set but did not
	// translate to the version requested.
	MissingFields []MissingField
}

ConversionError is returned from To*() methods. Inspect this error to get more details on what did not convert.

func (*ConversionError) Error 

func (e *ConversionError) Error() string

Error implements error.

type DiffItem 

type DiffItem struct {
	State DiffItemState
	Path  Path
	A     any
	B     any
}

DiffItem is an element that is different.

type DiffItemState 

type DiffItemState string

DiffItemState gives details on the diff. 

var (
	//  DiffItemDifferent means the element at the Path differs between A and B.
	DiffItemDifferent DiffItemState = "Different"
	//  DiffItemOnlyInA means the element at the Path only exists in A, the
	//  value in B is nil.
	DiffItemOnlyInA DiffItemState = "OnlyInA"
	//  DiffItemOnlyInB means the element at the Path only exists in B, the
	//  value in B is nil.
	DiffItemOnlyInB DiffItemState = "OnlyInB"
)

type DiffResult 

type DiffResult struct {
	Items []DiffItem
}

DiffResult gives a list of elements that differ.

func (*DiffResult) HasDiff 

func (r *DiffResult) HasDiff() bool

HasDiff is true if the result is has a diff.

type FieldTraits 

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

FieldTraits are the features and behavior for fields in the resource.

func NewFieldTraits 

func NewFieldTraits() *FieldTraits

NewFieldTraits creates a default traits.

func (*FieldTraits) AllowZeroValue 

func (dt *FieldTraits) AllowZeroValue(p Path)

AllowZeroValue specifies the type of the given path.

func (*FieldTraits) CheckSchema 

func (dt *FieldTraits) CheckSchema(t reflect.Type) error

CheckSchema validates that the traits are valid and match the schema of the given type.

func (*FieldTraits) Clone 

func (dt *FieldTraits) Clone() *FieldTraits

Clone create an exact copy of the traits.

func (*FieldTraits) NonZeroValue added in v1.30.0 

func (dt *FieldTraits) NonZeroValue(p Path)

NonZeroValue specifies the type of the given path.

func (*FieldTraits) OutputOnly 

func (dt *FieldTraits) OutputOnly(p Path)

OutputOnly specifies the type of the given path.

func (*FieldTraits) System 

func (dt *FieldTraits) System(p Path)

System specifies the type of the given path.

type FieldType 

type FieldType string

FieldType of the field. 

const (
	// FieldTypeOrdinary is a ordinary field. It will be compared by value in a
	// diff. It can be zero-value without being in a metafield.
	FieldTypeOrdinary FieldType = "Ordinary"
	// FieldTypeSystem fields are internal infrastructure related fields. These are never
	// copied or diff'd.
	FieldTypeSystem FieldType = "System"
	// FieldTypeOutputOnly are fields that are status set by the server. These
	// should never be set by the client.
	FieldTypeOutputOnly FieldType = "OutputOnly"
	// FieldTypeAllowZeroValue is an ordinary field that can be zero-value
	// without being in a metafield. This is used for testing. TODO(kl52752)
	// remove this field when all resources are migrating to
	// FieldTypeNonZeroValue.
	FieldTypeAllowZeroValue FieldType = "AllowZeroValue"
	// FieldTypeNonZeroValue is a field that's value must be non-zero or
	// specified in a meta-field. It will be compared by value in a diff.
	FieldTypeNonZeroValue FieldType = "NonZeroValue"
)

type FillOption 

type FillOption func(*filler)

FillOption is an option to Fill().

func BasicFiller 

func BasicFiller(fn func(reflect.Type, Path) any) FillOption

BasicFiller configures a different fill function for basic values in the struct.

type MissingField 

type MissingField struct {
	// Context gives the version to => from.
	Context ConversionContext
	// Path of the field that is missing.
	Path Path
	// Value of the source field.
	Value any
}

MissingField describes a field that was lost when converting between API versions due to the field not being present in struct.

type MutableResource 

type MutableResource[GA any, Alpha any, Beta any] interface {
	// CheckSchema should be called in init() to ensure that the resource being
	// wrapped meets the assumptions we are making for this the transformations
	// to work.
	CheckSchema() error

	// ResourceID is the resource ID of this resource.
	ResourceID() *cloud.ResourceID

	// ImpliedVersion returns the best API version for the set of
	// fields in the resource. It will return an error if it is not
	// clear which version should be used without missing
	// configuration.
	ImpliedVersion() (meta.Version, error)

	// Access the mutable resource.
	Access(f func(x *GA)) error
	// AccessAlpha resource.
	AccessAlpha(f func(x *Alpha)) error
	// AccessBeta resource.
	AccessBeta(f func(x *Beta)) error

	// ToGA returns the GA version of this resource. Use error.As
	// ConversionError to get the specific details.
	ToGA() (*GA, error)
	// ToAlpha returns the Alpha version of this resource. Use
	// error.As ConversionError to get the specific details.
	ToAlpha() (*Alpha, error)
	// ToBeta returns the Beta version of this resource. Use
	// error.As ConversionError to get the specific details.
	ToBeta() (*Beta, error)

	// Set the value to src. This skips some of the field
	// validation in Access* so should only be used with a valid
	// object returned from GCE.
	Set(src *GA) error
	// SetAlpha the value to src. This skips some of the field
	// validation in Access* so should only be used with a valid
	// object returned from GCE.
	SetAlpha(src *Alpha) error
	// SetBeta the value to src. This skips some of the field
	// validation in Access* so should only be used with a valid
	// object returned from GCE.
	SetBeta(src *Beta) error

	// Freeze the resource to a read-only copy. It is an error if it is ambiguous
	// which version is the correct one i.e. not all fields can be represented in a
	// single version of the resource.
	Freeze() (Resource[GA, Alpha, Beta], error)
}

MutableResource wraps the multi-versioned concrete resources.

type Path 

type Path []string

Path specifies a field in nested object. The type of the reference is given by the first character:

- "." is a field reference - "!" is a slice index - ":" is a map key - "*" is a pointer deref. - "#" is all array elements reference

func (Path) AnyMapIndex added in v1.26.0 

func (p Path) AnyMapIndex() Path

AnyMapIndex returns a path extended to match any map index.

func (Path) AnySliceIndex added in v1.26.0 

func (p Path) AnySliceIndex() Path

AnySliceIndex returns a path extended to match any slice index.

func (Path) Equal 

func (p Path) Equal(other Path) bool

Equal returns true if other is the same path. Note that this equality comparison does NOT interpret wildcard matches, e.g. .AnyIndex is only Equal() to .AnyIndex, not Equal to .Index(x).

Use Match() instead to match interpreting wildcards.

func (Path) Field 

func (p Path) Field(name string) Path

Field returns the path extended with a struct field reference.

func (Path) HasPrefix 

func (p Path) HasPrefix(prefix Path) bool

HasPrefix returns true if prefix is the prefix of this path. Prefix uses Match() semantics for wildcards.

func (Path) Index 

func (p Path) Index(i int) Path

Index returns the path extended with a slice dereference.

func (Path) MapIndex 

func (p Path) MapIndex(k any) Path

MapIndex returns the path extended with a map index.

func (Path) Match added in v1.26.0 

func (p Path) Match(other Path) bool

Match the given path, interpreting wildcard matching for the comparison. This function is symmetrical. Use Equal() instead to compare Paths for absolute equality (no wildcard interpretation).

func (Path) Pointer 

func (p Path) Pointer() Path

Pointer returns the path extended with a pointer dereference.

func (Path) ResolveType 

func (p Path) ResolveType(t reflect.Type) (reflect.Type, error)

ResolveType will attempt to traverse the type with the Path and return the type of the field.

func (Path) String 

func (p Path) String() string

String implements Stringer.

type PlaceholderType added in v1.26.0 

type PlaceholderType struct {
	// Standard fields that the system expects to always exist on a valid
	// resource.
	Name, SelfLink              string
	NullFields, ForceSendFields []string
}

PlaceholderType is used to represent GCE resource type versions that either don't exist (e.g. there is not alpha version of the given resource) or we do not intend to use (e.g. we omitted the type/version from being included in pkg/cloud/meta).

Example 

// MyRes does not have an Alpha type:
type MyRes Resource[ga.MyRes, PlaceholderType, beta.MyRes]

type Resource 

type Resource[GA any, Alpha any, Beta any] interface {
	// Version of the resource. This cannot be indeterminant.
	Version() meta.Version
	// ResourceID fully qualitfied name of the resource.
	ResourceID() *cloud.ResourceID

	// Convert to the concrete types.
	ToGA() (*GA, error)
	ToAlpha() (*Alpha, error)
	ToBeta() (*Beta, error)

	// Diff obtains the difference between this resource and
	// other, taking into account the versions of the resources
	// being compared. Cross Alpha and Beta comparisons are not
	// currently supported.
	Diff(other Resource[GA, Alpha, Beta]) (*DiffResult, error)
}

Resource is read-only view into the resource. A Resource has a definitive Version.

type TypeTrait 

type TypeTrait[GA any, Alpha any, Beta any] interface {
	// CopyHelpers are hooks called after the generic copy operation is
	// complete. The func is given the post-copy src and dest struct and is free
	// to modify dest to complete the copy operation.
	CopyHelperGAtoAlpha(dest *Alpha, src *GA) error
	CopyHelperGAtoBeta(dest *Beta, src *GA) error
	CopyHelperAlphaToGA(dest *GA, src *Alpha) error
	CopyHelperAlphaToBeta(dest *Beta, src *Alpha) error
	CopyHelperBetaToGA(dest *GA, src *Beta) error
	CopyHelperBetaToAlpha(dest *Alpha, src *Beta) error

	// FieldTraits returns the field traits for the version given.
	FieldTraits(meta.Version) *FieldTraits
}

TypeTrait allows for specialization of the behavior for operations involving resources.

type TypeTraitFuncs 

type TypeTraitFuncs[GA any, Alpha any, Beta any] struct {
	CopyHelperGAtoAlphaF   func(dest *Alpha, src *GA) error
	CopyHelperGAtoBetaF    func(dest *Beta, src *GA) error
	CopyHelperAlphaToGAF   func(dest *GA, src *Alpha) error
	CopyHelperAlphaToBetaF func(dest *Beta, src *Alpha) error
	CopyHelperBetaToGAF    func(dest *GA, src *Beta) error
	CopyHelperBetaToAlphaF func(dest *Alpha, src *Beta) error
	FieldTraitsF           func(meta.Version) *FieldTraits
}

TypeTraitFuncs is a TypeTrait that takes func instead of defining an interface.

func (*TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperAlphaToBeta 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperAlphaToBeta(dest *Beta, src *Alpha) error

func (*TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperAlphaToGA 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperAlphaToGA(dest *GA, src *Alpha) error

func (*TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperBetaToAlpha 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperBetaToAlpha(dest *Alpha, src *Beta) error

func (*TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperBetaToGA 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperBetaToGA(dest *GA, src *Beta) error

func (*TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperGAtoAlpha 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperGAtoAlpha(dest *Alpha, src *GA) error

Implements TypeTrait.

func (*TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperGAtoBeta 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) CopyHelperGAtoBeta(dest *Beta, src *GA) error

func (*TypeTraitFuncs[GA, Alpha, Beta]) FieldTraits 

func (f *TypeTraitFuncs[GA, Alpha, Beta]) FieldTraits(v meta.Version) *FieldTraits

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.