value.go

package logging

import (
	"time"

	"go.uber.org/zap"
)

// Value is a key with a value to log. Keys are declared once as constants of a module and give the values
// with the Value method of the key: KeyUser.Value(42). Use WithValuesFrom to add values to a logger.
type Value struct {
	key   Key
	value any
}

// Value makes a Value having the key and the value. The value is not inspected until the record is written.
func (k Key) Value(value any) Value {
	return Value{key: k, value: value}
}

// Key returns the key of the value.
func (v Value) Key() Key {
	return v.key
}

// Any returns the value. It is "***" for values of a RedactedKey.
func (v Value) Any() any {
	return v.value
}

// LoggingValues implements LoggingValuer: a Value provides itself.
func (v Value) LoggingValues() []Value {
	return []Value{v}
}

// Values is a set of Value, f.e. static values of a module. It implements LoggingValuer.
type Values []Value

// LoggingValues implements LoggingValuer.
func (v Values) LoggingValues() []Value {
	return v
}

// LoggingValuer is implemented by types providing their values for logging, f.e. a request or an order:
//
//	func (o Order) LoggingValues() []logging.Value {
//		return []logging.Value{KeyOrderID.Value(o.ID), KeyAmount.Value(o.Sum)}
//	}
//
//	log = logging.WithValuesFrom(log, order)
//
// The method is called on every WithValuesFrom call, it should be cheap. A panic of the method is not recovered.
type LoggingValuer interface {
	LoggingValues() []Value
}

// TypedKey is a key accepting values of type T only. It is a string so keys can be constants:
//
//	const KeyUser logging.TypedKey[int] = "user"
//
//	KeyUser.Value(42) // KeyUser.Value("x") does not compile
type TypedKey[T any] string

// Value makes a Value having the key and the value.
func (k TypedKey[T]) Value(value T) Value {
	return Value{key: Key(k), value: value}
}

// Key returns the untyped key, f.e. for context extractors.
func (k TypedKey[T]) Key() Key {
	return Key(k)
}

// String returns the key name.
func (k TypedKey[T]) String() string {
	return string(k)
}

// Aliases of TypedKey for common types.
type (
	// StringKey accepts string values.
	StringKey = TypedKey[string]
	// IntKey accepts int values.
	IntKey = TypedKey[int]
	// Int64Key accepts int64 values.
	Int64Key = TypedKey[int64]
	// Float64Key accepts float64 values.
	Float64Key = TypedKey[float64]
	// BoolKey accepts bool values.
	BoolKey = TypedKey[bool]
	// DurationKey accepts time.Duration values.
	DurationKey = TypedKey[time.Duration]
	// TimeKey accepts time.Time values.
	TimeKey = TypedKey[time.Time]
	// ErrorKey accepts error values.
	ErrorKey = TypedKey[error]
)

// RedactedKey is a key whose value is always replaced with "***", whatever Config.Redact is.
// The given value is never kept, inspected or encoded. It is a string so keys can be constants:
//
//	const KeyPassword logging.RedactedKey[string] = "password"
//
// It has no Key and SetToCtx methods on purpose, so the secret does not go around the masking via context.
type RedactedKey[T any] string

// Value makes a Value having the key and the masked value. The argument is ignored, it only keeps the type check.
func (k RedactedKey[T]) Value(_ T) Value {
	return Value{key: Key(k), value: redactedValue}
}

// String returns the key name.
func (k RedactedKey[T]) String() string {
	return string(k)
}

// valuesLogger is implemented by loggers adding several values by one call.
type valuesLogger interface {
	withValues(values []Value) Logger
}

// WithValuesFrom returns a logger having values of all the sources added, in order of the sources and their values.
// A source is a Value, Values or any LoggingValuer. Nil sources and values without a key are skipped.
// Values with the same key are not merged. Returns the logger itself if there is nothing to add.
func WithValuesFrom(logger Logger, sources ...LoggingValuer) Logger {
	values := make([]Value, 0, len(sources))

	for _, source := range sources {
		switch typed := source.(type) {
		case nil:
		case Value:
			values = append(values, typed)
		default:
			values = append(values, source.LoggingValues()...)
		}
	}

	filtered := values[:0]

	for _, value := range values {
		if value.key != "" {
			filtered = append(filtered, value)
		}
	}

	if len(filtered) == 0 {
		return logger
	}

	if vl, ok := logger.(valuesLogger); ok {
		return vl.withValues(filtered)
	}

	for _, value := range filtered {
		logger = logger.WithKey(value.key.String(), value.value)
	}

	return logger
}

var (
	_ valuesLogger = (*zapLogger)(nil)
	_ valuesLogger = (*Default)(nil)
	_ valuesLogger = (*TestLogger)(nil)
)

// withValues adds all the values by one call, config Redact is applied.
func (logger *zapLogger) withValues(values []Value) Logger {
	fields := make([]zap.Field, len(values))
	for i, value := range values {
		fields[i] = logger.st.redact.field(value.key.String(), value.value)
	}

	return logger.with(fields...)
}

func (l *Default) withValues(values []Value) Logger {
	plain := l.get().plain
	if vl, ok := plain.(valuesLogger); ok {
		return vl.withValues(values)
	}

	for _, value := range values {
		plain = plain.WithKey(value.key.String(), value.value)
	}

	return plain
}

func (tl *TestLogger) withValues(values []Value) Logger {
	return tl.zl.withValues(values)
}