git.squeep.com Git - akkoma/blob - lib/pleroma/uploaders/uploader.ex

   1 defmodule Pleroma.Uploaders.Uploader do
   2   @moduledoc """
   3   Defines the contract to put and get an uploaded file to any backend.
   4   """
   5
   6   @doc """
   7   Instructs how to get the file from the backend.
   8
   9   Used by `Pleroma.Plugs.UploadedMedia`.
  10   """
  11   @type get_method :: {:static_dir, directory :: String.t()} | {:url, url :: String.t()}
  12   @callback get_file(file :: String.t()) :: {:ok, get_method()}
  13
  14   @doc """
  15   Put a file to the backend.
  16
  17   Returns:
  18
  19   * `:ok` which assumes `{:ok, upload.path}`
  20   * `{:ok, spec}` where spec is:
  21     * `{:file, filename :: String.t}` to handle reads with `get_file/1` (recommended)
  22
  23     This allows to correctly proxy or redirect requests to the backend, while allowing to migrate backends without breaking any URL.
  24   * `{url, url :: String.t}` to bypass `get_file/2` and use the `url` directly in the activity.
  25   * `{:error, String.t}` error information if the file failed to be saved to the backend.
  26
  27
  28   """
  29   @callback put_file(Pleroma.Upload.t()) ::
  30               :ok | {:ok, {:file | :url, String.t()}} | {:error, String.t()}
  31
  32   @spec put_file(module(), Pleroma.Upload.t()) ::
  33           {:ok, {:file | :url, String.t()}} | {:error, String.t()}
  34   def put_file(uploader, upload) do
  35     case uploader.put_file(upload) do
  36       :ok -> {:ok, {:file, upload.path}}
  37       other -> other
  38     end
  39   end
  40 end