fields.go

package skbtrace

import (
	"fmt"
	"regexp"
	"strings"
)

const (
	// Either an object name starting with dollar sign (i.e. $)
	// or a global variable/field alias (latter might have dashes)
	reFieldObjGroup    = "([$]\\w+|[0-9a-z_\\-|]+)"
	reFieldFieldGroups = "(?:->)?([0-9a-z_\\->.|]+)?"
)

var reField = regexp.MustCompile("^" + reFieldObjGroup + reFieldFieldGroups + "$")

func newFieldRefErrorf(
	obj, fieldName string, err error,
	fmtstr string, args ...interface{},
) *errorImpl {
	fieldIdent := string(ExprField(obj, fieldName))
	return newErrorf(ErrLevelField, fieldIdent, err, fmtstr, args...)
}

const (
	// Use converters when dumping value or as a key in printed map,
	// default if no mask is specified
	ConverterDump uint = 1 << iota

	// Use converters when generating key in non-printable map
	ConverterHiddenKey

	// Use converter in filters. Not recommended, instead filter
	// preprocessor should process user-supplied constant
	ConverterFilter

	// Use Converter as argument to argument to aggregation function
	// For now it uses same converter as prettifier to apply ntohs
	// conversion (it is absurd to require aggregation on really
	// pretty fields like IP address)
	ConverterAggregateArg = ConverterDump
)

// FieldConverter is a prototype of Field.Converter field
type FieldConverter func(obj, field string) ([]Statement, Expression)

// FieldPreprocessor is a prototype of Field.Preprocessor field
type FieldPreprocessor func(op, value string) (string, error)

// Field describes a single position in a printf-statement generated by FieldGroup and
// used as a handler for structure field name (structure itself is stored in FieldGroup),
// help (description of field), formatting specifier and text which precedes value and
// optional converter function which may produce extra statements and expression for field
// value.
type Field struct {
	// Name of struct field defined in header file
	Name string

	// Alias for using single-string shortcut without verbose object->field form
	// i.e. 'src' is '$iph->saddr'
	Alias string

	// If specified allows to specify an alias accessible from multiple paths
	// Whichever is more favorable wins
	WeakAlias bool

	// Format key which precedes value when printing. If omitted, Name is used
	FmtKey string

	// Format specifier for BPFTrace printf()
	FmtSpec string

	// Converter function which is used to retrieve field value (which returned as expression)
	// using statements from object obj and its field named field
	Converter FieldConverter

	// ConverterMask overrides contexts in which converter will be used
	ConverterMask uint

	// Preprocessor function is used to convert human-readable value used in filter
	// to machine value
	Preprocessor FieldPreprocessor

	// FilterOperator processes op specified in filter into an expression by filter
	FilterOperator func(expr Expression, op, value string) (Expression, error)

	// SanityFilter produces a template of filter which should be checked
	// when getting the object to avoid printing junk data
	SanityFilter *Filter

	// Help for fields helper subcommand
	Help string
}

// FieldGroup produces a single printf statement (and some converter statements from
// the fields) for a single object. If object is omitted, then fields are interpreted as
// global variables.
// NOTE: bpftrace has limitation of 7 format specs per statement, hence splitting
// fields into rows. Also, it is a bit prettier on my vertical display.
type FieldGroup struct {
	// Name of the row (might be non-unique, in this case multiple rows will be dumped)
	Row string

	// Object variable name to be dumped. Might be empty for objectless fields
	// taken from probe args or global variables, otherwise must refer to a valid
	// object registered by AddObjects
	Object string

	// List of fields in this group
	Fields []*Field

	// Name of the row for base group (used only for help)
	BaseFieldGroup string

	// Prefix for field aliases: if non empty, field copies will get different
	// aliases prefixed with this string and a dash. Useful for multiple instances
	// of header, or in/out interface logic
	FieldAliasPrefix string
}

type fieldAliasRef struct {
	fg         *FieldGroup
	field      *Field
	weakGroups []*FieldGroup
}

func (fref *fieldAliasRef) Ref() *fieldAliasRef {
	return fref
}

func (fref *fieldAliasRef) Level() ErrorLevel {
	return ErrLevelField
}

func (fref *fieldAliasRef) Resolve(fg *FieldGroup) {
	fref.fg = fg

	// When resolving field aliases, field found originally may have different preprocessors,
	// so retry searching.
	fref.field = fg.findFieldByAlias(fref.field.Alias)
	if fref.field == nil {
		panic("cannot find field while re-resolving fref alias")
	}
}

// Wraps base field group into prefix. Useful for inner headers
func (fg FieldGroup) Wrap(obj, prefix string) FieldGroup {
	fg.Object = obj
	fg.BaseFieldGroup = fg.Row
	fg.FieldAliasPrefix = prefix
	fg.Row = fmt.Sprintf("%s-%s", prefix, fg.Row)
	return fg
}

// Find a field from the pair of strings. Token can be one of
// - field alias
// - global variable name or probe context name
// - object name, in this case fieldName is expected to be non-empty
func (b *Builder) findField(token, fieldName string) *fieldAliasRef {
	if fieldName == "" {
		// First try to interpret this as alias, but fallback to objectless fields
		// if not successful
		fref := b.fieldAliasMap[token]
		if fref != nil {
			return fref
		}
	}

	objFields := b.fieldObjectMap[token]
	if len(objFields) == 0 {
		// Try to interpret obj/fieldName as objectless global variable, such as comm
		// This is useful when parsing filters, but might be of use in other contexts
		// NOTE: that will require caller to swap fields as well
		if fieldName == "" {
			token, fieldName = fieldName, token
			objFields = b.fieldObjectMap[token]
		}

		if len(objFields) == 0 {
			return nil
		}
	}

	for _, fref := range objFields {
		if fref.field.Name == fieldName || fref.field.FmtKey == fieldName {
			return fref
		}
	}
	return nil
}

