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

Uploads in-memory data in a single request (simple upload).

Options

• :content_type — defaults to "application/octet-stream"
• :predefined_acl — e.g. "publicRead"
• :timeout — request timeout in ms

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

Initiates a resumable upload session and returns its session URI.

Options

• :content_type — value sent as X-Upload-Content-Type
• :attrs — Object resource metadata (sent as the JSON request body)
• :origin — browser origin to forward as the Origin header. Required for browser-based resumable uploads (initiate the session server-side, hand the session URI to the browser): GCS only returns CORS headers on requests to the session URI if the session was initiated with an Origin — the bucket's CORS configuration alone does not apply. Must be the origin the browser will upload from. Mirrors origin in Google's official clients (e.g. createResumableUpload in google-cloud-node, Blob.create_resumable_upload_session in google-cloud-python).
• :timeout — request timeout in ms

@spec upload(
  String.t(),
  String.t(),
  binary() | {:file, Path.t()} | Enumerable.t(),
  keyword()
) ::
  {:ok, map()} | {:error, GcpGcs.Error.t()}

Uploads from a source, choosing a strategy automatically:

• a binary → simple upload (put_object/4)
• {:file, path} → resumable streamed upload (upload_file/4)
• an Enumerable of binaries → resumable streamed upload (upload_stream/4)

@spec upload_chunk(String.t(), binary(), keyword()) ::
  {:ok, map()} | {:resume, non_neg_integer()} | {:error, GcpGcs.Error.t()}

Uploads a single chunk to a resumable session_uri.

Options (required: :offset)

• :offset — byte offset of this chunk within the object
• :total — total object size if known, or nil/omitted for the streaming case (intermediate chunks send /*)
• :timeout — request timeout in ms

Returns

• {:resume, next_offset} — chunk stored, more expected (HTTP 308)
• {:ok, object} — upload complete (HTTP 200/201)
• {:error, %GcpGcs.Error{}}

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

Uploads a local file using a resumable session, streaming it in one request with constant memory.

Content type defaults to a guess from the object's extension.

Options

• :content_type — overrides the guessed content type
• :chunk_size — read size in bytes (rounded to a 256 KiB multiple)
• :attrs — Object resource metadata to set on the new object
• :timeout — request timeout in ms

@spec upload_stream(String.t(), String.t(), Enumerable.t(), keyword()) ::
  {:ok, map()} | {:error, GcpGcs.Error.t()}

Uploads from an Enumerable of binaries using a resumable session.

The data is rebuffered into 256 KiB-aligned chunks and sent incrementally, so the total size need not be known up front and memory stays bounded.

Options

• :content_type — defaults to "application/octet-stream"
• :chunk_size — chunk size in bytes (rounded to a 256 KiB multiple)
• :attrs — Object resource metadata to set on the new object
• :timeout — per-request timeout in ms