resource

package
v0.0.0-...-8846729 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2024 License: MIT Imports: 22 Imported by: 22

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	TweenComplete = io.EOF
	TweenStopped  = errors.New("tween stopped")
)
View Source 
var DefaultTweenOptions = []TweenOption{
	WithBounds(0, 100),
	WithFramesPerSecond(10),
	WithDuration(time.Second),
	WithEasing(ease.Linear),
}
View Source 
var ExpectAbsentPreconditionFailed = status.Error(codes.AlreadyExists, "value already exists")

ExpectAbsentPreconditionFailed is returned when an update configured WithExpectAbsent already has a value.

View Source 
var ExpectedValuePreconditionFailed = status.Error(codes.FailedPrecondition, "current value is not as expected")

ExpectedValuePreconditionFailed is returned when an update configured WithExpectedValue fails its comparison.

Functions

func GenerateUniqueId 

func GenerateUniqueId(rng io.Reader, exists func(candidate string) bool) (string, error)

GenerateUniqueId attempts to find a unique id using rand and using the given function to check existence. This will attempt a few times before giving up and returning an error.

func GetAndUpdate 

func GetAndUpdate(mu *sync.RWMutex, get GetFn, change ChangeFn, save SaveFn) (oldValue proto.Message, newValue proto.Message, err error)

GetAndUpdate applies an atomic get and update operation in the context of proto messages. mu.RLock will be held during the get call. mu.Lock will be held during the save call. No locks will be held during the change call.

An error will be returned if the value returned by get changes during the change call.

func ValidateNoProgress 

func ValidateNoProgress(name string, tween *types.Tween) error

func ValidateNonNegativeDuration 

func ValidateNonNegativeDuration(name string, tween *types.Tween) error

func ValidateTweenOnUpdate 

func ValidateTweenOnUpdate(name string, tween *types.Tween) error

Types

type ChangeFn 

type ChangeFn func(old, dst proto.Message) (proto.Message, error)

ChangeFn is called to apply changes to a proto.Message. old and dst are the current message and a message to change. If old is nil, there is no current message. If dst is nil, then the resource was unable to allocate a message of the correct type to apply changes to. The implementation is free to ignore both arguments but must return a message containing the desired changes.

type Clock 

type Clock interface {
	Now() time.Time
}

Clock defines all time related features required by this package.

func WallClock 

func WallClock() Clock

WallClock returns a Clock backed by the time package.

type Collection 

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

func NewCollection 

func NewCollection(options ...Option) *Collection

func (*Collection) Add 

func (c *Collection) Add(id string, body proto.Message, opts ...WriteOption) (proto.Message, error)

Add associates the given body with the id. If id already exists then an error is returned. A common set of options is WithGenIDIfAbsent() and WithIDCallback, which allows this function to generate a unique id if the given id is empty.

Calling Add is equivalent to calling Update(id, body, WithExpectAbsent(), WithCreateIfAbsent(), opts...)

func (*Collection) Clock 

func (c *Collection) Clock() Clock

Clock returns the clock used by this resource for reporting time.

func (*Collection) Delete 

func (c *Collection) Delete(id string, opts ...WriteOption) (proto.Message, error)

Delete removes the item with the given id from this collection. The removed item will be returned. If the id is unknown an error will be returned, unless WithAllowMissing is specified. Read-update-write operations can be checked via WithExpectedValue or WithExpectedCheck options.

func (*Collection) Get 

func (c *Collection) Get(id string, opts ...ReadOption) (proto.Message, bool)

Get will find the entry with the given ID. If no such entry exists, returns false.

func (*Collection) List 

func (c *Collection) List(opts ...ReadOption) []proto.Message

List returns a list of all the entries, sorted by their ID.

func (*Collection) Pull 

func (c *Collection) Pull(ctx context.Context, opts ...ReadOption) <-chan *CollectionChange

func (*Collection) PullID 

func (c *Collection) PullID(ctx context.Context, id string, opts ...ReadOption) <-chan *ValueChange

PullID subscribes to changes for a single item in the collection. The returned channel will close if ctx is Done or the item identified by id is deleted.

func (*Collection) Update 

func (c *Collection) Update(id string, msg proto.Message, opts ...WriteOption) (proto.Message, error)

type CollectionChange 

type CollectionChange struct {
	Id         string
	ChangeTime time.Time
	ChangeType types.ChangeType
	OldValue   proto.Message
	NewValue   proto.Message
	// Deprecated, use LastSeedValue instead.
	// SeedValue will be true if the change was part of sending initial data as opposed to an update.
	SeedValue bool
	// LastSeedValue will be true if this change is the last change as part of the seed values.
	LastSeedValue bool
}

