When adding extra info using using docsWith, the responses vanished from
the output. This was due to combineAction being left-biased, and
docsWith combining the extra info with the enpoint (in that
order). Flipping combineAction solves this.
This change makes an attempt of abstracting out some of the common
functionality found in the handlers for the different request methods.
There's still a bit of code duplication between the cases for headers
and no headers and empty responses. But it's a significant relative
improvement already.
The main `Server.Internal` module was getting a bit large for my taste.
It now contains just the instances. All the administrative utilities
are in their own dedicated modules.
This change adapt the auth combinator example to the new router code.
In general, the server interpretation of user-written combinators will
be affected by the new routing code.
The change here also introduces a change in functionality: previously,
wrong authentication triggered a "hard failure", whereas we now trigger
a "soft failure", which is recoverable. For the simple example, this
does not make a lot of difference.
In general, I think having a soft failure is the right option to take
here, although we want a more general story about the relative
priorities of different error codes.
Due to the delayed treatment of checks during the server interpretation,
we now have the ability to produce "better" error codes for certain
APIs. This change introduces test cases for some of these situations and
their new, desired results. These tests would mostly fail with the old
approach to routing.
Instead of directly interpreting a server as a `RoutingApplication`,
this change introduces the concept of a `Router`, which is a datatype
with several constructors.
In particular, the type of the `route` function changes from
route :: Proxy layout -> Server layout -> RoutingApplication
to
route :: Proxy layout -> IO (RouteResult (Server layout)) -> Router
Most important in practice is the case of the `StaticRouter` constructor
in `Router`. For choices between statically known paths, we can now use
a lookup table to dispatch requests rather than trying each request
individually.
This brings down routing complexity of a common case from
O(n) to O(log n).
Another important change is that the handler that is passed down by
`route` is no longer of type `Server layout`, but of type
`IO (RouteResult (Server layout))`. This means that API constructs
can "delay" checks and failure. For example, `ReqBody` does not have
to fetch the request body and feed it to the handler immediately; it
can instead record these actions in the handler that is passed down.
The code will only be executed at a leaf / endpoint of the API.
This is desired behaviour: We prefer to save work by doing all matching
on static path components first. Furthermore, we get better error codes
by doing so.
