rules

Documentation

Overview

Package rules defines an expression-based authorization model. It compiles human-readable rule definitions into executable programs and evaluates them against an evaluation environment in the request context.

Index

• type Compiler
  • func NewCompiler() *Compiler
  • func (c *Compiler) Compile(rules []config.Rule) ([]rule, error)
• type Engine
  • func NewEngine(rules []config.Rule) (Engine, error)
• type EngineFunc
  • func (f EngineFunc) Eval(env Environment) (Result, error)
• type Environment
  • func NewEnvironment(tok jwt.Token, req *http.Request) Environment
  • func (e Environment) Claim(name string) any
• type Result

Types

type Compiler

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

Compiler compiles declarative rule definitions into executable programs. It enforces result types for each expression (bool for when, string for user, and slice for roles) at compile time.

func NewCompiler

func NewCompiler() *Compiler

NewCompiler builds a compiler that type-checks expressions against the Environment and enables bytecode optimizations.

func (*Compiler) Compile

func (c *Compiler) Compile(rules []config.Rule) ([]rule, error)

Compile compiles a slice of declarative rules into executable Rules. Rules are compiled in order and returned in the same order.

type Engine

type Engine interface {
	// Eval scans rules in order and returns the first allow decision alongside
	// the user and role(s) to forward to CouchDB. If a deny rule matches, access
	// is denied immediately. If no rule matches, access is denied by default.
	//
	// On denial (explicit or implicit), a zero-value Result and nil error are
	// returned so the caller can decide how to respond upstream.
	Eval(env Environment) (Result, error)
}

Engine evaluates a list of authorization rules in order.

func NewEngine

func NewEngine(rules []config.Rule) (Engine, error)

NewEngine compiles the provided declarative rules and returns an Engine. The given slice must not be empty.

type EngineFunc

type EngineFunc func(env Environment) (Result, error)

EngineFunc is an adapter to allow the use of ordinary functions as Engines.

func (EngineFunc) Eval

func (f EngineFunc) Eval(env Environment) (Result, error)

Eval implements the Engine interface.

type Environment

type Environment struct {

	// Method is the HTTP method of the request.
	Method string
	// Path is the request path (including the leading slash).
	Path string
	// DB is the name of the target CouchDB database.
	DB string
	// contains filtered or unexported fields
}

Environment provides the input context for rule evaluation. It carries request metadata (method, path, database) and the parsed token.

func NewEnvironment

func NewEnvironment(tok jwt.Token, req *http.Request) Environment

NewEnvironment populates an Environment from a token and request. It extracts the HTTP method, raw path, and derives the database name.

func (Environment) Claim

func (e Environment) Claim(name string) any

Claim returns the value of a JWT claim by name. It returns nil when the claim is not set or cannot be decoded.

type Result

type Result struct {
	// Pass indicates whether access is granted.
	Pass bool
	// User is the CouchDB user name to authenticate as when Pass is true.
	User string
	// Roles is a comma-separated list of CouchDB roles when Pass is true.
	Roles string
}

Result captures the outcome of evaluating rules for a request.