CollectionChange contains information about a change to a Collection.

type Comparer 

type Comparer interface {
	// Compare compares two messages that changed at a specific time.
	// If ok is false then this Comparator did not attempt to compare the two messages, in other words the equal result
	// should be ignored.
	Compare(x, y proto.Message) bool
}

Comparer compares two messages for equivalence. This interface is used during the Pull operation to de-duplicate consecutive emissions.

type ComparerFunc 

type ComparerFunc func(x, y proto.Message) bool

ComparerFunc converts a func of the correct signature into a Comparer.

func (ComparerFunc) Compare 

func (c ComparerFunc) Compare(x, y proto.Message) bool

type CreateFn 

type CreateFn func(id string) proto.Message

CreateFn is called to generate a message based on the ID the message is going to have.

type EmptyOption 

type EmptyOption struct {
}

EmptyOption is an Option that makes no changes to the semantics of the resource. Useful for embedding in another struct to enable custom resource options.

type EmptyReadOption 

type EmptyReadOption struct {
}

EmptyReadOption is a ReadOption that makes no changes to the semantics of the read. Useful for embedding in another struct to enable custom read options.

type EmptyWriteOption 

type EmptyWriteOption struct{}

EmptyWriteOption is a WriteOption that makes no changes to the semantics of the write. Useful for embedding in another struct to enable custom write options.

type FilterFunc 

type FilterFunc func(id string, item proto.Message) bool

FilterFunc defines the signature for a function that filters items from a collection.

type GetFn 

type GetFn func() (item proto.Message, err error)

GetFn is called to retrieve the message from the external store.

type IDInterceptor 

type IDInterceptor = func(oldID string) (newID string)

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option configures a resource value or collection.

func WithClock 

func WithClock(c Clock) Option

WithClock configures the clock used when time is needed. Defaults to a Clock backed by the time package.

func WithEquivalence 

func WithEquivalence(e Comparer) Option

WithEquivalence configures how consecutive emissions are compared, equivalent emissions are not emitted. Defaults to nil, no equivalence checking is performed, all events will be emitted.

func WithIDInterceptor 

func WithIDInterceptor(interceptor IDInterceptor) Option

WithIDInterceptor will map IDs provided to Collection methods to another ID before reading or writing from the collection. Applicable only to Collection. For example, this can be used to make a case-insensitive collection by mapping all IDs to lowercase.

func WithInitialRecord 

func WithInitialRecord(id string, value proto.Message) Option

WithInitialRecord configures an initial record for a collection resource. Panics if a record with the given id has already been configured.

func WithInitialValue 

func WithInitialValue(initialValue proto.Message) Option

WithInitialValue configures the initial value for the resource. Applies only to Value.

func WithMessageEquivalence 

func WithMessageEquivalence(e cmp.Message) Option

WithMessageEquivalence is like WithEquivalence but using a cmp.Message.

func WithNoDuplicates 

func WithNoDuplicates() Option

WithNoDuplicates is like WithMessageEquivalence(cmp.Equal()).

func WithRNG 

func WithRNG(rng io.Reader) Option

WithRNG configures the source of randomness for the resource. Defaults to rand.Rand with a time seed.

func WithWritableFields 

func WithWritableFields(mask *fieldmaskpb.FieldMask) Option

WithWritableFields configures write operations on the resource to accept updates to the given fields only. Explicit writes to fields not in this mask will fail.

func WithWritablePaths 

func WithWritablePaths(m proto.Message, paths ...string) Option

WithWritablePaths is like WithWritableFields using fieldmaskpb.New.

type ReadOption 

type ReadOption interface {
	// contains filtered or unexported methods
}

ReadOption configures settings for reading data.

func WithBackpressure 

func WithBackpressure(backpressure bool) ReadOption

WithBackpressure will enabled or disable backpressure for Pull calls. Defaults to false. It has no effect on Get calls. Pulls with backpressure enabled will block the corresponding call to Set until the update has been received, so the Pull will always receive all changes. If backpressure is disabled, then if the Pull channel receiver can't keep up, older updates will be dropped or merged into newer updates while attempting to keep the semantics of the pull.

func WithInclude 

func WithInclude(include FilterFunc) ReadOption

WithInclude instructs collection List or Pull methods to only include items where the given FilterFunc returns true. During Pull if an item is updated so it's inclusion changes, the ChangeType will correctly reflect the change of inclusion for that type in the response set. For example if the item wasn't included in the response, then was updated so that include now returns true, then the change is an ADD.

func WithReadMask 

func WithReadMask(mask *fieldmaskpb.FieldMask) ReadOption

WithReadMask configures the properties that will be filled in the response value.

func WithReadPaths 

