ecluse:ecluse-core
Safe HaskellNone
LanguageGHC2021

Ecluse.Core.Server.Response

Description

Map policy and upstream outcomes to HTTP statuses. Artifact requests use one outcome, while packuments choose a status from the surviving versions. Ecosystem contracts own response bodies.

Synopsis

Serve outcomes

data ServeDecision Source #

The outcome of deciding a request: serve it, or refuse it with a reason. Every client-facing reply renders one.

Constructors

Admit

Serve the request (the 200 stream for an artifact).

Reject Rejection

Refuse the request, with the reason and a client-facing message.

data Rejection Source #

A refusal: why the request was refused, and an intuitive message for the client.

Constructors

Rejection 

Fields

Instances

Instances details
Show Rejection Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Eq Rejection Source # 
Instance details

Defined in Ecluse.Core.Server.Response

data RejectReason Source #

Why a request was refused. A policy refusal is final for this request. An inability to decide carries a Transience for 503 or 500.

Constructors

ByPolicy RuleName [Reason]

A rule denied the version (deny-by-default included): the deciding rule, and the reasons the decision gave.

Unavailable Transience

The version could not be vetted. Refuse it, with transience indicating whether a retry can help.

MissingIntegrity

A public artifact lacks a digest, so admission cannot verify its bytes. Trusted private artifacts are exempt.

BelowIntegrityFloor

A public artifact's strongest digest falls below the configured floor. Trusted private artifacts are exempt.

UpstreamInvalid

An upstream reply was invalid or unusable, such as a document that names a different package.

Instances

Instances details
Show RejectReason Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Eq RejectReason Source # 
Instance details

Defined in Ecluse.Core.Server.Response

data Transience Source #

Whether a retry can help: a transient fault serves 503, and an internal or parse fault 500.

Constructors

WillResolve (Maybe RetryAfter)

A retry may succeed after an outage, timeout, or open breaker. RetryAfter suggests a client delay.

WontResolve

Not expected to self-heal, so the request is a 500, never a 503.

Instances

Instances details
Show Transience Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

Eq Transience Source # 
Instance details

Defined in Ecluse.Core.Rules.Types

newtype RetryAfter Source #

A Retry-After delay in whole seconds, never confused with another integer on its way to a header or a sweep's wait.

Constructors

RetryAfter Int 

newtype RuleName Source #

The name of the rule that decided a refusal, for the audit trail and the denial body.

Constructors

RuleName Text 

Instances

Instances details
Show RuleName Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Eq RuleName Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Ord RuleName Source # 
Instance details

Defined in Ecluse.Core.Server.Response

rejectUnavailable :: Transience -> Text -> ServeDecision Source #

Refuse a request that could not be decided. A caller states the Transience, and artifactStatus picks the status.

serveDecisionOf :: RuleEvidence -> Decision -> ServeDecision Source #

Project a rules Decision into a serve outcome. A version no rule could vet is refused as Unavailable.

Concrete-artifact status

data ArtifactStatus Source #

The HTTP status a concrete-artifact request renders to. PackumentStatus chooses a packument's over its survivors.

Constructors

Ok

200: admitted, so the proxy streams the artifact.

Forbidden

403: refused by policy. The route's response contract shapes the body.

Unavailable' (Maybe RetryAfter)

503: a transient inability to decide. A known RetryAfter becomes the header.

ServerError

500: a permanent or internal inability to decide. Not retryable.

BadGateway

502: an upstream reply was invalid or unusable.

NotFound

404: the upstream did not have the artifact (forwarded miss).

artifactStatus :: ServeDecision -> ArtifactStatus Source #

A serve outcome's concrete-artifact status: 503 only where it will resolve. It never yields NotFound.

artifactHttpStatus :: ArtifactStatus -> Status Source #

The HTTP status an ArtifactStatus renders as.

Packument status (over the merged survivor set)

data PackumentStatus Source #

The HTTP status a packument request renders to. A name no origin holds is decided before the merge.

Constructors

PackumentOk

200: at least one version survived, so the proxy serves the merged, filtered packument.

PackumentDenied

No version survived and every exclusion was a policy or integrity refusal. A listing answers 404 and a native coordinate 403, each with the refusals in its body.

PackumentForbidden

403: no version survived and none was excluded, so no exclusion names a cause.

PackumentUnavailable (Maybe RetryAfter)

503: no version survived and an exclusion can recover. A suggested delay becomes Retry-After.

PackumentBadGateway

502: no valid origin remained and an upstream reply was invalid or unusable.

PackumentServerError

500: no version survived, no exclusion is retryable, and one is a permanent or internal inability to decide. Retrying cannot help.

packumentStatus :: [ServeDecision] -> PackumentStatus Source #

With no survivor the most recoverable cause wins (503 over 502, as an origin may yet answer). An empty input is a 403.

longestRetry :: [Maybe RetryAfter] -> Maybe RetryAfter Source #

The longest suggested RetryAfter among transient causes, or Nothing when none suggested one.

Denial help text

data HelpMessage Source #

An operator-configured message appended to every denial. Stored trimmed, so an all-blank value contributes nothing.

Instances

Instances details
Show HelpMessage Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Eq HelpMessage Source # 
Instance details

Defined in Ecluse.Core.Server.Response

mkHelpMessage :: Text -> HelpMessage Source #

Build a HelpMessage, trimming surrounding whitespace.

appendHelp :: Maybe HelpMessage -> Text -> Text Source #

Append a non-blank operator HelpMessage to a denial message, separated by a single space.

A refusal's two parts

data Refusal Source #

A refusal's text in two parts, so an ecosystem without an envelope for both still keeps the help message.

Constructors

Refusal 

Fields

Instances

Instances details
Show Refusal Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Eq Refusal Source # 
Instance details

Defined in Ecluse.Core.Server.Response

Methods

(==) :: Refusal -> Refusal -> Bool #

(/=) :: Refusal -> Refusal -> Bool #

mkRefusal :: Maybe HelpMessage -> Text -> Refusal Source #

Pair a decided reason with the mount's configured help message, if it has a non-blank one.

renderRefusal :: Refusal -> Text Source #

The refusal as one line: the reason, with the help message appended after a single space.

refusalHelpBytes :: Refusal -> Maybe LByteString Source #

The help message alone as body bytes, absent when none is configured.