Network.Goggles

Dependencies

The examples require the following declarations (which in turn mean that the req and bytestring libraries are imported by the user's project). You will also need the OverloadedStrings language extension :

import qualified Data.ByteString.Lazy as LB
import Network.HTTP.Req (responseBody)
import Network.Goggles

Examples

This first example, listBucket, reads content from a cloud storage bucket:

1. it loads the GCP credentials (username and RSA key),
2. retrieves a token via OAuth2,
3. performs a single call to the Cloud Storage API endpoint that lists the metadata related to the contents of a storage bucket, and
4. returns the raw API data to the user as a lazy ByteString.

listBucket :: IO LB.ByteString
listBucket = do
  let usr = "...iam.gserviceaccount.com"
      bucket = "<my-gcs-bucket>"
      key = "<rsa_key>"
  pvtkey <- parseRSAPrivateKey key
  let creds = GCPServiceAccount pvtkey usr Nothing ""
  hdl <- createHandle creds scopesDefault
  responseBody <$> evalWebApiIO hdl (listObjects bucket)

Running WebApiM programs

createHandle :: HasCredentials c => Credentials c -> Options c -> IO (Handle c)

Create a Handle with an empty token

evalWebApiIO :: Handle c -> WebApiM c a -> IO a

Evaluate a WebApiM action, given a Handle.

NB : Assumes all exceptions are handled by throwM

Lifting IO programs into WebApiM

liftWebApiIO :: HasCredentials c => IO a -> WebApiM c a

Lift an `IO a` action into the WebApiM monad, and catch synchronous exceptions, while rethrowing the asynchronous ones to IO

Types

newtype WebApiM c a

The main type of the library. It can easily be re-used in libraries that interface with more than one cloud API provider because its type parameter c lets us be declare distinct behaviours for each.

Constructors

WebApiM

Fields

• runWebApiM :: ReaderT (Handle c) IO a

Instances

Monad (WebApiM c)

Methods

(>>=) :: WebApiM c a -> (a -> WebApiM c b) -> WebApiM c b

(>>) :: WebApiM c a -> WebApiM c b -> WebApiM c b

return :: a -> WebApiM c a

fail :: String -> WebApiM c a

Functor (WebApiM c)

Methods

fmap :: (a -> b) -> WebApiM c a -> WebApiM c b

(<$) :: a -> WebApiM c b -> WebApiM c a

Applicative (WebApiM c)

Methods

pure :: a -> WebApiM c a

(<*>) :: WebApiM c (a -> b) -> WebApiM c a -> WebApiM c b

liftA2 :: (a -> b -> c) -> WebApiM c a -> WebApiM c b -> WebApiM c c

(*>) :: WebApiM c a -> WebApiM c b -> WebApiM c b

(<*) :: WebApiM c a -> WebApiM c b -> WebApiM c a

HasCredentials c => Alternative (WebApiM c)

Methods

empty :: WebApiM c a

(<|>) :: WebApiM c a -> WebApiM c a -> WebApiM c a

some :: WebApiM c a -> WebApiM c [a]

many :: WebApiM c a -> WebApiM c [a]

HasCredentials c => MonadIO (WebApiM c)

Methods

liftIO :: IO a -> WebApiM c a

HasCredentials c => MonadRandom (WebApiM c)

the whole point of this parametrization is to have a distinct MonadHttp for each API provider/DSP

instance HasCredentials c => MonadHttp (Boo c) where handleHttpException = throwM

Methods

getRandomBytes :: ByteArray byteArray => Int -> WebApiM c byteArray

HasCredentials c => MonadThrow (WebApiM c)

Methods

throwM :: Exception e => e -> WebApiM c a

HasCredentials c => MonadCatch (WebApiM c)

Methods

catch :: Exception e => WebApiM c a -> (e -> WebApiM c a) -> WebApiM c a

HasCredentials c => MonadReader (Handle c) (WebApiM c)

Methods

ask :: WebApiM c (Handle c)

local :: (Handle c -> Handle c) -> WebApiM c a -> WebApiM c a

reader :: (Handle c -> a) -> WebApiM c a

Authentication

class HasCredentials c where

This class

Minimal complete definition

tokenFetch

Associated Types

type Credentials c

type Options c

type TokenContent c

Methods

tokenFetch :: WebApiM c (Token c)

data Token c

An authentication Token with an expiry date

Constructors

Token

Fields

• tToken :: TokenContent c
• tTime :: UTCTime

data Handle c

A Handle contains all information necessary to communicating with a cloud API provider:

• Authentication credentials (e.g. username/password)
• Authentication token (used to authenticate every API call)
• Options (e.g. GCP authentication scopes)

Constructors

Handle

Fields

• credentials :: Credentials c
• token :: TVar (Maybe (Token c))
• options :: Options c

Instances

HasCredentials c => MonadReader (Handle c) (WebApiM c)

Methods

ask :: WebApiM c (Handle c)

local :: (Handle c -> Handle c) -> WebApiM c a -> WebApiM c a

reader :: (Handle c -> a) -> WebApiM c a

Private key

parseRSAPrivateKey :: MonadThrow m => Text -> m PrivateKey

Parse a chunk of text into an RSA private key. For Google Cloud Platform , this is the private key associated with the user's "service account" (for server-to-server API use)

https://console.cloud.google.com/apis/credentials

Note: do not supply the RSA header and footer or any newlines (they will be inserted by this function).

Exceptions

data KeyException

Authentication key exceptions

Constructors

NoSecretFound !String

NoParsePK !String

NoRSAKey !String

Instances

Eq KeyException

Methods

(==) :: KeyException -> KeyException -> Bool

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

Show KeyException

Methods

showsPrec :: Int -> KeyException -> ShowS

show :: KeyException -> String

showList :: [KeyException] -> ShowS

Exception KeyException

Methods

toException :: KeyException -> SomeException

fromException :: SomeException -> Maybe KeyException

displayException :: KeyException -> String

data JWTError

Errors associated with JWT-encoded token request

Constructors

BadExpirationTime !String

CryptoSignError !String

Instances

Show JWTError

Methods

showsPrec :: Int -> JWTError -> ShowS

show :: JWTError -> String

showList :: [JWTError] -> ShowS

Exception JWTError

Methods

toException :: JWTError -> SomeException

fromException :: SomeException -> Maybe JWTError

displayException :: JWTError -> String

data TokenExchangeException

Token exchange exceptions

Constructors

NotFound !String

Something went wrong with the request, token not found

APICredentialsNotFound !String

Instances

Show TokenExchangeException

Methods

showsPrec :: Int -> TokenExchangeException -> ShowS

show :: TokenExchangeException -> String

showList :: [TokenExchangeException] -> ShowS

Exception TokenExchangeException

Methods

toException :: TokenExchangeException -> SomeException

fromException :: SomeException -> Maybe TokenExchangeException

displayException :: TokenExchangeException -> String

data CloudException

Cloud API exception

Constructors

UnknownError !String

IOError !String

TimeoutError !String

JsonDecodeError !String

XMLDecodeError !String

Instances

Show CloudException

Methods

showsPrec :: Int -> CloudException -> ShowS

show :: CloudException -> String

showList :: [CloudException] -> ShowS

Exception CloudException

Methods

toException :: CloudException -> SomeException

fromException :: SomeException -> Maybe CloudException

displayException :: CloudException -> String