policy

package
v0.1.0-rc.3 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 2 Imported by: 1

Documentation

Overview

Package policy decides how a type that cannot carry stash tags is encrypted, from what its schema says about each field.

Tags are the way to declare a type that you write. A policy is for a type that a schema generates, such as a protobuf message whose field options hold the field's data categories. A Source gives the facts about each field; a rule has a Matcher and a Decision; the first rule that matches a field decides it. stashgen.Generate runs the rules and writes the same generated file that it writes from tags. Only the generate program runs a policy.

Every field of the message needs a decision. A field that no rule decides stops the generator with the field's name and its annotations. A policy has an Otherwise rule only when its author writes one.

Index

Constants

This section is empty.

Variables

View Source
var (
	Equality = IndexSpec{Name: "equality"}
	Ore      = IndexSpec{Name: "ore"}
	Ope      = IndexSpec{Name: "ope"}
)

The indexes that take no options.

Functions

This section is empty.

Types

type Annotation

type Annotation struct {
	Key    string
	Values []string
}

Annotation is one annotation on a field: a key and its values. For a protobuf field option the key is the option's full name.

type Context

type Context string

Context is the context of every field of a message, as the `context=` tag gives it for a struct.

type Decision

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

Decision is what a rule decides for a field: one of the tag verbs, or a refusal. A decision spells itself in the tag grammar, so the generator reads a policy's decision through the same parser as a tag.

func Encrypt

func Encrypt() Decision

Encrypt seals the field with no index.

func EncryptIndex

func EncryptIndex(indexes ...IndexSpec) Decision

EncryptIndex seals the field and derives each index beside it.

func EncryptInto

func EncryptInto(eqlType string) Decision

EncryptInto seals the field into one EQL value of this type.

func Fail

func Fail(reason string) Decision

Fail refuses the field: the generator stops with the reason.

func Index

func Index(indexes ...IndexSpec) Decision

Index derives the indexes alone, with no ciphertext.

func Omit

func Omit() Decision

Omit leaves the field out.

func Passthrough

func Passthrough() Decision

Passthrough stores the field as it is.

type Fact

type Fact struct {
	// Message is the full name of the message, for errors.
	Message string
	// Name is the field's name in the schema, such as the proto field name.
	// It is the column name unless a rule gives another with [Name].
	Name string
	// GoName is the field of the Go struct the schema generated.
	GoName string
	// Kind is the field's kind in the schema's own words, such as "string" or
	// "int64". Rules may match on it.
	Kind string
	// Annotations are what the schema says about the field, such as its
	// data categories.
	Annotations []Annotation
}

Fact is what a source knows about one field: its name, its Go name, its kind and its annotations. A policy reads facts and never learns where they came from.

func (Fact) String

func (f Fact) String() string

String spells the field and its annotations, for the error that names a field no rule decides.

func (Fact) Values

func (f Fact) Values(key string) []string

Values returns every value under key, in order.

type IndexName

type IndexName string

IndexName is one of the tag words for an index: equality, match, ore, ope or json.

type IndexOption

type IndexOption struct {
	Key   string
	Value string
}

IndexOption is one option of an index, as the tag writes it in parentheses.

type IndexSpec

type IndexSpec struct {
	Name    IndexName
	Options []IndexOption
}

IndexSpec is one index with its options, as a rule names it: the engine's own word for the data form of an index.

func JSON

func JSON(options ...IndexOption) IndexSpec

JSON is the json index, with its options.

func Match

func Match(options ...IndexOption) IndexSpec

Match is the match index, with its options.

func (IndexSpec) String

func (i IndexSpec) String() string

String spells the index as a tag does: match or match(k=3).

type Key

type Key string

Key is an annotation key, such as the full name of a protobuf field option.

func (Key) Is

func (k Key) Is(value string) Matcher

Is matches a field with a value under key equal to value.

func (Key) Under

func (k Key) Under(prefix string) Matcher

Under matches a field with a value under key that is prefix, or starts with prefix and a dot: Key("c").Under("user") matches "user" and "user.contact.email", and not "username".

