@@ -17,7 +17,28 @@ import Servant.Client.Core
1717import Servant.Server
1818import Servant.Server.Internal
1919
20−-- | Types to use in you API description
20+-- | Combinator for your Servant API description. Prepend it to your API for greater enjoyment!
21+-- Example:
22+--
23+-- @
24+-- type MyAPI = RequestTracking :> "ping" :> Get '[JSON] Text
25+-- @
26+--
27+-- In addition to the API combinator, you also need to create a context handler that will
28+-- handler the tracking data (see 'ReqtrackInfo') and produce desired output, which in turn
29+-- will be passed to your API handlers.
30+-- The type of values passed to API handlers is controlled by @type instance TrackingData RequestTracking@,
31+-- which isn't set by default.
32+-- The server code should look something like this:
33+--
34+-- @
35+-- data TrackingArg = ...
36+--
37+-- type instance TrackingData RequestTracking = TrackingArg
38+--
39+-- trackingHandler :: ReqtrackingHandler (Maybe ReqtrackInfo) TrackingArg
40+--
41+-- @
2142data RequestTracking
2243
2344type family TrackingData a
@@ -25,9 +46,18 @@ type family TrackingData a
2546-- | Same as above, except no argument is passed to a handler.
2647data RequestTracking_
2748
28−newtype ReqtrackingHandler r o = ReqtrackingHandler { unReqtrackingHandler :: r -> Handler o
49+newtype ReqtrackingHandler r o = ReqtrackingHandler { runReqtrackingHandler :: r -> Handler o
2950 } deriving (Functor)
3051
52+instance Applicative (ReqtrackingHandler r) where
53+ pure x = ReqtrackingHandler $ \_ -> pure x
54+ f <*> v = ReqtrackingHandler $ \r -> runReqtrackingHandler f r <*> runReqtrackingHandler v r
55+
56+instance Monad (ReqtrackingHandler r) where
57+ return = pure
58+ f >>= g = ReqtrackingHandler $ \r -> do a <- runReqtrackingHandler f r
59+ runReqtrackingHandler (g a) r
60+
3161mkReqtrackingHandler :: (Maybe ReqtrackInfo -> Handler o) -> ReqtrackingHandler (Maybe ReqtrackInfo) o
3262mkReqtrackingHandler = ReqtrackingHandler
3363