package constraint¶
Package constraint lets a Go library type declare cross-field constraints on its inputs in a type-safe, string-free way. A type lists them from a Constraints method, referring to its own fields directly:
func (v CertInput) Constraints() []constraint.Constraint {
return []constraint.Constraint{
constraint.ExactlyOneOf(v.SelfSigned, v.AcmArn, v.PemBundle),
constraint.When(constraint.Equals(v.Tier, "prod")).
Require(constraint.Present(v.ValidityDays)).
Message("production certs need an explicit validity"),
}
}
Because the fields are real struct fields, the Go compiler checks that they exist and a rename updates them, so there are no stale field-name strings. unobin reads these declarations from source at compile time (goschema) and resolves each field reference to its kebab input name, merging them with any constraints written in UB. The methods are not evaluated at runtime, so a returned value carries the rule's kind and message but not its field names, which the compiler supplies from source. The declarative vocabulary matches the one a UB constraints block uses.
Types¶
type Clause¶
Clause is a predicate whose condition has been stated with When; call Require on it to give the requirement that must hold when the condition does.
func When¶
When begins a conditional predicate. Pair it with Require.
func (Clause) Require¶
Require completes a When predicate: when the When condition holds, every require condition must hold too.
type Condition¶
Condition is a boolean over a type's inputs, used to build predicates. Like Constraint it is opaque and read from source, not evaluated here.
func Above¶
Above holds when field is greater than value (literal or field). A null operand makes the condition pass.
func Absent¶
Absent holds when field is unset (null).
func All¶
All holds when every condition holds.
func Any¶
Any holds when at least one condition holds.
func AtLeast¶
AtLeast holds when field is greater than or equal to value, which may be a literal or another field. A null operand makes the condition pass.
func AtMost¶
AtMost holds when field is less than or equal to value (literal or field). A null operand makes the condition pass.
func Below¶
Below holds when field is less than value (literal or field). A null operand makes the condition pass.
func Equals¶
Equals holds when field equals value.
func IsFalse¶
IsFalse holds when the boolean field is false.
func IsTrue¶
IsTrue holds when the boolean field is true.
func MaxItems¶
MaxItems holds when field has at most n elements. A null field passes, since presence is Present's job.
func MinItems¶
MinItems holds when field has at least n elements. A null field passes, since presence is Present's job.
func Not¶
Not holds when the condition does not hold.
func NotEmpty¶
NotEmpty holds when field is set and has at least one element, so an explicitly empty list fails it. Strings and maps count the same way.
func NotEquals¶
NotEquals holds when field does not equal value.
func OneOf¶
OneOf holds when field's value is one of the given values.
func Present¶
Present holds when field is set (not null).
type Constraint¶
Constraint is one declared rule, built by one of the constructors below. It is opaque: an author builds it and returns it; unobin reads the rule from source rather than from this value.
func AtLeastOneOf¶
AtLeastOneOf requires that at least one of the fields is set.
func AtMostOneOf¶
AtMostOneOf requires that no more than one of the fields is set.
func ExactlyOneOf¶
ExactlyOneOf requires that exactly one of the fields is set.
func ForEach¶
ForEach applies per-element rules to a list field, mirroring the @for-each a UB constraint uses. The body receives one element and returns the constraints that must hold for every element of the list; a field reference inside the body names the element's field, and a reference to the receiver names a top-level field as usual. A null or empty list checks nothing.
As with every constructor in this package, ForEach is read from source and never called: the body declares rules and must be a single return of a constraint list.
constraint.ForEach(v.Replicas, func(r Replica) []constraint.Constraint {
return []constraint.Constraint{
constraint.ExactlyOneOf(r.Inline, r.FromFile),
constraint.RequiredWith(r.TLS, v.CACert),
}
})
func ForbiddenWith¶
ForbiddenWith requires that when field is set, no forbids field is set.
func Must¶
Must is an unconditional predicate: every condition must hold.
func RequiredTogether¶
RequiredTogether requires that the fields are all set or all unset.
func RequiredWith¶
RequiredWith requires that when field is set, every requires field is set.
func (Constraint) Message¶
Message attaches a custom failure message and returns the updated rule, for chaining after a predicate: When(...).Require(...).Message("...").
type Kind¶
Kind classifies a constraint. The set kinds (everything but predicate) are about which fields are set; a predicate is a when/require condition.