condition

README

condition

Contains interfaces and methods for evaluating data for success or failure criteria. Conditions are a combination of operators (e.g., AND, OR) and inspectors (e.g. string equals "foo", regular expression matches "^foo") that can be used by applications that need to verify data before applying other processing functions. Each inspector defines its own data processing patterns, but there are a set of common patterns shared among most inspector:

• evaluating JSON values
• evaluating bytes

The package can be used like this:

package main

import (
	"fmt"

	"github.com/brexhq/substation/condition"
)

func main() {
	inspector := condition.Strings{
		Key:        "hello",
		Expression: "world",
		Function:   "equals",
	}

	data := []byte(`{"hello":"world"}`)
	ok, err := inspector.Inspect(data)
	if err != nil {
		panic(err)
	}

	if ok {
		fmt.Println("data passed inspection")
	} else {
		fmt.Println("data failed inspection")
	}
}

Information for each operator and inspector is available in the GoDoc.

Documentation

Index

• Constants
• type AND
  • func (o AND) Operate(data []byte) (bool, error)
• type Content
  • func (c Content) Inspect(data []byte) (output bool, err error)
• type Default
  • func (o Default) Operate(data []byte) (bool, error)
• type IP
  • func (c IP) Inspect(data []byte) (output bool, err error)
• type Inspector
  • func InspectorFactory(cfg config.Config) (Inspector, error)
  • func MakeInspectors(cfg []config.Config) ([]Inspector, error)
• type JSONSchema
  • func (c JSONSchema) Inspect(data []byte) (output bool, err error)
• type JSONValid
  • func (c JSONValid) Inspect(data []byte) (output bool, err error)
• type NAND
  • func (o NAND) Operate(data []byte) (bool, error)
• type NOR
  • func (o NOR) Operate(data []byte) (bool, error)
• type OR
  • func (o OR) Operate(data []byte) (bool, error)
• type Operator
  • func OperatorFactory(cfg OperatorConfig) (Operator, error)
• type OperatorConfig
• type RegExp
  • func (c RegExp) Inspect(data []byte) (output bool, err error)
• type Strings
  • func (c Strings) Inspect(data []byte) (output bool, err error)

Constants

const IPInvalidType = errors.Error("IPInvalidType")

IPInvalidType is returned when the IP inspector is configured with an invalid type.

const InspectorInvalidFactoryConfig = errors.Error("InspectorInvalidFactoryConfig")

InspectorInvalidFactoryConfig is returned when an unsupported Inspector is referenced in InspectorFactory.

const OperatorInvalidFactoryConfig = errors.Error("OperatorInvalidFactoryConfig")

OperatorInvalidFactoryConfig is returned when an unsupported Operator is referenced in OperatorFactory.

const OperatorMissingInspectors = errors.Error("OperatorMissingInspectors")

OperatorMissingInspectors is returned when an Operator that requres Inspectors is created with no inspectors.

const StringsInvalidFunction = errors.Error("StringsInvalidFunction")

StringsInvalidFunction is returned when the Strings inspector is configured with an invalid function.

Types

type AND

type AND struct {
	Inspectors []Inspector
}

AND implements the Operator interface and applies the boolean AND logic to configured inspectors.

func (AND) Operate

func (o AND) Operate(data []byte) (bool, error)

Operate returns true if all Inspectors return true, otherwise it returns false.

type Content

type Content struct {
	Type   string `json:"type"`
	Negate bool   `json:"negate"`
}

Content evaluates bytes by their content type. This inspector uses the standard library's net/http package to identify the content type of data (more information is available here: https://pkg.go.dev/net/http#DetectContentType). When used in Substation pipelines, it is most effective when using processors that change the format of data (e.g., process/gzip). The inspector supports MIME types that follow this specification: https://mimesniff.spec.whatwg.org/.

The inspector has these settings:

Type:
	the MIME type used during inspection
