Expressivity of Response

[noelwelsh]

A handler produces an IO[A]. The Response has the job of turning that into a HTTP response. There are three parts to consider:

• How structure in A corresponds to the HTTP response. For example, if A is Option[B], what do we do on the Some case and what do we do on the None case?
• How failures in the IO produced by the handler correspond to HTTP responses. The default would be to produce a 500, but we might want to instead default to a 404, or have structure in the exceptions correspond to structure in the HTTP response.
• How failures in the Response itself are handled. This is rare but can happen with the static file responses, for example.

So there need to be three families of combinators to handle three distinct cases. Need to think of the naming scheme to distinguish these three cases, and then the specific combinators.

[noelwelsh]

Here's a sketch of a design:

Goals:

1. All HTTP handling should be expressible in the Routes DSL, so it's 1) written in a standard way across projects and 2) isolated from the business logic.
2. Routes should be bidirectional, meaning that clients that call routes can be generated from the route description.

There will probably have to be a few backdoors to allow things that cannot be expressed by the DSL. These backdoors will probably not be bidirectional.

Some details:

• Of the cases above, "structure in A" is the most common case, so should have the most idiomatic API. So orElse and other common names should be used for this.

• Handing failures is uncommon. Some of these combinators will have to dispatch on exceptions, which may not be bidirectional.

The structure of HTTP requests and responses is fixed but we need different interpreters (one to handle requests, one to create clients) so a reified implementation is appropriate.