| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Network.Goggles
Contents
Description
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):
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
Constructors
| GCPServiceAccount | |
Fields
| |
Instances
data GCPTokenOptions Source #
Constructors
| GCPTokenOptions | |
Fields
| |
Instances
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.
Instances
| 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
class HasCredentials c where Source #
This class
Minimal complete definition
Methods
tokenFetch :: Cloud c (Token c) Source #
Instances
An authentication Token with an expiry date
Constructors
| Token | |
Fields
| |
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)
Constructors
| Handle | |
Fields
| |
Instances
| 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
Errors associated with JWT-encoded token request
Constructors
| BadExpirationTime !String | |
| CryptoSignError !String |
data TokenExchangeException Source #
Token exchange exceptions
Constructors
| NotFound !String | Something went wrong with the request, token not found |
| APICredentialsNotFound !String |
data CloudException Source #
Cloud API exception
Constructors
| UnknownError !String | |
| IOError !String | |
| TimeoutError !String | |
| JsonDecodeError !String |
Instances