Polysemy.Http

Documentation

A basic Polysemy effect abstracting HTTP requests:

import Polysemy (resourceToIO, runM)
import qualified Polysemy.Http as Http
import Polysemy.Http (interpretHttpNative, interpretLogStdout)

main :: IO ()
main = do
  result <- runM $
    resourceToIO $
    interpretLogStdout $
    interpretHttpNative $
    Http.request (Http.get "hackage.haskell.org" "package/polysemy-http")
  print result

data Http c :: Effect

The main effect for HTTP requests. The parameter c determines the representation of raw chunks.

Instances

type DefiningModule Http

Defined in Polysemy.Http.Data.Http

type DefiningModule Http = "Polysemy.Http.Data.Http"

request :: forall c r. Member (Http c) r => Request -> Sem r (Either HttpError (Response LByteString))

Synchronously run an HTTP request and return the response.

stream :: forall c r a. Member (Http c) r => Request -> (Response c -> Sem r (Either HttpError a)) -> Sem r (Either HttpError a)

Open a connection without consuming data and pass the response to a handler for custom transmission. The intended purpose is to allow streaming transfers.

Interpreters

interpretHttpNative :: Members [Embed IO, Log, Resource] r => InterpreterFor (Http BodyReader) r

Interpret Http BodyReader using the native Client implementation. BodyReader is an alias for IO ByteString, it is how http-client represents chunks. This uses the default interpreter for Manager.

interpretHttpStrict :: Members [Embed IO, Error HttpError] r => [Response LByteString] -> [ByteString] -> InterpreterFor (Http Int) r

In-Memory interpreter for Http. The first parameter is a list of Response. When a request is made, one response is popped of the head and returned. If the list is exhausted, a 502 response is returned.

Request and Response

data Request

HTTP request parameters, used by Http.

Constructors

Request

Fields

• _method :: Method
• _host :: Host
• _port :: Maybe Port
• _tls :: Tls
• _path :: Path
• _headers :: [(HeaderName, HeaderValue)]
• _query :: [(QueryKey, Maybe QueryValue)]
• _body :: Body

Instances

Eq Request

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Request -> Request -> Bool

(/=) :: Request -> Request -> Bool

Show Request

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Request -> ShowS

show :: Request -> String

showList :: [Request] -> ShowS

HasRequest Request

Defined in Polysemy.Http.Data.Request

Methods

request :: Lens' Request Request

body :: Lens' Request Body

headers :: Lens' Request [(HeaderName, HeaderValue)]

host :: Lens' Request Host

method :: Lens' Request Method

path :: Lens' Request Path

port :: Lens' Request (Maybe Port)

query :: Lens' Request [(QueryKey, Maybe QueryValue)]

tls :: Lens' Request Tls

newtype Body

Request body, using LByteString because it is what encode produces.

Constructors

Body LByteString

Instances

Eq Body

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Body -> Body -> Bool

(/=) :: Body -> Body -> Bool

Show Body

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Body -> ShowS

show :: Body -> String

showList :: [Body] -> ShowS

IsString Body

Defined in Polysemy.Http.Data.Request

Methods

fromString :: String -> Body

newtype QueryValue

The value of a query parameter.

Constructors

QueryValue Text

Instances

Eq QueryValue

Defined in Polysemy.Http.Data.Request

Methods

(==) :: QueryValue -> QueryValue -> Bool

(/=) :: QueryValue -> QueryValue -> Bool

Show QueryValue

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> QueryValue -> ShowS

show :: QueryValue -> String

showList :: [QueryValue] -> ShowS

IsString QueryValue

Defined in Polysemy.Http.Data.Request

Methods

fromString :: String -> QueryValue

newtype QueryKey

The key of a query parameter.

Constructors

QueryKey Text

Instances

Eq QueryKey

Defined in Polysemy.Http.Data.Request

Methods

(==) :: QueryKey -> QueryKey -> Bool

(/=) :: QueryKey -> QueryKey -> Bool

Show QueryKey

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> QueryKey -> ShowS

show :: QueryKey -> String

showList :: [QueryKey] -> ShowS

IsString QueryKey

Defined in Polysemy.Http.Data.Request

Methods

fromString :: String -> QueryKey

newtype Path

Rrequest path.

Constructors

Path Text

Instances

Eq Path

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Path -> Path -> Bool

(/=) :: Path -> Path -> Bool

Show Path

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Path -> ShowS

show :: Path -> String

showList :: [Path] -> ShowS

IsString Path

Defined in Polysemy.Http.Data.Request

Methods

fromString :: String -> Path

newtype Tls

A flag that indicates whether a request should use TLS.

Constructors

Tls Bool

Instances

Eq Tls

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Tls -> Tls -> Bool

(/=) :: Tls -> Tls -> Bool

Show Tls

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Tls -> ShowS

show :: Tls -> String

showList :: [Tls] -> ShowS

newtype Port

Request port.

Constructors

Port Int

