Initial QSfera import

Server/vendor/golang.org/x/tools/internal/event/core/event.go

@@ -0,0 +1,95 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package core provides support for event based telemetry.
+package core
+
+import (
+	"fmt"
+	"iter"
+	"time"
+
+	"golang.org/x/tools/internal/event/label"
+)
+
+// Event holds the information about an event of note that occurred.
+type Event struct {
+	at time.Time
+
+	// As events are often on the stack, storing the first few labels directly
+	// in the event can avoid an allocation at all for the very common cases of
+	// simple events.
+	// The length needs to be large enough to cope with the majority of events
+	// but no so large as to cause undue stack pressure.
+	// A log message with two values will use 3 labels (one for each value and
+	// one for the message itself).
+
+	static  [3]label.Label // inline storage for the first few labels
+	dynamic []label.Label  // dynamically sized storage for remaining labels
+}
+
+func (ev Event) At() time.Time { return ev.at }
+
+func (ev Event) Format(f fmt.State, r rune) {
+	if !ev.at.IsZero() {
+		fmt.Fprint(f, ev.at.Format("2006/01/02 15:04:05 "))
+	}
+	for l := range ev.Labels() {
+		fmt.Fprintf(f, "\n\t%v", l)
+	}
+}
+
+func (ev Event) Valid(index int) bool {
+	return index >= 0 && index < len(ev.static)+len(ev.dynamic)
+}
+
+func (ev Event) Label(index int) label.Label {
+	if index < len(ev.static) {
+		return ev.static[index]
+	}
+	return ev.dynamic[index-len(ev.static)]
+}
+
+// Labels returns an iterator over the event's valid labels.
+func (ev Event) Labels() iter.Seq[label.Label] {
+	return func(yield func(label.Label) bool) {
+		for _, l := range ev.static {
+			if l.Valid() && !yield(l) {
+				return
+			}
+		}
+		for _, l := range ev.dynamic {
+			if l.Valid() && !yield(l) {
+				return
+			}
+		}
+	}
+}
+
+func (ev Event) Find(key label.Key) label.Label {
+	for _, l := range ev.static {
+		if l.Key() == key {
+			return l
+		}
+	}
+	for _, l := range ev.dynamic {
+		if l.Key() == key {
+			return l
+		}
+	}
+	return label.Label{}
+}
+
+func MakeEvent(static [3]label.Label, labels []label.Label) Event {
+	return Event{
+		static:  static,
+		dynamic: labels,
+	}
+}
+
+// CloneEvent event returns a copy of the event with the time adjusted to at.
+func CloneEvent(ev Event, at time.Time) Event {
+	ev.at = at
+	return ev
+}

Server/vendor/golang.org/x/tools/internal/event/core/export.go

@@ -0,0 +1,67 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package core
+
+import (
+	"context"
+	"sync/atomic"
+	"time"
+
+	"golang.org/x/tools/internal/event/label"
+)
+
+// Exporter is a function that handles events.
+// It may return a modified context and event.
+type Exporter func(context.Context, Event, label.Map) context.Context
+
+var exporter atomic.Pointer[Exporter]
+
+// SetExporter sets the global exporter function that handles all events.
+// The exporter is called synchronously from the event call site, so it should
+// return quickly so as not to hold up user code.
+func SetExporter(e Exporter) {
+	if e == nil {
+		// &e is always valid, and so p is always valid, but for the early abort
+		// of ProcessEvent to be efficient it needs to make the nil check on the
+		// pointer without having to dereference it, so we make the nil function
+		// also a nil pointer
+		exporter.Store(nil)
+	} else {
+		exporter.Store(&e)
+	}
+}
+
+// deliver is called to deliver an event to the supplied exporter.
+// it will fill in the time.
+func deliver(ctx context.Context, exporter Exporter, ev Event) context.Context {
+	// add the current time to the event
+	ev.at = time.Now()
+	// hand the event off to the current exporter
+	return exporter(ctx, ev, ev)
+}
+
+// Export is called to deliver an event to the global exporter if set.
+func Export(ctx context.Context, ev Event) context.Context {
+	// get the global exporter and abort early if there is not one
+	exporterPtr := exporter.Load()
+	if exporterPtr == nil {
+		return ctx
+	}
+	return deliver(ctx, *exporterPtr, ev)
+}
+
+// ExportPair is called to deliver a start event to the supplied exporter.
+// It also returns a function that will deliver the end event to the same
+// exporter.
+// It will fill in the time.
+func ExportPair(ctx context.Context, begin, end Event) (context.Context, func()) {
+	// get the global exporter and abort early if there is not one
+	exporterPtr := exporter.Load()
+	if exporterPtr == nil {
+		return ctx, func() {}
+	}
+	ctx = deliver(ctx, *exporterPtr, begin)
+	return ctx, func() { deliver(ctx, *exporterPtr, end) }
+}

