Foundational Concepts
Pattern Matching
In general, Seedwing treats a policy as a pattern-matching exercise. The requester presents structured data representing what they know to the policy engine for a decision. The engine attempts to match the provided data with a pattern that describes what shape, format or other qualities that the data should exhibit in order to be considered "in compliance".
Policies, Patterns, Functions and Expressions
The core constructs of policies authored in Dogma are:
-
Patterns
-
Functions
-
Expressions
Policies
A "policy" is simply an application of a pattern towards a decision that results in a relatively boolean outcome. Within Dogma, there is no actual concrete "policy" construct.
Policies are used in a variety of ways. Simple schema-validation is a policy that defines what a compliant well-formed document should look like. Gate-checks in the course of a software pipeline represent another policy that defines what is acceptable to progress beyond a particular point of the pipeline.
Patterns
The base construct within Dogma is the pattern.
In general, a pattern describes, in varying degrees of detail, the range of acceptable inputs.
Any input that does not match the pattern is considered to not comply with the pattern.
Patterns are defined in terms of values, functions, and expressions.
A primordial pattern in Dogma defines the structure or content of valid input values.
Similar to many programming languages, general primordial patterns are defined, including:
-
strings
-
integers
-
decimals
-
booleans
-
octets
Additionally, a policy author can define new structured patterns that are object- or list-shaped, where each component is recursively defined to be of a pattern type.
When an input value is presented to a pattern, the pattern acts not unlike a function, accepting the value, and either passing it back as the output upon match, or passing along nothing if it fails to match.
Functions
A function can also be considered a kind of pattern if you squint hard enough from far enough away, since they are also presented with an input value and pass along an output value if successful. The primary difference is that functions are written in Rust, not Dogma, and they may pass along completely different values as output.
For instance, a function base64 accepts a string input, and if that input can be successfully decoded as a base64 input, the output value is the decoded value.
Expressions
Expression constructs in Dogma may actually appear in two different contexts.
Pattern Expressions
Pattern expressions are when two or more patterns are combined using algebraic and or or operators (&& and ||).
In the case of &&, the entire expression is only satisfied if all component terms are satisfied.
For ||, the entire expression is satisified if any component term is satisfied.
Short-circuiting applies to ||, as a success is a success.
Short-circuiting does not apply to &&, so that all viable failures can be detected early, instead of piece-meal.