func WithReadPaths(m proto.Message, paths ...string) ReadOption

WithReadPaths configures the properties that will be filled in the response value. Panics if paths aren't part of m.

func WithUpdatesOnly 

func WithUpdatesOnly(updatesOnly bool) ReadOption

WithUpdatesOnly instructs Pull methods to only send updates. The default behaviour is to send the current value, followed by future updates.

type ReadRequest 

type ReadRequest struct {
	ReadMask *fieldmaskpb.FieldMask

	UpdatesOnly  bool
	Backpressure bool

	Include FilterFunc
}

ReadRequest configures the properties of a read operation.

func ComputeReadConfig 

func ComputeReadConfig(opts ...ReadOption) *ReadRequest

ComputeReadConfig returns a ReadRequest configured using the given ReadOptions.

func (*ReadRequest) Exclude 

func (rr *ReadRequest) Exclude(id string, m proto.Message) bool

Exclude returns true if the given message should be excluded from responses to collection List or Pull.

func (*ReadRequest) FilterClone 

func (rr *ReadRequest) FilterClone(m proto.Message) proto.Message

FilterClone in the equivalent of rr.ResponseFilter().FilterClone(m).

func (*ReadRequest) ResponseFilter 

func (rr *ReadRequest) ResponseFilter() *masks.ResponseFilter

ResponseFilter returns a masks.ResponseFilter configured using this readRequest properties.

type SaveFn 

type SaveFn func(msg proto.Message)

SaveFn is called to save the message in the external store.

type Tween 

type Tween struct {
	Start           float32
	End             float32
	Duration        time.Duration
	Easing          ease.TweenFunc
	FramesPerSecond float32
	// contains filtered or unexported fields
}

func NewTween 

func NewTween(opts ...TweenOption) *Tween

func (*Tween) NextFrame 

func (t *Tween) NextFrame() (float32, error)

type TweenOption 

type TweenOption func(*Tween)

func WithBounds 

func WithBounds(start, end float32) TweenOption

func WithDuration 

func WithDuration(duration time.Duration) TweenOption

func WithEasing 

func WithEasing(easing ease.TweenFunc) TweenOption

func WithFramesPerSecond 

func WithFramesPerSecond(fps float32) TweenOption

type UpdateInterceptor 

type UpdateInterceptor func(old, new proto.Message)

UpdateInterceptor describes a function that applies changes to an existing message

type Value 

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

Value represents a simple state field in an object. Think Temperature or Volume or Occupancy. Use a Value to gain thread safe reads/writes that also support FieldMasks and update notifications.

func NewValue 

func NewValue(opts ...Option) *Value

func (*Value) Clock 

func (r *Value) Clock() Clock

Clock returns the clock used by this resource for reporting time.

func (*Value) Get 

func (r *Value) Get(opts ...ReadOption) proto.Message

func (*Value) Pull 

func (r *Value) Pull(ctx context.Context, opts ...ReadOption) <-chan *ValueChange

Pull emits a ValueChange on the returned chan whenever the underlying value changes. The changes emitted can be adjusted using WithEquivalence. The returned chan will be closed when no more events will be emitted, either because ctx was cancelled or for other reasons.

func (*Value) Set 

func (r *Value) Set(value proto.Message, opts ...WriteOption) (proto.Message, error)

Set updates the current value of this Value with the given value. Returns the new value. Provide WriteOption to control masks and other variables during the update.

type ValueChange 

type ValueChange struct {
	Value      proto.Message
	ChangeTime time.Time
	// Deprecated, use LastSeedValue instead.
	// SeedValue will be true if the change was part of sending initial data as opposed to an update.
	SeedValue bool
	// LastSeedValue will be true if this change is the last change as part of the seed values.
	LastSeedValue bool
}

ValueChange contains information about a change to a Value.

type WriteOption 

type WriteOption interface {
	// contains filtered or unexported methods
}

func InterceptAfter 

func InterceptAfter(interceptor UpdateInterceptor) WriteOption

InterceptAfter registers a function that will be called after changes have been made but before they are saved. This is useful if there are computed properties in the message that might need setting if an update has occurred, for example a `LastUpdateTime` or similar.

Example 

r.Set(val, InterceptAfter(func(old, new proto.Message) {
  // assume casting
  if old.Quantity != new.Quantity {
    new.UpdateTime = timestamppb.Now()
  }
}))

func InterceptBefore 

func InterceptBefore(interceptor UpdateInterceptor) WriteOption

InterceptBefore registers a function that will be called before the update occurs. The new value passed to the function will be the Message given as part of the update operation. Do not write to the old value of the callback, this is for information only. This is useful when applying delta update to a value, in this case you can append the old value to the update value to get the sum.

Example 

