state

Documentation

Overview

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

Index

• func IsConflictError(err error) bool
• func IsNotFoundError(err error) bool
• func IsOwnerConflictError(err error) bool
• func IsPhaseConflictError(err error) bool
• func IsUnsupportedError(err error) bool
• type Access
• type CoreState
  • func Filter(coreState CoreState, rule FilteringRule) CoreState
• type CreateOption
  • func WithCreateOwner(owner string) CreateOption
• type CreateOptions
• type DestroyOption
  • func WithDestroyOwner(owner string) DestroyOption
• type DestroyOptions
• type ErrConflict
• type ErrNotFound
• type ErrOwnerConflict
• type ErrPhaseConflict
• type ErrUnsupported
• type Event
• type EventType
  • func (eventType EventType) String() string
• type FilteringRule
• type GetOption
• type GetOptions
• type ListOption
  • func WithLabelQuery(opt ...resource.LabelQueryOption) ListOption
• type ListOptions
• type ResourceConditionFunc
• type State
  • func WrapCore(coreState CoreState) State
• type TeardownOption
  • func WithTeardownOwner(owner string) TeardownOption
• type TeardownOptions
• type UpdateOption
  • func WithExpectedPhase(phase resource.Phase) UpdateOption
  • func WithExpectedPhaseAny() UpdateOption
  • func WithUpdateOwner(owner string) UpdateOption
• type UpdateOptions
  • func DefaultUpdateOptions() UpdateOptions
• type UpdaterFunc
• type Verb
  • func (verb Verb) Readonly() bool
• type WatchForCondition
  • func (condition *WatchForCondition) Matches(event Event) (bool, error)
• type WatchForConditionFunc
  • func WithCondition(conditionFunc ResourceConditionFunc) WatchForConditionFunc
  • func WithEventTypes(types ...EventType) WatchForConditionFunc
  • func WithFinalizerEmpty() WatchForConditionFunc
  • func WithPhases(phases ...resource.Phase) WatchForConditionFunc
• type WatchKindOption
  • func WatchWithLabelQuery(opt ...resource.LabelQueryOption) WatchKindOption
  • func WithBootstrapContents(enable bool) WatchKindOption
  • func WithKindTailEvents(n int) WatchKindOption
• type WatchKindOptions
• type WatchOption
  • func WithTailEvents(n int) WatchOption
• type WatchOptions

Functions

func IsConflictError

func IsConflictError(err error) bool

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

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

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

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

ErrConflict should be implemented by already exists/update conflict 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

type ErrUnsupported interface {
	UnsupportedError()
}

ErrUnsupported should be implemented by unsupported operation errors.

type Event

type Event struct {
	Resource resource.Resource
	Old      resource.Resource
	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
)

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.

type GetOptions

type GetOptions struct{}

GetOptions for the CoreState.Get function.

type ListOption

type ListOption func(*ListOptions)

ListOption builds ListOptions.

func WithLabelQuery

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

WithLabelQuery appends a label query to the list options.

type ListOptions

type ListOptions struct {
	LabelQuery resource.LabelQuery
}

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
}

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

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

WatchWithLabelQuery appends a label query to the list options.

func WithBootstrapContents

func WithBootstrapContents(enable bool) WatchKindOption

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

func WithKindTailEvents

func WithKindTailEvents(n int) WatchKindOption

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

type WatchKindOptions

type WatchKindOptions struct {
	LabelQuery        resource.LabelQuery
	BootstrapContents bool
	TailEvents        int
}

WatchKindOptions for the CoreState.WatchKind function.

type WatchOption

type WatchOption func(*WatchOptions)

WatchOption builds WatchOptions.

func WithTailEvents

func WithTailEvents(n int) WatchOption

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

type WatchOptions

type WatchOptions struct {
	TailEvents int
}

WatchOptions for the CoreState.Watch function.