feat(decl): add declarative test framework foundation

go.mod

@@ -17,7 +17,8 @@ require (
 	github.com/spf13/pflag v1.0.5
 	github.com/spf13/viper v1.19.0
 	github.com/stretchr/testify v1.9.0
-	golang.org/x/sys v0.25.0
+	golang.org/x/sys v0.26.0
+	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.31.1
 	k8s.io/cli-runtime v0.31.1
 	k8s.io/client-go v0.31.1
@@ -96,22 +97,21 @@ require (
 	github.com/xlab/treeprint v1.2.0 // indirect
 	go.starlark.net v0.0.0-20240725214946-42030a7cedce // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/crypto v0.27.0 // indirect
+	golang.org/x/crypto v0.28.0 // indirect
 	golang.org/x/exp v0.0.0-20240909161429-701f63a606c0 // indirect
-	golang.org/x/net v0.29.0 // indirect
+	golang.org/x/net v0.30.0 // indirect
 	golang.org/x/oauth2 v0.23.0 // indirect
 	golang.org/x/sync v0.8.0 // indirect
-	golang.org/x/term v0.24.0 // indirect
-	golang.org/x/text v0.18.0 // indirect
+	golang.org/x/term v0.25.0 // indirect
+	golang.org/x/text v0.19.0 // indirect
 	golang.org/x/time v0.6.0 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1 // indirect
-	google.golang.org/grpc v1.66.2 // indirect
-	google.golang.org/protobuf v1.34.2 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9 // indirect
+	google.golang.org/grpc v1.67.1 // indirect
+	google.golang.org/protobuf v1.35.1 // indirect
 	gopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 	k8s.io/api v0.31.1 // indirect
 	k8s.io/component-base v0.31.1 // indirect
 	k8s.io/klog/v2 v2.130.1 // indirect

go.sum

@@ -191,8 +191,8 @@ go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN8
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
-golang.org/x/crypto v0.27.0 h1:GXm2NjJrPaiv/h1tb2UH8QfgC/hOf/+z0p6PT8o1w7A=
-golang.org/x/crypto v0.27.0/go.mod h1:1Xngt8kV6Dvbssa53Ziq6Eqn0HqbZi5Z6R0ZpwQzt70=
+golang.org/x/crypto v0.28.0 h1:GBDwsMXVQi34v5CCYUm2jkJvu4cbtru2U4TN2PSyQnw=
+golang.org/x/crypto v0.28.0/go.mod h1:rmgy+3RHxRZMyY0jjAJShp2zgEdOqj2AO7U0pYmeQ7U=
 golang.org/x/exp v0.0.0-20240909161429-701f63a606c0 h1:e66Fs6Z+fZTbFBAxKfP3PALWBtpfqks2bwGcexMxgtk=
 golang.org/x/exp v0.0.0-20240909161429-701f63a606c0/go.mod h1:2TbTHSBQa924w8M6Xs1QcRcFwyucIwBGpK1p2f1YFFY=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
@@ -201,8 +201,8 @@ golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
-golang.org/x/net v0.29.0 h1:5ORfpBpCs4HzDYoodCDBbwHzdR5UrLBZ3sOnUJmFoHo=
-golang.org/x/net v0.29.0/go.mod h1:gLkgy8jTGERgjzMic6DS9+SP0ajcu6Xu3Orq/SpETg0=
+golang.org/x/net v0.30.0 h1:AcW1SDZMkb8IpzCdQUaIq2sP4sZ4zw+55h6ynffypl4=
+golang.org/x/net v0.30.0/go.mod h1:2wGyMJ5iFasEhkwi13ChkO/t1ECNC4X4eBKkVFyYFlU=
 golang.org/x/oauth2 v0.23.0 h1:PbgcYx2W7i4LvjJWEbf0ngHV6qJYr86PkAV3bXdLEbs=
 golang.org/x/oauth2 v0.23.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -215,14 +215,14 @@ golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.25.0 h1:r+8e+loiHxRqhXVl6ML1nO3l1+oFoWbnlu2Ehimmi34=
-golang.org/x/sys v0.25.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/term v0.24.0 h1:Mh5cbb+Zk2hqqXNO7S1iTjEphVL+jb8ZWaqh/g+JWkM=
-golang.org/x/term v0.24.0/go.mod h1:lOBK/LVxemqiMij05LGJ0tzNr8xlmwBRJ81PX6wVLH8=
+golang.org/x/sys v0.26.0 h1:KHjCJyddX0LoSTb3J+vWpupP9p0oznkqVk/IfjymZbo=
+golang.org/x/sys v0.26.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.25.0 h1:WtHI/ltw4NvSUig5KARz9h521QvRC8RmF/cuYqifU24=
+golang.org/x/term v0.25.0/go.mod h1:RPyXicDX+6vLxogjjRxjgD2TKtmAO6NZBsBRfrOLu7M=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
-golang.org/x/text v0.18.0 h1:XvMDiNzPAl0jr17s6W9lcaIhGUfUORdGCNsuLmPG224=
-golang.org/x/text v0.18.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
+golang.org/x/text v0.19.0 h1:kTxAhCbGbxhK0IwgSKiMO5awPoDQ0RpfiVYBfK860YM=
+golang.org/x/text v0.19.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=
 golang.org/x/time v0.6.0 h1:eTDhh4ZXt5Qf0augr54TN6suAUudPcawVZeIAPU7D4U=
 golang.org/x/time v0.6.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -235,12 +235,12 @@ golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8T
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1 h1:pPJltXNxVzT4pK9yD8vR9X75DaWYYmLGMsEvBfFQZzQ=
-google.golang.org/genproto/googleapis/rpc v0.0.0-20240903143218-8af14fe29dc1/go.mod h1:UqMtugtsSgubUsoxbuAoiCXvqvErP7Gf0so0mK9tHxU=
-google.golang.org/grpc v1.66.2 h1:3QdXkuq3Bkh7w+ywLdLvM56cmGvQHUMZpiCzt6Rqaoo=
-google.golang.org/grpc v1.66.2/go.mod h1:s3/l6xSSCURdVfAnL+TqCNMyTDAGN6+lZeVxnZR128Y=
-google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
-google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9 h1:QCqS/PdaHTSWGvupk2F/ehwHtGc0/GYkT+3GAcR1CCc=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9/go.mod h1:GX3210XPVPUjJbTUbvwI8f2IpZDMZuPJWDzDuebbviI=
+google.golang.org/grpc v1.67.1 h1:zWnc1Vrcno+lHZCOofnIMvycFcc0QRGIzm9dhnDX68E=
+google.golang.org/grpc v1.67.1/go.mod h1:1gLDyUQU7CTLJI90u3nXZ9ekeghjeM7pTDZlqFNg2AA=
+google.golang.org/protobuf v1.35.1 h1:m3LfL6/Ca+fqnjnlqQXNpFPABW1UD7mjh8KO2mKFytA=
+google.golang.org/protobuf v1.35.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

pkg/test/field/doc.go

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2024 The Falco Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package field defines a generic way to reference and assign values to any test field by leveraging reflection and
+// struct field tagging. Struct field tagging is used to check for semantic assignability. A source field is assignable
+// to a destination field if the following two condition applies:
+// - source field go type is assignable and/or convertible to destination field go type
+// - source field is semantically assignable to destination field
+// "Semantically assignable" means that both fields have the same `field_type`. A `field_type` must be assigned to a
+// field via struct field tagging.
+package field

pkg/test/field/field.go

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2024 The Falco Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package field
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+// Retriever allows to retrieve information regarding fields.
+type Retriever interface {
+	// Field returns information related to the field with the provided name.
+	Field(name string) (*Field, error)
+}
+
+// Field contains information regarding a field, such as its value and its field type.
+type Field struct {
+	// Path represents the unique location of a field in the parent container. A Path is composed of one or multiple
+	// dot-separated field path segments. This addressing mechanism allows to organize fields in a hierarchical way.
+	Path string
+	// Value contains the value associated to the field. It can be settable or not, depending on how it is created.
+	Value reflect.Value
+	// Type is mainly used to check if a source Field Value can be semantically assigned to a destination Field Value.
+	// Semantic assignability means that both fields have the same Type. A Type must be assigned to a Field via
+	// `field_type` struct field tag (e.g.: `field_type:"<field_type>"`).
+	Type Type
+}
+
+// Type represents the type of field.
+type Type string
+
+const (
+	// TypeUndefined specifies an undefined field type. This is a special value indicating the absence of a Type for a
+	// Field. The value of a Field marked as undefined cannot be assigned nor set to any other Field value.
+	TypeUndefined Type = "undefined"
+	// TypeFD specifies that the field contains a file descriptor.
+	TypeFD Type = "fd"
+	// TypeBuffer specifies that the field contains a buffer.
+	TypeBuffer Type = "buffer"
+	// TypeBufferLen specifies that the field contains a buffer length.
+	TypeBufferLen Type = "buffer_len"
+	// TypeFilePath specifies that the field contains a file path.
+	TypeFilePath Type = "file_path"
+	// TypeOpenFlags specifies that the field contains the open system call flags.
+	TypeOpenFlags Type = "open_flags"
+	// TypeOpenMode specifies that the field contains the open system call modes.
+	TypeOpenMode Type = "open_mode"
+	// TypeOpenHow specifies that the field contains the openat2 system call open_how parameter.
+	TypeOpenHow Type = "open_how"
+	// TypeLinkAtFlags specifies that the field contains the linkat system call flags.
+	TypeLinkAtFlags Type = "linkat_flags"
+	// TypeModuleParams specifies that the field contains the init_module system call params.
+	TypeModuleParams Type = "module_params"
+	// TypeFinitModuleFlags specifies that the field contains the finit_module system call flags.
+	TypeFinitModuleFlags Type = "finit_module_flags"
+	// TypeDup3Flags specifies that the field contains the dup3 system call flags.
+	TypeDup3Flags Type = "dup3_flags"
+	// TypeSocketAddress specifies that the field contains a sockaddr.
+	TypeSocketAddress Type = "socket_address"
+	// TypeSocketDomain specifies that the field contains the socket system call domain.
+	TypeSocketDomain Type = "socket_domain"
+	// TypeSocketType specifies that the field contains the socket system call type.
+	TypeSocketType Type = "socket_type"
+	// TypeSocketProtocol specifies that the field contains the socket system call protocol.
+	TypeSocketProtocol Type = "socket_protocol"
+	// TypeSendFlags specifies that the field contains the sendto system call flags.
+	TypeSendFlags Type = "send_flags"
+)
+
+const (
+	// fieldPathSegmentsSeparator is the token used to separate one segment from another in a multi-segment field path.
+	fieldPathSegmentsSeparator = "."
+)
+
+// Paths returns the field paths of the fields contained in the provided fieldContainer. fieldContainer's Kind must be
+// Struct; otherwise, the function will panic. A field path is generated for each field that is neither a struct nor a
+// pointer to a struct. For each field whose type has the struct kind, the function recursively invokes itself to
+// provide field paths for each of its eligible subfields. Each field that is a struct pointer is dereferenced and then
+// treated as a field whose type has the struct kind.
+func Paths(fieldContainer reflect.Type) map[string]struct{} {
+	fieldContainerNumFields := fieldContainer.NumField()
+	// Guess we are generating a number of path equal to the number of container fields.
+	fieldPaths := make(map[string]struct{}, fieldContainerNumFields)
+	for i := 0; i < fieldContainerNumFields; i++ {
+		field := fieldContainer.Field(i)
+		fieldTy := field.Type
+		fieldPath := Path(field.Name)
+		switch fieldTy.Kind() {
+		case reflect.Ptr:
+			// Dereference the pointer and give up if it does not point to a struct.
+			fieldTy = fieldTy.Elem()
+			if fieldTy.Kind() != reflect.Struct {
+				continue
+			}
+		case reflect.Struct:
+		default:
+			// Field is neither a struct nor a pointer to a struct: add to the field paths set and go to the next field.
+			fieldPaths[fieldPath] = struct{}{}
+			continue
+		}
+		// At this point we know that the field type has the struct kind, so we can recursively call ourselves and
+		// collect all subfields paths.
+		subFieldPaths := Paths(fieldTy)
+		// Generate the complete field path by prefixing, to each subfield, the current field path.
+		for subFieldPath := range subFieldPaths {
+			fieldPaths[fieldPath+fieldPathSegmentsSeparator+subFieldPath] = struct{}{}
+		}
+	}
+	return fieldPaths
+}
+
+// Path converts the provided string to the corresponding field path representation.
+func Path(s string) string {
+	return strings.ToLower(s)
+}
+
+// splitFieldPath splits the provided field path into multiple segments.
+func splitFieldPath(fieldPath string) []string {
+	return strings.Split(fieldPath, fieldPathSegmentsSeparator)
+}
+
+// ByName returns information for the field identified by name. The field is searched in the provided fieldContainers,
+// and the first match is returned.
+func ByName(name string, fieldContainers ...reflect.Value) (*Field, error) {
+	fieldPath := Path(name)
+	fieldPathSegments := splitFieldPath(fieldPath)
+
+	for _, fieldContainer := range fieldContainers {
+		if field := byName(fieldContainer, fieldPath, fieldPathSegments); field != nil {
+			return field, nil
+		}
+	}
+	return nil, fmt.Errorf("unknown field %q", name)
+}
+
+// byName returns the fieldContainer's field identified by the provided fieldPathSegments. If a field is not found, it
+// returns nil.
+func byName(fieldContainer reflect.Value, fieldPath string, fieldPathSegments []string) *Field {
+	for _, fieldPathSegment := range fieldPathSegments[:len(fieldPathSegments)-1] {
+		field, ok := fieldContainer.Type().FieldByNameFunc(func(name string) bool {
+			return Path(name) == fieldPathSegment
+		})
+		if !ok {
+			return nil
+		}
+		fieldContainer = fieldContainer.FieldByIndex(field.Index)
+	}
+
+	lastFieldPathSegment := fieldPathSegments[len(fieldPathSegments)-1]
+	field, ok := fieldContainer.Type().FieldByNameFunc(func(name string) bool {
+		return Path(name) == lastFieldPathSegment
+	})
+	if !ok {
+		return nil
+	}
+
+	return &Field{
+		Path:  fieldPath,
+		Value: fieldContainer.FieldByIndex(field.Index),
+		Type:  fieldType(&field),
+	}
+}
+
+// fieldType returns the type of the provided struct field.
+func fieldType(field *reflect.StructField) Type {
+	tagValue, ok := field.Tag.Lookup("field_type")
+	if !ok || tagValue == "" {
+		return TypeUndefined
+	}
+	return Type(tagValue)
+}
+
+// Set sets the Value of the current field to the Value of the provided source field. If the source Value is neither
+// assignable nor convertible to the destination Value, or it is not semantically assignable to it, Set returns an
+// error.
+func (f *Field) Set(srcField *Field) error {
+	dstFieldType := f.Type
+	dstFieldValue := f.Value
+
+	srcFieldType := srcField.Type
+	srcFieldValue := srcField.Value
+
+	if dstFieldType == TypeUndefined {
+		return fmt.Errorf("field type is undefined for destination field")
+	}
+
+	if srcFieldType == TypeUndefined {
+		return fmt.Errorf("field type is undefined for source field")
+	}
+
+	// Test raw type assignability or convertibility.
+	isAssignable := srcFieldValue.Type().AssignableTo(dstFieldValue.Type())
+	isConvertible := srcFieldValue.CanConvert(dstFieldValue.Type())
+	if !isAssignable && !isConvertible {
+		return fmt.Errorf("%T is neither assignable nor convertible to %T", srcFieldValue.Interface(),
+			dstFieldValue.Interface())
+	}
+
+	// Test semantic type assignability
+	if dstFieldType != srcFieldType {
+		return fmt.Errorf("%q is not semantically assignable to %q", srcFieldType, dstFieldType)
+	}
+
+	if isAssignable {
+		dstFieldValue.Set(srcFieldValue)
+		return nil
+	}
+
+	// Not assignable but convertible
+	dstFieldValue.Set(srcFieldValue.Convert(dstFieldValue.Type()))
+	return nil
+}

pkg/test/loader/doc.go

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2024 The Falco Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package loader defines a Loader, able to unmarshall a YAML document into a Configuration.
+package loader