r.Set(val, InterceptBefore(func(old, change proto.Message) {
  if val.Delta {
    // assume casting
    change.Quantity += old.Quantity
  }
}))

func WithAllFieldsWritable 

func WithAllFieldsWritable() WriteOption

WithAllFieldsWritable instructs the update to ignore the resources configured writable fields. All fields will be writable if using this option. Prefer WithMoreWritableFields if possible.

func WithAllowMissing 

func WithAllowMissing(allowMissing bool) WriteOption

WithAllowMissing instructs a delete to not return an error if the item is absent.

func WithCreateIfAbsent 

func WithCreateIfAbsent() WriteOption

WithCreateIfAbsent instructs the write to create an entry if none already exist. Applicable only to Collection updates. When specified any interceptors will receive a zero old value of the collection item type.

func WithCreatedCallback 

func WithCreatedCallback(cb func()) WriteOption

WithCreatedCallback calls cb if during an update, a new value is created. Applicable only to Collection updates. Use the response from the Update call to get the actual value.

func WithExpectAbsent 

func WithExpectAbsent() WriteOption

WithExpectAbsent instructs the update to only proceed if the current value is absent. If the precondition fails the update will return the error ExpectAbsentPreconditionFailed. The precondition will be checked _before_ InterceptBefore.

func WithExpectedCheck 

func WithExpectedCheck(fn func(msg proto.Message) error) WriteOption

WithExpectedCheck instructs the update to only proceed if the current value, when passed to fn, returns no error. The error returned from fn will be returned from the update call. The precondition will be checked _before_ InterceptBefore.

func WithExpectedValue 

func WithExpectedValue(expectedValue proto.Message) WriteOption

WithExpectedValue instructs the update to only proceed if the current value is equal to expectedValue. If the precondition fails the update will return the error ExpectedValuePreconditionFailed. The precondition will be checked _before_ InterceptBefore.

func WithGenIDIfAbsent 

func WithGenIDIfAbsent() WriteOption

WithGenIDIfAbsent instructs an update operation to generate an ID if one isn't provided. Typically only useful when WithCreateIfAbsent is used, otherwise the update will fail with NotFound. See WithIDCallback if the ID is stored as a property in the resource type.

func WithIDCallback 

func WithIDCallback(cb func(id string)) WriteOption

WithIDCallback calls cb with an ID that has been generated, typically during create calls. Applicable only to Collection updates. If the resource being stored in the collection has a property that holds the id, then cb should set that property using the given id string.

func WithMoreUpdateMask 

func WithMoreUpdateMask(mask *fieldmaskpb.FieldMask) WriteOption

WithMoreUpdateMask adds the given fields to the update mask.

func WithMoreUpdatePaths 

func WithMoreUpdatePaths(paths ...string) WriteOption

WithMoreUpdatePaths is like WithMoreUpdateMask but with paths instead.

func WithMoreWritableFields 

func WithMoreWritableFields(writableFields *fieldmaskpb.FieldMask) WriteOption

WithMoreWritableFields adds the given fields to the resources configured writable fields before validating the update. Prefer this over WithAllFieldsWritable.

func WithMoreWritablePaths 

func WithMoreWritablePaths(writablePaths ...string) WriteOption

WithMoreWritablePaths is like WithMoreWritableFields but with paths instead.

func WithResetMask 

func WithResetMask(mask *fieldmaskpb.FieldMask) WriteOption

WithResetMask configures the update to clear these fields from the final value. This will happen after InterceptBefore, but before InterceptAfter. WithWritableFields does not affect this.

func WithResetPaths 

func WithResetPaths(paths ...string) WriteOption

WithResetPaths is like WithResetMask but the FieldMask is made from the given paths.

func WithUpdateMask 

func WithUpdateMask(mask *fieldmaskpb.FieldMask) WriteOption

WithUpdateMask configures the update to only apply to these fields. nil will update all writable fields. Fields specified here that aren't in the Resources writable fields will result in an error

func WithUpdatePaths 

func WithUpdatePaths(paths ...string) WriteOption

WithUpdatePaths is like WithUpdateMask but the FieldMask is made from the given paths.

func WithWriteTime 

func WithWriteTime(t time.Time) WriteOption

WithWriteTime configures the update to behave as if the write happened at time t, instead of now. Any change events that may be emitted with this write use t as their ChangeTime. Computational values, for example tweening, can use this to correctly determine the computed value.

type WriteRequest 

type WriteRequest struct {
	UpdateMask *fieldmaskpb.FieldMask
	// contains filtered or unexported fields
}

func ComputeWriteConfig 

func ComputeWriteConfig(opts ...WriteOption) WriteRequest

Source Files

View all Source files

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.