buckets

defmodule Buckets.SignedURL do
  @moduledoc """
  Represents a signed URL for direct access to objects in cloud storage.

  Signed URLs provide temporary, secure access to objects without requiring
  authentication. They are commonly used for:
  - Direct file downloads from cloud storage
  - Direct uploads to cloud storage (especially with LiveView)
  - Temporary sharing of private files

  ## Structure

  A SignedURL contains:
  - `:url` - The complete signed URL string that can be used for access
  - `:location` - The `Buckets.Location` struct indicating where the object is stored

  ## Usage

  SignedURLs are typically generated by adapters through the `url/2` callback:

      {:ok, signed_url} = MyApp.Cloud.url(object, expires_in: 3600)

      # Access the URL string
      url_string = signed_url.url
      # or use String.Chars protocol
      url_string = to_string(signed_url)

  ## LiveView Uploads

  SignedURLs are used for direct uploads in LiveView:

      {:ok, config} = MyApp.Cloud.live_upload(entry)
      # config.url is a SignedURL for uploading

  ## JSON Encoding

  SignedURLs implement the `Jason.Encoder` protocol and encode to just the URL string:

      Jason.encode!(%{upload_url: signed_url})
      # {"upload_url": "https://storage.example.com/bucket/file?signature=..."}

  ## Security Considerations

  - Signed URLs typically expire after a set time period
  - They should be treated as sensitive data
  - Different adapters have different expiration limits and security features
  """
  defstruct [:url, :location]

  @type t() :: %__MODULE__{
          url: String.t(),
          location: Buckets.Location.t()
        }

  @doc """
  Converts a SignedURL to its URL string representation.

  This function extracts just the URL string from the SignedURL struct.
  It's also used by the `String.Chars` protocol implementation.

  ## Examples

      iex> signed_url = %Buckets.SignedURL{url: "https://example.com/file?sig=123"}
      iex> Buckets.SignedURL.to_string(signed_url)
      "https://example.com/file?sig=123"

      # Also works with Kernel.to_string/1
      iex> to_string(signed_url)
      "https://example.com/file?sig=123"
  """
  def to_string(signed_url), do: signed_url.url

  defimpl String.Chars do
    defdelegate to_string(url), to: Buckets.SignedURL
  end

  defimpl Jason.Encoder do
    def encode(url, opts), do: Jason.Encode.string(to_string(url), opts)
  end
end