attribute

Documentation

Overview

Package attribute provides a type-safe container of custom attributes named Values. This can be used to add custom metadata to a resolved address. Custom attributes are declared using NewKey to create a strongly-typed key. The values can then be defined using the key's Value method.

The following example declares two custom attributes, a floating point "weight", and a string "geographic region". It then constructs a new resolved Address that has values for each of them.

var (
	Weight           = attribute.NewKey[float64]()
	GeographicRegion = attribute.NewKey[string]()

	Address = resolver.Address{
		HostPort:   "111.222.123.234:5432",
		Attributes: attribute.NewValues(
			Weight.Value(1.25),
			GeographicRegion.Value("us-east1"),
		),
	}
)

Custom Resolver implementations can attach any kind of metadata to an address this way. This can be combined with a custom picker that uses the metadata, which can access the properties in a type-safe way using the GetValue function.

Such metadata can be used to implement regional affinity or to implement a weighted round-robin or random selection strategy (where a weight could be used to send more traffic to an address that has more available resources, such as more compute, memory, or network bandwidth).

Index

• func GetValue[T any](values Values, key *Key[T]) (value T, ok bool)
• type Key
  • func NewKey[T any]() *Key[T]
  • func (k *Key[T]) Value(value T) Value
• type Value
• type Values
  • func NewValues(values ...Value) Values

Functions

func GetValue

func GetValue[T any](values Values, key *Key[T]) (value T, ok bool)

GetValue retrieves a single value from the given Values. If the key is not present, the zero value and false will be returned instead.

Types

type Key

type Key[T any] struct {
	// contains filtered or unexported fields
}

Key is an attribute key. Applications should use NewKey to create a new key for each distinct attribute. The type T is the type of values this attribute can have.

func NewKey

func NewKey[T any]() *Key[T]

NewKey returns a new key that can have values of type T. Each call to NewKey results in a distinct attribute key, even if multiple are created for the same type. (Keys are identified by their address.)

func (*Key[T]) Value

func (k *Key[T]) Value(value T) Value

Value constructs a new Attr value, which can be passed to NewValues.

type Value

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

Value is a single custom attribute, composed of a key and corresponding value.

type Values

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

Values is a collection of type-safe custom metadata values. It contains a mapping of Key to value for any number of attribute keys.

func NewValues

func NewValues(values ...Value) Values

NewValues creates a new Values object with the provided values.

Use this function in tandem with Key.Value, like this:

var testKey = attribute.NewKey[string]()
...
attribute.NewValues(testKey.Value("test"))