Servant.Foreign

Generate the necessary data for codegen as a list, each Req describing one endpoint from your API type.

Full description of an endpoint in your API, generated by listFromAPI. It should give you all the information needed to generate foreign language bindings.

Every field containing ftype will use the foreign type mapping specified via HasForeignType (see its docstring on how to set that up).

See https://docs.servant.dev/en/stable/tutorial/ApiType.html for accessible documentation of the possible content of an endpoint.

HasForeignType maps Haskell types with types in the target language of your backend. For example, let's say you're implementing a backend to some language X, and you want a Text representation of each input/output type mentioned in the API:

-- First you need to create a dummy type to parametrize your
-- instances.
data LangX

-- Otherwise you define instances for the types you need
instance HasForeignType LangX Text Int where
   typeFor _ _ _ = "intX"

-- Or for example in case of lists
instance HasForeignType LangX Text a => HasForeignType LangX Text [a] where
   typeFor lang ftype _ = "listX of " <> typeFor lang ftype (Proxy :: Proxy a)

Finally to generate list of information about all the endpoints for an API you create a function of a form:

getEndpoints :: (HasForeign LangX Text api, GenerateList Text (Foreign Text api))
             => Proxy api -> [Req Text]
getEndpoints api = listFromAPI (Proxy :: Proxy LangX) (Proxy :: Proxy Text) api

-- If language __X__ is dynamically typed then you can use
-- a predefined NoTypes parameter with the NoContent output type:

getEndpoints :: (HasForeign NoTypes NoContent api, GenerateList Text (Foreign NoContent api))
             => Proxy api -> [Req NoContent]
getEndpoints api = listFromAPI (Proxy :: Proxy NoTypes) (Proxy :: Proxy NoContent) api

Utility class used by listFromAPI which computes the data needed to generate a function for each endpoint and hands it all back in a list.

Implementation of the Servant framework types.

Relevant instances: Everything containing HasForeignType.

The language definition without any foreign types. It can be used for dynamic languages which do not do type annotations.

Full endpoint url, with all captures and parameters

A part of the Url’s path.

Whether a segment is a Cap.

Crashing Arg extraction from segment, TODO: remove

Url Query argument.

Urls can contain query arguments, which is a list of key-value pairs. In a typical url, query arguments look like this:

?foo=bar&alist[]=el1&alist[]=el2&aflag

Each pair can be

• ?foo=bar: a plain key-val pair, either optional or required (QueryParam)

• ?aflag: a flag (no value, implicitly Bool with default false if it’s missing) (QueryFlag)

• ?alist[]=el1&alist[]=el2: list of values (QueryParams)

_queryArgType will be set accordingly.

For the plain key-val pairs (QueryParam), _queryArgName’s ftype will be wrapped in a Maybe if the argument is optional.

Type of a QueryArg.

Maps a name to the foreign type that belongs to the annotated value.

Used for header args, query args, and capture args.

Canonical name of the endpoint, can be used to generate a function name.

You can use the functions in Servant.Foreign.Inflections, like camelCase to transform to Text.

See documentation of _reqBodyContentType

See documentation of Arg

A type for responses without content-body.

Union of two APIs, first takes precedence in case of overlap.

Example:

