GcpGcs.Client (GcpGcs v0.2.0)

Copy Markdown View Source

HTTP transport for the Google Cloud Storage JSON API.

Wraps Finch and handles authentication, query/body encoding, JSON decoding, response streaming, and error normalization. Most users should use the high-level GcpGcs API instead of calling this module directly.

Three entry points:

  • request/3 — JSON metadata operations (decodes the body, success = 2xx)
  • raw_request/3 — returns the raw response for any status (used by resumable uploads, which rely on 308 Resume Incomplete)
  • stream/5 — streams the response body through a reducer (used by downloads)

Summary

Types

body()
method()

Functions

encode_object(name)

Percent-encodes an object name for use in a URL path (encodes / as %2F).

raw_request(method, url, opts \\ [])

Performs a request and returns the raw %Finch.Response{} for any HTTP status.

request(method, url, opts \\ [])

Performs a JSON request and decodes the response body.

stream(method, url, opts, acc, reducer)

Streams a response body through reducer, starting from acc.

Types

body()

@type body() ::
  nil
  | {:json, term()}
  | {:binary, binary(), String.t()}
  | {:stream, Enumerable.t(), String.t()}

method()

@type method() :: :get | :post | :put | :patch | :delete | :head

Functions

encode_object(name)

@spec encode_object(String.t()) :: String.t()

Percent-encodes an object name for use in a URL path (encodes / as %2F).

raw_request(method, url, opts \\ [])

@spec raw_request(method(), String.t(), keyword()) ::
  {:ok, Finch.Response.t()} | {:error, GcpGcs.Error.t()}

Performs a request and returns the raw %Finch.Response{} for any HTTP status.

Only transport and authentication failures produce {:error, _}; HTTP statuses (including 4xx and 308) are returned as {:ok, response} so the caller can interpret them (e.g. resumable upload chunking).

request(method, url, opts \\ [])

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

Performs a JSON request and decodes the response body.

Options

  • :query — keyword list or map appended as the query string
  • :headers — extra request headers (list of {name, value})
  • :body — request body, see body/0 (default nil)
  • :auth — set false to skip authentication (default true)
  • :timeout — receive timeout in ms (default GcpGcs.Config.default_timeout/0)

Returns {:ok, decoded} on a 2xx response (%{} when the body is empty), or {:error, %GcpGcs.Error{}}.

stream(method, url, opts, acc, reducer)

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

Streams a response body through reducer, starting from acc.

reducer receives {:status, integer}, {:headers, headers}, and {:data, binary} chunks (as Finch.stream/5). On a non-2xx status the body is collected and returned as {:error, %GcpGcs.Error{}} instead.

Returns {:ok, {status, headers, acc}} on success.