state

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2024 License: MPL-2.0 Imports: 4 Imported by: 41

Documentation

Overview

Package state describes interface of the core state manager/broker.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsConflictError 

func IsConflictError(err error, opts ...ErrcheckOption) bool

IsConflictError checks if err is resource already exists/update conflict.

func IsInvalidWatchBookmarkError added in v0.7.6 

func IsInvalidWatchBookmarkError(err error) bool

IsInvalidWatchBookmarkError checks if err is invalid watch bookmark.

func IsNotFoundError 

func IsNotFoundError(err error) bool

IsNotFoundError checks if err is resource not found.

func IsOwnerConflictError 

func IsOwnerConflictError(err error) bool

IsOwnerConflictError checks if err is owner conflict error.

func IsPhaseConflictError 

func IsPhaseConflictError(err error) bool

IsPhaseConflictError checks if err is phase conflict error.

func IsUnsupportedError added in v0.2.0 

func IsUnsupportedError(err error) bool

IsUnsupportedError checks if err is unsupported operation.

Types

type Access 

type Access struct {
	ResourceNamespace resource.Namespace
	ResourceType      resource.Type
	ResourceID        resource.ID

	Verb Verb
}

Access describes state API access in a generic way.

type Bookmark added in v0.7.0 

type Bookmark []byte

Bookmark is an opaque value that can be used to resume watching from a specific point.

type CoreState 

type CoreState interface {
	// Get a resource by type and ID.
	//
	// If a resource is not found, error is returned.
	Get(context.Context, resource.Pointer, ...GetOption) (resource.Resource, error)

	// List resources by type.
	List(context.Context, resource.Kind, ...ListOption) (resource.List, error)

	// Create a resource.
	//
	// If a resource already exists, Create returns an error.
	Create(context.Context, resource.Resource, ...CreateOption) error

	// Update a resource.
	//
	// If a resource doesn't exist, error is returned.
	// On update current version of resource `new` in the state should match
	// the version on the backend, otherwise conflict error is returned.
	Update(ctx context.Context, newResource resource.Resource, opts ...UpdateOption) error

	// Destroy a resource.
	//
	// If a resource doesn't exist, error is returned.
	// If a resource has pending finalizers, error is returned.
	Destroy(context.Context, resource.Pointer, ...DestroyOption) error

	// Watch state of a resource by type.
	//
	// It's fine to watch for a resource which doesn't exist yet.
	// Watch is canceled when context gets canceled.
	// Watch sends initial resource state as the very first event on the channel,
	// and then sends any updates to the resource as events.
	Watch(context.Context, resource.Pointer, chan<- Event, ...WatchOption) error

	// WatchKind watches resources of specific kind (namespace and type).
	WatchKind(context.Context, resource.Kind, chan<- Event, ...WatchKindOption) error

	// WatchKindAggregated watches resources of specific kind (namespace and type), updates are sent aggregated.
	WatchKindAggregated(context.Context, resource.Kind, chan<- []Event, ...WatchKindOption) error
}

CoreState is the central broker in the system handling state and changes.

CoreState provides the core API that should be implemented. State extends CoreState API, but it can be implemented on top of CoreState.

func Filter 

func Filter(coreState CoreState, rule FilteringRule) CoreState

Filter state access by some rules.

Filter allows building RBAC access pattern or any other kinds of restictions.

type CreateOption 

type CreateOption func(*CreateOptions)

CreateOption builds CreateOptions.

func WithCreateOwner 

func WithCreateOwner(owner string) CreateOption

WithCreateOwner sets an owner for the created object.

type CreateOptions 

type CreateOptions struct {
	Owner string
}

CreateOptions for the CoreState.Create function.

type DestroyOption 

type DestroyOption func(*DestroyOptions)

DestroyOption builds DestroyOptions.

func WithDestroyOwner 

func WithDestroyOwner(owner string) DestroyOption

WithDestroyOwner checks an owner on the object being destroyed.

type DestroyOptions 

type DestroyOptions struct {
	Owner string
}

DestroyOptions for the CoreState.Destroy function.

type ErrConflict 

type ErrConflict interface {
	ConflictError()
	GetResource() resource.Pointer
}

ErrConflict should be implemented by already exists/update conflict errors.

type ErrInvalidWatchBookmark added in v0.7.6 

