This module provides a common set of operations which can be performed against the remote Google Service APIs. Typically you will import this module qualified along with modules from the various gogol-* libraries for services you wish to communicate with.

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 calling functions 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:

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE FlexibleContexts #-}
{-# LANGUAGE OverloadedLabels #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ScopedTypeVariables #-}

import Control.Lens ((.~), (<&>), (?~))
import Control.Monad.Trans.Resource (liftResourceT)
import Data.Conduit (runConduit, (.|))
import qualified Data.Conduit.Binary as Conduit
import Data.Function ((&))
import Data.Generics.Labels ()
import Data.Proxy
import Data.Text
import qualified Data.Text as Text
import Gogol
import qualified Gogol.Storage as Storage
import System.IO (stdout)

import qualified Data.Text as Text

example :: IO Storage.Object
example = do
  lgr <- newLogger Debug stdout                                                                          -- (1)
  env <- newEnv <&> (envLogger .~ lgr) . (envScopes .~ (Proxy :: Proxy '[Storage.Devstorage'ReadWrite])) -- (2) (3)
  body <- sourceBody "/path/to/image.jpg"                                                                -- (4)
  let key = "image.jpg"
      bucket = "my-storage-bucket"

  runResourceT $                                                                                         -- (5)
    upload env (Storage.newStorageObjectsInsert bucket (Storage.newObject & #name ?~ key)) body

Breaking down the above example, we have the following points of interest:

1. A new Logger to replace the default noop logger is created, set to print debug information and errors to stdout.
2. The Env is created using newEnv. This creates a new HTTP Manager and retrieves the application default Credentials.
3. The lenses envLogger and envScopes are used to set the newly created Logger and authorised OAuth2 scopes, respectively. Explicitly annotating the Env with the scopes ensures that any mismatch between the remote operations performed in upload and the credential scopes are raised as errors at compile time. See the Authorization section for more information.

4. The streaming body for the object is retrieved from a FilePath, and the MIME type is calculated from the file extension. The MIME type is used as the object's Content-Type in Cloud Storage, and can be overriden using the bodyContentType lens as follows:

   import Network.HTTP.Media ((//))
   
   body <- sourceBody f <&> bodyContentType .~ "application" // "json"

5. Finally, we run the Google computation using runResourceT which serialises the StorageObjectsInsert type to a HTTP request and sets the streaming Body. The resulting Object 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.

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:

• Gogol.Auth.InstalledApplication - Applications installed on devices.
• Gogol.Auth.ServiceAccount - Applications deployed to custom environments.
• Gogol.Auth.ApplicationDefault - Applications deployed to App Engine (GAE) or Compute Engine (GCE).

See Gogol.Auth for more information.

Each request within a particular send, upload or download context requires specific OAuth2 scopes to be have been authorized for the given credentials.

For example, the Google Storage StorageObjectsInsert 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 function call 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 Env. 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 Envs set of scopes. The various gogol-* libraries export their individual scopes from @Gogol.*" and you can use the (!) combinator to combine these into a larger set.

For example:

import Control.Lens ((<&>), (.~))
import Gogol
import Gogol.Monitoring
import Gogol.Compute

main :: IO ()
main = do
    env <- newEnv <&> envScopes .~ (Proxy :: Proxy '[Monitoring'Read, Monitoring'Write, Compute'ReadOnly])
    ...

>>> :type env
Env '["https://www.googleapis.com/auth/monitoring.read", "https://www.googleapis.com/auth/monitoring.write", "https://www.googleapis.com/auth/compute.readonly"]

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 Gogol
import Gogol.Compute

local (override (computeService & serviceHost .~ "localhost")) $ do
   _ <- send $ instancesGet "project" "zone" "instance-id"
   ...

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 tinylog or fast-logger.

Requests can be sent asynchronously, but due to guarantees about resource closure require the use of lifted-async.

Google Compute metadata can be retrieve when running on GCE instances. See the documentation in Gogol.Compute.Metadata for the available functions.