free-http: An HTTP Client based on Free Monads.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

`free-http` is an http-client based on Free Monads. `free-http` exposes a Free Monad to express standard http verbs as well as several backends to interpet programs written in the free monad using various http clients (currently: a pure client, an `http-client`-backed client, and a random client). Please see the ReadMe for usage.


[Skip to Readme]

Properties

Versions 0.1.0.1, 0.1.0.2, 0.1.1.0, 0.1.1.1, 0.1.1.2, 0.1.1.3, 0.1.1.3, 0.2.0
Change log None available
Dependencies base (>4.6 && <4.9), bytestring (>=0.10.0.0), free (>=4.0), http-client (>=0.4.0), http-types (>=0.8.0), mtl (>=2.0.0.0), QuickCheck (>=2.7), text (>=1.0.0.0), time (>=1.4.0.1), transformers (>=0.4.0.0) [details]
License MIT
Author Aaron Levin
Maintainer vilevin@gmail.com
Category Network
Home page https://github.com/aaronlevin/free-http
Source repo head: git clone git://github.com/aaronlevin/free-http.git
Uploaded by aaronlevin at 2015-07-15T03:53:32Z

Modules

[Index]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for free-http-0.1.1.3

[back to package description]

Free Your Client... and Your Requests Will Follow

free-http is an http-client based on Free Monads. free-http exposes a Free Monad to express standard http verbs as well as several backends to interpet programs written in the free monad using various http clients (currently: a pure client, an http-client-backed client, and a random client).

See here for an example.

To use free-http, simply:

  1. Import Network.HTTP.Client.Free to use the library.
  2. Choose your base request type by defining your own instance of the RequestType type family or importing one from an interpreter. E.g.
data MyClient
type instance RequestType MyClient = Request

or

import Network.HTTP.Free.Client.HttpClient (HttpClient)
  1. Choose your base response type by defining your own instance of the ResponseTYpe type family or importing one from an interpreter. E.g.
type instance ResponseType MyClient = Response ByteString

or

import Network.HTTP.Free.Client.HttpClient (HttpClient)
  1. Write a program in the 'FreeHttp MyClient m a' free monad.
  2. Import an interpreter, such as 'HttpClient'
import Network.HTTP.Free.Client.HttpClient
  1. Run your program against the interpreter:
runHttp (myProgram :: FreeHttp MyClient IO String)

Design Choices

RequestType and ResponseType

Haskell is fortunate to have several very well-designed http clients: http-client, wreq, http-conduit, pipes-http, etc. Unfortunately, a few of those clients support several different Request and Response types. To keep free-http flexible, we use two type families defined as:

type family RequestType client  :: *
type family ResponseType client :: *

Our HttpF functor is thus defined as:

data HttpF client a = HttpF StdMethod (RequestType client) (ResponseType client -> a)
                    deriving Functor

This allows our HttpF functor to be agnostic of the foundational request and response type, while allowing interpreter authors to specify the concrete types they need for their http client libraries (e.g. Request in the case of http-client). A consequence of this is that free-http clients (you) need to specify, at some point, the foundation you're using. This can be done in two ways:

  1. You can define your own foundation (see above).
  2. You can import one from an interpreter.

To specify your request and response foundation, use replace the client type in HttpF client a or FreeHttp client m a to the type signalling your foundation. For example, the http-client, pure, and arbitrary interpreters use HttpClient, PureClient, and ArbitraryClient respectively.