wreq-0.5.0.1: An easy-to-use HTTP client library.

Copyright | (c) 2014 Bryan O'Sullivan
License | BSD-style
Maintainer | bos@serpentine.com
Stability | experimental
Portability | GHC
Safe Haskell | None
Language | Haskell98

Network.Wreq.Session

Contents

- Session creation
  - More control-oriented session creation
- HTTP verbs
  - Configurable verbs
- Extending a session

Description

The functions in this module use a `Session` to handle the following common needs:

- TCP connection reuse. This is important for performance when multiple requests go to a single server, particularly if TLS is being used.
- Transparent cookie management. Any cookies set by the server persist from one request to the next. (Bypass this overhead using `withAPISession`.)

This module is designed to be used alongside the Network.Wreq module. Typical usage will look like this:

    import Network.Wreq
    import qualified Network.Wreq.Session as Sess

    main = Sess.withSession $ \sess ->
      Sess.get sess "http://httpbin.org/get"

We create a `Session` using `withSession`, then pass the session to subsequent functions. When talking to a REST-like service that does not use cookies, it is more efficient to use `withAPISession`.

Note the use of qualified import statements in the examples above, so that we can refer unambiguously to the `Session`-specific implementation of HTTP GET.

Synopsis

- data Session
- withSession :: (Session -> IO a) -> IO a
- withAPISession :: (Session -> IO a) -> IO a
- withSessionWith :: ManagerSettings -> (Session -> IO a) -> IO a
- withSessionControl :: Maybe CookieJar -> ManagerSettings -> (Session -> IO a) -> IO a
- get :: Session -> String -> IO (Response ByteString)
- post :: Postable a => Session -> String -> a -> IO (Response ByteString)
- head_ :: Session -> String -> IO (Response ())
- options :: Session -> String -> IO (Response ())
- put :: Putable a => Session -> String -> a -> IO (Response ByteString)
- delete :: Session -> String -> IO (Response ByteString)
- customMethod :: String -> Session -> String -> IO (Response ByteString)
- getWith :: Options -> Session -> String -> IO (Response ByteString)
- postWith :: Postable a => Options -> Session -> String -> a -> IO (Response ByteString)
- headWith :: Options -> Session -> String -> IO (Response ())
- optionsWith :: Options -> Session -> String -> IO (Response ())
- putWith :: Putable a => Options -> Session -> String -> a -> IO (Response ByteString)
- deleteWith :: Options -> Session -> String -> IO (Response ByteString)
- customMethodWith :: String -> Options -> Session -> String -> IO (Response ByteString)
- seshRun :: Lens' Session (Session -> Run Body -> Run Body)

# Session creation

data Session Source #

A session that spans multiple requests. This is responsible for cookie management and TCP connection reuse.

Instances

Show Session Source # |
Methods showsPrec :: Int -> Session -> ShowS # show :: Session -> String # showList :: [Session] -> ShowS #

withSession :: (Session -> IO a) -> IO a Source #

Create a `Session`, passing it to the given function. The `Session` will no longer be valid after that function returns.

This session manages cookies and uses default session manager configuration.

withAPISession :: (Session -> IO a) -> IO a Source #

Create a session.

This uses the default session manager settings, but does not manage cookies. It is intended for use with REST-like HTTP-based APIs, which typically do not use cookies.

## More control-oriented session creation

withSessionWith :: ManagerSettings -> (Session -> IO a) -> IO a Source #

Deprecated: Use withSessionControl instead.

Create a session, using the given manager settings. This session manages cookies.

withSessionControl Source #

Arguments

:: Maybe CookieJar | If `Nothing` is specified, no cookie management will be performed.
-> ManagerSettings |
-> (Session -> IO a) |
-> IO a |

Create a session, using the given cookie jar and manager settings.

# HTTP verbs

get :: Session -> String -> IO (Response ByteString) Source #

`Session`-specific version of `get`.

post :: Postable a => Session -> String -> a -> IO (Response ByteString) Source #

`Session`-specific version of `post`.

head_ :: Session -> String -> IO (Response ()) Source #

`Session`-specific version of `head_`.

options :: Session -> String -> IO (Response ()) Source #

`Session`-specific version of `options`.

put :: Putable a => Session -> String -> a -> IO (Response ByteString) Source #

`Session`-specific version of `put`.

delete :: Session -> String -> IO (Response ByteString) Source #

`Session`-specific version of `delete`.

customMethod :: String -> Session -> String -> IO (Response ByteString) Source #

`Session`-specific version of `customMethod`.

## Configurable verbs

getWith :: Options -> Session -> String -> IO (Response ByteString) Source #

`Session`-specific version of `getWith`.

postWith :: Postable a => Options -> Session -> String -> a -> IO (Response ByteString) Source #

`Session`-specific version of `postWith`.

headWith :: Options -> Session -> String -> IO (Response ()) Source #

`Session`-specific version of `headWith`.

optionsWith :: Options -> Session -> String -> IO (Response ()) Source #

`Session`-specific version of `optionsWith`.

putWith :: Putable a => Options -> Session -> String -> a -> IO (Response ByteString) Source #

`Session`-specific version of `putWith`.

deleteWith :: Options -> Session -> String -> IO (Response ByteString) Source #

`Session`-specific version of `deleteWith`.

customMethodWith :: String -> Options -> Session -> String -> IO (Response ByteString) Source #

`Session`-specific version of `customMethodWith`.

# Extending a session

seshRun :: Lens' Session (Session -> Run Body -> Run Body) Source #