Documentation
¶
Overview ¶
Package rules checks and compiles a collection's rules (the `rules:` section of its collection.yaml): expr-lang expressions deciding, per operation, whether a caller may act on a whole document. Read rules also become backend-neutral storage filters. It knows nothing about HTTP or MongoDB.
Index ¶
Constants ¶
This section is empty.
Variables ¶
Ops lists the operations in a fixed order.
Functions ¶
This section is empty.
Types ¶
type Op ¶
type Op string
Op is an operation a rule can allow.
const ( Read Op = "read" Create Op = "create" Update Op = "update" Delete Op = "delete" // Restore and Purge are the operations of a collection that soft-deletes // (collection.yaml): restore decides who may read the deleted documents // and bring them back, purge who may remove them for good. Neither is // covered by `write`: they are denied unless declared. Restore Op = "restore" Purge Op = "purge" // Invoke is a function's invoke rule (function.yaml): it decides who // may call the function and sees only `user`. Invoke Op = "invoke" // Config is the read rule of a path of the realm's app configuration // (app-config/rules.yaml): it sees `user` and `now`, with no document. Config Op = "config" )
type Rule ¶
type Rule struct {
Op Op
Key string // the rules key it came from: the op, or "write"
Source string
// contains filtered or unexported fields
}
Rule is one compiled rule.
func CompileConfig ¶ added in v0.8.2
CompileConfig compiles and checks the read rule of a path of the app configuration. It may use `user`, `now`, hasRole with the realm's roles and hasConsent with its consents; there is no document.
func CompileInvoke ¶
CompileInvoke compiles and checks a function's invoke rule. It may use `user`, hasRole with the realm's roles and appConfig with the values configLeaf says exist (nil when the realm declares no app configuration); there is no document.
func (*Rule) Allow ¶
Allow evaluates the rule. An evaluation error (for example comparing values of different types) is returned, and must be treated as a denial.
func (*Rule) AlwaysFalse ¶ added in v0.8.2
AlwaysFalse reports whether the rule is literally `false`: nobody is ever allowed.
func (*Rule) AlwaysTrue ¶ added in v0.8.2
AlwaysTrue reports whether the rule is literally `true`: it allows everyone, with or without a session, so what it guards can be cached publicly.
func (*Rule) CanAllowAnonymous ¶ added in v0.8.2
CanAllowAnonymous reports whether the rule may be true for a caller without credentials: false only when it is false whatever the document holds, such as `user != nil`, `hasRole(user, 'admin')` or `hasConsent(user, 'terms')`. It reads the rule's syntax tree with three values; `document` and `now` are unknown.
func (*Rule) Filter ¶
Filter turns a read rule into a storage filter for the given caller. The result is simplified: Const(true) allows every document, Const(false) none, whatever they contain.
func (*Rule) UsesConfig ¶ added in v0.8.2
UsesConfig reports whether the rule reads the app configuration.
type Schema ¶
type Schema struct {
// DocumentField reports whether a dot path exists on stored documents
// (schema fields plus id and _meta fields).
DocumentField func(path string) bool
// DataField reports whether a dot path exists in request bodies.
DataField func(path string) bool
// ScalarField reports whether a document path holds a single value:
// declared with types that don't include "array", and not reached
// through an array. Read rules may only compare such fields, because
// MongoDB compares arrays element by element.
ScalarField func(path string) bool
// ArrayField reports whether a document path is declared as an array
// (and not reached through another array), for `value in document.path`.
ArrayField func(path string) bool
// DateField reports whether a path is stored as a date (x-backd-store:
// date): its value is a time in rules, comparable with `now`. May be nil.
DateField func(path string) bool
// Roles are the role names declared in realm.yaml.
Roles []string
// Consents are the consent names declared in realm.yaml, for hasConsent.
Consents []string
// ConfigLeaf reports whether a dot path is a value of the realm's app
// configuration, for appConfig; nil when the realm declares none.
ConfigLeaf func(path string) bool
}
Schema describes what the rules of one collection may refer to.
type Set ¶
type Set struct {
File string
// contains filtered or unexported fields
}
Set is a collection's compiled rules. A nil rule denies the operation.
func Parse ¶
Parse compiles and checks the `rules:` section of a collection's collection.yaml: a mapping of operation (read, create, update, delete, restore, purge, or write for the three that change a document) to an expression.
func (*Set) UsesConfig ¶ added in v0.8.2
UsesConfig reports whether any rule of the set reads the app configuration.
type User ¶
type User struct {
ID string `expr:"id"`
Email string `expr:"email"`
EmailVerified bool `expr:"email_verified"`
Roles []string `expr:"roles"`
// MFA says the session used a second factor; Methods are how it was created: the
// first factor and, with MFA, "totp" or "recovery". API keys are ["key"].
MFA bool `expr:"mfa"`
Methods []string `expr:"methods"`
// Consents maps each consent the user holds to the version they accepted.
Consents map[string]string `expr:"consents"`
}
User is the signed-in user as rules see it; nil for anonymous callers.
type Values ¶
type Values struct {
User *User // nil for anonymous callers
Document map[string]any // stored document (read, update, delete)
Data map[string]any // incoming document (create, update)
Now time.Time
// Config is the app configuration, by dot path of each value, for appConfig();
// only filled in when a rule reads it.
Config map[string]any
}
Values are what a rule is evaluated with.
Source Files