type ErrInvalidWatchBookmark interface {
	InvalidWatchBookmarkError()
}

ErrInvalidWatchBookmark should be implemented by "invalid watch bookmark" errors.

type ErrNotFound 

type ErrNotFound interface {
	NotFoundError()
}

ErrNotFound should be implemented by "not found" errors.

type ErrOwnerConflict 

type ErrOwnerConflict interface {
	OwnerConflictError()
}

ErrOwnerConflict should be implemented by owner conflict errors.

type ErrPhaseConflict 

type ErrPhaseConflict interface {
	PhaseConflictError()
}

ErrPhaseConflict should be implemented by resource phase conflict errors.

type ErrUnsupported added in v0.2.0 

type ErrUnsupported interface {
	UnsupportedError()
}

ErrUnsupported should be implemented by unsupported operation errors.

type ErrcheckOption added in v0.6.3 

type ErrcheckOption func(*ErrcheckOptions)

ErrcheckOption defines an additional error check option.

func WithResourceNamespace added in v0.6.3 

func WithResourceNamespace(ns resource.Namespace) ErrcheckOption

WithResourceNamespace checks if the error is related to the resource namespace.

func WithResourceType added in v0.6.3 

func WithResourceType(rt resource.Type) ErrcheckOption

WithResourceType checks if the error is related to the resource type.

type ErrcheckOptions added in v0.6.3 

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

ErrcheckOptions defines additional error check options.

type Event 

type Event struct {
	Resource resource.Resource
	Old      resource.Resource
	Error    error
	Bookmark Bookmark
	Type     EventType
}

Event is emitted when resource changes.

type EventType 

type EventType int

EventType is a type of StateEvent related to resource change. 

const (
	// Resource got created.
	Created EventType = iota
	// Resource got changed.
	Updated
	// Resource was destroyed.
	Destroyed
	// Initial set of items for WatchKind(WithBootstrapContents) was sent.
	Bootstrapped
	// Error happened in the watch.
	Errored
)

Various EventTypes.

func (EventType) String 

func (eventType EventType) String() string

type FilteringRule 

type FilteringRule func(ctx context.Context, access Access) error

FilteringRule defines a function which gets invoked on each state access.

Function might allow access by returning nil or deny access by returning an error which will be returned to the caller.

type GetOption 

type GetOption func(*GetOptions)

GetOption builds GetOptions.

func WithGetUnmarshalOptions added in v0.2.0 

func WithGetUnmarshalOptions(opt ...UnmarshalOption) GetOption

WithGetUnmarshalOptions sets unmarshal options for Get API.

type GetOptions 

type GetOptions struct {
	UnmarshalOptions UnmarshalOptions
}

GetOptions for the CoreState.Get function.

type ListOption 

type ListOption func(*ListOptions)

ListOption builds ListOptions.

func WithIDQuery added in v0.3.0 

func WithIDQuery(opt ...resource.IDQueryOption) ListOption

WithIDQuery appends an ID query to the list options.

func WithLabelQuery 

func WithLabelQuery(opt ...resource.LabelQueryOption) ListOption

WithLabelQuery appends a label query to the list options.

func WithListUnmarshalOptions added in v0.2.0 

func WithListUnmarshalOptions(opt ...UnmarshalOption) ListOption

WithListUnmarshalOptions sets unmarshal options for List API.

type ListOptions 

type ListOptions struct {
	IDQuery          resource.IDQuery
	LabelQueries     resource.LabelQueries
	UnmarshalOptions UnmarshalOptions
}

ListOptions for the CoreState.List function.

type ResourceConditionFunc 

type ResourceConditionFunc func(resource.Resource) (bool, error)

ResourceConditionFunc checks some condition on the resource.

type State 

