policy

Documentation

Index

• type Decision
• type Document
  • func LoadJSONDocument(path string) (Document, error)
  • func ParseJSONDocument(r io.Reader) (Document, error)
• type Effect
  • func (e Effect) IsValid() bool
• type Engine
  • func CompileDocument(doc Document, opts ...EngineOption) (*Engine, error)
  • func CompilePolicies(policies []Policy, opts ...EngineOption) (*Engine, error)
  • func (e *Engine) Evaluate(_ context.Context, input any) Decision
• type EngineOption
  • func WithDefaultEffect(effect Effect) EngineOption
  • func WithExprOptions(opts ...expr.Option) EngineOption
  • func WithSchemaDefinition(schema any) EngineOption
• type Policy
• type Rule

Types

type Decision

type Decision struct {
	Effect       Effect `json:"effect"`
	Policy       string `json:"policy,omitempty"`
	Rule         string `json:"rule,omitempty"`
	Message      string `json:"message,omitempty"`
	Matched      bool   `json:"matched"`
	Evaluated    int    `json:"evaluated_rules"`
	Error        error  `json:"error"`
	ErrorMessage string `json:"error_message,omitempty"`
}

Decision captures the result of evaluating a policy set.

type Document

type Document struct {
	Version       string   `json:"version,omitempty" yaml:"version,omitempty"`
	DefaultEffect *Effect  `json:"default_effect,omitempty" yaml:"default_effect,omitempty"`
	Policies      []Policy `json:"policies" yaml:"policies"`
}

Document describes a collection of policies that can be serialized as JSON or YAML.

func LoadJSONDocument

func LoadJSONDocument(path string) (Document, error)

LoadJSONDocument reads a JSON document from disk.

func ParseJSONDocument

func ParseJSONDocument(r io.Reader) (Document, error)

ParseJSONDocument decodes a policy document from JSON.

type Effect

type Effect string

Effect represents the outcome of a rule evaluation.

const (
	// EffectAllow grants the action.
	EffectAllow Effect = "ALLOW"
	// EffectDeny blocks the action.
	EffectDeny Effect = "DENY"
)

func (Effect) IsValid

func (e Effect) IsValid() bool

IsValid returns true when the effect is one of the supported values.

type Engine

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

Engine evaluates compiled policies against an input context.

func CompileDocument

func CompileDocument(doc Document, opts ...EngineOption) (*Engine, error)

CompileDocument converts a policy document into an executable engine.

func CompilePolicies

func CompilePolicies(policies []Policy, opts ...EngineOption) (*Engine, error)

CompilePolicies is a convenience helper when you already materialised policies.

func (*Engine) Evaluate

func (e *Engine) Evaluate(_ context.Context, input any) Decision

Evaluate runs all compiled policies against the provided context value. The final decision honours DENY over ALLOW, with a configurable default fallback.

type EngineOption

type EngineOption func(*engineConfig)

EngineOption configures compilation behaviour.

func WithDefaultEffect

func WithDefaultEffect(effect Effect) EngineOption

WithDefaultEffect defines the fallback effect used when no rule matches.

func WithExprOptions

func WithExprOptions(opts ...expr.Option) EngineOption

WithExprOptions passes expr compilation options for every rule.

func WithSchemaDefinition

func WithSchemaDefinition(schema any) EngineOption

WithSchemaDefinition defines the expected data structure for type validation at compile time. Pass an empty struct to define which fields exist and their types. Unknown fields or type mismatches will be caught during policy compilation. Example: policy.WithSchemaDefinition(TransactionContext{})

type Policy

type Policy struct {
	Name          string   `json:"name" yaml:"name"`
	Description   string   `json:"description,omitempty" yaml:"description,omitempty"`
	DefaultEffect *Effect  `json:"default_effect,omitempty" yaml:"default_effect,omitempty"`
	Rules         []Rule   `json:"rules" yaml:"rules"`
	Tags          []string `json:"tags,omitempty" yaml:"tags,omitempty"`
}

Policy groups a list of rules under a logical name.

type Rule

type Rule struct {
	ID          string            `json:"id,omitempty" yaml:"id,omitempty"`
	Description string            `json:"description,omitempty" yaml:"description,omitempty"`
	Effect      Effect            `json:"effect" yaml:"effect"`
	Condition   string            `json:"condition" yaml:"condition"`
	Metadata    map[string]string `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

Rule contains a single expression condition paired with an outcome.