formatter.go

package gerrors

import (
	"fmt"
	"regexp"
	"text/template"
)

const (
	defaultTemplate = "error: {{.Identifier}}({{.ErrorCode}}) - {{.Message}}"

	// missingValueReplacement is the value that will be used to replace
	// invalid provided values for labels if replacing these missing values
	// are allowed.
	missingValueReplacement = "no-value"

	// keyMaxLength is the upper limit for the length of label key.
	// This is to prevent the key from being too long and to follow
	// errordetails protocol buffer message standard.
	keyMaxLength = 64
)

var (
	// DefaultFormatter holds a ready to use formatter with the default options.
	// DefaultFormatter uses the default template with no pre-defined labels and
	// no logger. It replaces invalid values with the missingValueReplacement.
	// DefaultFormatter uses defaultCoreCallback function for translating error
	// codes to human and machine readable strings and information.
	DefaultFormatter = NewFormatter()

	// keyRE is the regular expression to enforce label keys to have
	// alphanumerical characters, dashes and underscores.
	// This is to follow errordetails protocol buffer message standard.
	keyRE = regexp.MustCompile(`[^a-zA-Z0-9-_]`)
)

// Formatter is the main component of this package which provide
// handlers to create new errors. Formatter controls how every error
// will be parsed and formatted.
// Errors generated by a single formatter, will have a certain set of
// similar behaviors. These behaviors can be customized while creating
// a new formatter.
type Formatter struct {
	logger                  logger
	labels                  map[string]string
	template                *template.Template
	allowMissingValue       bool
	missingValueReplacement string
	coreDataLookup          Lookuper
}

// FormatterOption is the approach for customizing the formatter.
// Every option used during creation of a new formatter is of this type.
// Most of the functions starting with "With" are helpers to customize the formatter.
type FormatterOption func(*Formatter)

// NewFormatter creates a new formatter with the default options.
// Check [DefaultFormatter] for more information on the default options.
// It accepts a variadic number of FormatterOptions for customizing the returned
// formatter. Check helper functions that returns [FormatterOption] for more information.
func NewFormatter(opts ...FormatterOption) *Formatter {
	tpl, err := template.New("gerror").Parse(defaultTemplate)
	if err != nil {
		panic(err)
	}

	defaultLookuper := NewMapper(Unknown, GetDefaultMapping())

	f := &Formatter{
		labels:                  make(map[string]string),
		template:                tpl,
		allowMissingValue:       true,
		missingValueReplacement: missingValueReplacement,
		coreDataLookup:          defaultLookuper,
		logger:                  nil,
	}

	for _, opt := range opts {
		opt(f)
	}

	return f
}

// WithTemplate customizes formatter defaultTemplate.
// This template should follow text/template syntax. Function panics if template is invalid.
// Supported variables are:
//
//   - {{.Identifier}}: the identifier of the error. (e.g. unavailable, internal, ...)
//
//   - {{.ErrorCode}}: core error code. (e.g. 1, 2, ...)
//
//   - {{.GrpcErrorCode}}: grpc error code. (e.g. 2, 5, ...)
//
//   - {{.Message}}: the message of the provided error or default message of the error code.
//
//   - {{.DefaultMessage}}: the default message of the error code.
//
//   - {{.Labels}}: formatter's label plus error-specific labels. Treat it as a map.
//
//     f := NewFormatter(WithTemplate("error: {{.Identifier}}(code {{.ErrorCode}}) - {{.Message}}"))
func WithTemplate(templateString string) FormatterOption {
	tpl, err := template.New("gerror").Parse(templateString)
	if err != nil {
		panic(err)
	}

	return func(f *Formatter) {
		f.template = tpl
	}
}

// WithLogger attach a logger to the formatter.
// provided logger should at least implement the [logger] interface.
// If the provide logger implements other type of loggers as well
// (e.g [infoLogger], [traceLogger], ...), we can control how the created error
// should be logged by the formatter.
// If formatter is not configured with a logger or if the logger does not
// implement the provided logger, formatter simply ignore logging the error.
func WithLogger(logger logger) FormatterOption {
	return func(f *Formatter) {
		f.logger = logger
	}
}