type State interface {
	CoreState

	// UpdateWithConflicts automatically handles conflicts on update.
	UpdateWithConflicts(context.Context, resource.Pointer, UpdaterFunc, ...UpdateOption) (resource.Resource, error)

	// WatchFor watches for resource to reach all of the specified conditions.
	WatchFor(context.Context, resource.Pointer, ...WatchForConditionFunc) (resource.Resource, error)

	// Teardown a resource (mark as being destroyed).
	//
	// If a resource doesn't exist, error is returned.
	// It's not an error to tear down a resource which is already being torn down.
	// Teardown returns a flag telling whether it's fine to destroy a resource.
	Teardown(context.Context, resource.Pointer, ...TeardownOption) (bool, error)

	// AddFinalizer adds finalizer to resource metadata handling conflicts.
	AddFinalizer(context.Context, resource.Pointer, ...resource.Finalizer) error

	// RemoveFinalizer removes finalizer from resource metadata handling conflicts.
	RemoveFinalizer(context.Context, resource.Pointer, ...resource.Finalizer) error

	// ContextWithTeardown returns a new context which will be canceled when the resource is torn down or destroyed.
	//
	// The passed in context should be canceled, otherwise the goroutine might leak from this call.
	// If the resource doesn't exist, the context is canceled immediately.
	ContextWithTeardown(context.Context, resource.Pointer) (context.Context, error)
}

State extends CoreState with additional features which can be implemented on any CoreState.

func WrapCore 

func WrapCore(coreState CoreState) State

WrapCore converts CoreState to State.

type TeardownOption 

type TeardownOption func(*TeardownOptions)

TeardownOption builds TeardownOptions.

func WithTeardownOwner 

func WithTeardownOwner(owner string) TeardownOption

WithTeardownOwner checks an owner on the object being torn down.

type TeardownOptions 

type TeardownOptions struct {
	Owner string
}

TeardownOptions for the CoreState.Teardown function.

type UnmarshalOption added in v0.2.0 

type UnmarshalOption func(*UnmarshalOptions)

UnmarshalOption builds MarshalOptions.

func WithSkipProtobufUnmarshal added in v0.2.0 

func WithSkipProtobufUnmarshal() UnmarshalOption

WithSkipProtobufUnmarshal skips full unmarshaling returning a generic wrapper.

This options preservers original YAML representation.

type UnmarshalOptions added in v0.2.0 

type UnmarshalOptions struct {
	SkipProtobufUnmarshal bool
}

UnmarshalOptions control resources marshaling/unmarshaling.

type UpdateOption 

type UpdateOption func(*UpdateOptions)

UpdateOption builds UpdateOptions.

func WithExpectedPhase 

func WithExpectedPhase(phase resource.Phase) UpdateOption

WithExpectedPhase modifies expected resource phase for the update request.

Default value is resource.PhaseRunning.

func WithExpectedPhaseAny 

func WithExpectedPhaseAny() UpdateOption

WithExpectedPhaseAny accepts any resource phase for the update request.

Default value is resource.PhaseRunning.

func WithUpdateOwner 

func WithUpdateOwner(owner string) UpdateOption

WithUpdateOwner checks an owner on the object being updated.

type UpdateOptions 

type UpdateOptions struct {
	ExpectedPhase *resource.Phase
	Owner         string
}

UpdateOptions for the CoreState.Update function.

func DefaultUpdateOptions 

func DefaultUpdateOptions() UpdateOptions

DefaultUpdateOptions returns default value for UpdateOptions.

type UpdaterFunc 

type UpdaterFunc func(resource.Resource) error

UpdaterFunc is called on resource to update it to the desired state.

UpdaterFunc should also bump resource version.

type Verb 

type Verb int

Verb is API verb. 

const (
	Get Verb = iota
	List
	Watch
	Create
	Update
	Destroy
)

Verb definitions.

func (Verb) Readonly 

func (verb Verb) Readonly() bool

Readonly returns true for verbs which don't modify data.

type WatchForCondition 

type WatchForCondition struct {
	// If set, match only if func returns true.
	Condition ResourceConditionFunc
	// If set, wait for resource phase to be one of the specified.
	Phases []resource.Phase
	// If set, watch only for specified event types.
	EventTypes []EventType
	// If true, wait for the finalizers to empty
	FinalizersEmpty bool
}

WatchForCondition describes condition WatchFor is waiting for.

func (*WatchForCondition) Matches 

func (condition *WatchForCondition) Matches(event Event) (bool, error)

Matches checks whether event matches a condition.

type WatchForConditionFunc 

type WatchForConditionFunc func(*WatchForCondition) error

WatchForConditionFunc builds WatchForCondition.

func WithCondition 

func WithCondition(conditionFunc ResourceConditionFunc) WatchForConditionFunc

WithCondition for specified condition on the resource.

func WithEventTypes 

func WithEventTypes(types ...EventType) WatchForConditionFunc

WithEventTypes watches for specified event types (one of).