Instances

Eq Port

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Port -> Port -> Bool

(/=) :: Port -> Port -> Bool

Show Port

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Port -> ShowS

show :: Port -> String

showList :: [Port] -> ShowS

newtype Host

Request host name.

Constructors

Host Text

Instances

Eq Host

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Host -> Host -> Bool

(/=) :: Host -> Host -> Bool

Show Host

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Host -> ShowS

show :: Host -> String

showList :: [Host] -> ShowS

IsString Host

Defined in Polysemy.Http.Data.Request

Methods

fromString :: String -> Host

data Method

All standard HTTP methods, mirroring those from Types, plus a constructor for arbitrary strings.

Constructors

Get

Post

Put

Delete

Head

Trace

Connect

Options

Patch

Custom Text

Instances

Eq Method

Defined in Polysemy.Http.Data.Request

Methods

(==) :: Method -> Method -> Bool

(/=) :: Method -> Method -> Bool

Show Method

Defined in Polysemy.Http.Data.Request

Methods

showsPrec :: Int -> Method -> ShowS

show :: Method -> String

showList :: [Method] -> ShowS

IsString Method

Defined in Polysemy.Http.Data.Request

Methods

fromString :: String -> Method

data Response b

The response produced by Http.

Constructors

Response

Fields

• status :: Status

  Uses the type from HTTP for convenience

• body :: b

  parameterized in the body to allow different interpreters to use other representations.

• headers :: [Header]

  Does not use the type from HTTP because it is an alias.

Instances

Eq b => Eq (Response b)

Defined in Polysemy.Http.Data.Response

Methods

(==) :: Response b -> Response b -> Bool

(/=) :: Response b -> Response b -> Bool

Show b => Show (Response b)

Defined in Polysemy.Http.Data.Response

Methods

showsPrec :: Int -> Response b -> ShowS

show :: Response b -> String

showList :: [Response b] -> ShowS

Show (Response BodyReader)

Defined in Polysemy.Http.Data.Response

Methods

showsPrec :: Int -> Response BodyReader -> ShowS

show :: Response BodyReader -> String

showList :: [Response BodyReader] -> ShowS

pattern Server :: Status -> b -> [Header] -> Response b

Match on a response with a 5xx status.

pattern Client :: Status -> b -> [Header] -> Response b

Match on a response with a 4xx status.

pattern Redirect :: Status -> b -> [Header] -> Response b

Match on a response with a 3xx status.

pattern Success :: Status -> b -> [Header] -> Response b

Match on a response with a 2xx status.

pattern Info :: Status -> b -> [Header] -> Response b

Match on a response with a 1xx status.

data Header

An HTTP header.

Constructors

Header HeaderName HeaderValue

Instances

Eq Header

Defined in Polysemy.Http.Data.Header

Methods

(==) :: Header -> Header -> Bool

(/=) :: Header -> Header -> Bool

Show Header

Defined in Polysemy.Http.Data.Header

Methods

showsPrec :: Int -> Header -> ShowS

show :: Header -> String

showList :: [Header] -> ShowS

newtype HeaderValue

The value of a header.

Constructors

HeaderValue Text

Instances

Eq HeaderValue

Defined in Polysemy.Http.Data.Header

Methods

(==) :: HeaderValue -> HeaderValue -> Bool

(/=) :: HeaderValue -> HeaderValue -> Bool

Show HeaderValue

Defined in Polysemy.Http.Data.Header

Methods

showsPrec :: Int -> HeaderValue -> ShowS

show :: HeaderValue -> String

showList :: [HeaderValue] -> ShowS

IsString HeaderValue

Defined in Polysemy.Http.Data.Header

Methods

fromString :: String -> HeaderValue

newtype HeaderName

The name of a header.

Constructors

HeaderName Text

Instances

Eq HeaderName

Defined in Polysemy.Http.Data.Header

Methods

(==) :: HeaderName -> HeaderName -> Bool

(/=) :: HeaderName -> HeaderName -> Bool

Show HeaderName

Defined in Polysemy.Http.Data.Header

Methods

showsPrec :: Int -> HeaderName -> ShowS

show :: HeaderName -> String

showList :: [HeaderName] -> ShowS

IsString HeaderName

Defined in Polysemy.Http.Data.Header

Methods

fromString :: String -> HeaderName

get :: Host -> Path -> Request

post :: Host -> Path -> Body -> Request

put :: Host -> Path -> Body -> Request

delete :: Host -> Path -> Request

getUrl :: Text -> Either Text Request

postUrl :: Body -> Text -> Either Text Request

putUrl :: Body -> Text -> Either Text Request

deleteUrl :: Text -> Either Text Request

Streaming

streamResponse :: Members [Http c, Error HttpError, Resource] r => Request -> (forall x. StreamEvent o c h x -> Sem r x) -> Sem r o

Initiate a request and stream the response, calling process after connecting, for every chunk, after closing the connection, and for the return value. StreamEvent is used to indicate the stage of the request cycle.

