Copyright | (c) 2015-2016 Brendan Hay |
---|---|
License | Mozilla Public License, v. 2.0. |
Maintainer | Brendan Hay <brendan.g.hay@gmail.com> |
Stability | provisional |
Portability | non-portable (GHC extensions) |
Safe Haskell | None |
Language | Haskell2010 |
This module provides a Google
monad and common set of operations which
can be performed against the remote Google Service APIs. Typically you will
import this module along with modules from various gogol-*
libraries
for the services you wish to communicate with.
- newtype Google s a = Google {}
- class (Functor m, Applicative m, Monad m, MonadIO m, MonadCatch m, AllowScopes s) => MonadGoogle s m | m -> s where
- liftGoogle :: Google s a -> m a
- runGoogle :: (MonadResource m, HasEnv s r) => r -> Google s a -> m a
- runResourceT :: MonadBaseControl IO m => ResourceT m a -> m a
- data Env s
- class HasEnv s a | a -> s where
- environment :: Lens' a (Env s)
- envOverride :: Lens' a (Dual (Endo ServiceConfig))
- envLogger :: Lens' a Logger
- envManager :: Lens' a Manager
- envStore :: Lens' a (Store s)
- envScopes :: Lens' a (Proxy s)
- newEnv :: (MonadIO m, MonadCatch m, AllowScopes s) => m (Env s)
- newEnvWith :: (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Env s)
- getApplicationDefault :: (MonadIO m, MonadCatch m) => Manager -> m (Credentials s)
- (!) :: proxy xs -> proxy ys -> Proxy (Nub (xs ++ ys))
- allow :: proxy s -> k s -> k s
- class AllowScopes a
- type family HasScope s a :: Constraint
- send :: (MonadGoogle s m, HasScope s a, GoogleRequest a) => a -> m (Rs a)
- download :: (MonadGoogle s m, HasScope s (MediaDownload a), GoogleRequest (MediaDownload a)) => a -> m (Rs (MediaDownload a))
- upload :: (MonadGoogle s m, HasScope s (MediaUpload a), GoogleRequest (MediaUpload a)) => a -> Body -> m (Rs (MediaUpload a))
- data Body :: * = Body !MediaType !RequestBody
- bodyContentType :: Lens' Body MediaType
- sourceBody :: MonadIO m => FilePath -> m Body
- getMIMEType :: FilePath -> MediaType
- configure :: HasEnv s a => (ServiceConfig -> ServiceConfig) -> a -> a
- override :: HasEnv s a => ServiceConfig -> a -> a
- timeout :: (MonadReader r m, HasEnv s r) => Seconds -> m a -> m a
- serviceHost :: Lens' ServiceConfig ByteString
- servicePort :: Lens' ServiceConfig Int
- servicePath :: Lens' ServiceConfig Builder
- serviceSecure :: Lens' ServiceConfig Bool
- serviceTimeout :: Lens' ServiceConfig (Maybe Seconds)
- class AsError a where
- _Error :: Prism' a Error
- _TransportError :: Prism' a HttpException
- _SerializeError :: Prism' a SerializeError
- _ServiceError :: Prism' a ServiceError
- class AsAuthError a where
- _AuthError :: Prism' a AuthError
- _RetrievalError :: Prism' a HttpException
- _MissingFileError :: Prism' a FilePath
- _InvalidFileError :: Prism' a (FilePath, Text)
- _TokenRefreshError :: Prism' a (Status, Text, Maybe Text)
- trying :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Either a r)
- catching :: MonadCatch m => Getting (First a) SomeException a -> m r -> (a -> m r) -> m r
- type Logger = LogLevel -> Builder -> IO ()
- data LogLevel
- newLogger :: MonadIO m => LogLevel -> Handle -> m Logger
- newManager :: ManagerSettings -> IO Manager
- tlsManagerSettings :: ManagerSettings
Usage
The request and response types provided by the various gogol-*
libraries can
be used with either send
, upload
, or download
, depending upon the
request's purpose. Namely, send
is the function you will most commonly use to
send requests, with upload
and download
as convenience when dealing with
streaming requests and responses respectively.
To get started we will need to specify our Google Service credentials and
create an Env
environment containing configuration which will be used by
runGoogle
to perform any actions. Your Google Credentials
can be supplied
in a number of ways, by having Gogol retrieve
Application Default Credentials
for use on Google App Engine and Google Compute Engine, or by explicitly
supplying your credentials. See the Credentials section for
information about supported credential mechanisms.
The following example demonstrates uploading a file to Google
Cloud Storage using ObjectsInsert
from
gogol-storage:
import Control.Lens ((&), (.~), (<&>), (?~)) import Data.Text (Text) import Network.Google import Network.Google.Storage import System.IO (stdout) import qualified Data.Text as Text example :: IO Object example = do lgr <- newLogger Debug stdout -- (1) env <- newEnv <&> (envLogger .~ lgr) . (envScopes .~ storageReadWriteScope) -- (2) (3) body <- sourceBody "/path/to/image.jpg" -- (4) let key = "image.jpg" bkt = "my-storage-bucket" runResourceT . runGoogle env $ -- (5) upload (objectsInsert bkt object' & oiName ?~ key) bkt
Breaking down the above example, we have the following points of interest:
- A new
Logger
to replace the default noop logger is created, set to print debug information and errors tostdout
. - The
Env
is created usingnewEnv
. This creates a new HTTPManager
and retrieves the application defaultCredentials
. - The lenses
envLogger
andenvScopes
are used to set the newly createdLogger
and authorised OAuth2 scopes, respectively. Explicitly annotating theEnv
with the scopes ensures that any mismatch between the remote operations performed inrunGoogle
and the credential scopes are raised as errors at compile time. See the Authorization section for more information. The streaming
body
for the object is retrieved from aFilePath
, and the MIME type is calculated from the file extension. The MIME type is used as the object'sContent-Type
in Cloud Storage, and can be overriden using thebodyContentType
lens as follows:import Network.HTTP.Media ((//)) body <- sourceBody f <&> bodyContentType .~ "application" // "json"
- Finally, we run the
Google
computation using
which serialises therunResourceT
.runGoogle
ObjectsInsert
type to a HTTP request and sets the streamingBody
. The resultingObject
metadata is then parsed from a successful HTTP response. 1 Additional examples can be found can be found in the Gogol project's source control.
The Google Monad
The Google
monad containing configuration environment and tracks
resource allocation via ResourceT
.
The functions in Network.Google are generalised
MonadBase IO (Google s) Source | |
MonadBaseControl IO (Google s) Source | |
AllowScopes [Symbol] s => MonadGoogle s (Google s) Source | |
Monad (Google s) Source | |
Functor (Google s) Source | |
Applicative (Google s) Source | |
Alternative (Google s) Source | |
MonadPlus (Google s) Source | |
MonadThrow (Google s) Source | |
MonadCatch (Google s) Source | |
MonadMask (Google s) Source | |
MonadIO (Google s) Source | |
MonadResource (Google s) Source | |
MonadReader (Env s) (Google s) Source | |
type StM (Google s) a = StM (ReaderT (Env s) (ResourceT IO)) a Source |
class (Functor m, Applicative m, Monad m, MonadIO m, MonadCatch m, AllowScopes s) => MonadGoogle s m | m -> s where Source
Monads in which Google
actions may be embedded.
The functions in Network.Google have MonadGoogle
constraints to provide
automatic lifting when embedding Google
as a layer inside your own
application stack.
liftGoogle :: Google s a -> m a Source
Lift a computation to the Google
monad.
MonadGoogle s m => MonadGoogle s (MaybeT m) Source | |
MonadGoogle s m => MonadGoogle s (ListT m) Source | |
MonadGoogle s m => MonadGoogle s (IdentityT m) Source | |
AllowScopes [Symbol] s => MonadGoogle s (Google s) Source | |
(Monoid w, MonadGoogle s m) => MonadGoogle s (WriterT w m) Source | |
(Monoid w, MonadGoogle s m) => MonadGoogle s (WriterT w m) Source | |
MonadGoogle s m => MonadGoogle s (StateT s' m) Source | |
MonadGoogle s m => MonadGoogle s (StateT s' m) Source | |
MonadGoogle s m => MonadGoogle s (ReaderT r m) Source | |
MonadGoogle s m => MonadGoogle s (ExceptT e m) Source | |
(Monoid w, MonadGoogle s m) => MonadGoogle s (RWST r w s' m) Source | |
(Monoid w, MonadGoogle s m) => MonadGoogle s (RWST r w s' m) Source |
runGoogle :: (MonadResource m, HasEnv s r) => r -> Google s a -> m a Source
Run a Google
action using the specified environment and
credentials annotated with sufficient authorization scopes.
runResourceT :: MonadBaseControl IO m => ResourceT m a -> m a
Unwrap a ResourceT
transformer, and call all registered release actions.
Note that there is some reference counting involved due to resourceForkIO
.
If multiple threads are sharing the same collection of resources, only the
last call to runResourceT
will deallocate the resources.
Since 0.3.0
Environment
The environment containing the parameters required to make Google requests.
class HasEnv s a | a -> s where Source
environment :: Lens' a (Env s) Source
envOverride :: Lens' a (Dual (Endo ServiceConfig)) Source
The currently applied overrides to all Service
configuration.
envLogger :: Lens' a Logger Source
The function used to output log messages.
envManager :: Lens' a Manager Source
The Manager
used to create and manage open HTTP connections.
envStore :: Lens' a (Store s) Source
The credential store used to sign requests for authentication with Google.
newEnv :: (MonadIO m, MonadCatch m, AllowScopes s) => m (Env s) Source
Creates a new environment with a newly initialized Manager
, without logging.
and Credentials that are determined by calling getApplicationDefault
.
Use newEnvWith
to supply custom credentials such as an OAuthClient
and OAuthCode
.
The Allow
ed OAuthScope
s are used to authorize any service_account
that is
found with the appropriate scopes. See the top-level module of each individual
gogol-*
library for a list of available scopes, such as
Network.Google.Compute.authComputeScope
.
Lenses from HasEnv
can be used to further configure the resulting Env
.
See: newEnvWith
, getApplicationDefault
.
newEnvWith :: (MonadIO m, MonadCatch m, AllowScopes s) => Credentials s -> Logger -> Manager -> m (Env s) Source
Create a new environment.
See: newEnv
.
Credentials
By default newEnv
uses getApplicationDefault
to discover credentials
from the underlying, following Google's official library behaviour.
If you wish to manually specify Credentials
via newEnvWith
, you can use one
of the following supported credential mechanisms:
- Network.Google.Auth.InstalledApplication - Applications installed on devices.
- Network.Google.Auth.ServiceAccount - Applications deployed to custom environments.
- Network.Google.Auth.ApplicationDefault - Applications deployed to App Engine (GAE) or Compute Engine (GCE).
See Network.Google.Auth for more information.
getApplicationDefault :: (MonadIO m, MonadCatch m) => Manager -> m (Credentials s) Source
Performs credentials discovery in the following order:
- Read the default credentials from a file specified by
the environment variable
GOOGLE_APPLICATION_CREDENTIALS
if it exists. - Read the platform equivalent of
~/.config/gcloud/application_default_credentials.json
if it exists. The~/.config
component of the path can be overriden by the environment variableCLOUDSDK_CONFIG
if it exists. - Retrieve the default service account application credentials if
running on GCE. The environment variable
NO_GCE_CHECK
can be used to skip this check if set to a truthy value such as1
ortrue
.
The specified Scope
s are used to authorize any service_account
that is
found with the appropriate OAuth2 scopes, otherwise they are not used. See the
top-level module of each individual gogol-*
library for a list of available
scopes, such as Network.Google.Compute.computeScope
.
Authorization
Each request within a particular runGoogle
context requires specific
OAuth2 scopes to be have been authorized for the given credentials.
For example, the Google Storage ObjectsInsert
has the associated scopes of:
type Scopes ObjectsInsert = '["https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/devstorage.full_control", "https://www.googleapis.com/auth/devstorage.read_write"]
Multiple differing requests within a given runGoogle
context will then require
the credentials to have a minimal set of these associated request scopes.
This authorization information is represented as a type-level set,
the s
type parameter of Google
and MonadGoogle
. A mismatch
of the sent request scopes and the Env
credential scopes results in a informative
compile error.
You can use allow
or the envScopes
lens to specify the Env
s set of scopes.
The various gogol-*
libraries export their individual scopes from @Network.Google.*"
and you can use the '(!)' combinator to combine these into a larger set.
For example:
import Control.Lens ((<&>), (.~)) import Network.Google import Network.Google.Monitoring main :: IO () main = do env <- newEnv <&> envScopes .~ (monitoringReadScope ! monitoringWriteScope ! computeReadOnlyScope) ...
>>>
:type env
Env '["https://www.googleapis.com/auth/monitoring.read", "https://www.googleapis.com/auth/monitoring.write", "https://www.googleapis.com/auth/compute.readonly"]
class AllowScopes a Source
AllowScopes [Symbol] s => AllowScopes * (Credentials s) Source | |
AllowScopes [k] ([] k) Source | |
(KnownSymbol x, AllowScopes [Symbol] xs) => AllowScopes [Symbol] ((:) Symbol x xs) Source |
type family HasScope s a :: Constraint Source
Determine if _any_ of the scopes a request requires is listed in the scopes the credentials supports.
For error message/presentation purposes, this wraps the result of
the HasScope
membership check to show both lists of scopes before
reduction.
HasScope s a = (s `HasScope'` Scopes a) ~ True |
Sending Requests
send :: (MonadGoogle s m, HasScope s a, GoogleRequest a) => a -> m (Rs a) Source
Send a request, returning the associated response if successful.
Throws Error
.
Streaming Media
download :: (MonadGoogle s m, HasScope s (MediaDownload a), GoogleRequest (MediaDownload a)) => a -> m (Rs (MediaDownload a)) Source
Send a request returning the associated streaming media response if successful.
Some request data types have two possible responses, the JSON metadata and
a streaming media response. Use send
to retrieve the metadata and download
to retrieve the streaming media.
Equivalent to:
send
.MediaDownload
Throws Error
.
upload :: (MonadGoogle s m, HasScope s (MediaUpload a), GoogleRequest (MediaUpload a)) => a -> Body -> m (Rs (MediaUpload a)) Source
Send a request with an attached multipart/related media upload.
Equivalent to:
send
.MediaUpload
Throws Error
.
bodyContentType :: Lens' Body MediaType
sourceBody :: MonadIO m => FilePath -> m Body Source
Construct a Body
from a FilePath
.
This uses getMIMEType
to calculate the MIME type from the file extension,
you can use bodyContentType
to set a MIME type explicitly.
getMIMEType :: FilePath -> MediaType Source
Attempt to calculate the MIME type based on file extension.
Defaults to application/octet-stream
if no file extension is recognised.
Service Configuration
Each service has its own configuration such as host, port, path prefix, and timeout which can be customized independent of other services. It can be desirable to customize this when mocking service endpoints or adjusting HTTP response timeouts for a specific request.
For example, to point all calls to Google Compute to https://localhost
instead
of the actual remote endpoint, we can use Control.Monad.Reader.local
in conjunction
with override
:
import Control.Lens ((&), (.~)) import Control.Monad.Reader (local) import Network.Google import Network.Google.Compute local (override (computeService & serviceHost .~ "localhost")) $ do _ <- send $ instancesGet "project" "zone" "instance-id" ...
Overriding Defaults
override :: HasEnv s a => ServiceConfig -> a -> a Source
Override a specific ServiceConfig
. All requests belonging to the
supplied service will use this configuration instead of the default.
Typically you would override a modified version of the default ServiceConfig
for the desired service:
override (gmailService & serviceHost .~ "localhost") env
Or when using Network.Google with Control.Monad.Reader or Control.Lens.Zoom
and the ServiceConfig
lenses:
local (override (computeService & serviceHost .~ "localhost")) $ do ...
See: configure
.
timeout :: (MonadReader r m, HasEnv s r) => Seconds -> m a -> m a Source
Scope an action such that any HTTP response will use this timeout value.
Default timeouts are chosen by considering:
- This
timeout
, if set. - The related
Service
timeout for the sent request if set. (Default 70s) - The
envManager
timeout, if set. - The
ClientRequest
timeout. (Default 30s)
Lenses
serviceHost :: Lens' ServiceConfig ByteString
servicePort :: Lens' ServiceConfig Int
servicePath :: Lens' ServiceConfig Builder
serviceSecure :: Lens' ServiceConfig Bool
serviceTimeout :: Lens' ServiceConfig (Maybe Seconds)
Handling Errors
class AsError a where
_Error :: Prism' a Error
_TransportError :: Prism' a HttpException
_SerializeError :: Prism' a SerializeError
_ServiceError :: Prism' a ServiceError
AsError SomeException | |
AsError Error |
class AsAuthError a where Source
_AuthError :: Prism' a AuthError Source
A general authentication error.
_RetrievalError :: Prism' a HttpException Source
An error occured while communicating over HTTP with either then local metadata or remote accounts.google.com endpoints.
_MissingFileError :: Prism' a FilePath Source
The specified default credentials file could not be found.
_InvalidFileError :: Prism' a (FilePath, Text) Source
An error occured parsing the default credentials file.
_TokenRefreshError :: Prism' a (Status, Text, Maybe Text) Source
An error occured when attempting to refresh a token.
trying :: MonadCatch m => Getting (First a) SomeException a -> m r -> m (Either a r)
catching :: MonadCatch m => Getting (First a) SomeException a -> m r -> (a -> m r) -> m r
Logging
The exposed logging interface is a primitive Logger
function which gets
threaded through service calls and serialisation routines. This allows the
consuming library to output useful information and diagnostics.
The newLogger
function can be used to construct a simple logger which writes
output to a Handle
, but in most production code you should probably consider
using a more robust logging library such as
tiny-log or
fast-logger.
type Logger = LogLevel -> Builder -> IO () Source
A function threaded through various request and serialisation routines to log informational and debug messages.
Constructing a Logger
newLogger :: MonadIO m => LogLevel -> Handle -> m Logger Source
This is a primitive logger which can be used to log builds to a Handle
.
Note: A more sophisticated logging library such as tinylog or fast-logger should be used in production code.
Constructing a HTTP Manager
newManager :: ManagerSettings -> IO Manager
tlsManagerSettings :: ManagerSettings
Running Asynchronous Actions
Requests can be sent asynchronously, but due to guarantees about resource closure require the use of lifted-async.
Compute Metadata
Google Compute metadata can be retrieve when running on GCE instances. See the documentation in Network.Google.Compute.Metadata for the available functions.