{- |
Module      : Servant.API.Routes.Route
Copyright   : (c) Frederick Pringle, 2025
License     : BSD-3-Clause
Maintainer  : frederick.pringle@fpringle.com

Simple term-level representation of Servant API endpoints.
-}
module Servant.API.Routes.Route
  ( -- * API routes

    -- | The 'Route' type is not sophisticated, and its internals are hidden.
    -- Create 'Route's using 'Servant.API.Routes.Route.defRoute', and update its fields
    -- using the provided [lenses](#g:optics).
    Route
  , defRoute
  , renderRoute

    -- * Optics #optics#
  , routeMethod
  , routePath
  , routeParams
  , routeRequestHeaders
  , routeRequestBody
  , routeResponse
  , routeAuths
  , routeDescription
  , routeSummary
  , add

    -- * Auxiliary types
  , RouteDescription (..)
  , RouteSummary (..)
  )
where

import qualified Data.Set as Set
import qualified Data.Text as T
import qualified Data.Text.Encoding as TE
import Lens.Micro
import Network.HTTP.Types.Method (Method)
import "this" Servant.API.Routes.Internal.Route
import "this" Servant.API.Routes.Param
import "this" Servant.API.Routes.Path
import "this" Servant.API.Routes.Request
import "this" Servant.API.Routes.Response

{- | Given a REST 'Method', create a default 'Route': root path (@"/"@) with no params,
headers, body, auths, or response.
-}
defRoute :: Method -> Route
defRoute :: Method -> Route
defRoute Method
method =
  Route
    { _routeMethod :: Method
_routeMethod = Method
method
    , _routePath :: Path
_routePath = Path
rootPath
    , _routeParams :: Set Param
_routeParams = Set Param
forall a. Set a
Set.empty
    , _routeRequestHeaders :: Set HeaderRep
_routeRequestHeaders = Set HeaderRep
forall a. Monoid a => a
mempty
    , _routeRequestBody :: Request
_routeRequestBody = Request
noRequest
    , _routeResponse :: Responses
_routeResponse = Responses
noResponse
    , _routeAuths :: Set Auth
_routeAuths = Set Auth
forall a. Monoid a => a
mempty
    , _routeDescription :: Maybe RouteDescription
_routeDescription = Maybe RouteDescription
forall a. Maybe a
Nothing
    , _routeSummary :: Maybe RouteSummary
_routeSummary = Maybe RouteSummary
forall a. Maybe a
Nothing
    }

{- | Pretty-print a 'Route'. Note that the output is minimal and doesn't contain all the information
contained in a 'Route'. For full output, use the 'Data.Aeson.ToJSON' instance.

> ghci> renderRoute $ defRoute \"POST\"
> "POST /"
> ghci> :{
> ghci| renderRoute $
> ghci|   defRoute \"POST\"
> ghci|     & routePath %~ prependPathPart "api/v2"
> ghci|     & routeParams .~ [singleParam @"p1" @T.Text, flagParam @"flag", arrayElemParam @"p2s" @(Maybe Int)]
> ghci| :}
> "POST /api/v2?p1=<Text>&flag&p2s=<[Maybe Int]>"
-}
renderRoute :: Route -> T.Text
renderRoute :: Route -> Text
renderRoute Route {Maybe RouteDescription
Maybe RouteSummary
Method
Set Auth
Set Param
Set HeaderRep
Path
Request
Responses
_routeMethod :: Route -> Method
_routePath :: Route -> Path
_routeParams :: Route -> Set Param
_routeRequestHeaders :: Route -> Set HeaderRep
_routeRequestBody :: Route -> Request
_routeResponse :: Route -> Responses
_routeAuths :: Route -> Set Auth
_routeDescription :: Route -> Maybe RouteDescription
_routeSummary :: Route -> Maybe RouteSummary
_routeMethod :: Method
_routePath :: Path
_routeParams :: Set Param
_routeRequestHeaders :: Set HeaderRep
_routeRequestBody :: Request
_routeResponse :: Responses
_routeAuths :: Set Auth
_routeDescription :: Maybe RouteDescription
_routeSummary :: Maybe RouteSummary
..} =
  [Text] -> Text
forall a. Monoid a => [a] -> a
mconcat
    [ Text
method
    , Text
" "
    , Text
path
    , Text
params
    ]
  where
    method :: Text
method = Method -> Text
TE.decodeUtf8 Method
_routeMethod
    path :: Text
path = Path -> Text
renderPath Path
_routePath
    params :: Text
params =
      if Set Param -> Bool
forall a. Set a -> Bool
forall (t :: * -> *) a. Foldable t => t a -> Bool
null Set Param
_routeParams
        then Text
""
        else Text
"?" Text -> Text -> Text
forall a. Semigroup a => a -> a -> a
<> Text -> [Text] -> Text
T.intercalate Text
"&" (Param -> Text
renderParam (Param -> Text) -> [Param] -> [Text]
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> Set Param -> [Param]
forall a. Set a -> [a]
Set.toList Set Param
_routeParams)

add :: (Ord a) => ASetter s t (Set.Set a) (Set.Set a) -> a -> s -> t
add :: forall a s t. Ord a => ASetter s t (Set a) (Set a) -> a -> s -> t
add ASetter s t (Set a) (Set a)
setter = ASetter s t (Set a) (Set a) -> (Set a -> Set a) -> s -> t
forall s t a b. ASetter s t a b -> (a -> b) -> s -> t
over ASetter s t (Set a) (Set a)
setter ((Set a -> Set a) -> s -> t)
-> (a -> Set a -> Set a) -> a -> s -> t
forall b c a. (b -> c) -> (a -> b) -> a -> c
. a -> Set a -> Set a
forall a. Ord a => a -> Set a -> Set a
Set.insert