Safe Haskell | None |
---|---|
Language | Haskell2010 |
This module is the entry point to the goggles
library, which is a Haskell interface to the cloud services hosted by Google (e.g. storage, compute, mail, etc.: https://cloud.google.com/) .
Most Google Cloud Platform (GCP) functionality requires authentication, which must be obtained beforehand from the website either with a free trial or a paid plan.
From now on, we'll assume the user has such credentials and is able to load them alongside this library.
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:
- it loads the GCP credentials (username and RSA key),
- retrieves a token via OAuth2,
- performs a single call to the Cloud Storage API endpoint that lists the metadata related to the contents of a storage bucket, and
- 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 <$> evalCloudIO hdl (listObjects bucket)
- getObject :: Text -> Text -> Cloud GCP LbsResponse
- listObjects :: Text -> Cloud GCP LbsResponse
- putObject :: Text -> Text -> ByteString -> Cloud GCP LbsResponse
- scopesDefault :: [Text]
- createHandle :: HasCredentials c => Credentials c -> Options c -> IO (Handle c)
- evalCloudIO :: Handle c -> Cloud c a -> IO a
- liftCloudIO :: HasCredentials c => IO a -> Cloud c a
- data GCP
- data GCPServiceAccount = GCPServiceAccount {}
- data GCPTokenOptions = GCPTokenOptions {
- _tokenOptionsScopes :: [Text]
- newtype Cloud c a = Cloud {}
- class HasCredentials c where
- type Credentials c
- type Options c
- type TokenContent c
- data Token c = Token {
- tToken :: TokenContent c
- tTime :: UTCTime
- data Handle c = Handle {
- credentials :: Credentials c
- token :: TVar (Maybe (Token c))
- options :: Options c
- parseRSAPrivateKey :: MonadThrow m => Text -> m PrivateKey
- data KeyException
- data JWTError
- data TokenExchangeException
- data CloudException
API endpoints
Google Cloud Storage
getObject :: Text -> Text -> Cloud GCP LbsResponse Source #
`getObject b p` retrieves the contents of a GCS object (of full path p
) in bucket b
listObjects :: Text -> Cloud GCP LbsResponse Source #
`listObjects b` retrieves a list of objects stored in bucket b
putObject :: Text -> Text -> ByteString -> Cloud GCP LbsResponse Source #
`putObject b p body` uploads a bytestring body
into a GCS object (of full path p
) in bucket b
GCP Authentication scopes
scopesDefault :: [Text] Source #
OAuth2 scopes for the various Google Cloud Platform services.
Please refer to
https://developers.google.com/identity/protocols/googlescopes
for the full list
Running Cloud programs
createHandle :: HasCredentials c => Credentials c -> Options c -> IO (Handle c) Source #
Create a Handle
with an empty token
Executing IO actions within Cloud
liftCloudIO :: HasCredentials c => IO a -> Cloud c a Source #
Lift an `IO a` action into the Cloud
monad, and catch synchronous exceptions, while rethrowing the asynchronous ones to IO
Types
data GCPServiceAccount Source #
Credentials for Google Cloud Platform
GCPServiceAccount | |
|
data GCPTokenOptions Source #
GCPTokenOptions | |
|
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.
Monad (Cloud c) Source # | |
Functor (Cloud c) Source # | |
Applicative (Cloud c) Source # | |
HasCredentials c => Alternative (Cloud c) Source # | |
HasCredentials c => MonadIO (Cloud c) Source # | |
HasCredentials c => MonadRandom (Cloud c) Source # | 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 |
HasCredentials c => MonadThrow (Cloud c) Source # | |
HasCredentials c => MonadCatch (Cloud c) Source # | |
MonadHttp (Cloud GCP) # | We can provide a custom http exception handler rather than throwing exceptions with this instance |
HasCredentials c => MonadReader (Handle c) (Cloud c) Source # | |
Authentication
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)
Handle | |
|
HasCredentials c => MonadReader (Handle c) (Cloud c) Source # | |
Private key
parseRSAPrivateKey :: MonadThrow m => Text -> m PrivateKey Source #
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 Source #
Authentication key exceptions
Errors associated with JWT-encoded token request
data TokenExchangeException Source #
Token exchange exceptions
NotFound !String | Something went wrong with the request, token not found |
APICredentialsNotFound !String |
data CloudException Source #
Cloud API exception