Safe Haskell	None
Language	Haskell2010

GitHub.Request

Contents

A convenient execution of requests
Types
Request execution in IO
Helpers
- Preview
SSL

Description

This module provides data types and helper methods, which makes possible to build alternative API request intepreters in addition to provided IO functions.

Simple example using operational package. See samples/Operational/Operational.hs

type GithubMonad a = Program (GH.Request 'False) a

-- | Intepret GithubMonad value into IO
runMonad :: Manager -> GH.Auth -> GithubMonad a -> ExceptT GH.Error IO a
runMonad mgr auth m = case view m of
   Return a   -> return a
   req :>>= k -> do
       b <- ExceptT $ GH.executeRequestWithMgr mgr auth req
       runMonad mgr auth (k b)

-- | Lift request into Monad
githubRequest :: GH.Request 'False a -> GithubMonad a
githubRequest = singleton

Synopsis

github :: (AuthMethod am, GitHubRW req res) => am -> req -> res
github' :: GitHubRO req res => req -> res
class GitHubRW req res | req -> res
class GitHubRO req res | req -> res
type Request = GenRequest ('MtJSON :: MediaType Type)
data GenRequest (mt :: MediaType Type) (rw :: RW) a where
- Query :: forall (mt :: MediaType Type) (rw :: RW) a. Paths -> QueryString -> GenRequest mt rw a
- PagedQuery :: forall a (t :: Type -> Type) b (mt :: MediaType Type) (rw :: RW). (a ~ t b, Foldable t, Semigroup a) => Paths -> QueryString -> FetchCount -> GenRequest mt rw a
- Command :: forall (mt :: MediaType Type) a. CommandMethod -> Paths -> ByteString -> GenRequest mt 'RW a
data CommandMethod
- = Post
- | Patch
- | Put
- | Delete
toMethod :: CommandMethod -> Method
type Paths = [Text]
type QueryString = [(ByteString, Maybe ByteString)]
executeRequest :: forall am (mt :: MediaType Type) a (rw :: RW). (AuthMethod am, ParseResponse mt a) => am -> GenRequest mt rw a -> IO (Either Error a)
executeRequestWithMgr :: forall am (mt :: MediaType Type) a (rw :: RW). (AuthMethod am, ParseResponse mt a) => Manager -> am -> GenRequest mt rw a -> IO (Either Error a)
executeRequestWithMgrAndRes :: forall am (mt :: MediaType Type) a (rw :: RW). (AuthMethod am, ParseResponse mt a) => Manager -> am -> GenRequest mt rw a -> IO (Either Error (Response a))
executeRequest' :: forall (mt :: MediaType Type) a. ParseResponse mt a => GenRequest mt 'RO a -> IO (Either Error a)
executeRequestWithMgr' :: forall (mt :: MediaType Type) a. ParseResponse mt a => Manager -> GenRequest mt 'RO a -> IO (Either Error a)
executeRequestMaybe :: forall am (mt :: MediaType Type) a. (AuthMethod am, ParseResponse mt a) => Maybe am -> GenRequest mt 'RO a -> IO (Either Error a)
unsafeDropAuthRequirements :: forall (mt :: MediaType Type) (rw' :: RW) a (rw :: RW). GenRequest mt rw' a -> GenRequest mt rw a
class Accept (mt :: MediaType Type) where
- contentType :: Tagged mt ByteString
- modifyRequest :: Tagged mt (Request -> Request)
class Accept mt => ParseResponse (mt :: MediaType Type) a where
- parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged mt (m a)
makeHttpRequest :: forall am (mt :: MediaType Type) (rw :: RW) a m. (AuthMethod am, MonadThrow m, Accept mt) => Maybe am -> GenRequest mt rw a -> m Request
parseStatus :: MonadError Error m => StatusMap a -> Status -> m a
parsePageLinks :: Response a -> PageLinks
type StatusMap a = [(Int, a)]
getNextUrl :: Response a -> Maybe URI
performPagedRequest :: forall a m (mt :: MediaType Type). (ParseResponse mt a, Semigroup a, MonadCatch m, MonadError Error m) => (Request -> m (Response ByteString)) -> (a -> Bool) -> Request -> Tagged mt (m (Response a))
parseResponseJSON :: (FromJSON a, MonadError Error m) => Response ByteString -> m a
class PreviewAccept p where
- previewContentType :: Tagged ('MtPreview p) ByteString
- previewModifyRequest :: Tagged ('MtPreview p) (Request -> Request)
class PreviewAccept p => PreviewParseResponse p a where
- previewParseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtPreview p) (m a)
withOpenSSL :: IO a -> IO a
tlsManagerSettings :: ManagerSettings

A convenient execution of requests

github :: (AuthMethod am, GitHubRW req res) => am -> req -> res Source #

A convenience function to turn functions returning Request rw x, into functions returning IO (Either Error x).

>>> :t \auth -> github auth userInfoForR
\auth -> github auth userInfoForR
  :: AuthMethod am => am -> Name User -> IO (Either Error User)

>>> :t github pullRequestsForR
\auth -> github auth pullRequestsForR
  :: AuthMethod am =>
     am
     -> Name Owner
     -> Name Repo
     -> PullRequestMod
     -> FetchCount
     -> IO (Either Error (Data.Vector.Vector SimplePullRequest))

github' :: GitHubRO req res => req -> res Source #

Like github' but for RO i.e. read-only requests. Note that GitHub has low request limit for non-authenticated requests.

>>> :t github' userInfoForR
github' userInfoForR :: Name User -> IO (Either Error User)

class GitHubRW req res | req -> res Source #

A type-class implementing github.

Minimal complete definition

githubImpl

Instances

Instances details

GitHubRW req res => GitHubRW (a -> req) (a -> res) Source #
Instance details Defined in GitHub.Request Methods githubImpl :: AuthMethod am => am -> (a -> req) -> a -> res
(ParseResponse mt req, res ~ Either Error req) => GitHubRW (GenRequest mt rw req) (IO res) Source #
Instance details Defined in GitHub.Request Methods githubImpl :: AuthMethod am => am -> GenRequest mt rw req -> IO res

class GitHubRO req res | req -> res Source #

A type-class implementing github'.

Minimal complete definition

githubImpl'

Instances

Instances details

GitHubRO req res => GitHubRO (a -> req) (a -> res) Source #
Instance details Defined in GitHub.Request Methods githubImpl' :: (a -> req) -> a -> res
(ParseResponse mt req, res ~ Either Error req, rw ~ 'RO) => GitHubRO (GenRequest mt rw req) (IO res) Source #
Instance details Defined in GitHub.Request Methods githubImpl' :: GenRequest mt rw req -> IO res

Types

type Request = GenRequest ('MtJSON :: MediaType Type) Source #

Most requests ask for JSON.

data GenRequest (mt :: MediaType Type) (rw :: RW) a where Source #

Github request data type.

rw describes whether authentication is required. It's required for non-GET requests.
mt describes the media type, i.e. how the response should be interpreted.
a is the result type

Note: Request is not Functor on purpose.

Constructors

Query :: forall (mt :: MediaType Type) (rw :: RW) a. Paths -> QueryString -> GenRequest mt rw a
PagedQuery :: forall a (t :: Type -> Type) b (mt :: MediaType Type) (rw :: RW). (a ~ t b, Foldable t, Semigroup a) => Paths -> QueryString -> FetchCount -> GenRequest mt rw a
Command	Command
Fields :: forall (mt :: MediaType Type) a. CommandMethod command -> Paths path -> ByteString body -> GenRequest mt 'RW a

Instances

Instances details

Eq (GenRequest rw mt a) Source #
Instance details Defined in GitHub.Data.Request Methods (==) :: GenRequest rw mt a -> GenRequest rw mt a -> Bool # (/=) :: GenRequest rw mt a -> GenRequest rw mt a -> Bool #
Ord (GenRequest rw mt a) Source #
Instance details Defined in GitHub.Data.Request Methods compare :: GenRequest rw mt a -> GenRequest rw mt a -> Ordering # (<) :: GenRequest rw mt a -> GenRequest rw mt a -> Bool # (<=) :: GenRequest rw mt a -> GenRequest rw mt a -> Bool # (>) :: GenRequest rw mt a -> GenRequest rw mt a -> Bool # (>=) :: GenRequest rw mt a -> GenRequest rw mt a -> Bool # max :: GenRequest rw mt a -> GenRequest rw mt a -> GenRequest rw mt a # min :: GenRequest rw mt a -> GenRequest rw mt a -> GenRequest rw mt a #
Show (GenRequest rw mt a) Source #
Instance details Defined in GitHub.Data.Request Methods showsPrec :: Int -> GenRequest rw mt a -> ShowS # show :: GenRequest rw mt a -> String # showList :: [GenRequest rw mt a] -> ShowS #
Hashable (GenRequest rw mt a) Source #
Instance details Defined in GitHub.Data.Request Methods hashWithSalt :: Int -> GenRequest rw mt a -> Int # hash :: GenRequest rw mt a -> Int #
(ParseResponse mt req, res ~ Either Error req, rw ~ 'RO) => GitHubRO (GenRequest mt rw req) (IO res) Source #
Instance details Defined in GitHub.Request Methods githubImpl' :: GenRequest mt rw req -> IO res
(ParseResponse mt req, res ~ Either Error req) => GitHubRW (GenRequest mt rw req) (IO res) Source #
Instance details Defined in GitHub.Request Methods githubImpl :: AuthMethod am => am -> GenRequest mt rw req -> IO res

data CommandMethod Source #

Http method of requests with body.

Constructors

Post
Patch
Put
Delete

Instances

Instances details

Eq CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

(==) :: CommandMethod -> CommandMethod -> Bool #

(/=) :: CommandMethod -> CommandMethod -> Bool #

Ord CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

compare :: CommandMethod -> CommandMethod -> Ordering #

(<) :: CommandMethod -> CommandMethod -> Bool #

(<=) :: CommandMethod -> CommandMethod -> Bool #

(>) :: CommandMethod -> CommandMethod -> Bool #

(>=) :: CommandMethod -> CommandMethod -> Bool #

max :: CommandMethod -> CommandMethod -> CommandMethod #

min :: CommandMethod -> CommandMethod -> CommandMethod #

Data CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> CommandMethod -> c CommandMethod #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c CommandMethod #

toConstr :: CommandMethod -> Constr #

dataTypeOf :: CommandMethod -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c CommandMethod) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c CommandMethod) #

gmapT :: (forall b. Data b => b -> b) -> CommandMethod -> CommandMethod #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> CommandMethod -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> CommandMethod -> r #

gmapQ :: (forall d. Data d => d -> u) -> CommandMethod -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> CommandMethod -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> CommandMethod -> m CommandMethod #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> CommandMethod -> m CommandMethod #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> CommandMethod -> m CommandMethod #

Bounded CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

minBound :: CommandMethod #

maxBound :: CommandMethod #

Enum CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

succ :: CommandMethod -> CommandMethod #

pred :: CommandMethod -> CommandMethod #

toEnum :: Int -> CommandMethod #

fromEnum :: CommandMethod -> Int #

enumFrom :: CommandMethod -> [CommandMethod] #

enumFromThen :: CommandMethod -> CommandMethod -> [CommandMethod] #

enumFromTo :: CommandMethod -> CommandMethod -> [CommandMethod] #

enumFromThenTo :: CommandMethod -> CommandMethod -> CommandMethod -> [CommandMethod] #

Generic CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Associated Types

type Rep CommandMethod

Instance details

Defined in GitHub.Data.Request

type Rep CommandMethod = D1 ('MetaData "CommandMethod" "GitHub.Data.Request" "github-0.30.0.1-inplace" 'False) ((C1 ('MetaCons "Post" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Patch" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "Put" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Delete" 'PrefixI 'False) (U1 :: Type -> Type)))

Methods

from :: CommandMethod -> Rep CommandMethod x #

to :: Rep CommandMethod x -> CommandMethod #

Read CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

readsPrec :: Int -> ReadS CommandMethod #

readList :: ReadS [CommandMethod] #

readPrec :: ReadPrec CommandMethod #

readListPrec :: ReadPrec [CommandMethod] #

Show CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

showsPrec :: Int -> CommandMethod -> ShowS #

show :: CommandMethod -> String #

showList :: [CommandMethod] -> ShowS #

Hashable CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

Methods

hashWithSalt :: Int -> CommandMethod -> Int #

hash :: CommandMethod -> Int #

type Rep CommandMethod Source #

Instance details

Defined in GitHub.Data.Request

type Rep CommandMethod = D1 ('MetaData "CommandMethod" "GitHub.Data.Request" "github-0.30.0.1-inplace" 'False) ((C1 ('MetaCons "Post" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Patch" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "Put" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Delete" 'PrefixI 'False) (U1 :: Type -> Type)))

toMethod :: CommandMethod -> Method Source #

type Paths = [Text] Source #

type QueryString = [(ByteString, Maybe ByteString)] Source #

Request query string

Request execution in IO

executeRequest :: forall am (mt :: MediaType Type) a (rw :: RW). (AuthMethod am, ParseResponse mt a) => am -> GenRequest mt rw a -> IO (Either Error a) Source #

Execute Request in IO

executeRequestWithMgr :: forall am (mt :: MediaType Type) a (rw :: RW). (AuthMethod am, ParseResponse mt a) => Manager -> am -> GenRequest mt rw a -> IO (Either Error a) Source #

Like executeRequest but with provided Manager.

executeRequestWithMgrAndRes :: forall am (mt :: MediaType Type) a (rw :: RW). (AuthMethod am, ParseResponse mt a) => Manager -> am -> GenRequest mt rw a -> IO (Either Error (Response a)) Source #

Execute request and return the last received Response.

Since: 0.24

executeRequest' :: forall (mt :: MediaType Type) a. ParseResponse mt a => GenRequest mt 'RO a -> IO (Either Error a) Source #

Like executeRequest but without authentication.

executeRequestWithMgr' :: forall (mt :: MediaType Type) a. ParseResponse mt a => Manager -> GenRequest mt 'RO a -> IO (Either Error a) Source #

Like executeRequestWithMgr but without authentication.

executeRequestMaybe :: forall am (mt :: MediaType Type) a. (AuthMethod am, ParseResponse mt a) => Maybe am -> GenRequest mt 'RO a -> IO (Either Error a) Source #

Helper for picking between executeRequest and executeRequest'.

The use is discouraged.

unsafeDropAuthRequirements :: forall (mt :: MediaType Type) (rw' :: RW) a (rw :: RW). GenRequest mt rw' a -> GenRequest mt rw a Source #

Partial function to drop authentication need.

Helpers

class Accept (mt :: MediaType Type) where Source #

Minimal complete definition

Nothing

Methods

contentType :: Tagged mt ByteString Source #

modifyRequest :: Tagged mt (Request -> Request) Source #

Instances

Instances details

Accept ('MtDiff :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtDiff :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtDiff :: MediaType Type) (Request -> Request) Source #
Accept ('MtJSON :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtJSON :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtJSON :: MediaType Type) (Request -> Request) Source #
Accept ('MtPatch :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtPatch :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtPatch :: MediaType Type) (Request -> Request) Source #
Accept ('MtRaw :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtRaw :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtRaw :: MediaType Type) (Request -> Request) Source #
Accept ('MtRedirect :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtRedirect :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtRedirect :: MediaType Type) (Request -> Request) Source #
Accept ('MtSha :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtSha :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtSha :: MediaType Type) (Request -> Request) Source #
Accept ('MtStar :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtStar :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtStar :: MediaType Type) (Request -> Request) Source #
Accept ('MtStatus :: MediaType Type) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtStatus :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtStatus :: MediaType Type) (Request -> Request) Source #
Accept ('MtUnit :: MediaType Type) Source #	Note: we don't ignore response status. We only accept any response body.
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtUnit :: MediaType Type) ByteString Source # modifyRequest :: Tagged ('MtUnit :: MediaType Type) (Request -> Request) Source #
PreviewAccept p => Accept ('MtPreview p) Source #
Instance details Defined in GitHub.Request Methods contentType :: Tagged ('MtPreview p) ByteString Source # modifyRequest :: Tagged ('MtPreview p) (Request -> Request) Source #

class Accept mt => ParseResponse (mt :: MediaType Type) a where Source #

Methods

parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged mt (m a) Source #

Instances

Instances details

a ~ ByteString => ParseResponse ('MtDiff :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtDiff :: MediaType Type) (m a) Source #
FromJSON a => ParseResponse ('MtJSON :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtJSON :: MediaType Type) (m a) Source #
a ~ ByteString => ParseResponse ('MtPatch :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtPatch :: MediaType Type) (m a) Source #
a ~ ByteString => ParseResponse ('MtRaw :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtRaw :: MediaType Type) (m a) Source #
b ~ URI => ParseResponse ('MtRedirect :: MediaType Type) b Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtRedirect :: MediaType Type) (m b) Source #
a ~ ByteString => ParseResponse ('MtSha :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtSha :: MediaType Type) (m a) Source #
FromJSON a => ParseResponse ('MtStar :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtStar :: MediaType Type) (m a) Source #
HasStatusMap a => ParseResponse ('MtStatus :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtStatus :: MediaType Type) (m a) Source #
a ~ () => ParseResponse ('MtUnit :: MediaType Type) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtUnit :: MediaType Type) (m a) Source #
PreviewParseResponse p a => ParseResponse ('MtPreview p) a Source #
Instance details Defined in GitHub.Request Methods parseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtPreview p) (m a) Source #

makeHttpRequest :: forall am (mt :: MediaType Type) (rw :: RW) a m. (AuthMethod am, MonadThrow m, Accept mt) => Maybe am -> GenRequest mt rw a -> m Request Source #

Create http-client Request.

for PagedQuery, the initial request is created.
for Status, the Request for underlying Request is created, status checking is modifying accordingly.

parseStatus :: MonadError Error m => StatusMap a -> Status -> m a Source #

Helper for handling of RequestStatus.

parseStatus :: StatusMap a -> Status -> Either Error a

parsePageLinks :: Response a -> PageLinks Source #

Parse the PageLinks from an HTTP response, where the information is encoded in the Link header.

type StatusMap a = [(Int, a)] Source #

getNextUrl :: Response a -> Maybe URI Source #

Query Link header with rel=next from the request headers.

performPagedRequest Source #

Arguments

:: forall a m (mt :: MediaType Type). (ParseResponse mt a, Semigroup a, MonadCatch m, MonadError Error m)
=> (Request -> m (Response ByteString))	`httpLbs` analogue
-> (a -> Bool)	predicate to continue iteration
-> Request	initial request
-> Tagged mt (m (Response a))

Helper for making paginated requests. Responses, a are combined monoidally.

The result is wrapped in the last received Response.

performPagedRequest :: (FromJSON a, Semigroup a)
                    => (Request -> ExceptT Error IO (Response ByteString))
                    -> (a -> Bool)
                    -> Request
                    -> ExceptT Error IO (Response a)

parseResponseJSON :: (FromJSON a, MonadError Error m) => Response ByteString -> m a Source #

Parse API response.

parseResponse :: FromJSON a => Response ByteString -> Either Error a

Preview

class PreviewAccept p where Source #

Minimal complete definition

previewContentType

Methods

previewContentType :: Tagged ('MtPreview p) ByteString Source #

previewModifyRequest :: Tagged ('MtPreview p) (Request -> Request) Source #

class PreviewAccept p => PreviewParseResponse p a where Source #

Methods

previewParseResponse :: MonadError Error m => Request -> Response ByteString -> Tagged ('MtPreview p) (m a) Source #

SSL

This always exist, independently of openssl configuration flag. They change accordingly, to make use of the library simpler.

withOpenSSL :: IO a -> IO a #

tlsManagerSettings :: ManagerSettings Source #