Negate (optional):
	if set to true, then the inspection is negated (i.e., true becomes false, false becomes true)
	defaults to false

The inspector supports these patterns:

data:
	[31, 139, 8, 0, 0, 0, 0, 0, 0, 255, 74, 203, 207, 7, 4, 0, 0, 255, 255, 33, 101, 115, 140, 3, 0, 0, 0] == application/x-gzip

The inspector uses this Jsonnet configuration:

{
	type: 'content',
	// returns true if the bytes have a valid Gzip header
	settings: {
		type: 'application/x-gzip',
		negate: false,
	},
}

func (Content) Inspect

func (c Content) Inspect(data []byte) (output bool, err error)

Inspect evaluates data with the Content inspector.

type Default

type Default struct{}

Default implements the Operator interface.

func (Default) Operate

func (o Default) Operate(data []byte) (bool, error)

Operate always returns true. This is the default operator returned by OperatorFactory.

type IP

type IP struct {
	Key    string `json:"key"`
	Type   string `json:"type"`
	Negate bool   `json:"negate"`
}

IP evaluates IP addresses by their type and usage. This inspector uses the standard library's net package to identify the type and usage of the address (more information is available here: https://pkg.go.dev/net#IP).

The inspector has these settings:

Key (optional):
	the JSON key-value to retrieve for inspection
Type:
	the IP address type used during inspection
	must be one of:
		loopback: valid loopback address
		multicast: valid multicast address
		multicast_link_local: valid link local multicast address
		private: valid private address
		unicast_global: valid global unicast address
		unicast_link_local: valid link local unicast address
		unspecified: valid "unspecified" address (e.g., 0.0.0.0, ::)
Negate (optional):
	if set to true, then the inspection is negated (i.e., true becomes false, false becomes true)
	defaults to false

The inspector supports these patterns:

json:
	{"ip_address":"10.0.0.1"} == private
data:
	10.0.0.1 == private

The inspector uses this Jsonnet configuration:

{
	type: 'ip',
	settings: {
		key: 'ip_address',
		type: 'private',
	},
}

func (IP) Inspect

func (c IP) Inspect(data []byte) (output bool, err error)

Inspect evaluates data with the IP inspector.

type Inspector

type Inspector interface {
	Inspect([]byte) (bool, error)
}

Inspector is the interface shared by all inspector methods.

func InspectorFactory

func InspectorFactory(cfg config.Config) (Inspector, error)

InspectorFactory loads Inspectors from an InspectorConfig. This function is the preferred way to create Inspectors.

func MakeInspectors

func MakeInspectors(cfg []config.Config) ([]Inspector, error)

MakeInspectors is a convenience function for creating several Inspectors.

type JSONSchema

type JSONSchema struct {
	Schema []struct {
		Key  string `json:"key"`
		Type string `json:"type"`
	} `json:"schema"`
	Negate bool `json:"negate"`
}

JSONSchema evaluates JSON objects against a schema.

The inspector has these settings:

Schema.Key:
	the JSON key-value to retrieve for inspection
Schema.Type:
	the value type used during inspection of the Schema.Key
	must be one of:
		string
		number (float, int)
		boolean (true, false)
		json
Negate (optional):
	if set to true, then the inspection is negated (i.e., true becomes false, false becomes true)
	defaults to false

The inspector supports these patterns:

json:
	{"foo":"foo","bar":123} == string,number

The inspector uses this Jsonnet configuration:

{
	type: 'json_schema',
	settings: {
		schema: [
			{
				key: "foo",
				type: "string",
			},
			{
				key: "bar",
				type: "number",
			}
		],
	},
}

func (JSONSchema) Inspect

func (c JSONSchema) Inspect(data []byte) (output bool, err error)

Inspect evaluates data with the JSONSchema inspector.

type JSONValid

type JSONValid struct {
	Negate bool `json:"negate"`
}

JSONValid evaluates JSON objects for validity.

