Linnet.Endpoint

Documentation

data EndpointResult (m :: * -> *) a

Result of returned by Endpoint that could be either:

• Matched containing reminder of the input together with Output inside of monad m
• NotMatched in case endpoint doesn't match the input

Constructors

Matched

Fields

• matchedReminder :: Input
• matchedOutput :: m (Output a)

NotMatched

Instances

Functor m => Functor (EndpointResult m)

Defined in Linnet.Endpoint

Methods

fmap :: (a -> b) -> EndpointResult m a -> EndpointResult m b

(<$) :: a -> EndpointResult m b -> EndpointResult m a

Show (m (Output a)) => Show (EndpointResult m a)

Defined in Linnet.Endpoint

Methods

showsPrec :: Int -> EndpointResult m a -> ShowS

show :: EndpointResult m a -> String

showList :: [EndpointResult m a] -> ShowS

data Endpoint (m :: * -> *) a

Basic Linnet data type that abstracts away operations over HTTP communication. While WAI Application has type of Request -> (Response -> IO ResponseReceived) -> IO ResponseReceived, it's practical to treat web applications as functions of Request -> BusinessLogic -> IO Response where BusinessLogic is usually a function of a -> m b where a and b are data to be decoded from the request / encoded to response, m is some monad, and this is the most interesting part of an application.

Endpoint's purpose is exactly to abstract details of encoding and decoding, along with routing and the rest, and provide simple interface to encapsulate BusinessLogic into a final web application.

Business logic is encoded as transformation in fmap, mapOutput, mapOutputM, mapM and the like. Usual way to transform endpoint is to use ~> and ~>> operators:

get (path @Text) ~> (\segment -> return $ ok segment)

Here, ~> is just an inverted alias for mapOutputM function. Often, endpoint is a product of multiple endpoints, and here ~>> proves to be very handy:

get (p' "sum" // path @Int // path @Int) ~>> (\i1 i2 -> return $ ok (i1 + i2) )

The trick is that // defines sequential AND combination of endpoints that is represented as endpoint of HList, so instead of dealing with heterogeneous list, it's possible to use ~>> instead and map with a function of multiple arguments.

Endpoints are also composable in terms of OR logic with |+| operator that is useful for routing:

getUsers = get (p' "users") ~>> (ok <$> fetchUsers)
newUser = post (p' "users" // jsonBody @User) ~>> (\user -> ok <$> createUser user)
usersApi = getUsers |+| newUser

An endpoint might be converted into WAI Application using bootstrap and @TypeApplications language pragma:

main = run 9000 app
       where app = bootstrap @TextPlain usersApi & compile & toApp id

Constructors

Endpoint

Fields

• runEndpoint :: Input -> EndpointResult m a
• toString :: String

Instances

Functor m => Functor (Endpoint m)

Defined in Linnet.Endpoint

Methods

fmap :: (a -> b) -> Endpoint m a -> Endpoint m b

(<$) :: a -> Endpoint m b -> Endpoint m a

MonadCatch m => Applicative (Endpoint m)

Defined in Linnet.Endpoint

Methods

pure :: a -> Endpoint m a

(<*>) :: Endpoint m (a -> b) -> Endpoint m a -> Endpoint m b

liftA2 :: (a -> b -> c) -> Endpoint m a -> Endpoint m b -> Endpoint m c

(*>) :: Endpoint m a -> Endpoint m b -> Endpoint m b

(<*) :: Endpoint m a -> Endpoint m b -> Endpoint m a

MonadCatch m => Alternative (Endpoint m)

Defined in Linnet.Endpoint

Methods

empty :: Endpoint m a

(<|>) :: Endpoint m a -> Endpoint m a -> Endpoint m a

some :: Endpoint m a -> Endpoint m [a]

many :: Endpoint m a -> Endpoint m [a]

Show (Endpoint m a)

Defined in Linnet.Endpoint

Methods

showsPrec :: Int -> Endpoint m a -> ShowS

show :: Endpoint m a -> String

showList :: [Endpoint m a] -> ShowS

(KnownSymbol ct, ToResponse ct a, ToResponse ct SomeException, Compile cts m (HList es), MonadCatch m) => Compile (Coproduct (Proxy ct) cts) m (HList (Endpoint m a ': es))

Defined in Linnet.Compile

Methods

compile :: HList (Endpoint m a ': es) -> ReaderT Request m Response

isMatched :: EndpointResult m a -> Bool

maybeReminder :: EndpointResult m a -> Maybe Input

lift :: Functor m => m a -> Endpoint m a

Lift monadic value m a into Endpoint that always matches

liftOutputM :: m (Output a) -> Endpoint m a

Lift monadic output m (Output a) into Endpoint that always matches

mapM' :: Monad m => (a -> m b) -> Endpoint m a -> Endpoint m b

Map over the Output of endpoint with function returning new value a lifted in monad m

mapOutput :: Monad m => (a -> Output b) -> Endpoint m a -> Endpoint m b

Map over the value of Endpoint with function returning new Output b

mapOutputM :: Monad m => (a -> m (Output b)) -> Endpoint m a -> Endpoint m b

Map over the value of Endpoint with function returning new m (Output b)

handle :: (MonadCatch m, Exception e) => (e -> m (Output a)) -> Endpoint m a -> Endpoint m a

Handle exception in monad m of Endpoint result using provided function that returns new Output

handleAll :: MonadCatch m => (SomeException -> m (Output a)) -> Endpoint m a -> Endpoint m a

Handle all exceptions in monad m of Endpoint result

try :: (Exception e, MonadCatch m) => Endpoint m a -> Endpoint m (Either e a)

Lift an exception of type e into Either

transformOutput :: (m (Output a) -> m (Output b)) -> Endpoint m a -> Endpoint m b

transform :: Monad m => (m a -> m b) -> Endpoint m a -> Endpoint m b

(~>) :: Monad m => Endpoint m a -> (a -> m (Output b)) -> Endpoint m b infixl 0

Inversed alias for mapOutputM

(~>>) :: (Monad m, FnToProduct fn ls (m (Output b))) => Endpoint m (HList ls) -> fn -> Endpoint m b infixl 0

Advanced version of ~> operator that allows to map Endpoint m (HList ls) over a function of arity N equal to N elements of HList. General rule of thumb when to use this operator is whenever there is an HList on the left side.

productWith :: forall m a b c. MonadCatch m => Endpoint m a -> Endpoint m b -> (a -> b -> c) -> Endpoint m c

Create product of two Endpoints that sequentially match a request. | If some of endpoints doesn't match a request, the final result is also non-matching

(//) :: (MonadCatch m, AdjoinHList (a ': (b ': '[])) out) => Endpoint m a -> Endpoint m b -> Endpoint m (HList out) infixr 2

Create product of two Endpoints that sequentially match a request and values are adjoined into HList. If some of endpoints doesn't match a request, the final result is also non-matching

(|+|) :: forall m a b out. (MonadCatch m, AdjoinCoproduct (Coproduct a (Coproduct b CNil)) out) => Endpoint m a -> Endpoint m b -> Endpoint m out infixl 2

Create new Endpoint of two endpoints, adjoining values into Coproduct During request resolution the following logic is applied:

• If none of endpoints match, resulting endpoint is also non-matching
• If both endpoints match, the more specific one is selected (with shorter reminder)

root :: Applicative m => Endpoint m Request

Endpoint that always matches and returns a request from Input

zero :: Applicative m => Endpoint m (HList '[])

Endpoint that always matches and doesn't change any reminder