func WithFinalizerEmpty 

func WithFinalizerEmpty() WatchForConditionFunc

WithFinalizerEmpty waits for the resource finalizers to be empty.

func WithPhases 

func WithPhases(phases ...resource.Phase) WatchForConditionFunc

WithPhases watches for specified resource phases.

type WatchKindOption 

type WatchKindOption func(*WatchKindOptions)

WatchKindOption builds WatchOptions.

func WatchWithIDQuery added in v0.3.0 

func WatchWithIDQuery(opt ...resource.IDQueryOption) WatchKindOption

WatchWithIDQuery appends an ID query to the watch options.

func WatchWithLabelQuery 

func WatchWithLabelQuery(opt ...resource.LabelQueryOption) WatchKindOption

WatchWithLabelQuery appends a label query to the watch options.

func WithBootstrapContents 

func WithBootstrapContents(enable bool) WatchKindOption

WithBootstrapContents enables loading initial list of resources as 'created' events for WatchKind API.

func WithKindStartFromBookmark added in v0.7.0 

func WithKindStartFromBookmark(bookmark Bookmark) WatchKindOption

WithKindStartFromBookmark sets a bookmark to start watching from.

func WithKindTailEvents 

func WithKindTailEvents(n int) WatchKindOption

WithKindTailEvents returns N most recent events as part of the response.

func WithWatchKindUnmarshalOptions added in v0.2.0 

func WithWatchKindUnmarshalOptions(opt ...UnmarshalOption) WatchKindOption

WithWatchKindUnmarshalOptions sets unmarshal options for WatchKind API.

type WatchKindOptions 

type WatchKindOptions struct {
	IDQuery           resource.IDQuery
	LabelQueries      resource.LabelQueries
	StartFromBookmark Bookmark
	UnmarshalOptions  UnmarshalOptions
	BootstrapContents bool
	TailEvents        int
}

WatchKindOptions for the CoreState.WatchKind function.

type WatchOption 

type WatchOption func(*WatchOptions)

WatchOption builds WatchOptions.

func WithStartFromBookmark added in v0.7.0 

func WithStartFromBookmark(bookmark Bookmark) WatchOption

WithStartFromBookmark sets a bookmark to start watching from.

func WithTailEvents 

func WithTailEvents(n int) WatchOption

WithTailEvents returns N most recent events as part of the response.

func WithWatchUnmarshalOptions added in v0.2.0 

func WithWatchUnmarshalOptions(opt ...UnmarshalOption) WatchOption

WithWatchUnmarshalOptions sets unmarshal options for Watch API.

type WatchOptions 

type WatchOptions struct {
	StartFromBookmark Bookmark
	TailEvents        int
	UnmarshalOptions  UnmarshalOptions
}

WatchOptions for the CoreState.Watch function.

Source Files

View all Source files

Directories

Path Synopsis
Package conformance implements tests which verify conformance of the implementation with the spec.
 Package conformance implements tests which verify conformance of the implementation with the spec.
impl
inmem
Package inmem provides an implementation of state.State in memory.
 Package inmem provides an implementation of state.State in memory.
namespaced
Package namespaced provides an implementation of state split by namespaces.
 Package namespaced provides an implementation of state split by namespaces.
store
Package store provides support for in-memory backing store implementations.
 Package store provides support for in-memory backing store implementations.
store/bolt
Package bolt implements inmem resource collection backing store in BoltDB (github.com/etcd-io/bbolt).
 Package bolt implements inmem resource collection backing store in BoltDB (github.com/etcd-io/bbolt).
store/compression
Package compression provides compression support for store.Marshaler.
 Package compression provides compression support for store.Marshaler.
store/encryption
Package encryption provides encryption support for store.Marshaler.
 Package encryption provides encryption support for store.Marshaler.
Package protobuf provides wrappers/adapters between gRPC service and state.CoreState.
 Package protobuf provides wrappers/adapters between gRPC service and state.CoreState.
client
Package client provides a wrapper around gRPC State client to provide state.CoreState.
 Package client provides a wrapper around gRPC State client to provide state.CoreState.
server
Package server provides a wrapper around state.CoreState into gRPC server.
 Package server provides a wrapper around state.CoreState into gRPC server.
Package registry provides registries for namespaces and resource definitions.
 Package registry provides registries for namespaces and resource definitions.

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.