Server/vendor/golang.org/x/tools/internal/event/core/fast.go

@@ -0,0 +1,77 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package core
+
+import (
+	"context"
+
+	"golang.org/x/tools/internal/event/keys"
+	"golang.org/x/tools/internal/event/label"
+)
+
+// Log1 takes a message and one label delivers a log event to the exporter.
+// It is a customized version of Print that is faster and does no allocation.
+func Log1(ctx context.Context, message string, t1 label.Label) {
+	Export(ctx, MakeEvent([3]label.Label{
+		keys.Msg.Of(message),
+		t1,
+	}, nil))
+}
+
+// Log2 takes a message and two labels and delivers a log event to the exporter.
+// It is a customized version of Print that is faster and does no allocation.
+func Log2(ctx context.Context, message string, t1 label.Label, t2 label.Label) {
+	Export(ctx, MakeEvent([3]label.Label{
+		keys.Msg.Of(message),
+		t1,
+		t2,
+	}, nil))
+}
+
+// Metric1 sends a label event to the exporter with the supplied labels.
+func Metric1(ctx context.Context, t1 label.Label) context.Context {
+	return Export(ctx, MakeEvent([3]label.Label{
+		keys.Metric.New(),
+		t1,
+	}, nil))
+}
+
+// Metric2 sends a label event to the exporter with the supplied labels.
+func Metric2(ctx context.Context, t1, t2 label.Label) context.Context {
+	return Export(ctx, MakeEvent([3]label.Label{
+		keys.Metric.New(),
+		t1,
+		t2,
+	}, nil))
+}
+
+// Start1 sends a span start event with the supplied label list to the exporter.
+// It also returns a function that will end the span, which should normally be
+// deferred.
+func Start1(ctx context.Context, name string, t1 label.Label) (context.Context, func()) {
+	return ExportPair(ctx,
+		MakeEvent([3]label.Label{
+			keys.Start.Of(name),
+			t1,
+		}, nil),
+		MakeEvent([3]label.Label{
+			keys.End.New(),
+		}, nil))
+}
+
+// Start2 sends a span start event with the supplied label list to the exporter.
+// It also returns a function that will end the span, which should normally be
+// deferred.
+func Start2(ctx context.Context, name string, t1, t2 label.Label) (context.Context, func()) {
+	return ExportPair(ctx,
+		MakeEvent([3]label.Label{
+			keys.Start.Of(name),
+			t1,
+			t2,
+		}, nil),
+		MakeEvent([3]label.Label{
+			keys.End.New(),
+		}, nil))
+}

Server/vendor/golang.org/x/tools/internal/event/doc.go

@@ -0,0 +1,7 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package event provides a set of packages that cover the main
+// concepts of telemetry in an implementation agnostic way.
+package event

Server/vendor/golang.org/x/tools/internal/event/event.go

