Safe Haskell	None
Language	GHC2021

Ecluse.Core.Rules

Contents

The boot-bound rule capabilities
The built-in rule dispatch
The engine's prepared rule
Boot-time ordering
Evaluation
Observing the advisory source

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

data RuleDeps = RuleDeps {
- rdAdvisoryDatabase :: AdvisoryDatabase
- rdCurrentAdvisoryEtag :: IO (Maybe DbEtag)
- rdBreakerReporter :: BreakerReporter
- rdSourceReporter :: SourceReporter
- rdAdvisoryFreshness :: IO AdvisoryFreshness
}
data AdvisoryDatabase
- = NoAdvisoryDatabase
- | AdvisoryDatabase (forall a. (Maybe (DbEtag, CveLookup) -> IO a) -> IO a)
withCveLookup :: RuleDeps -> (Maybe (DbEtag, CveLookup) -> IO a) -> IO a
data VerdictSource
- = FromEvidence (EvalContext -> RuleEvidence -> RuleVerdict)
- | FromAdvisories AdvisoryAlignment (AdvisoryRows -> RuleEvidence -> RuleVerdict)
data AdvisoryAlignment = AdvisoryAlignment {
- onExpiredPush :: FailureAlignment
- onFaultedRead :: FailureAlignment
}
verdictSource :: Rule -> VerdictSource
type AdvisoryRows = Maybe (DbEtag, PackageAdvisories)
readAdvisories :: RuleDeps -> PackageName -> IO AdvisoryRows
data PreparedRule = PreparedRule {
- prepName :: Text
- prepPrecedence :: Int
- prepEval :: RuleEval
}
data RuleEval
- = PerVersion (EvalContext -> RuleEvidence -> IO RuleVerdict)
- | PerPackage PackageRead
data PackageRead = PackageRead {
- prFreshness :: IO AdvisoryFreshness
- prResilience :: Maybe Resilience
- prRows :: PackageName -> IO AdvisoryRows
- prAlignment :: AdvisoryAlignment
- prVerdict :: AdvisoryRows -> RuleEvidence -> RuleVerdict
- prReporter :: SourceReporter
}
data Resilience = Resilience {
- resConfig :: EffectfulConfig
- resBreaker :: TVar Breaker
- resBreakerReporter :: BreakerReporter
- resClock :: IO UTCTime
}
prepare :: RuleDeps -> [PrecededRule] -> IO [PreparedRule]
prepResilience :: PreparedRule -> Maybe Resilience
bootOrder :: [PreparedRule] -> [PreparedRule]
renderBootOrder :: [PreparedRule] -> [Text]
newEvaluator :: EvalContext -> [PreparedRule] -> IO (RuleEvidence -> IO Decision)
evalRules :: EvalContext -> [PreparedRule] -> RuleEvidence -> IO Decision
renderDecision :: RuleEvidence -> Decision -> Text
renderDuration :: NominalDiffTime -> Text
renderIneligible :: AdvisoryFreshness -> Maybe Text
cveIdsInReason :: Text -> [Text]
data SourceHealth
- = SourceAnswered Text
- | SourceUnavailable Text Reason
data SourceReporter = SourceReporter {
- reportSource :: SourceHealth -> IO ()
- noteAdmission :: AdmissionIdentity -> IO Bool
}
noSourceReporter :: SourceReporter

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

rdAdvisoryDatabase :: AdvisoryDatabase
rdCurrentAdvisoryEtag :: IO (Maybe DbEtag)
A non-pinning read of the active DbEtag. It holds no generation open, so it never delays a shadow-swap.
rdBreakerReporter :: BreakerReporter
Where advisory rules report breaker transitions, as ecluse.rule.breaker.state.
rdSourceReporter :: SourceReporter
Where each advisory rule a request reaches reports whether it could consult the source, so an outage is observed as a transition rather than once per request.
rdAdvisoryFreshness :: IO AdvisoryFreshness
How old the serving artifact's push is, read again for every package read. The wall clock alone ages it, so an unchanged artifact expires in a warm process.

data AdvisoryDatabase Source #

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

Constructors