// WithLookuper customizes the default mapper that translates [Code] to [CoreError].
// Using this formatter option, it is possible to completely revamp all the Code
// constants from acceptable error code and define a new set of error codes and
// a new mapper that can translate these new error codes to more details.
func WithLookuper(l Lookuper) FormatterOption {
	return func(f *Formatter) {
		f.coreDataLookup = l
	}
}

// WithMissingValueReplacement allows the formatter to accepts missing values
// when labels are being added to the formatter. In case a value is missing,
// or is invalid, formatter will replace it with this replacement string.
// Replacing missing values is allowed by default.
func WithMissingValueReplacement(replacement string) FormatterOption {
	return func(f *Formatter) {
		f.allowMissingValue = true
		f.missingValueReplacement = replacement
	}
}

// WithDisabledMissingValueReplacement allows user to disallow replacing missing values.
// In this case, a label with missing or invalid value will be ignored and not added to
// the error.
func WithDisabledMissingValueReplacement() FormatterOption {
	return func(f *Formatter) {
		f.allowMissingValue = false
	}
}

// WithLabels add a set of default labels to the formatter.
// All these labels will be included in every error generated by the formatter.
// It can be used to group errors together in a function scope or a call scope.
func WithLabels(keyValues ...any) FormatterOption {
	return func(f *Formatter) {
		for i := 0; i < len(keyValues); i += 2 {
			key, val, ok := f.getStringifiedKeyValue(keyValues, i)
			if !ok {
				continue
			}

			f.labels[key] = val
		}
	}
}

// Clone returns a copy of the formatter. Any change to this copy is safe since
// it would not change the original formatter.
// The global formatter can be cloned whenever you enter a new scope to be customized
// for that scope only.
func (f *Formatter) Clone() *Formatter {
	newF := Formatter{
		logger:                  f.logger,
		labels:                  make(map[string]string),
		template:                f.template,
		allowMissingValue:       f.allowMissingValue,
		missingValueReplacement: f.missingValueReplacement,
		coreDataLookup:          f.coreDataLookup,
	}

	for k, v := range f.labels {
		newF.labels[k] = v
	}

	return &newF
}

// AddLabels adds a set of labels to the formatter.
// keyValues should be pairs of data, where the first element is a key and must be a
// string and follows [maxKeyLength] and [keyRE].
// The second element is the value and will be converted to string. If value is missing
// [missingValueReplacement] and [allowMissingValue] are used to decide how to handle it.
// If the key has invalid characters or is too long, it will be modified to a valid key.
func (f *Formatter) AddLabels(keyValues ...any) *Formatter {
	for i := 0; i < len(keyValues); i += 2 {
		key, val, ok := f.getStringifiedKeyValue(keyValues, i)
		if !ok {
			continue
		}

		f.labels[key] = val
	}

	return f
}

// MissingValueReplacement returns whether replacing missing values is allowed or not.
// And if it is allowed, what will be replaced for missing values.
func (f *Formatter) MissingValueReplacement() (string, bool) {
	return f.missingValueReplacement, f.allowMissingValue
}

// LabelsSlice return formatter's default labels as a slice.
// Even indexed elements are keys and odd indexed elements are values
// sequentially attached to the slice.
// To have a map of labels, use LabelsMap.
func (f *Formatter) LabelsSlice() []string {
	labels := make([]string, len(f.labels)*2)
	index := 0

	for k, v := range f.labels {
		labels[index], labels[index+1] = k, v
		index += 2
	}

	return labels
}

// LabelsMap returns formatter's default labels as a map.
// To have a slice of labels, use LabelsSlice.
func (f *Formatter) LabelsMap() map[string]string {
	return f.labels
}

func (f *Formatter) getStringifiedKeyValue(keyValues []any, keyIndex int) (string, string, bool) {
	key, ok := keyValues[keyIndex].(string)
	if !ok {
		return "", "", false
	}

	// Ensure that key follows the standard format
	// @see https://pkg.go.dev/google.golang.org/genproto/googleapis/rpc/errdetails#ErrorInfo
	key = keyRE.ReplaceAllString(key, "-")

	if len(key) > keyMaxLength {
		key = key[:keyMaxLength-1]
	}

	value := f.missingValueReplacement
	if keyIndex+1 < len(keyValues) {
		value = fmt.Sprintf("%v", keyValues[keyIndex+1])
	} else if !f.allowMissingValue {
		return "", "", false
	}

	return key, value, true
}