@@ -6,6 +6,8 @@
66{-# LANGUAGE TypeFamilies #-}
77{-# LANGUAGE UndecidableInstances #-}
88
9+{-# OPTIONS_GHC -fno-warn-duplicate-exports #-}
10+
911-- |
1012-- Module : Network.Google
1113-- Copyright : (c) 2015 Brendan Hay
@@ -14,10 +16,67 @@
1416-- Stability : provisional
1517-- Portability : non-portable (GHC extensions)
1618--
17−module Network.Google where
19+-- This module provides a simple 'AWS' monad and a set of operations which
20+-- can be performed against remote Google Service APIs, for use with the types
21+-- supplied by the various @gogol-*@ libraries.
22+--
23+-- A 'MonadGoogle' typeclass is used as a function constraint to provide automatic
24+-- lifting of functions when embedding 'Google' as a layer inside your own
25+-- application stack.
26+module Network.Google
27+ (
28+ -- * Running Google Actions
29+ Google
30+ , runGoogle
31+ , runResourceT
32+
33+ -- * Authentication and Environment
34+ , newEnv
35+ , Env
36+ , HasEnv (..)
37+
38+ -- ** Credential Discovery
39+ , Credentials (..)
40+
41+ -- * Sending Requests
42+ , send
43+
44+ -- ** Media Downloads
45+ , download
46+
47+ -- ** Service Configuration
48+ -- ** Overriding Defaults
49+ , configure
50+ , override
51+
52+ -- *** Scoped Actions
53+ , reconfigure
54+ , timeout
55+
56+ -- ** Media Uploads
57+ , Body
58+ , ToBody (..)
59+ , OctetStream
60+ , PlainText
61+ , JSON
62+
63+ -- * Running Asynchronous Actions
64+ -- $async
65+
66+ -- * Handling Errors
67+ , AsError (..)
68+ , AsAuthError (..)
69+
70+ , trying
71+ , catching
72+
73+ -- * Re-exported Types
74+ , Proxy (..)
75+ , module Network.Google.Types
76+ ) where
1877
1978import Control.Applicative
20−import Control.Exception.Lens (throwingM)
79+import Control.Exception.Lens
2180import Control.Monad
2281import Control.Monad.Base
2382import Control.Monad.Catch
@@ -34,9 +93,11 @@ import Control.Monad.Trans.Maybe (MaybeT)
3493import Control.Monad.Trans.Resource
3594import qualified Control.Monad.Writer.Lazy as LW
3695import qualified Control.Monad.Writer.Strict as W
96+import Network.Google.Auth
3797import Network.Google.Env
3898import Network.Google.Internal.HTTP
3999import Network.Google.Prelude
100+import Network.Google.Types
40101
41102newtype Google a = Google { unGoogle :: ReaderT Env (ResourceT IO) a }
42103 deriving
@@ -93,19 +154,35 @@ instance (Monoid w, MonadGoogle m) => MonadGoogle (RW.RWST r w s m) where
93154instance (Monoid w, MonadGoogle m) => MonadGoogle (LRW.RWST r w s m) where
94155 liftGoogle = lift . liftGoogle
95156
157+-- | Run a 'Google' aciton using the specified environment.
96158runGoogle :: (MonadResource m, HasEnv r) => r -> Google a -> m a
97159runGoogle e m = liftResourceT $ runReaderT (unGoogle m) (e ^. environment)
98160
161+-- | Send a request, returning the associated response if successful.
162+--
163+-- Throws 'Error'.
99164send :: (MonadGoogle m, GoogleRequest a) => a -> m (Rs a)
100165send x = liftGoogle $ do
101166 e <- ask
102167 r <- perform e x
103168 hoistError r
104169
105−media :: (MonadGoogle m, GoogleRequest (MediaDownload a))
106− => a
107− -> m (Rs (MediaDownload a))
108−media = send . MediaDownload
170+-- | Send a request returning the associated streaming media response if successful.
171+--
172+-- Some request data types have two possible responses, the JSON metadata and
173+-- a streaming media response. Use 'send' to retrieve the metadata and 'download'
174+-- to retrieve the streaming media.
175+--
176+-- Throws 'Error'.
177+download :: (MonadGoogle m, GoogleRequest (MediaDownload a))
178+ => a
179+ -> m (Rs (MediaDownload a))
180+download = send . MediaDownload
109181
110182hoistError :: MonadThrow m => Either Error a -> m a
111183hoistError = either (throwingM _Error) return
184+
185+{- $async
186+Requests can be sent asynchronously, but due to guarantees about resource closure
187+require the use of <http://hackage.haskell.org/package/lifted-async lifted-async>.
188+-}