NoAdvisoryDatabase
AdvisoryDatabase (forall a. (Maybe (DbEtag, CveLookup) -> IO a) -> IO a)	Bracketed access to the lookup and ETag acquired together, `Nothing` until a generation loads.

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 onExpiredPush :: FailureAlignment Fixed per rule, since expiry is unavailability configuration cannot waive. onFaultedRead :: FailureAlignment The rule's configured alignment for a timeout, a spent retry budget, or an open breaker.

verdictSource :: Rule -> VerdictSource Source #

The single dispatch over the closed vocabulary. A rule that reads a fact nothing supplied refuses rather than abstaining, so the fold stops at it.

type AdvisoryRows = Maybe (DbEtag, PackageAdvisories) Source #

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

readAdvisories :: RuleDeps -> PackageName -> IO AdvisoryRows Source #

Pin a generation and read one package's rows through it, their bounds parsed once for all its versions. A query fault escapes to the caller.

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 on its own. A throw refuses admission.
PerPackage PackageRead	A verdict for each version from the evaluator's one advisory read of the package.

data PackageRead Source #

An advisory rule: how to make the evaluator's shared read when this rule reaches it first, and how the rule decides from that read.

Constructors

PackageRead

Fields

prFreshness :: IO AdvisoryFreshness
The push-age reading, taken ahead of the breaker.
prResilience :: Maybe Resilience
The policy around the read, or Nothing where no database is configured and the read does no IO.
prRows :: PackageName -> IO AdvisoryRows
The package's rows in one pinned generation.
prAlignment :: AdvisoryAlignment
How this rule resolves an ineligible push and a faulted read.
prVerdict :: AdvisoryRows -> RuleEvidence -> RuleVerdict
This rule's verdict for each version, from the rows.
prReporter :: SourceReporter
Where this rule reports whether the read let it consult the source.

data Resilience Source #

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

Constructors

Resilience

Fields

resConfig :: EffectfulConfig
The per-attempt timeout, retry budget/backoff, and breaker threshold/cooldown.
resBreaker :: TVar Breaker
This rule's circuit-breaker state, shared across requests.
resBreakerReporter :: BreakerReporter
The observer this rule's breaker reports state transitions to (ecluse.rule.breaker.state). Inert (noBreakerReporter) when unobserved.
resClock :: IO UTCTime
The wall clock the breaker reads for admission and cooldown, separate from the request snapshot ctxNow. A fresh read at failure commit starts the cooldown at the failure.

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

Allocate each advisory rule's breaker once. With no advisory database configured, an advisory rule's read does no IO and returns the rule's fixed verdict, so it runs without 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 :: [PreparedRule] -> [Text] Source #

Render the boot order as one line per rule, in evaluation order, so an operator sees at boot how their policy will resolve.

Evaluation

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

An evaluator for one request's versions, in boot order. Its advisory rules must come from one prepare, since the first reached reads the package once for them all. A throw refuses.

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

Decide one version through a fresh newEvaluator.

renderDecision :: RuleEvidence -> Decision -> Text Source #

A human-readable summary of a decision, suitable for logs and the denial response body.

renderDuration :: NominalDiffTime -> Text Source #

Keep two non-zero units to distinguish near-threshold durations. Negative values render as zero.

renderIneligible :: AdvisoryFreshness -> Maybe Text Source #

Why a push is not eligible evidence, or Nothing while it is. A serving generation the store gave no publication time for reads as unverified, because its age cannot be established.

cveIdsInReason :: Text -> [Text] Source #

Read the advisory identifiers from a scored denial reason, or return none.

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 Reason	The named rule could not consult its source, for the given cause.

Instances

Instances details

Show SourceHealth Source #
Instance details Defined in Ecluse.Core.Rules.Outage.Internal Methods showsPrec :: Int -> SourceHealth -> ShowS # show :: SourceHealth -> String # showList :: [SourceHealth] -> ShowS #
Eq SourceHealth Source #
Instance details Defined in Ecluse.Core.Rules.Outage.Internal Methods (==) :: SourceHealth -> SourceHealth -> Bool # (/=) :: SourceHealth -> SourceHealth -> Bool #

data SourceReporter Source #

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

Constructors

SourceReporter
Fields reportSource :: SourceHealth -> IO () Report one evaluation's reading. noteAdmission :: AdmissionIdentity -> IO Bool Whether the gate logs this admission's evidence: once per identity for the life of the outage.

noSourceReporter :: SourceReporter Source #

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