Safe Haskell	None
Language	GHC2021

Ecluse.Core.Server.Route

Contents

A route
Routing a request
Rendering a route
Building a route table

Description

A route is one record for a URL the proxy serves. It holds the method, template, action, and documentation. A route table folds into a mount router where the first match wins and all other requests receive a 404. The manifest renders RouteDescription projections of the records the router runs.

Synopsis

data Route v = Route {
- routeName :: RouteName
- routeMethod :: MethodMatch
- routeAccepts :: MediaNegotiation response
- routeSegs :: [PatternSeg v]
- routeBuild :: Method -> [v] -> Maybe (ResponseAction response)
- routeSummary :: Text
- routeDescription :: Text
- routeRequest :: Maybe RequestSpec
- routeContract :: ResponseContract response
}
newtype RouteName = RouteName {
- unRouteName :: Text
}
data PatternSeg v
- = SegLit Text
- | SegCap (Capture v)
data Capture v = Capture {
- capName :: Text
- capDescription :: Text
- capConsume :: [Text] -> Maybe (v, [Text])
- capRender :: v -> [Text]
}
data MethodMatch
- = MethodPut
- | MethodPost
- | MethodDelete
- | MethodRead
data MediaNegotiation response
- = AcceptsAnything
- | AcceptsOnly (NonEmpty ByteString) (Maybe HelpMessage -> response)
routerOf :: RouteAction -> [Route v] -> MountRouter
matchRoute :: [Route v] -> Method -> RequestHeaders -> [Text] -> Maybe (Route v, RouteAction)
renderRoute :: Route v -> [v] -> Maybe [Text]
answering :: response -> Method -> [v] -> Maybe (ResponseAction response)
refusing :: (Maybe HelpMessage -> response) -> Method -> [v] -> Maybe (ResponseAction response)
safeSegment :: (Text -> v) -> [Text] -> Maybe (v, [Text])
isHead :: Method -> Bool

A route

data Route v Source #

One route: how it matches, what it does, and what it documents. The type parameter v is the ecosystem's capture value, the only part of a route not shared across ecosystems.

Constructors

Route

Fields

routeName :: RouteName
Unique within its ecosystem. The manifest qualifies it for OpenAPI's global operation ID.
routeMethod :: MethodMatch
The method condition a request must satisfy to match.
routeAccepts :: MediaNegotiation response
Served media types and the response when a request admits none.
routeSegs :: [PatternSeg v]
The mount-relative path template: literal segments and named captures, in order.
routeBuild :: Method -> [v] -> Maybe (ResponseAction response)
Builds an action from captured values in template order. Nothing falls through to the next route, and a HEAD uses the GET builder because its response has no body.
routeSummary :: Text
A one-line summary (the OpenAPI operation summary).
routeDescription :: Text
The fuller prose description of what the route does.
routeRequest :: Maybe RequestSpec
The request body a write route accepts. Nothing for a read.
routeContract :: ResponseContract response
Runtime dispatch and the manifest share this response contract.

newtype RouteName Source #

A route's name within its ecosystem ("packument", "tarball"). The manifest adds the ecosystem namespace when it needs a globally unique identifier.

Constructors

RouteName
Fields unRouteName :: Text

Instances

Instances details

Show RouteName Source #
Instance details Defined in Ecluse.Core.Server.Route Methods showsPrec :: Int -> RouteName -> ShowS # show :: RouteName -> String # showList :: [RouteName] -> ShowS #
Eq RouteName Source #
Instance details Defined in Ecluse.Core.Server.Route Methods (==) :: RouteName -> RouteName -> Bool # (/=) :: RouteName -> RouteName -> Bool #
Ord RouteName Source #
Instance details Defined in Ecluse.Core.Server.Route Methods compare :: RouteName -> RouteName -> Ordering # (<) :: RouteName -> RouteName -> Bool # (<=) :: RouteName -> RouteName -> Bool # (>) :: RouteName -> RouteName -> Bool # (>=) :: RouteName -> RouteName -> Bool # max :: RouteName -> RouteName -> RouteName # min :: RouteName -> RouteName -> RouteName #

data PatternSeg v Source #

One segment of a path template: a fixed segment matched verbatim, or a named capture. A capture consumes one or more leading segments and yields a value.

Constructors

SegLit Text
SegCap (Capture v)

data Capture v Source #

A named path capture and its parser. capConsume may claim more than one segment, which an ecosystem whose identifier spans a decoded '/' needs, and Nothing fails the match.

Constructors

Capture

Fields

capName :: Text
The capture name, as it appears in the template ({package}).
capDescription :: Text
A one-line, human-facing description for the documentation.
capConsume :: [Text] -> Maybe (v, [Text])
Consume the leading segments this capture claims, yielding its value and the tail.
capRender :: v -> [Text]
capConsume inverted, so a served URL is built from the record that must claim it.

data MethodMatch Source #

The method condition on a route: a closed vocabulary rather than a predicate, so the manifest can name the documented method. A method outside it matches no route and denies.

Constructors

MethodPut	The write method (`PUT`).
MethodPost	The submission method (`POST`).
MethodDelete	The removal method (`DELETE`).
MethodRead	The read methods (`GET` and `HEAD`).

Instances

Instances details

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

data MediaNegotiation response Source #

What a route serves, and what it refuses a client that will not take it. The refusal renders into the route's own contract, so the 406 is documented from the record that serves it.

Constructors

AcceptsAnything	The route negotiates nothing: every request is admitted whatever it says it accepts.
AcceptsOnly (NonEmpty ByteString) (Maybe HelpMessage -> response)	The route serves these media types alone, and refuses a request whose `Accept` admits none of them under the mount's configured help message.

Routing a request

routerOf :: RouteAction -> [Route v] -> MountRouter Source #

Fold an ecosystem's route table into its mount's router. The first route that claims the request decides it, and deny-by-default is structural because there is no other way to answer.

matchRoute :: [Route v] -> Method -> RequestHeaders -> [Text] -> Maybe (Route v, RouteAction) Source #

The route that claims a request, and the action it names: the first route whose method condition holds, whose segments are consumed exactly, and whose builder accepts the captures.

Rendering a route

renderRoute :: Route v -> [v] -> Maybe [Text] Source #

The mount-relative path a route serves one set of captures under. A rewritten artifact URL is built through this, so the URL served and the route that must claim it are one record.

Building a route table

answering :: response -> Method -> [v] -> Maybe (ResponseAction response) Source #

A routeBuild that answers with one fixed value whatever the method and captures. The literal routes an ecosystem answers itself, rather than through the data plane, are built with it.

refusing :: (Maybe HelpMessage -> response) -> Method -> [v] -> Maybe (ResponseAction response) Source #

answering for a refusal: the route decides it, and the site holding the mount's dependencies renders it under the configured help message.

safeSegment :: (Text -> v) -> [Text] -> Maybe (v, [Text]) Source #

A capConsume that claims one leading segment, and only when it is a safe path component. A traversal, separator, or control character therefore fails the match before the value exists.

isHead :: Method -> Bool Source #

Whether a request is the bodiless read. A HEAD is a variation of its GET, not a route.