@spec download(String.t(), String.t(), keyword()) ::
  {:ok, binary()} | {:error, GcpGcs.Error.t()}

Downloads an object and returns its full contents as a binary.

Prefer download_to_file/4 or stream/5 for large objects.

Options

• :generation — a specific object generation
• :timeout — request timeout in ms

@spec download_to_file(String.t(), String.t(), Path.t(), keyword()) ::
  :ok | {:error, GcpGcs.Error.t()}

Streams an object's contents to a local file at path, using constant memory.

Returns :ok. On error the partially-written file is removed.

@spec stream(String.t(), String.t(), keyword(), acc, (term(), acc -> acc)) ::
  {:ok, acc} | {:error, GcpGcs.Error.t()}
when acc: term()

Streams an object's contents through reducer, folding from acc.

reducer receives {:headers, headers} once, then {:data, binary} for each body chunk, returning the updated accumulator. Returns {:ok, acc}.

Example

# Count bytes without buffering the object
{:ok, total} =
  GcpGcs.Download.stream("my-bucket", "big.bin", [], 0, fn
    {:data, chunk}, n -> n + byte_size(chunk)
    _other, n -> n
  end)