servant-server-0.20: A family of combinators for defining webservices APIs and serving them

Safe Haskell | Safe-Inferred
Language | Haskell2010

Servant.Server.Internal.Router

Synopsis

- type Router env = Router' env RoutingApplication
- data CaptureHint = CaptureHint {
  - captureName :: Text
  - captureType :: TypeRep
  }
- toCaptureTag :: CaptureHint -> Text
- toCaptureTags :: [CaptureHint] -> Text
- data Router' env a
  - = StaticRouter (Map Text (Router' env a)) [env -> a]
  - | CaptureRouter [CaptureHint] (Router' (Text, env) a)
  - | CaptureAllRouter [CaptureHint] (Router' ([Text], env) a)
  - | RawRouter (env -> a)
  - | Choice (Router' env a) (Router' env a)
- pathRouter :: Text -> Router' env a -> Router' env a
- leafRouter :: (env -> a) -> Router' env a
- choice :: Router' env a -> Router' env a -> Router' env a
- data RouterStructure
  - = StaticRouterStructure (Map Text RouterStructure) Int
  - | CaptureRouterStructure [CaptureHint] RouterStructure
  - | RawRouterStructure
  - | ChoiceStructure RouterStructure RouterStructure
- routerStructure :: Router' env a -> RouterStructure
- sameStructure :: Router' env a -> Router' env b -> Bool
- routerLayout :: Router' env a -> Text
- tweakResponse :: (RouteResult Response -> RouteResult Response) -> Router env -> Router env
- runRouter :: NotFoundErrorFormatter -> Router () -> RoutingApplication
- runRouterEnv :: NotFoundErrorFormatter -> Router env -> env -> RoutingApplication
- runChoice :: NotFoundErrorFormatter -> [env -> RoutingApplication] -> env -> RoutingApplication
- worseHTTPCode :: Int -> Int -> Bool

# Documentation

type Router env = Router' env RoutingApplication #

data CaptureHint #

Holds information about pieces of url that are captured as variables.

Constructors

CaptureHint |

Fields

- captureName :: Text

  Holds the name of the captured variable

- captureType :: TypeRep

  Holds the type of the captured variable

#### Instances

Instances details

Show CaptureHint # |
Instance details Defined in Servant.Server.Internal.Router Methods showsPrec :: Int -> CaptureHint -> ShowS # show :: CaptureHint -> String # showList :: [CaptureHint] -> ShowS #
Eq CaptureHint # |
Instance details Defined in Servant.Server.Internal.Router Methods (==) :: CaptureHint -> CaptureHint -> Bool # (/=) :: CaptureHint -> CaptureHint -> Bool #

toCaptureTag :: CaptureHint -> Text #

toCaptureTags :: [CaptureHint] -> Text #

data Router' env a #

Internal representation of a router.

The first argument describes an environment type that is expected as extra input by the routers at the leaves. The environment is filled while running the router, with path components that can be used to process captures.

Constructors

StaticRouter (Map Text (Router' env a)) [env -> a] | the map contains routers for subpaths (first path component used for lookup and removed afterwards), the list contains handlers for the empty path, to be tried in order

CaptureRouter [CaptureHint] (Router' (Text, env) a)

first path component is passed to the child router in its environment and removed afterwards. The first argument is a list of hints for all variables that can be captured by the router. The fact that it is a list is counter-intuitive, because the `Capture` combinator only allows to capture a single varible, with a single name and a single type. However, the `choice` smart constructor may merge two `Capture` combinators with different hints, thus forcing the type to be '[CaptureHint]'. Because `CaptureRouter` is built from a `Capture` combinator, the list of hints should always be non-empty.

CaptureAllRouter [CaptureHint] (Router' ([Text], env) a) | all path components are passed to the child router in its environment and are removed afterwards The first argument is a hint for the list of variables that can be captured by the router. Note that the `captureType` field of the hint should always be '[a]' for some `a`.
RawRouter (env -> a) | to be used for routes we do not know anything about
Choice (Router' env a) (Router' env a) | left-biased choice between two routers

#### Instances

Instances details

Functor (Router' env) # |
Instance details Defined in Servant.Server.Internal.Router Methods fmap :: (a -> b) -> Router' env a -> Router' env b # (<$) :: a -> Router' env b -> Router' env a #

pathRouter :: Text -> Router' env a -> Router' env a #

Smart constructor for a single static path component.

leafRouter :: (env -> a) -> Router' env a #

Smart constructor for a leaf, i.e., a router that expects the empty path.

choice :: Router' env a -> Router' env a -> Router' env a #

Smart constructor for the choice between routers. We currently optimize the following cases:

- Two static routers can be joined by joining their maps and concatenating their leaf-lists.
- Two dynamic routers can be joined by joining their codomains.
- Choice nodes can be reordered.

data RouterStructure #

Datatype used for representing and debugging the structure of a router. Abstracts from the handlers at the leaves.

Two `Router`s can be structurally compared by computing their `RouterStructure` using `routerStructure` and then testing for equality, see `sameStructure`.

Constructors

StaticRouterStructure (Map Text RouterStructure) Int |
CaptureRouterStructure [CaptureHint] RouterStructure | The first argument holds information about variables that are captured by the router. There may be several hints if several routers have been aggregated by the `choice` smart constructor.
RawRouterStructure |
ChoiceStructure RouterStructure RouterStructure |

#### Instances

Instances details

Show RouterStructure # |
Instance details Defined in Servant.Server.Internal.Router Methods showsPrec :: Int -> RouterStructure -> ShowS # show :: RouterStructure -> String # showList :: [RouterStructure] -> ShowS #
Eq RouterStructure # |
Instance details Defined in Servant.Server.Internal.Router Methods (==) :: RouterStructure -> RouterStructure -> Bool # (/=) :: RouterStructure -> RouterStructure -> Bool #

routerStructure :: Router' env a -> RouterStructure #

Compute the structure of a router.

Assumes that the request or text being passed in `WithRequest` or `CaptureRouter` does not affect the structure of the underlying tree.

sameStructure :: Router' env a -> Router' env b -> Bool #

Compare the structure of two routers.

routerLayout :: Router' env a -> Text #

Provide a textual representation of the structure of a router.

tweakResponse :: (RouteResult Response -> RouteResult Response) -> Router env -> Router env #

Apply a transformation to the response of a `Router`.

runRouter :: NotFoundErrorFormatter -> Router () -> RoutingApplication #

Interpret a router as an application.

runRouterEnv :: NotFoundErrorFormatter -> Router env -> env -> RoutingApplication #

runChoice :: NotFoundErrorFormatter -> [env -> RoutingApplication] -> env -> RoutingApplication #

Try a list of routing applications in order. We stop as soon as one fails fatally or succeeds. If all fail normally, we pick the "best" error.

worseHTTPCode :: Int -> Int -> Bool #