handle ::
  StreamEvent Double (IO ByteString) Int a ->
  Sem r a
handle = \case
  StreamEvent.Acquire (Response status body headers) ->
    pure 1
  StreamEvent.Chunk handle (StreamChunk c) ->
    pure ()
  StreamEvent.Result (Response status body headers) handle ->
    pure 5.5
  StreamEvent.Release handle ->
    pure ()

>>> runInterpreters $ streamResponse (Http.get "host.com" "path/to/file") handle
5.5

data StreamEvent r c h a where

Control algebra for streaming requests. r is the final return type of the stream handler, after the request is processed to completion. c is the raw chunk data type h is the handle type that identifies the active request. It is entirely controlled by the consumer and may be empty.

Constructors

Acquire :: Response c -> StreamEvent r c h h

Used when calling the handler after the request has been initiated, but no data has been read.

Chunk :: h -> StreamChunk -> StreamEvent r c h ()

Used when calling the handler for each received chunk.

Result :: Response c -> h -> StreamEvent r c h r

Used when calling the handler after the request has finished transferring. It should return the final result.

Release :: h -> StreamEvent r c h ()

Used to finalize the transfer, e.g. for resource cleanup.

Entity

data EntityDecode d :: Effect

Abstraction of json decoding, potentially usable for other content types like xml.

Instances

type DefiningModule EntityDecode

Defined in Polysemy.Http.Data.Entity

type DefiningModule EntityDecode = "Polysemy.Http.Data.Entity"

decode :: forall d r. Member (EntityDecode d) r => LByteString -> Sem r (Either EntityError d)

Lazily decode a LByteString to a value of type d

decodeStrict :: forall d r. Member (EntityDecode d) r => ByteString -> Sem r (Either EntityError d)

Strictly decode a ByteString to a value of type d

data EntityEncode d :: Effect

Abstraction of json encoding, potentially usable for other content types like xml.

Instances

type DefiningModule EntityEncode

Defined in Polysemy.Http.Data.Entity

type DefiningModule EntityEncode = "Polysemy.Http.Data.Entity"

encode :: forall d r. Member (EntityEncode d) r => d -> Sem r LByteString

Lazily encode a value of type d to a LByteString

encodeStrict :: forall d r. Member (EntityEncode d) r => d -> Sem r ByteString

Strictly encode a value of type d to a ByteString

type family Entities es r :: Constraint where ...

Convenience constraint for requiring multiple entity effects, to be used like Members.

foo :: Entities [Encode Int, Decode Double] r => Sem r ()

Equations

Entities '[] r = ()

Entities (Encode d ': ds) r = (Member (EntityEncode d) r, Entities ds r)

Entities (Decode d ': ds) r = (Member (EntityDecode d) r, Entities ds r)

data Decode a

Marker type to be used with Entities

data Encode a

Marker type to be used with Entities

type family Decoders ds r :: Constraint where ...

Convenience constraint for requiring multiple decoders.

foo :: Decoders [Int, Double] r => Sem r ()

Equations

Decoders '[] r = ()

Decoders (d ': ds) r = (Member (EntityDecode d) r, Decoders ds r)

type family Encoders es r :: Constraint where ...

Convenience constraint for requiring multiple encoders.

foo :: Encoders [Int, Double] r => Sem r ()

Equations

Encoders '[] r = ()

Encoders (d ': ds) r = (Member (EntityEncode d) r, Encoders ds r)

data EntityError

Generic error type for decoders.

Constructors

EntityError Text Text

Instances

Eq EntityError

Defined in Polysemy.Http.Data.Entity

Methods

(==) :: EntityError -> EntityError -> Bool

(/=) :: EntityError -> EntityError -> Bool

Show EntityError

Defined in Polysemy.Http.Data.Entity

Methods

showsPrec :: Int -> EntityError -> ShowS

show :: EntityError -> String

showList :: [EntityError] -> ShowS

interpretEntityEncodeAeson :: ToJSON d => Sem (EntityEncode d ': r) a -> Sem r a

Interpreter for EntityEncode that uses Aeson.

interpretEntityDecodeAeson :: FromJSON d => Sem (EntityDecode d ': r) a -> Sem r a

Interpreter for EntityDecode that uses Aeson.

Utilities

Connection Pool

data Manager :: Effect

This effect abstracts the creation of a Manager in order to allow pool sharing in a flexible way.

Instances

type DefiningModule Manager

Defined in Polysemy.Http.Data.Manager

type DefiningModule Manager = "Polysemy.Http.Data.Manager"

Logging

data Log :: Effect

An effect that wraps Log for less boilerplate. Constructors are manual because HasCallStack is always in scope.

interpretLogNull :: InterpreterFor Log r

No-op interpreter for Log

interpretLogStdout :: Member (Embed IO) r => Sem (Log ': r) a -> Sem r a

Default interpreter for Log that uses Log to print to stdout