The inspector has these settings:

Negate (optional):
	if set to true, then the inspection is negated (i.e., true becomes false, false becomes true)
	defaults to false

The inspector supports these patterns:

json:
	{"foo":"foo","bar":123} == valid
	foo == invalid

The inspector uses this Jsonnet configuration:

{
	type: 'json_valid',
}

func (JSONValid) Inspect

func (c JSONValid) Inspect(data []byte) (output bool, err error)

Inspect evaluates data with the JSONValid inspector.

type NAND

type NAND struct {
	Inspectors []Inspector
}

NAND implements the Operator interface and applies the boolean NAND logic to configured inspectors.

func (NAND) Operate

func (o NAND) Operate(data []byte) (bool, error)

Operate returns true if all Inspectors return false, otherwise it returns true.

type NOR

type NOR struct {
	Inspectors []Inspector
}

NOR implements the Operator interface and applies the boolean NOR logic to configured inspectors.

func (NOR) Operate

func (o NOR) Operate(data []byte) (bool, error)

Operate returns true if any Inspectors return false, otherwise it returns true.

type OR

type OR struct {
	Inspectors []Inspector
}

OR implements the Operator interface and applies the boolean OR logic to configured inspectors.

func (OR) Operate

func (o OR) Operate(data []byte) (bool, error)

Operate returns true if any Inspectors return true, otherwise it returns false.

type Operator

type Operator interface {
	Operate([]byte) (bool, error)
}

Operator is the interface shared by all operator methods. Most operators contain a list of Inspectors that the operand applies to.

func OperatorFactory

func OperatorFactory(cfg OperatorConfig) (Operator, error)

OperatorFactory loads Operators from an OperatorConfig. This function is the preferred way to create Operators.

type OperatorConfig

type OperatorConfig struct {
	Operator   string
	Inspectors []config.Config
}

OperatorConfig contains an array of Inspector configurations that are used to evaluate data.

type RegExp

type RegExp struct {
	Key        string `json:"key"`
	Expression string `json:"expression"`
	Negate     bool   `json:"negate"`
}

RegExp evaluates data using a regular expression. This inspector uses a regexp cache provided by internal/regexp.

The inspector has these settings:

Key (optional):
	the JSON key-value to retrieve for inspection
Expression:
	the regular expression to use during inspection
Negate (optional):
	if set to true, then the inspection is negated (i.e., true becomes false, false becomes true)
	defaults to false

The inspector supports these patterns:

json:
	{"foo":"bar"} == ^bar
data:
	bar == ^bar

The inspector uses this Jsonnet configuration:

{
	type: 'regexp',
	settings: {
		key: 'foo',
		expression: '^bar',
	},
}

func (RegExp) Inspect

func (c RegExp) Inspect(data []byte) (output bool, err error)

Inspect evaluates data with the RegExp inspector.

type Strings

type Strings struct {
	Key        string `json:"key"`
	Expression string `json:"expression"`
	Function   string `json:"function"`
	Negate     bool   `json:"negate"`
}

Strings evaluates data using string functions. This inspector uses the standard library's strings package.

The inspector has these settings:

Key (optional):
	the JSON key-value to retrieve for inspection
Expression:
	the substring expression to use during inspection
Function:
	the string evaluation function to use during inspection
	must be one of:
		equals
		contains
		endswith
		startswith
Negate (optional):
	if set to true, then the inspection is negated (i.e., true becomes false, false becomes true)
	defaults to false

The inspector supports these patterns:

json:
	{"foo":"bar"} == bar
data:
	bar == bar

The inspector uses this Jsonnet configuration:

{
	type: 'strings',
	settings: {
		key: 'foo',
		expression: 'bar',
		function: 'endswith',
	},
}

func (Strings) Inspect

func (c Strings) Inspect(data []byte) (output bool, err error)

Inspect evaluates data with the Strings inspector.