type Matcher

type Matcher interface {
	Match(Fact) bool
}

Matcher selects the fields a rule applies to.

func Field

func Field(name string) Matcher

Field matches the field with this schema name.

type MatcherFunc

type MatcherFunc func(Fact) bool

MatcherFunc is a Matcher made from a function.

func (MatcherFunc) Match

func (m MatcherFunc) Match(f Fact) bool

Match calls the function.

type Message

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

Message is one message with its context and its rules, as ForMessage builds it and stashgen.Generate reads it.

func ForMessage

func ForMessage(message any, context Context, rules Rule) Message

ForMessage binds a message to its context and the rules that decide its fields. The message is a value of the generated Go type, such as &pb.Individual{}; the source reads its schema and the generator its type.

func (Message) Context

func (m Message) Context() string

Context returns the message's context.

func (Message) Decide

func (m Message) Decide(f Fact) (Outcome, bool)

Decide runs the rules on one field.

func (Message) Message

func (m Message) Message() any

Message returns the message value given to ForMessage.

type Option

type Option func(*Outcome)

Option modifies a rule's outcome.

func Identity

func Identity(identity string) Option

Identity keeps the field's context when its column gets a new name.

func Name

func Name(column string) Option

Name sets the field's column name.

type Outcome

type Outcome struct {
	Decision Decision
	// Name is the column name, or "" for the field's schema name.
	Name string
	// Identity is the field's part of its context, or "" for the column
	// name. A field whose column is renamed keeps its identity, so data
	// written before the change still decrypts.
	Identity string
}

Outcome is a decision applied to one field: the decision, and the name and identity a rule's options set.

func (Outcome) Reason

func (o Outcome) Reason() string

Reason is the reason of a Fail decision, or "".

func (Outcome) Tag

func (o Outcome) Tag(name string) (tag string, ok bool)

Tag spells the outcome for a field in the tag grammar: what the field's stash tag would say. ok is false for a refusal, which Outcome.Reason explains, and for the zero Outcome.

type Rule

type Rule interface {
	Decide(Fact) (Outcome, bool)
}

Rule decides a field, or reports that it does not match.

func Otherwise

func Otherwise(d Decision, options ...Option) Rule

Otherwise decides every field that no earlier rule matched.

func When

func When(m Matcher, d Decision, options ...Option) Rule

When is a rule: the fields the matcher selects get the decision.

type Rules

type Rules []Rule

Rules are rules tried in order; the first that matches decides.

func FirstOf

func FirstOf(rules ...Rule) Rules

FirstOf returns the rules, tried in order.

func (Rules) Decide

func (r Rules) Decide(f Fact) (Outcome, bool)

Decide tries each rule in order.

func (Rules) OrElse

func (r Rules) OrElse(other Rule) Rules

OrElse returns the rules, then other for the fields they do not match.

type Source

type Source interface {
	// Facts returns one fact for each field of the message, in declared
	// order. The message is the value given to [ForMessage].
	Facts(message any) ([]Fact, error)
}

Source gives the facts about each field of a message.

type SourceFunc

type SourceFunc func(message any) ([]Fact, error)

SourceFunc is a Source made from a function.

func (SourceFunc) Facts

func (s SourceFunc) Facts(message any) ([]Fact, error)

Facts calls the function.

Directories

Path Synopsis
Package protosource reads the facts about a protobuf message's fields: each field's name, its Go name, its kind, and its options as annotations.
Package protosource reads the facts about a protobuf message's fields: each field's name, its Go name, its kind, and its options as annotations.
internal/testpb
Package testpb is protoc-gen-go output for the protosource tests: the two messages of docs/plans/2026-10-04-plan-builder/proto, where classification.data_categories is a repeated string field option.
Package testpb is protoc-gen-go output for the protosource tests: the two messages of docs/plans/2026-10-04-plan-builder/proto, where classification.data_categories is a repeated string field option.

Jump to

Keyboard shortcuts

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