func (fg *FieldGroup) findFieldByAlias(aliasName string) *Field {
	for _, field := range fg.Fields {
		if field.Alias == aliasName {
			return field
		}
	}
	return nil
}

// generateFieldExpression generates statements which are required to convert value,
// expression which allows to access it which can be probe argument, global variable
// or an object's field or returns an error if expression cannot be produced.
// If field is being printed (in dump or aggregate) useConverters may be passed to
// apply human-readable converters
func (b *Builder) generateFieldExpression(
	fg *FieldGroup, field *Field, probe *Probe, convMask uint,
) ([]Statement, Expression, error) {
	if field.Converter != nil {
		fieldConvMask := field.ConverterMask
		if fieldConvMask == 0 {
			fieldConvMask = ConverterDump
		}
		if convMask&fieldConvMask != 0 {
			convStmts, expr := field.Converter(fg.Object, field.Name)
			return convStmts, expr, nil
		}
	}

	if fg.Object == "" {
		if varExpr, ok := b.globalVars[field.Name]; ok {
			return nil, varExpr, nil
		}

		if arg, ok := probe.Args[field.Name]; ok {
			return nil, Expr(arg), nil
		}

		return nil, "", newFieldRefErrorf(fg.Object, field.Name, nil,
			"cannot generate field expression for objectless field")
	}

	return nil, ExprField(fg.Object, field.Name), nil
}

// Generates printf() statements for the corresponding field group
// No context checking is performed here as it is expected that caller already
// performed necessary casts
func (b *Builder) generatePrintStatements(fg *FieldGroup, probe *Probe) ([]Statement, error) {
	var stmts []Statement
	var values []Expression
	var fmtSpecs []string

	for _, field := range fg.Fields {
		fieldStms, expr, err := b.generateFieldExpression(fg, field, probe, ConverterDump)
		if err != nil {
			return nil, err
		}

		stmts = append(stmts, fieldStms...)
		values = append(values, expr)

		fmtKey := field.FmtKey
		if len(fmtKey) == 0 {
			fmtKey = field.Name
		}
		fmtSpec := field.FmtSpec
		if len(fmtSpec) == 0 {
			fmtSpec = "%d"
		}
		fmtSpecs = append(fmtSpecs, fmt.Sprintf("%s %s", fmtKey, fmtSpec))
	}

	return append(stmts, Stmtf(`printf("%s: %s\n", %s)`,
		strings.ToUpper(fg.Row), strings.Join(fmtSpecs, " "), ExprJoin(values))), nil
}

// Parses key as supplied in CLI in obj->field notation to pair of token and
// fieldName which can be used for
func (b *Builder) parseKey(key string) (token string, fieldName string, err error) {
	groups := reField.FindStringSubmatch(key)
	if len(groups) < 2 || len(groups) > 3 {
		err = newCommonError(ErrLevelField, key, ErrMsgParseError)
		return
	}

	token = groups[1]
	if len(groups) == 3 {
		fieldName = groups[2]
	}
	return
}

// Resolves raw keys passed in command line into field references
func (b *Builder) prepareKeys(rawKeys []string) ([]*fieldAliasRef, error) {
	keys := make([]*fieldAliasRef, 0, len(rawKeys))
	for _, rawKey := range rawKeys {
		token, fieldName, err := b.parseKey(rawKey)
		if err != nil {
			return nil, err
		}

		key := b.findField(token, fieldName)
		if key == nil {
			return nil, newCommonError(ErrLevelField, rawKey, ErrMsgNotFound)
		}

		keys = append(keys, key)
	}
	return keys, nil
}

// Generates expressions and statements for keys used by associative arrays.
// If array is dumped to stdout, useConverters should be set to true to apply converters
func (b *Builder) generateKeyExpressions(
	keys []*fieldAliasRef, probe *Probe, convMask uint,
) (stmts []Statement, exprs []Expression, err error) {
	for _, fref := range keys {
		keyStmts, expr, err := b.generateFieldExpression(fref.fg, fref.field, probe, convMask)
		if err != nil {
			return nil, nil, err
		}
		stmts = append(stmts, keyStmts...)
		exprs = append(exprs, expr)
	}
	return
}

// Builds a block (or finds it) having all key variables available
func (b *Builder) getBlockWithKeys(
	block *Block, keys []*fieldAliasRef, convMask uint,
) (*Block, []Expression, error) {
	if len(keys) == 0 {
		return block, nil, nil
	}

	for _, key := range keys {
		keyBlock, err := b.getBlockWithObject(block, key.fg.Object)
		if err != nil {
			return nil, nil, err
		}
		block = keyBlock
	}

	stmts, exprs, err := b.generateKeyExpressions(keys, block.probe, convMask)
	if err != nil {
		return nil, nil, err
	}

	block.Add(stmts...)
	return block, exprs, nil
}

func (b *Builder) getFieldWeakRefs(frefs []*fieldAliasRef) []weakAliasRef {
	weakRefs := make([]weakAliasRef, 0)
	for _, fref := range frefs {
		if fref.weakGroups != nil {
			weakRefs = append(weakRefs, fref)
		}
	}
	return weakRefs
}