@@ -0,0 +1,127 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package event
+
+import (
+	"context"
+
+	"golang.org/x/tools/internal/event/core"
+	"golang.org/x/tools/internal/event/keys"
+	"golang.org/x/tools/internal/event/label"
+)
+
+// Exporter is a function that handles events.
+// It may return a modified context and event.
+type Exporter func(context.Context, core.Event, label.Map) context.Context
+
+// SetExporter sets the global exporter function that handles all events.
+// The exporter is called synchronously from the event call site, so it should
+// return quickly so as not to hold up user code.
+func SetExporter(e Exporter) {
+	core.SetExporter(core.Exporter(e))
+}
+
+// Log takes a message and a label list and combines them into a single event
+// before delivering them to the exporter.
+func Log(ctx context.Context, message string, labels ...label.Label) {
+	core.Export(ctx, core.MakeEvent([3]label.Label{
+		keys.Msg.Of(message),
+	}, labels))
+}
+
+// IsLog returns true if the event was built by the Log function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsLog(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.Msg
+}
+
+// Error takes a message and a label list and combines them into a single event
+// before delivering them to the exporter. It captures the error in the
+// delivered event.
+func Error(ctx context.Context, message string, err error, labels ...label.Label) {
+	core.Export(ctx, core.MakeEvent([3]label.Label{
+		keys.Msg.Of(message),
+		keys.Err.Of(err),
+	}, labels))
+}
+
+// IsError returns true if the event was built by the Error function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsError(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.Msg &&
+		ev.Label(1).Key() == keys.Err
+}
+
+// Metric sends a label event to the exporter with the supplied labels.
+func Metric(ctx context.Context, labels ...label.Label) {
+	core.Export(ctx, core.MakeEvent([3]label.Label{
+		keys.Metric.New(),
+	}, labels))
+}
+
+// IsMetric returns true if the event was built by the Metric function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsMetric(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.Metric
+}
+
+// Label sends a label event to the exporter with the supplied labels.
+func Label(ctx context.Context, labels ...label.Label) context.Context {
+	return core.Export(ctx, core.MakeEvent([3]label.Label{
+		keys.Label.New(),
+	}, labels))
+}
+
+// IsLabel returns true if the event was built by the Label function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsLabel(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.Label
+}
+
+// Start sends a span start event with the supplied label list to the exporter.
+// It also returns a function that will end the span, which should normally be
+// deferred.
+func Start(ctx context.Context, name string, labels ...label.Label) (context.Context, func()) {
+	return core.ExportPair(ctx,
+		core.MakeEvent([3]label.Label{
+			keys.Start.Of(name),
+		}, labels),
+		core.MakeEvent([3]label.Label{
+			keys.End.New(),
+		}, nil))
+}
+
+// IsStart returns true if the event was built by the Start function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsStart(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.Start
+}
+
+// IsEnd returns true if the event was built by the End function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsEnd(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.End
+}
+
+// Detach returns a context without an associated span.
+// This allows the creation of spans that are not children of the current span.
+func Detach(ctx context.Context) context.Context {
+	return core.Export(ctx, core.MakeEvent([3]label.Label{
+		keys.Detach.New(),
+	}, nil))
+}
+
+// IsDetach returns true if the event was built by the Detach function.
+// It is intended to be used in exporters to identify the semantics of the
+// event when deciding what to do with it.
+func IsDetach(ev core.Event) bool {
+	return ev.Label(0).Key() == keys.Detach
+}

Server/vendor/golang.org/x/tools/internal/event/keys/keys.go