>>> :{type MyApi = "books" :> Get '[JSON] [Book] -- GET /books       :<|> "books" :> ReqBody '[JSON] Book :> Post '[JSON] () -- POST /books:}

An empty API: one which serves nothing. Morally speaking, this should be the unit of :<|>. Implementors of interpretations of API types should treat EmptyAPI as close to the unit as possible.

Capture which can be modified. For example with Description.

The contained API (second argument) can be found under ("/" ++ path) (path being the first argument).

Example:

>>> -- GET /hello/world>>> -- returning a JSON encoded World value>>> type MyApi = "hello" :> "world" :> Get '[JSON] World

Capture all remaining values from the request path under a certain type a.

Example:

>>> -- GET /src/*>>> type MyAPI = "src" :> CaptureAll "segments" Text :> Get '[JSON] SourceFile

Verb is a general type for representing HTTP verbs (a.k.a. methods). For convenience, type synonyms for each verb with a 200 response code are provided, but you are free to define your own:

>>> type Post204 contentTypes a = Verb 'POST 204 contentTypes a

NoContentVerb is a specific type to represent NoContent responses. It does not require either a list of content types (because there's no content) or a status code (because it should always be 204).

A Stream endpoint for a given method emits a stream of encoded values at a given Content-Type, delimited by a framing strategy. Type synonyms are provided for standard methods.

QueryParam which can be Required, Lenient, or modified otherwise.

Lookup the values associated to the sym query string parameter and try to extract it as a value of type [a]. This is typically meant to support query string parameters of the form param[]=val1&param[]=val2 and so on. Note that servant doesn't actually require the []s and will fetch the values just fine with param=val1&param=val2, too.

Example:

>>> -- /books?authors[]=<author1>&authors[]=<author2>&...>>> type MyApi = "books" :> QueryParams "authors" Text :> Get '[JSON] [Book]

Lookup a potentially value-less query string parameter with boolean semantics. If the param sym is there without any value, or if it's there with value "true" or "1", it's interpreted as True. Otherwise, it's interpreted as False.

Example:

>>> -- /books?published>>> type MyApi = "books" :> QueryFlag "published" :> Get '[JSON] [Book]

Document the URI fragment in API. Useful in combination with Link.

Example:

>>> -- /post#TRACKING>>> type MyApi = "post" :> Fragment Text :> Get '[JSON] Tracking

Endpoint for plugging in your own Wai Applications.

The given Application will get the request as received by the server, potentially with a modified (stripped) pathInfo if the Application is being routed with :>.

In addition to just letting you plug in your existing WAI Applications, this can also be used with functions from Servant.Server.StaticFiles to serve static files stored in a particular directory on your filesystem

Note: ReqBody' is always Required.

Provides access to the host or IP address from which the HTTP request was sent.

Was this request made over an SSL connection?

Note that this value will not tell you if the client originally made this request over SSL, but rather whether the current connection is SSL. The distinction lies with reverse proxies. In many cases, the client will connect to a load balancer over SSL, but connect to the WAI handler without SSL. In such a case, the handlers would get NotSecure, but from a user perspective, there is a secure connection.

A persistent store for values of arbitrary types.

This variant is the simplest and creates keys in the IO monad. See the module Data.Vault.ST if you want to use it with the ST monad instead.

WithNamedContext names a specific tagged context to use for the combinators in the API. (See also in servant-server, Servant.Server.Context.) For example:

type UseNamedContextAPI = WithNamedContext "myContext" '[String] (
    ReqBody '[JSON] Int :> Get '[JSON] Int)

Both the ReqBody and Get combinators will use the WithNamedContext with type tag "myContext" as their context.

Contexts are only relevant for servant-server.

For more information, see the tutorial.

HTTP Version.

Note that the Show instance is intended merely for debugging.

Add a short summary for (part of) API.

Example:

>>> type MyApi = Summary "Get book by ISBN." :> "books" :> Capture "isbn" Text :> Get '[JSON] Book

Add more verbose description for (part of) API.

Example:

>>> :{type MyApi = Description "This comment is visible in multiple Servant interpretations \ \and can be really long if necessary. \ \Haskell multiline String support is not perfect \ \but it's still very readable.":> Get '[JSON] Book:}

Combinator for embedding a record of named routes into a Servant API type.

Strictly parsed argument. Not wrapped.

Extract the given header's value as a value of type a. I.e. header sent by client, parsed by server.

Example:

>>> newtype Referer = Referer Text deriving (Eq, Show)>>> >>>            -- GET /view-my-referer>>> type MyApi = "view-my-referer" :> Header "from" Referer :> Get '[JSON] Referer

HTTP standard method (as defined by RFC 2616, and PATCH which is defined by RFC 5789).

Combinator for Basic Access Authentication.

• IMPORTANT*: Only use Basic Auth over HTTPS! Credentials are not hashed or encrypted. Note also that because the same credentials are sent on every request, Basic Auth is not as secure as some alternatives. Further, the implementation in servant-server does not protect against some types of timing attacks.

In Basic Auth, username and password are base64-encoded and transmitted via the Authorization header. Handshakes are not required, making it relatively efficient.

A simple datatype to hold data required to decorate a request

Capture a value from the request path under a certain type a.

Example:

>>> -- GET /books/:isbn>>> type MyApi = "books" :> Capture "isbn" Text :> Get '[JSON] Book

Instances of Accept represent mimetypes. They are used for matching against the Accept HTTP header of the request, and for setting the Content-Type header of the response

Example:

>>> import Network.HTTP.Media ((//), (/:))>>> data HTML>>> :{instance Accept HTML where   contentType _ = "text" // "html" /: ("charset", "utf-8"):}

Instantiate this class to register a way of serializing a type based on the Accept header.

Example:

data MyContentType

instance Accept MyContentType where
   contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8")

instance Show a => MimeRender MyContentType a where
   mimeRender _ val = pack ("This is MINE! " ++ show val)

type MyAPI = "path" :> Get '[MyContentType] Int

Instantiate this class to register a way of deserializing a type based on the request's Content-Type header.

>>> import Network.HTTP.Media hiding (Accept)>>> import qualified Data.ByteString.Lazy.Char8 as BSC>>> data MyContentType = MyContentType String

>>> :{instance Accept MyContentType where   contentType _ = "example" // "prs.me.mine" /: ("charset", "utf-8"):}

>>> :{instance Read a => MimeUnrender MyContentType a where   mimeUnrender _ bs = case BSC.take 12 bs of     "MyContentType" -> return . read . BSC.unpack $ BSC.drop 12 bs     _ -> Left "didn't start with the magic incantation":}

>>> type MyAPI = "path" :> ReqBody '[MyContentType] Int :> Get '[JSON] Int

A generalized Authentication combinator. Use this if you have a non-standard authentication technique.

NOTE: THIS API IS EXPERIMENTAL AND SUBJECT TO CHANGE.

A class with a type family that applies an appropriate type family to the api parameter. For example, AsApi will leave api untouched, while AsServerT m will produce ServerT api m.

A type that specifies that an API record contains an API definition. Only useful at type-level.

A constraint alias, for work with mode and routes.

Turns a generic product type into a tree of :<|> combinators.

Inverse of toServant.

This can be used to turn generated values such as client functions into records.

You may need to provide a type signature for the output type (your record type).

Get a Proxy of an API type.

See ToServant, but at value-level.

Leniently parsed argument, i.e. parsing never fail. Wrapped in Either Text.

Optional argument. Wrapped in Maybe.

Required argument. Not wrapped.

Lookup the value associated to the sym query string parameter and try to extract it as a value of type a.

Example:

>>> -- /books?author=<author name>>>> type MyApi = "books" :> QueryParam "author" Text :> Get '[JSON] [Book]

Extract an deep object from a query string.

Example:

>>> -- /books?filter[author][name]=<author name>&filter[year]=<book year>>>> type MyApi = "books" :> DeepQuery "filter" BookQuery :> Get '[JSON] [Book]

Extract the whole query string from a request. This is useful for query strings containing dynamic parameter names. For query strings with static parameter names, QueryParam is more suited.

Example:

>>> -- /books?author=<author name>&year=<book year>>>> type MyApi = "books" :> QueryString :> Get '[JSON] [Book]

Variant of Raw that lets you access the underlying monadic context to process the request.

Extract the request body as a value of type a.

Example:

>>> -- POST /books>>> type MyApi = "books" :> ReqBody '[JSON] Book :> Post '[JSON] Book