Supabase.Fetcher is a comprehensive HTTP client designed to interface seamlessly with Supabase services. This module acts as the backbone for making HTTP requests, streaming data, uploading files, and managing request/response lifecycles within the Supabase ecosystem.

Key Features

• Request Composition: Build requests with method, headers, body, and query parameters using a composable builder pattern via Supabase.Fetcher.Request.
• Streaming Support: Stream large responses efficiently using Finch.stream/5, reducing memory usage for large payloads.
• Error Management: Centralized error handling through Supabase.ErrorParser, supporting structured and semantic error reporting.

Key Components

HTTP Clients

Supabase.Fetcher provides a Supabase.Fetcher.Adapter behaviour that defines the interface to implement custom HTTP clients backends (e.g Finch, Req, :httpc).

That way is possible to use the same API defined on Supabase.Fetcher and customize how make the actual HTTP request. The default implementation uses Supabase.Fetcher.Adapter.Finch.

You can customize the HTTP client used in Supabase.Fetcher with the Supabase.Fetcher.Request.with_http_client/2 function while building your request:

fetcher =
  Supabase.Fetcher.Request.new(client)
  |> Supabase.Fetcher.Request.with_http_client(Supabase.Fetcher.Adapter.Httpc)copy

supabase_potion would ideally provide multiple client implementations but you can safely extend to your own preference using the aforementioned behaviour, something like:

defmodule MyHTTPClient do
  @moduledoc "My custom HTTP client to be used as backend for `Supabase.Fetcher`"

  @behaviour Supabase.Fetcher.Adapter

  @impl true
  def request(%Supabase.Fetcher.Request{}), do: # ...

  @impl true
  # optional, if the client support async requests
  def request_async(%Supabase.Fetcher.Request{}), do: # ...

  @impl true
  # optional, if the client support response streaming
  def stream(%Supabase.Fetcher.Request{}), do: # ...
  def stream(%Supabase.Fetcher.Request{}, on_response), do: # ...

  @impl true
  # required to Storage upload to work
  def upload(%Supabase.Fetcher.Request{}, file_path, options), do: # ...
endcopy

Decoders and Parsers

• Body Decoder: Custom modules implementing the Supabase.Fetcher.BodyDecoder behaviour can decode response bodies into application-specific formats.
• Error Parser: Handle service-specific errors using Supabase.Error implementations, ensuring consistent error reporting across services.

Streaming

• stream/1 and stream/2 support fine-grained control over streamed responses, allowing consumers to process data incrementally while retaining access to status and headers.

Upload Support

Effortlessly upload binary files using the upload/2 function, which manages content type, headers, and streaming.

Example Usage

Basic Request

{:ok, %Supabase.Fetcher.Response{} = response} =
  Supabase.Fetcher.Request.new(client)
  |> Supabase.Fetcher.Request.with_auth_url("/token")
  |> Supabase.Fetcher.Request.with_method(:post)
  |> Supabase.Fetcher.Request.with_body(%{username: "test", password: "test"})
  |> Supabase.Fetcher.request()copy

Streaming

Consume the whole stream

{:ok, %Supabase.Fetcher.Response{body: <<...>>}} =
  Supabase.Fetcher.Request.new(client)
  |> Supabase.Fetcher.Request.with_storage_url("/large-file")
  |> Supabase.Fetcher.stream()copy

Fine-grained control over body stream

on_response = fn {status, headers, body} ->
  try do
    file = File.stream!("output.txt", [:write, :utf8])

    body
    |> Stream.into(file)
    |> Stream.run()

    {:ok, %Supabase.Fetcher.Response{status: status, headers: headers}}
  rescue
    e in File.Error -> {:error, e.reason}
  end
end

{:ok, %Supabase.Fetcher.Response{body: stream}} =
  Supabase.Fetcher.Request.new(client)
  |> Supabase.Fetcher.Request.with_storage_url("/large-file")
  |> Supabase.Fetcher.stream(on_response)copy

Custom Decoders and Error Parsers

{:ok, %Supabase.Decoder{} = response} =
  Supabase.Fetcher.Request.new(client)
  |> Supabase.Fetcher.Request.with_functions_url("/execute")
  |> Supabase.Fetcher.Request.with_body_decoder(MyCustomDecoder)
  |> Supabase.Fetcher.Request.with_error_parser(MyErrorParser)
  |> Supabase.Fetcher.request()copy

Notes

This module is designed to be extensible and reusable for all Supabase-related services. It abstracts away the low-level HTTP intricacies while providing the flexibility developers need to interact with Supabase services in Elixir applications.

In general, if you don't have specific needs, custom application formats or you aren't building something new around Supabase.Fetcher you generally are safe using the default options if you only need to consume Supabase services as a client.