@@ -0,0 +1,237 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package keys
+
+import (
+	"fmt"
+	"math"
+	"strconv"
+
+	"golang.org/x/tools/internal/event/label"
+)
+
+// Value is a [label.Key] for untyped values.
+type Value struct {
+	name        string
+	description string
+}
+
+// New creates a new Key for untyped values.
+func New(name, description string) *Value {
+	return &Value{name: name, description: description}
+}
+
+func (k *Value) Name() string        { return k.name }
+func (k *Value) Description() string { return k.description }
+
+func (k *Value) Append(buf []byte, l label.Label) []byte {
+	return fmt.Append(buf, k.From(l))
+}
+
+// Get returns the label for the key of a label.Map.
+func (k *Value) Get(lm label.Map) any {
+	if t := lm.Find(k); t.Valid() {
+		return k.From(t)
+	}
+	return nil
+}
+
+// From returns the value of a Label.
+func (k *Value) From(t label.Label) any { return t.UnpackValue() }
+
+// Of creates a new Label with this key and the supplied value.
+func (k *Value) Of(value any) label.Label { return label.OfValue(k, value) }
+
+// Tag represents a key for tagging labels that have no value.
+// These are used when the existence of the label is the entire information it
+// carries, such as marking events to be of a specific kind, or from a specific
+// package.
+type Tag struct {
+	name        string
+	description string
+}
+
+// NewTag creates a new [label.Key] for tagging labels.
+func NewTag(name, description string) *Tag {
+	return &Tag{name: name, description: description}
+}
+
+func (k *Tag) Name() string        { return k.name }
+func (k *Tag) Description() string { return k.description }
+
+func (k *Tag) Append(buf []byte, l label.Label) []byte { return buf }
+
+// New creates a new Label with this key.
+func (k *Tag) New() label.Label { return label.OfValue(k, nil) }
+
+// Int is a [label.Key] for signed integers.
+type Int struct {
+	name        string
+	description string
+}
+
+// NewInt returns a new [label.Key] for int64 values.
+func NewInt(name, description string) *Int {
+	return &Int{name: name, description: description}
+}
+
+func (k *Int) Name() string        { return k.name }
+func (k *Int) Description() string { return k.description }
+
+func (k *Int) Append(buf []byte, l label.Label) []byte {
+	return strconv.AppendInt(buf, k.From(l), 10)
+}
+
+// Of creates a new Label with this key and the supplied value.
+func (k *Int) Of(v int) label.Label { return k.Of64(int64(v)) }
+
+// Of64 creates a new Label with this key and the supplied value.
+func (k *Int) Of64(v int64) label.Label { return label.Of64(k, uint64(v)) }
+
+// Get returns the label for the key of a label.Map.
+func (k *Int) Get(lm label.Map) int64 {
+	if t := lm.Find(k); t.Valid() {
+		return k.From(t)
+	}
+	return 0
+}
+
+// From returns the value of a Label.
+func (k *Int) From(t label.Label) int64 { return int64(t.Unpack64()) }
+
+// Uint is a [label.Key] for unsigned integers.
+type Uint struct {
+	name        string
+	description string
+}
+
+// NewUint creates a new [label.Key] for unsigned values.
+func NewUint(name, description string) *Uint {
+	return &Uint{name: name, description: description}
+}
+
+func (k *Uint) Name() string        { return k.name }
+func (k *Uint) Description() string { return k.description }
+
+func (k *Uint) Append(buf []byte, l label.Label) []byte {
+	return strconv.AppendUint(buf, k.From(l), 10)
+}
+
+// Of creates a new Label with this key and the supplied value.
+func (k *Uint) Of(v uint64) label.Label { return label.Of64(k, v) }
+
+// Get returns the label for the key of a label.Map.
+func (k *Uint) Get(lm label.Map) uint64 {
+	if t := lm.Find(k); t.Valid() {
+		return k.From(t)
+	}
+	return 0
+}
+
+// From returns the value of a Label.
+func (k *Uint) From(t label.Label) uint64 { return t.Unpack64() }
+
+// Float is a label.Key for floating-point values.
+type Float struct {
+	name        string
+	description string
+}
+
+// NewFloat creates a new [label.Key] for floating-point values.
+func NewFloat(name, description string) *Float {
+	return &Float{name: name, description: description}
+}
+
+func (k *Float) Name() string        { return k.name }
+func (k *Float) Description() string { return k.description }
+
+func (k *Float) Append(buf []byte, l label.Label) []byte {
+	return strconv.AppendFloat(buf, k.From(l), 'E', -1, 64)
+}
+
+// Of creates a new Label with this key and the supplied value.
+func (k *Float) Of(v float64) label.Label {
+	return label.Of64(k, math.Float64bits(v))
+}
+
+// Get returns the label for the key of a label.Map.
+func (k *Float) Get(lm label.Map) float64 {
+	if t := lm.Find(k); t.Valid() {
+		return k.From(t)
+	}
+	return 0
+}
+
+// From returns the value of a Label.
+func (k *Float) From(t label.Label) float64 {
+	return math.Float64frombits(t.Unpack64())
+}
+
+// String represents a key
+type String struct {
+	name        string
+	description string
+}
+
+// NewString creates a new Key for int64 values.
+func NewString(name, description string) *String {
+	return &String{name: name, description: description}
+}
+
+func (k *String) Name() string        { return k.name }
+func (k *String) Description() string { return k.description }
+
+func (k *String) Append(buf []byte, l label.Label) []byte {
+	return strconv.AppendQuote(buf, k.From(l))
+}
+
+// Of creates a new Label with this key and the supplied value.
+func (k *String) Of(v string) label.Label { return label.OfString(k, v) }
+
+// Get returns the label for the key of a label.Map.
+func (k *String) Get(lm label.Map) string {
+	if t := lm.Find(k); t.Valid() {
+		return k.From(t)
+	}
+	return ""
+}
+
+// From returns the value of a Label.
+func (k *String) From(t label.Label) string { return t.UnpackString() }
+
+// Error represents a key
+type Error struct {
+	name        string
+	description string
+}
+
+// NewError returns a new [label.Key] for error values.
+func NewError(name, description string) *Error {
+	return &Error{name: name, description: description}
+}
+
+func (k *Error) Name() string        { return k.name }
+func (k *Error) Description() string { return k.description }
+
+func (k *Error) Append(buf []byte, l label.Label) []byte {
+	return append(buf, k.From(l).Error()...)
+}
+
+// Of returns a new Label with this key and the supplied value.
+func (k *Error) Of(v error) label.Label { return label.OfValue(k, v) }
+
+// Get returns the label for the key of a label.Map.
+func (k *Error) Get(lm label.Map) error {
+	if t := lm.Find(k); t.Valid() {
+		return k.From(t)
+	}
+	return nil
+}
+
+// From returns the value of a Label.
+func (k *Error) From(t label.Label) error {
+	err, _ := t.UnpackValue().(error)
+	return err
+}

