ecluse:ecluse-core
Safe HaskellNone
LanguageGHC2021

Ecluse.Core.Rules

Description

The policy engine denies by default and decides in boot order. One advisory read per package serves every advisory rule an evaluator reaches, so a request's decisions read one generation.

Synopsis

The boot-bound rule capabilities

data RuleDeps Source #

One ecosystem's boot-bound rule capabilities: its advisory database and the rules' observers.

Constructors

RuleDeps 

Fields

data AdvisoryDatabase Source #

An ecosystem's advisory database, as configuration fixes it at boot.

Constructors

NoAdvisoryDatabase 
AdvisoryDatabase (forall a. (AdvisoryGeneration -> IO a) -> IO a)

Hold one generation's age reading and lookup access together through the caller's action.

data AdvisoryGeneration Source #

The age and lookup capabilities borrowed from one advisory generation.

Constructors

AdvisoryGeneration 

Fields

withCveLookup :: RuleDeps -> (Maybe (DbEtag, CveLookup) -> IO a) -> IO a Source #

Borrow the loaded generation, or Nothing when none is configured or none has loaded yet.

The built-in rule dispatch

data VerdictSource Source #

Where a built-in rule's verdict comes from.

Constructors

FromEvidence (EvalContext -> RuleEvidence -> RuleVerdict)

One version's evidence and the request context.

FromAdvisories AdvisoryAlignment (AdvisoryRows -> RuleEvidence -> RuleVerdict)

The package's advisory rows, with how the rule resolves when it cannot read them.

data AdvisoryAlignment Source #

How an advisory rule resolves when it cannot read: on an expired push, and on a faulted read.

Constructors

AdvisoryAlignment 

Fields

verdictSource :: Rule -> VerdictSource Source #

Dispatch the closed rule vocabulary. An unread required fact refuses instead of abstaining.

type AdvisoryRows = Maybe (DbEtag, PackageAdvisories) Source #

One package's advisory rows and the generation that served them, or Nothing while none is loaded.

readAdvisories :: PackageName -> Maybe (DbEtag, CveLookup) -> IO AdvisoryRows Source #

Parse one borrowed generation's package rows once for all versions. Query faults escape.

The engine's prepared rule

data PreparedRule Source #

Config obtains evaluators only through prepare, never from arbitrary code.

Constructors

PreparedRule 

Fields

  • prepName :: Text

    The stable, human-facing name: the boot-order tiebreak and the credited identity.

  • prepPrecedence :: Int

    The precedence at which this rule competes. Higher wins in the boot order.

  • prepEval :: RuleEval

    How the rule reaches the versions an evaluator decides.

data RuleEval Source #

How a prepared rule reaches the versions an evaluator decides.

Constructors

PerVersion (EvalContext -> RuleEvidence -> IO RuleVerdict)

Each version's verdict. It can run more than once for a version and must answer alike. A throw refuses admission.

PerPackage PackageRead

A verdict for each version from the evaluator's one advisory read of the package.

data PackageRead Source #

A rule's bracketed advisory read and its verdict over the shared result.

Constructors

PackageRead 

Fields

data Resilience Source #

The resilience policy around one advisory rule's reads. Each rule holds its own breaker state.

Constructors

Resilience 

Fields

prepare :: RuleDeps -> [PrecededRule] -> IO [PreparedRule] Source #

Allocate each advisory rule's breaker once. Unconfigured databases need no resilience.

prepResilience :: PreparedRule -> Maybe Resilience Source #

The resilience policy a prepared rule's package read runs under, if any.

Boot-time ordering

bootOrder :: [PreparedRule] -> [PreparedRule] Source #

Sort by descending precedence, then ascending rule name, independently of configuration order.

renderBootOrder :: [PrecededRule] -> [Text] Source #

Render each rule and its phases in the order bootOrder evaluates them.

Evaluation

newEvaluator :: EvalContext -> [PreparedRule] -> IO (RuleEvidence -> IO Decision) Source #

Decide a request's versions in boot order, catching throws. Advisory rules sharing one prepare read one generation.

evalRules :: EvalContext -> [PreparedRule] -> RuleEvidence -> IO Decision Source #

Decide one version through a fresh newEvaluator.

pushInability :: AdvisoryFreshness -> Maybe Inability Source #

Return why expired or undated evidence is unavailable, or Nothing while it is eligible.

Observing the advisory source

data SourceHealth Source #

What one rule's evaluation established about the source it reads.

Constructors

SourceAnswered Text

The named rule consulted its source, whatever it decided.

SourceUnavailable Text Inability

The named rule could not consult its source, for the given cause.

data SourceReporter Source #

The observer every advisory-reading evaluation reports to. The composition root installs the live one.

Constructors

SourceReporter 

Fields

noSourceReporter :: SourceReporter Source #

The inert reporter, for an ecosystem with no advisory source to observe. It logs every admission.