The free-http package

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]

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). 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)


[Skip to ReadMe]

Properties

Versions0.1.0.0, 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.2.0
Change logNone available
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
UploadedTue Jul 14 03:17:15 UTC 2015 by aaronlevin

Modules

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for free-http-0.1.0.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.