Server/vendor/golang.org/x/tools/internal/event/keys/standard.go

@@ -0,0 +1,22 @@
+// Copyright 2020 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package keys
+
+var (
+	// Msg is a key used to add message strings to label lists.
+	Msg = NewString("message", "a readable message")
+	// Label is a key used to indicate an event adds labels to the context.
+	Label = NewTag("label", "a label context marker")
+	// Start is used for things like traces that have a name.
+	Start = NewString("start", "span start")
+	// Metric is a key used to indicate an event records metrics.
+	End = NewTag("end", "a span end marker")
+	// Metric is a key used to indicate an event records metrics.
+	Detach = NewTag("detach", "a span detach marker")
+	// Err is a key used to add error values to label lists.
+	Err = NewError("error", "an error that occurred")
+	// Metric is a key used to indicate an event records metrics.
+	Metric = NewTag("metric", "a metric event marker")
+)

Server/vendor/golang.org/x/tools/internal/event/keys/util.go

@@ -0,0 +1,21 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package keys
+
+import (
+	"sort"
+	"strings"
+)
+
+// Join returns a canonical join of the keys in S:
+// a sorted comma-separated string list.
+func Join[S ~[]T, T ~string](s S) string {
+	strs := make([]string, 0, len(s))
+	for _, v := range s {
+		strs = append(strs, string(v))
+	}
+	sort.Strings(strs)
+	return strings.Join(strs, ",")
+}

Server/vendor/golang.org/x/tools/internal/event/label/label.go

