combine

package
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 6, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

Documentation

Overview

Package combine owns the Draft-09 AND/OR group structure shared by the Message-Instance h= (Section 9.3) and DKIM2-Signature s= (Section 10.9) tags: an ordered list of groups separated by "|", each an ordered list of sets separated by ",". A "," binds more tightly than "|".

Index

Constants

View Source
const (
	// AllSeparator joins the sets of one hash-all or sig-all group.
	AllSeparator byte = ','
	// AnySeparator joins the alternative hash-all or sig-all groups.
	AnySeparator byte = '|'
)
View Source
const MaxSets = 16

MaxSets is the hard bound of sets one layout can describe. It equals the hard max_hash_sets and max_signature_sets parser bounds, so a layout is a fixed-size value without heap state.

Variables

This section is empty.

Functions

func CountSets

func CountSets(value []byte) int

CountSets returns the number of sets Split would produce, so callers can enforce local resource bounds before parsing set contents.

Types

type Layout

type Layout struct {
	// contains filtered or unexported fields
}

Layout is the immutable group structure of one parsed or generated h= or s= value. Sets are numbered in field order; every group holds at least one set and groups are contiguous runs of that order.

func NewLayout

func NewLayout(sizes ...int) (Layout, bool)

NewLayout constructs a layout from ordered group sizes. It reports false when there is no group, a group is empty, or more than MaxSets sets are described, because Draft-09 grammar admits no empty group and the local bound admits no larger value.

func SingleGroup

func SingleGroup(count int) (Layout, bool)

SingleGroup returns the layout of one group holding count sets.

func Split

func Split(value []byte) ([][]byte, Layout, bool)

Split separates one unfolded h= or s= value into its raw set texts in field order and the group layout. The raw texts keep surrounding white space for the owning set parser. Split reports false when a group or set is empty, which covers leading, trailing, and doubled separators, or when the value holds more than MaxSets sets; callers enforce their own narrower bound with CountSets first.

func (Layout) Equal

func (l Layout) Equal(other Layout) bool

Equal reports whether two layouts describe the same group structure.

func (Layout) GroupOf

func (l Layout) GroupOf(index int) (int, bool)

GroupOf returns the zero-based group index of the set at index in field order, or false outside the layout.

func (Layout) GroupSizes

func (l Layout) GroupSizes() []int

GroupSizes returns the ordered group sizes.

func (Layout) Groups

func (l Layout) Groups() int

Groups returns the number of "|"-separated groups.

func (Layout) SeparatorBefore

func (l Layout) SeparatorBefore(index int) byte

SeparatorBefore returns the separator that precedes the set at index in field order: zero for the first set, AnySeparator at a group boundary, and AllSeparator inside a group. It returns zero for an index outside the layout.

func (Layout) Sets

func (l Layout) Sets() int

Sets returns the number of sets across all groups.

func (Layout) Valid

func (l Layout) Valid() bool

Valid reports whether the layout holds at least one non-empty group.

type Outcome

type Outcome struct {
	// contains filtered or unexported fields
}

Outcome is the overall result of one combination plus the decisive set: within the first group whose group result equals the overall result, the first set in field order whose intermediate equals that result. A set of a group with a different result never explains the outcome. Reporting uses the decisive set, so the public reason of a non-PASS outcome is deterministic.

func Hashes

func Hashes(layout Layout, intermediates []Result) Outcome

Hashes combines per-hash-set intermediates exactly as Draft-09 Section 14.7 steps 3 to 5 prescribe. A single hash-set yields its intermediate. Each hash-all group is PASS when every hash-set passes, else FAIL when any is FAIL, else PERMERROR; the hash-any result is PASS when any group passes, else FAIL when any group is FAIL, else PERMERROR. Hash intermediates are never TEMPERROR; one makes the outcome invalid.

func Signatures

func Signatures(layout Layout, intermediates []Result) Outcome

Signatures combines per-signature intermediates exactly as Draft-09 Section 14.6 steps 5 to 7 prescribe. Each sig-all group is PASS when every signature passes, else TEMPERROR when every non-PASS signature is TEMPERROR, else FAIL when any signature is FAIL, else PERMERROR. The sig-any result is PASS when any group passes, else TEMPERROR when any group is TEMPERROR, else FAIL when any group is FAIL, else PERMERROR.

func (Outcome) Decisive

func (o Outcome) Decisive() int

Decisive returns the field-order index of the decisive set: the first set carrying the overall result inside the first group whose result equals it.

func (Outcome) Pass

func (o Outcome) Pass() bool

Pass reports whether the outcome is a valid overall PASS.

func (Outcome) Result

func (o Outcome) Result() Result

Result returns the overall combination result.

func (Outcome) Valid

func (o Outcome) Valid() bool

Valid reports whether the outcome was computed from a coherent layout and intermediate list.

type Result

type Result uint8

Result is one Draft-09 intermediate or overall verification result of a signature or hash-set combination (Sections 14.6 and 14.7).

const (
	// ResultPass is a PASS intermediate or overall result.
	ResultPass Result = iota + 1
	// ResultFail is a FAIL intermediate or overall result.
	ResultFail
	// ResultTempError is a TEMPERROR intermediate or overall result. It
	// occurs only for signatures; hash combinations never yield it.
	ResultTempError
	// ResultPermError is a PERMERROR intermediate or overall result.
	ResultPermError
)

func (Result) Known

func (r Result) Known() bool

Known reports whether r is one of the four closed results.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL