Re-engineer Verb

[phadej]

The idea is that

Instead of having

a :> b :> Verb c

we could have

a :> b :> Verb (c :< d)

which is transformed into something like

a -> b -> m (c, d)

Verb glues RHS and LHS together. This way we can

• Have checked exceptions (here "date" endpoint cannot error!)

  type MyAPI = "date" :> Verb (Full Day)
          :<|> "time" :> Capture TimeZone :> Verb (ServantErr :< Full ZonedTime)

• Get rid of {-# OVERLAPPING #-} instances, as in

  type NoContentAPI = "tick" :> Verb NoContent

  NoContent doesn't overlap Full a. Similarly we can have Stream a and
  Headers ... :< ....

---

The devil in the details how to fit this into Router and DelayedIO
framework we have, but I don't see why it's not possible.

The names of auxiliary class HasServer' and Full combinator are open to
bikesheding.

---

Comments?

[alpmestan]

A little note: Oleg and I have been discussing this over the past couple of days. We want to unify everything to avoid as much duplication as possible. The alternative to being able to "augment" the response information as done here would be to have all the possible "options" be type parameters to Verb. Here's what that would look like: https://gist.github.com/alpmestan/4ad03493cb6fe87e02b514418e9f7f02

So we really want @phadej's idea to work :) This would make many adhoc things non adhoc (stream would not have to be a totally separate hierarchy of response combinators -- cc @gbaz -- while responses that provide some headers would just augment the response with those instead of having the ugly Headers '[...] resp hack -- and it just goes on and on. We could similarly have "exhaustive endpoint descriptions" that describe the happy paths as well as the other ones, so that derived clients would basically be "more strongly typed" than they are now, because for non-happy paths you're stuck with a ServantError value. Redirects would also work pretty easily in this setting (they're just a combination of status code + "Location" header after all).

[erewok]

As a user of Servant and a drive-by commentator, I really like this proposal. (I'd probably bike shed the <: combinator, though.)

[alpmestan]

As a user of Servant and a drive-by commentator, I really like this proposal. (I'd probably bike shed the <: combinator, though.)

We want to hear from our users, maybe even more in this issue than usual. Feel free to suggest another operator and to illustrate with snippets of code you'd like to be able to write.

[erewok]

Thank you, @alpmestan. I should have probably kept my mouth shut until I could suggest something better. I think the reason I objected initially to <: is that my brain wants to coerce it into the opposite of :> whereas Verb ServantErr SomeReturnType looks like Either a b.

I also want to be clear that I think of this as bike-shedding: the overall improvement discussed here is excellent, in my opinion, so don't let me distract from that.

[alpmestan]

Well your point about your brain being disturbed by :< is a good one. In fact when @phadej initially suggested this approach, I think he used :+, which I interpreted to mean "we augment the response with more information".

[erewok]

One question:

Would it be possible to do something like Verb ('[HTML] ServantErr <: '[JSON] SomeReturnType)?

I would probably never do this, just wondering.

[alpmestan]

Being able to express different "response paths" is one of the important goals of this issue. response path == status code + headers + content types + type of the response body, here. Ideally we want full flexibility, so as to assume nothing about what users want to do. Because there's always someone who will want to do that very thing that you thought was irrelevant =) It makes sense to only return errors in JSON while making the "success" response available in JSON and HTML, in some apps, so it's not all that far fetched after all.

[erewok]

Well, in that case then, would it possible to have different code paths depending on, for instance, objects that get submitted? I imagine something like this:

type MyApi = "a" :> ReqBody '[JSON] SomeType :> BasicAuth "api-access" User :> Verb ('[HTML] MyAppErr401 <: '[JSON] MyAppErr404 <: '[JSON] SomeReturnType)

In other words, is it more like an HList than Either a b? Or is it more like Alternative, as in Error1 || SuccessOrError2 where SuccessOrError2 is Error2 || Success...

[alpmestan]

It's the sum-type equivalent of HList that would model things accurately here, indeed. We want to model the overall response of the endpoint as being one of several possibilities. It would be up to the endpoint's code, using some dedicated function(s), to return this or that kind of response depending on its inputs and anything else you want. But at least all the possible responses (including error responses) would be declared and all of this would be documented by servant-docs, clients would with your example give something like postSomeType :: SomeType -> User -> ClientM (Either SomeReturnType (Either MyAppErr401 MyAppErr404)), etc.

[sboosali]

the sum-type equivalent of HList

the vinyl records library has "co-records", which says that any value in some type can be any of a list of valid types. https://hackage.haskell.org/package/vinyl-0.6.0/docs/Data-Vinyl-CoRec.html

for example, CoRec Identity '[SomeReturnType, MyAppErr401, MyAppErr404].

with the type alias that implies that each value can have zero or more errors,

type Result es a = CoRec Identity (a ': es) 
type MyResult = Result SomeReturnType '[MyAppErr401, MyAppErr404] 

a few other record libraries have n-ary variants, like the sum-of-products package, I mention vinyl because it's lightweight and the one I'm familiar with. and, since vinyl wraps each field with the same functor, working with effects is easier, since you can say stuff like Rec IO '[Integer, String] and conveniently convert it to IO (Rec Identity '[Integer, String]) with utility functions like rtraverse.

(sorry if this isn't relevant, I only skimmed the discussion)

[arianvp]

I have a little bit of prior work of this in my bachelor project https://github.com/arianvp/servis/raw/master/paper/paper.pdf

See the chapter about Explicit status Codes

[arianvp]

Brainstormed about this with @rightfold yesterday. How about something like this?:

Lets ditch the idea of having a coproduct of return types

You have Verb '[200, 201, 401] GET Signallying that an endpoint can return any of these three status codes. and some type family

type family IsElem x xs :: Constraint where
  IsElem x '[] = TypeError (Text "No")
  IsElem x (x ': xs) = ()
  IsElem x (y ': xs) = IsElem x xs

Then the way for people implementing a server to set a status code would be something like:

setStatusCode :: IsElem x xs => Proxy x -> Server (Verb Get xs) ()

This disallows a server implementing the spec from setting a status code that is not in the spec.

You could go one step further and use something like IxMonad to actually force the user to set the status code of the handler.

[erewok]

I like the direction that suggestion is going in, but (unless I'm misreading) it loses the option to specify different return types and different encodings for each return path.

To put those back in would look like:

Get '[(200, JSON, NormalType), (403, HTML, AuthError), etc.]

Edit:

Now that, I think about it, the original suggestion also had more of a combinator feel, so I could presumably do something like this:

type MyAppAuthErrors = AuthRequired401 :< AuthFailure403
Verb (MyAppAuthErrors :< Full ZonedTime)