@@ -0,0 +1,203 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package label
+
+import (
+	"fmt"
+	"io"
+	"slices"
+	"unsafe"
+)
+
+// Key is used as the identity of a Label.
+// Keys are intended to be compared by pointer only, the name should be unique
+// for communicating with external systems, but it is not required or enforced.
+type Key interface {
+	// Name returns the key name.
+	Name() string
+	// Description returns a string that can be used to describe the value.
+	Description() string
+	// Append appends the formatted value of the label to the supplied buffer.
+	Append(buf []byte, l Label) []byte
+}
+
+// Label holds a key and value pair.
+// It is normally used when passing around lists of labels.
+type Label struct {
+	key     Key
+	packed  uint64
+	untyped any
+}
+
+// Map is the interface to a collection of Labels indexed by key.
+type Map interface {
+	// Find returns the label that matches the supplied key.
+	Find(key Key) Label
+}
+
+// List is the interface to something that provides an iterable
+// list of labels.
+// Iteration should start from 0 and continue until Valid returns false.
+type List interface {
+	// Valid returns true if the index is within range for the list.
+	// It does not imply the label at that index will itself be valid.
+	Valid(index int) bool
+	// Label returns the label at the given index.
+	Label(index int) Label
+}
+
+// list implements LabelList for a list of Labels.
+type list struct {
+	labels []Label
+}
+
+// filter wraps a LabelList filtering out specific labels.
+type filter struct {
+	keys       []Key
+	underlying List
+}
+
+// listMap implements LabelMap for a simple list of labels.
+type listMap struct {
+	labels []Label
+}
+
+// mapChain implements LabelMap for a list of underlying LabelMap.
+type mapChain struct {
+	maps []Map
+}
+
+// OfValue creates a new label from the key and value.
+// This method is for implementing new key types, label creation should
+// normally be done with the Of method of the key.
+func OfValue(k Key, value any) Label { return Label{key: k, untyped: value} }
+
+// UnpackValue assumes the label was built using LabelOfValue and returns the value
+// that was passed to that constructor.
+// This method is for implementing new key types, for type safety normal
+// access should be done with the From method of the key.
+func (t Label) UnpackValue() any { return t.untyped }
+
+// Of64 creates a new label from a key and a uint64. This is often
+// used for non uint64 values that can be packed into a uint64.
+// This method is for implementing new key types, label creation should
+// normally be done with the Of method of the key.
+func Of64(k Key, v uint64) Label { return Label{key: k, packed: v} }
+
+// Unpack64 assumes the label was built using LabelOf64 and returns the value that
+// was passed to that constructor.
+// This method is for implementing new key types, for type safety normal
+// access should be done with the From method of the key.
+func (t Label) Unpack64() uint64 { return t.packed }
+
+type stringptr unsafe.Pointer
+
+// OfString creates a new label from a key and a string.
+// This method is for implementing new key types, label creation should
+// normally be done with the Of method of the key.
+func OfString(k Key, v string) Label {
+	return Label{
+		key:     k,
+		packed:  uint64(len(v)),
+		untyped: stringptr(unsafe.StringData(v)),
+	}
+}
+
+// UnpackString assumes the label was built using LabelOfString and returns the
+// value that was passed to that constructor.
+// This method is for implementing new key types, for type safety normal
+// access should be done with the From method of the key.
+func (t Label) UnpackString() string {
+	return unsafe.String((*byte)(t.untyped.(stringptr)), int(t.packed))
+}
+
+// Valid returns true if the Label is a valid one (it has a key).
+func (t Label) Valid() bool { return t.key != nil }
+
+// Key returns the key of this Label.
+func (t Label) Key() Key { return t.key }
+
+// Format is used for debug printing of labels.
+func (t Label) Format(f fmt.State, r rune) {
+	if !t.Valid() {
+		io.WriteString(f, `nil`)
+		return
+	}
+	io.WriteString(f, t.Key().Name())
+	io.WriteString(f, "=")
+	f.Write(t.Key().Append(nil, t)) // ignore error
+}
+
+func (l *list) Valid(index int) bool {
+	return index >= 0 && index < len(l.labels)
+}
+
+func (l *list) Label(index int) Label {
+	return l.labels[index]
+}
+
+func (f *filter) Valid(index int) bool {
+	return f.underlying.Valid(index)
+}
+
+func (f *filter) Label(index int) Label {
+	l := f.underlying.Label(index)
+	if slices.Contains(f.keys, l.Key()) {
+		return Label{}
+	}
+	return l
+}
+
+func (lm listMap) Find(key Key) Label {
+	for _, l := range lm.labels {
+		if l.Key() == key {
+			return l
+		}
+	}
+	return Label{}
+}
+
+func (c mapChain) Find(key Key) Label {
+	for _, src := range c.maps {
+		l := src.Find(key)
+		if l.Valid() {
+			return l
+		}
+	}
+	return Label{}
+}
+
+var emptyList = &list{}
+
+func NewList(labels ...Label) List {
+	if len(labels) == 0 {
+		return emptyList
+	}
+	return &list{labels: labels}
+}
+
+func Filter(l List, keys ...Key) List {
+	if len(keys) == 0 {
+		return l
+	}
+	return &filter{keys: keys, underlying: l}
+}
+
+func NewMap(labels ...Label) Map {
+	return listMap{labels: labels}
+}
+
+func MergeMaps(srcs ...Map) Map {
+	var nonNil []Map
+	for _, src := range srcs {
+		if src != nil {
+			nonNil = append(nonNil, src)
+		}
+	}
+	if len(nonNil) == 1 {
+		return nonNil[0]
+	}
+	return mapChain{maps: nonNil}
+}