Google Cloud Storage client for Elixir, built on the JSON API over Finch.

Provides bucket and object management, simple and resumable uploads, and streamed downloads. Responses are decoded JSON resources (maps with string keys); errors are GcpGcs.Error.t/0 structs.

Configuration

Production (default)

No configuration is required — requests go to storage.googleapis.com. Authentication uses, in order: a configured Goth instance, then the gcloud CLI. See GcpGcs.Auth.

# Optional: use Goth
config :gcp_gcs, :goth, MyApp.Goth

Development / test (emulator)

config :gcp_gcs, :emulator,
  scheme: "http",
  host: "localhost",
  port: 4443

See GcpGcs.Config for the full set of options.

Error handling

All functions return {:ok, result}/:ok or {:error, %GcpGcs.Error{}}. Pattern match on the error code:

case GcpGcs.get_object("my-bucket", "missing.txt") do
  {:ok, object} -> object
  {:error, %GcpGcs.Error{code: :not_found}} -> :missing
  {:error, %GcpGcs.Error{} = err} -> raise "GCS error: #{err}"
end

Examples

# Buckets
{:ok, _bucket} = GcpGcs.create_bucket("my-project", "my-bucket", location: "US")
{:ok, %{items: buckets}} = GcpGcs.list_buckets("my-project")

# Upload + download
{:ok, _object} = GcpGcs.put_object("my-bucket", "hello.txt", "Hello!")
{:ok, "Hello!"} = GcpGcs.download("my-bucket", "hello.txt")

# Stream a large file in and out with constant memory
{:ok, _} = GcpGcs.upload_file("my-bucket", "big.bin", "/tmp/big.bin")
:ok = GcpGcs.download_to_file("my-bucket", "big.bin", "/tmp/copy.bin")

# List a "directory"
{:ok, %{items: items, prefixes: dirs}} =
  GcpGcs.list_objects("my-bucket", prefix: "logs/", delimiter: "/")