The free-http package

[maintain]

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

Versions0.1.0.1, 0.1.0.2, 0.1.1.0, 0.1.1.1, 0.1.1.2, 0.1.1.3, 0.2.0, 0.2.0
Dependenciesbase (>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]
LicenseMIT
AuthorAaron Levin
Maintainervilevin@gmail.com
CategoryNetwork
Home pagehttps://github.com/aaronlevin/free-http
Source repositoryhead: git clone git://github.com/aaronlevin/free-http.git
UploadedWed Dec 30 23:51:56 UTC 2015 by aaronlevin

Modules

[Index]

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for free-http-0.2.0

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)
    
  3. 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)
    
  4. Write a program in the 'FreeHttp MyClient m a' free monad.

  5. Import an interpreter, such as 'HttpClient'

    import Network.HTTP.Free.Client.HttpClient
    
  6. 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.