Just a reminder to change the website link to http://haskell-servant.github.io/tutorial/. The current one returns a 404 now.

From @jkarni on April 14, 2015 14:24

A lot of the instances share code which could be abstracted into separate functions now that the number of instances is getting pretty large.

Copied from original issue: haskell-servant/servant-server#40

Consider the routing table:

type Routes =
  ...
  :<|> ReqBody User :> Post UserID
  :<|> Capture "userid" UserID :> ReqBody User :> Put ()
  ...

The first route fails for Put requests, but the second will find that
the request body has already been parsed, and will complain about ""
not being a parseable json representation of User.

The work-around is simple:

type Routes =
  ...
  :<|> Capture "userid" UserID :> ReqBody User :> Put ()
  :<|> ReqBody User :> Post UserID
  ...

But I'm not sure it is that simple in all cases, or that obvious to
understand the situation once you've stumbled into this trap.

We have some (limited) resources to work on a solution, but we would
like to hear what you think first.

Servant is AWwesome, btw. Thanks for writing it! (:

A lot of the lower-level functionality that is used to construct HasServer and HasClient instances (at least) are strongly related (often functions come in inverses). For example, getting a header and adding a header, or reading a body and returning a body. Writing functions for both is tedious and error-prone - not just for library maintainers, but also for users who might want to write a new combinator. This seems like a good candidate for availing ourselves of the bidirectionalization literature.

Ideally, we should be able to write an instance of a single class, and HasServer and HasClient come for free from that instance.

Please add any thoughts or ideas as a comment.

From @seanhess on April 16, 2015 17:44

Servant is using the same name getsources for both GET /sources and GET /sources/:id. Is there some way it could figure out to call the second one getsource?

type Api = "sources" :> Get [Source] :<|> "sources" :> Capture "id" Text :> Get (Source)

Copied from original issue: haskell-servant/servant-jquery#13

this is a good starting point.

I'm using JWTs for auth. I'm implementing the logic by hand, which is fine for now, but it is slightly more convenient to have a Cookie combinator so I don't have to parse the header by hand.

Here's an example. It works exactly like Header, doesn't assume anything about authentication, it just provides a cookie value to your code.

https://gist.github.com/seanhess/f4cf71ea58e4483d8ee4

Is there a place for a low-level Cookie combinator like this? I think it could live side-by-side with higher-level authentication code. If so I'd be happy to clean this up and issue a PR.

Ping me when you have something to read over.

Looks like some of the fromByteString/toByteString and Text tests sometimes fail (empty input, and very very small floats).

Wouldn't make sense to make ServantError an instance of Control.Exception ?

From @christian-marie on April 4, 2015 2:32

serveDocumentation is mentioned in the documentation for the Raw combinator, but the link goes nowhere. Some commented-out code can be found in Docs.hs, but that code doesn't seem to work (as far as I remember, due to targeting an old WAI version). The ToHTML is function it provides is a little silly too.

This works well: https://hackage.haskell.org/package/markdown

If we don't want to wear the dependencies of that package in servant-docs, perhaps it's time for a servant-extras package? It'd be nice to ship batteries included and export a function for such a useful use case.

Alternately we can just fix the docs to provide an up-to-date example in-line with Raw (the fact that it links to non-existent documentation is the most confusing..

Copied from original issue: haskell-servant/servant-server#36

From @jkarni on January 30, 2015 4:52

https://github.com/haskell-servant/servant-server/pull/22 adds the ability to have some overriding custom errors in RouteMismatch. It'd be nice to generalize this to a more flexible priority system, as discussed in the PR.

Copied from original issue: haskell-servant/servant-server#23

From @jkarni on April 19, 2015 10:45

https://gist.github.com/rschatz/3c0ebd3cbf319c8061a6 shows how we could do this, though I think we could come up with a variation of HandlerT that takes a variable number of arguments (not just one) and thus make e.g. enter-ing from Either (Int,String) a not require a dummy () argument, and things that require multiple arguments not have to be curried.

This also would include the appropriate instances for common mtl/tranformers monads.

Copied from original issue: haskell-servant/servant-server#43

In particular, check left/right inverse relationships for the instances.

Hi everyone!

I thought I'd open up an issue to act as a container for authentication-related discussion. The issue will be considered closed when the first iteration of authentication has been implemented, at which point further improvements will have their own issues.

Authentication

We want to support various types of authentication for http servers and clients:

• Basic authentication
• Digest authentication
• Cookie-based authentication
• Token-based authentication (for OAuth 1.0, OAuth 2.0, Amazon HMAC-style, and any others)

Further, we want to account for the following (not a total list):

• maintain type-safety as per servant's design goals, but also allow for flexibility of various authentication methods and protocols (both standardized and not standardized).
• per-realm authentication
• per-endpoint or site-wide authentication

Out of scope for this iteration (but worth thinking about):

• role-based authentication

References:

• example cookie-based authenatication in servant.

I welcome any thoughts, ideas, or suggestions! I will be creating an auth branch to feature work and will let everyone know when that's done.

This is something we've discussed quite a bit before, but I just realized there's no ticket for it. We're stuck in this position where failures (from failWith) happen without trying matches further down the :> chain, resulting in some bad error messages (e.g. Bad Request instead of Method Not Found), hard to implement authentication ( #70 ), and inefficiency (it's better not to try decoding a body if there's no matching route anyhow).

This relates to #48. It also likely relates to improved routing.

Design issues

Do we want only the leaves of the tree (the methods) to be able to adjudicate error messages? Or do we want combinator instances to be allowed (but not required) to adjudicate between failure and continuation as well? I think the former would be sufficient to conform to the behaviour of most frameworks, but the second may also allow for room for interesting possibilities (what comes to mind immediately is auth-protecting a set of endpoints without even allowing non-authenticated clients to figure out what the endpoints being protected are - not a crucial feature, but also almost certainly not the only one).

Implementation ideas

?

From @soenkehahn on April 17, 2015 10:37

@phunehehe and I came up with a test case for this: https://github.com/haskell-servant/servant-server/compare/badRequest-bug?expand=1

I'm not sure this is a bug or wanted behaviour though.

Copied from original issue: haskell-servant/servant-server#42

From @davidsd on April 4, 2015 0:46

Occasionally, I need access the underlying WAI Request in a handler. It might make sense to include a combinator FullRequest that gives access to this information. For instance, if I need remoteAddr, then instead of making a specialized RemoteAddr combinator (and another combinator for everything else I need), I can just get it from the Request. One might argue that this slightly breaks servant's abstraction, but having it seems like a useful middle ground between a servant handler and a full WAI Application. A possible implementation is

data FullRequest

instance HasServer a => HasServer (FullRequest :> a) where
  type Server (FullRequest :> a) = Request -> Server a
  route Proxy subserver request respond =
      route (Proxy :: Proxy a) (subserver request) request respond

Copied from original issue: haskell-servant/servant-server#35

I am confused. The front page example has not be updated yet (I can PR if needed) ?

I cannot compile it with 0.0.4.

I am probably missing something because the haddock would be out of dated as well ....

Can we still do type MyApi = "books" :> Get [Book] together with type MyApi = "books" :> Get '[JSON] [Book] ?

From @paf31 on January 22, 2015 18:47

Would you accept a PR to add a table of contents to the generated markdown?

I'm using servant for a medium sized project, and it would be nice if I could group docs into categories based on the tree of routes. I expect I would probably include a change in this PR to introduce a tree as an intermediate data structure.

Maybe we could even structure the markdown as a tree using nested lists, so that related routes appear in the same list. This would also allow me (later) to add a documentation string to every branch (subroute) in the tree.

Thanks.

Copied from original issue: haskell-servant/servant-docs#8

At the time of writing the payload of the ReqBody a type needs to have an instance of FromJSON. As I want to perform possibly complex validation (with database accesses etc.) so no invalid data can be constructed. My validation function has the form MonadIO m => Value -> m (Either Object a). Is it possible to build such a combinator?

Hei, is there a reason that servant-docs is 0.4, while servant-server and servnat are 0.4.0?

0.4! I'm so excited... (-:

From @thsutton on February 20, 2015 0:14

Currently the (Int, String) values represent an HTTP status only (i.e. the status code and reason phrase used in the HTTP response status line). It would be nice if servant handlers could supply a body to send to the client when they use throwError.

Alternatively, we could allow handlers to specify an HTTP status code and reason when they succeed, as well as fail.

This would make it possible to implement APIs like, for example, OAuth2 which issues 400 Bad Request responses which include a JSON document describing the specific error.

Copied from original issue: haskell-servant/servant-server#27

From @AndrewRademacher on March 25, 2015 14:44

Has there been any consideration for writing servant docs output in API Blueprint format 1A?

Copied from original issue: haskell-servant/servant-docs#17

Citing from http://hydra.cryp.to/build/841883/nixlog/1/raw:

src/Servant/Utils/StaticFiles.hs:36:41:
    Couldn't match type ‘system-filepath-0.4.13.4:Filesystem.Path.Internal.FilePath’
                   with ‘[Char]’
    Expected type: FilePath
      Actual type: system-filepath-0.4.13.4:Filesystem.Path.Internal.FilePath
    In the first argument of ‘defaultFileServerSettings’, namely
      ‘(decodeString (documentRoot ++ "/"))’
    In the first argument of ‘staticApp’, namely
      ‘(defaultFileServerSettings (decodeString (documentRoot ++ "/")))’

As Andres noted, Canonicalize breaks modularity. It shouldn't be the default behaviour. Moreover, we should add something like Unit to prevent it from traversing into specific types.

Canonicalize should also be named something else (maybe Distribute) since now it's no longer the canonical form (there isn't one), and it really just applies one transformation.

From @rtrvrtg on January 22, 2015 1:2

I was wondering if there are any plans to change the way that servant-jquery's Javascript wrapper functions get rendered. Currently, they're all rendered like so:

function getsomething(onSuccess, onError) {

However, I was wondering if we could customise the generateJS method to support alternative rendering methods, such as functions as variables, the Javascript Module Pattern, CommonJS (which is the same as the current one but with the addition of an exports declaration), and Purescript-ready methods (which require a bunch of nested functions, one for each parameter).

The outcome is that we might be able to invoke, say,

generateJS' (ModulePatternOutput "Foo.MySubmodule") getSomethingAjaxReq

and get

Foo.MySubmodule.getsomething = function(onSuccess, onError){
...

I'm happy to undertake investigation into this and put together a PR for it, but I was wondering what your thoughts were on this.

Copied from original issue: haskell-servant/servant-jquery#7

The version on hackage still has it, but it seems to have been taken out of the repository in commit 5470297. Having the routes defined in a quasi quoter makes the route definition look much more natural, while still giving you the advantages of servant.

Also, it would be cool if the new incarnation of the quasi quoter could also generate the routing function and not just the routing type, by providing it the name of haskell functions to use. I would imagine you might be able to use that to automatically derive the types of the routes as well, which would be cool.

From @Fuuzetsu on March 25, 2015 0:16

I have an API here that I DELETE to and which returns 200 (so we get Left "HTTP DELETE request failed with status: 200 - OK", another issue) and some body which we can not process because unlike Put or Post, we can't parametrise the Delete.

Copied from original issue: haskell-servant/servant-client#19

Hi folks,

There's been a decent amount of work on all the servant libraries since the 0.2 release, among which is a clean and extensible support for content-types.

Most of the discussion so far about this resides here.

We're basically wondering what you, users and fellow servant developers, would prefer:

1. Keep Get, Post and friends as the names for the JSON-only endpoints, and have the combinators that take the list of supported content types be named with a final prime ('), as in Get', Post', etc. This would probably have the benefit of not breaking any existing code.
2. The reverse: have Get, Post and friends be the combinators that take a type level list of supported content types, and have Get', Post' etc be the simple JSON-only versions.
3. Some other naming convention..?

The discussion linked above contains "sample code" to give you an idea of what each would look like.

Please express your vote in a comment to this issue here, and within a week or two we'll see what naming convention is preferred and we'll just go with that one.

Thanks in advance folks.

The instances for HasClient match on the type-level cons eg.

instance HasClient (Delete (ct ': cts) ())

For empty responses, there isn't a need for any content types; in fact, ct and cts aren't used in the instance body.

It would be useful if servant supported custom HTTP error responses in addition to NotFound, WrongMethod, and InvalidBody.

I'd be happy to add such support, but would like confirmation this feature would actually be merged before spending the time. Is this a contribution you would accept in servant?

Now that the world is moving towards ExceptT (cf. the errors package), we probably should too.

I am trying to implement authentication and got stuck with errors that
I think could more sustainably be fixed in the 'HasServer' class.
This is a recount of what happened, with a concrete question at the
end.

Relevant code is here: liqd/thentos@93016c1 (branch: liqd/thentos#81).

Very similar things are going on over at #70, but thentos writes the
credentials into the custom handler monad instead of passing them to
the handlers as an extra argument. My mind is a bit boggled right
now, but I think this is what's going on:

1. At the point in the route where the ThentosAuth link is found, a
   "partial server" in the custom handler monad with result type ()
   is constructed: Just look up the credentials in the request, write
   them into the custom monad's state, and return ().
2. This partial server cannot be executed here, because we are still
   collecting the handler's function arguments from the routes. Actions
   can be constructed half-way through the route, but they can't be
   executed before the entire route has been parsed successfully.
3. So instead, I push the action down the routes to where I can
   sequence it into the route's "proper" action. (@jkarni has showed me
   how to implement an earlier version of this trick.)

Now as you can see in module Thentos.Backend.Api.Auth if you
uncomment the code in lines 51, 54, HasServer wants sub-routes to
live in the standard servant monad.

I guess my question is, what would happen if the 'HasServer' class
looked like this?:

class HasServer layout (m :: * -> *) where
  type ServerT layout :: *
  route :: Proxy layout -> ServerT layout -> RoutingApplication

Also, is there a work-around?

Thanks! (-:

From @jkarni on April 15, 2015 15:17

BaseUrl should either be just be an argument to client, or the first argument to every function. (The former is, I think, preferable).

Copied from original issue: haskell-servant/servant-client#24

Add packages for HTML. They should only be a handful of lines each.

From @jkarni on January 30, 2015 4:52

https://github.com/haskell-servant/servant-server/pull/22 adds the ability to have some overriding custom errors in RouteMismatch. It'd be nice to generalize this to a more flexible priority system, as discussed in the PR.

Copied from original issue: haskell-servant/servant-server#23

ReqBody is great, it captures the whole POST body and make it available in a type. I wonder if it's intended that the same thing isn't available with GET. It would be nice if I can have a GET param that is a URL encoded JSON string converted into a type just like that. I would have used POST, but that has a vague effect on caching. Any thoughts?

From @jkarni on February 20, 2015 17:24

Copied from original issue: haskell-servant/servant-docs#13

From @tvh on March 13, 2015 6:14

Sometimes it is necessary to inspect more about a response than just the body. Some services will return important information in the header. It would be nice to have a mechanism to do this.

One option would be to change the instance for Raw, such that it returns the Full response instead of just parts of it. This would also be in symmetry to the server, where you have full access to wai.

Copied from original issue: haskell-servant/servant-client#16

From @davidsd on April 4, 2015 18:4

Might it be simpler/safer to return a Status instead of (Int, String) in the case of a handler error? That way, we could re-use already-defined statuses like ok200 or forbidden403. If we want custom error messages, we could just use mkStatus on our own.

Copied from original issue: haskell-servant/servant-server#37

Hello,
when I try to build a root that expects a simple String in the request body (rather than a Haskell data instance) like so:

type Api =
...
:<|> "item" :> "create" :> ReqBody (String) :> Post ()

I always get the rather generic error response

Invalid JSON in request body: Failed reading: satisfy

This is regardless of what I tried:

"asdf"
asdf
\"asdf\"

It never made it through the servant Json parsing to my actual handler (where "asdf" would likely cause another runtime error).

Am I missing something?

(The idea behind the String in the request body is, btw, to use digestive functors for validation. If anyone else has input on how to combine servant with digestive-functors, I'm all ears!)

I want to corrrect a typo in http://haskell-servant.github.io/tutorial/api-type.html. Is there a way to do that in form of a pull request? I searched the gh-pages branch and master but couldn't find anything.

Hello,

I can't figure out based on the example code, how to use servant with persistent. Instead of returning something like Greet (s. example), I have an IO action (because I access a database). Has someone done something like that? Is there an example? All help is appreciated!

There are a few problems with the example on hackage for servant-docs.

1. Missing Control.Lens import
2. MimeRender has no method toByteString. It should be mimeRender.
3. No instance for (HasLink Delete), it is missing some parameters.

Currently it is impossible to specify in any way which headers are returned. It would be nice if there was a way to specify this. Related issues: https://github.com/haskell-servant/servant-server/issues/25 https://github.com/haskell-servant/servant-client/issues/16.

As far as I can tell a ResponseHeader X a similar to Header should be implementable by collecting them in a type-level list on the way. I am however unsure about what the response type should be.