This commit introduces a new type-level combinator, `WithRoutingHeader`.
It modifies the behaviour of the following sub-API, such that all endpoint
of said API return an additional routing header in their response.
A routing header is a header that specifies which endpoint the
incoming request was routed to.
Endpoint are designated by their path, in which `Capture'` and
`CaptureAll` combinators are replaced by a capture hint.
This header can be used by downstream middlewares to gather
information about individual endpoints, since in most cases
a routing header uniquely identifies a single endpoint.
Example:
```haskell
type MyApi =
WithRoutingHeader :> "by-id" :> Capture "id" Int :> Get '[JSON] Foo
-- GET /by-id/1234 will return a response with the following header:
-- ("Servant-Routed-Path", "/by-id/<id::Int>")
```
To achieve this, two refactorings were necessary:
* Introduce a type `RouterEnv env` to encapsulate the `env` type
(as in `Router env a`), which contains a tuple-encoded list of url
pieces parsed from the incoming request.
This type makes it possible to pass more information throughout the
routing process, and the computation of the `Delayed env c` associated
with each request.
* Introduce a new kind of router, which only modifies the RouterEnv, and
doesn't affect the routing process otherwise.
`EnvRouter (RouterEnv env -> RouterEnv env) (Router' env a)`
This new router is used when encountering the `WithRoutingHeader`
combinator in an API, to notify the endpoints of the sub-API that they
must produce a routing header (this behaviour is disabled by default).
Close#1513.
GHC 9.2 needs explicit kind signature here, I don't really understand
why.
This kind signature is correct and not too restritive, because `HasLink`
is technically defined `class HasLink endpoint` which means that it is
infered as `k -> Constraint`. In the instance signature, we have
`HasLink ((arr :: a -> b) :> sub)`, so here the `k` is the same kind as
the one of `:>` which is not polykinded.
As the head method isn't allowed to contain any response body, no
general Head Verb is added. (This may easily lead to wrong usages...)
(https://httpwg.org/specs/rfc7231.html#HEAD)
* bumped cabal-version field
Cabal supports two types of licenses, native and SPDX, which can be seen here hackage.haskell.org/package/Cabal-3.6.2.0/docs/Distribution-Types-PackageDescription.html#v:licenseRaw
Several packages use BSD-3-Clause as a license, in conjonction with cabal-version: >=1.10 which cabal parses as Right (UnknownLicense "BSD-3").
If I change teh cabal-version to cabal-version: 2.2 , cabal correctly identifdies the license License (ELicense (ELicenseId BSD_3_Clause)).
* changed license from cabal to spdx format
aka BSD3 -> BSD-3-Clause: next cabal may deprecate the old format
Move `HasServer (NamedRoutes routes)` instance
The instance has been moved to `Servant.Server.Internal`, as the
instances for other combinators. It is necessary so that the instance
can be re-exported from `Servant.Server` without circular imports.
Otherwise, users have to import `Servant.Server.Generic` manually ;
forgetting to do so will produce confusing error messages about the
missing instance.
Move `HasClient (NamedRoutes routes)` instance
Moved so that the instance is made available when importing
`Servant.Client`, avoiding possibly confusing errors when
`Servant.Client.Generic` isn't imported.
Allows users to directly embed APIs defined as records of routes into
vanilla Servant API types.
E.g.:
```haskell
data MyRoutes mode = MyRoutes
{ version :: mode :- Get '[JSON] Int
, …
}
type API = "prefix" :> NamedRoutes MyRoutes :<|> …
```
APIs can thus be recursively defined directly with Generic record types.
* use Capture Description if available
* update golden/comprehensive.md
This is technically a breaking change, because if a Capture has both a
Description and a ToCapture instance, the Description now takes
precedence. Since this Description wasn't doing anything before, I am
guessing that most projects currently only use Description to describe
their endpoints and not their Captures, and thus that few people will be
affected by this breaking change.
* test the "no ToCapture instance" case
The case in which there is both a Description and a ToCapture instance
seems like a corner case. The more interesting cases are the one in
which there is a Description but no ToCapture instance, and the case in
which there is a ToCapture instance but no description.
We do not need the `ToJSON` instance for `WithStatus`
it would cause an overlap between:
```
ToJSON a => MimeRender JSON a
```
and
```
forall cty a. MimeRendercty a => MimeRender cty (WithStatus a)
```
and Servant just needs the `MimeRender` typeclass for it to work
* Add some more docs to the UVerb module
* cookbook/uverb: Change GHC versions
CI was complaining some version did not exist. Trying to bump
Also added 8.10.1
* doc/cookbook/uverb: Remove 8.4.4 from tested versions
CI was running into a cabal bug for some reason
