Buckets.Adapters.GCS (buckets v1.0.0-rc.1)

Google Cloud Storage adapter for Buckets.

This adapter provides a native implementation for GCS operations using only the :req HTTP client, without dependencies on :google_api_storage, :gcs_signed_url, or :goth.

Setup

To use this adapter, you need to start your Cloud module in your application's supervision tree to enable automatic token caching and refresh:

children = [
  # ... your other processes
  MyApp.Cloud
]

Supervisor.start_link(children, opts)

The Cloud module will automatically start the required authentication processes for GCS locations.

The supervisor will automatically manage authentication tokens for each unique set of service account credentials, refreshing them before they expire.

Configuration

You can configure GCS locations using either service account credentials as a JSON string or by providing a path to a service account JSON file:

config :my_app, MyCloud,
  locations: [
    gcs_direct: [
      adapter: Buckets.Adapters.GCS,
      bucket: "my-bucket",
      path: "uploads",
      service_account_credentials: System.fetch_env!("GOOGLE_CREDENTIALS")
    ],
    gcs_from_file: [
      adapter: Buckets.Adapters.GCS,
      bucket: "my-bucket",
      path: "uploads",
      service_account_path: "path/to/service-account.json"
    ]
  ]

The :service_account_credentials option accepts a JSON string, making it easy to pass credentials via environment variables:

service_account_credentials: System.get_env("GCS_SERVICE_ACCOUNT_JSON")

Performance

This implementation automatically caches and refreshes Google Cloud access tokens, significantly reducing latency compared to generating new tokens for each request. Tokens are refreshed 5 minutes before expiration to ensure uninterrupted service.

Summary

Functions

Gets a signed URL for temporarily delegating access to an object in a bucket.

Functions

Link to this function

url(remote_path, config)

Gets a signed URL for temporarily delegating access to an object in a bucket.

Errors

* 403 PERMISSION_DENIED: Permission 'iam.serviceAccounts.signBlob' denied on resource
  (or it may not exist). Make sure the authorized SA has role roles/iam.serviceAccountTokenCreator
  on the SA passed in the URL.

* 403 PERMISSION_DENIED: IAM Service Account Credentials API has not been used in project {project_id}
  before or it is disabled. Enable it by visiting {url} then retry. If you enabled this API recently,
  wait a few minutes for the action to propagate to our systems and retry. Make sure the authorized SA
  has role roles/iam.serviceAccountTokenCreator on the SA passed in the URL."