Add uploader (#9)

tfwright · web-flow · commit a0076b45b29d · 2023-11-10T10:26:22.000-07:00
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ Then to access the file:
 
 ## concepts
 
-There are three main concepts in capsule: storage, upload, and locator
+There are four main concepts in capsule: storage, upload, and locator, and uploader.
 
 *Note: As of version 0.6 Capsule all built-in storages and uploads except for Locator have been moved to [elixir-capsule/supplement](https://github.com/elixir-capsule/supplement).*
 
@@ -76,6 +76,32 @@ Note: you'll still need to take care of cleaning up the old file:
 
 `YourStorage.delete(old_file_data.id)`
 
+### uploader
+
+This helper was added in order to support DRYing up storage access. In most apps, there are certain types of assets that will be uploaded and handled in a similar, if not the same way, if only when it comes to where they are stored. You can `use` the uploader to codify the handling for specific types of assets.
+
+```
+defmodule AvatarUploader do
+  use Capsule.Uploader, storages: [cache: Disk, store: S3]
+
+  def storage_options(upload, :cache, opts) do
+    Keyword.put(opts, :prefix, "cache/#{Date.utc_today()}")
+  end
+
+  def storage_options(upload, :store, opts) do
+    opts
+    |> Keyword.put(:prefix, "users/#{opts[:user_id]}/avatar")
+    |> Keyword.drop(:user_id)
+  end
+
+  def build_metadata(upload, :store, _), do: [uploaded_at: DateTime.utc_now()]
+end
+```
+
+Then you can get the files where they need to be without constructing all the options everywhere they might be uploaded: `AvatarUploader.store(upload, :store, user_id: 1)`
+
+Note: as this example demonstrates, the function can receive arbitrary data and use it to customize how it builds the storage options before they are passed on.
+
 ## integrations
 
 * Ecto via [CapsuleEcto](https://github.com/elixir-capsule/capsule_ecto)
diff --git a/lib/capsule/uploader.ex b/lib/capsule/uploader.ex
@@ -0,0 +1,56 @@
+defmodule Capsule.Uploader do
+  alias Capsule.Locator
+
+  @type storage :: atom()
+  @type option :: {atom(), any()}
+
+  @callback store(any(), storage, [option]) :: {:ok, Locator.t()} | {:error, any()}
+  @callback build_options(any(), storage, [option]) :: [option]
+  @callback build_metadata(Locator.t(), storage, [option]) :: Keyword.t() | map()
+
+  defmacro __using__(opts) do
+    quote bind_quoted: [opts: opts] do
+      @behaviour Capsule.Uploader
+
+      @storages Keyword.fetch!(opts, :storages)
+
+      @impl Capsule.Uploader
+      def store(upload, storage_key, opts \\ []) do
+        storage = fetch_storage!(upload, storage_key)
+
+        upload
+        |> storage.put(build_options(upload, storage_key, opts))
+        |> case do
+          {:ok, id} ->
+            locator = Capsule.add_metadata(%Locator{id: id, storage: storage}, build_metadata(upload, storage_key, opts))
+
+            {:ok, locator}
+          error_tuple ->
+
+            error_tuple
+        end
+      end
+
+      @impl Capsule.Uploader
+      def build_metadata(_, _, _), do: []
+
+      @impl Capsule.Uploader
+      def build_options(_, _, instance_opts), do: instance_opts
+
+      defp fetch_storage!(upload, storage) do
+        @storages
+        |> case do
+          {m, f, a} -> apply(m, f, [upload | a])
+          storages when is_list(storages) -> storages
+        end
+        |> Keyword.fetch(storage)
+        |> case do
+          {:ok, storage} -> storage
+          _ -> raise "#{storage} not found in #{__MODULE__} storages. Available: #{inspect(Keyword.keys(@storages))}"
+        end
+      end
+
+      defoverridable build_options: 3, build_metadata: 3
+    end
+  end
+end
diff --git a/test/capsule/locator_test.exs b/test/capsule/locator_test.exs
@@ -10,7 +10,6 @@ defmodule Capsule.LocatorTest do
     end
   end
 
-
   describe "new/1 with map with required string keys" do
     test "returns struct" do
       assert {:ok, %Locator{}} = Locator.new(%{"id" => "fake", "storage" => "Fake"})
diff --git a/test/capsule/uploader_test.exs b/test/capsule/uploader_test.exs
@@ -0,0 +1,48 @@
+defmodule Capsule.UploaderTest do
+  use ExUnit.Case
+  doctest Capsule
+
+  alias Capsule.{Locator, Uploader}
+
+  defmodule BasicUploader do
+    use Uploader, storages: [temp: Capsule.Storages.Mock, perm: Capsule.Storages.Mock]
+  end
+
+  defmodule DynamicUploader do
+    use Uploader, storages: {__MODULE__, :get_storages, []}
+
+    def get_storages(_), do: [temp: Capsule.Storages.Mock]
+  end
+
+  describe "store/2 with basic uploader and valid storage key" do
+    setup do
+      %{result: BasicUploader.store(%Locator{id: "fake"}, :temp)}
+    end
+
+    test "succeeds", %{result: result} do
+      assert {:ok, _} = result
+    end
+
+    test "returns locator", %{result: result} do
+      assert {_, %Locator{}} = result
+    end
+  end
+
+  describe "store/2 with basic uploader invalid storage key" do
+    test "raises" do
+      assert_raise(RuntimeError, fn ->
+        BasicUploader.store(%Locator{id: "fake"}, :wrong)
+      end)
+    end
+  end
+
+  describe "store/2 with dynamic uploader and valid storage key" do
+    setup do
+      %{result: BasicUploader.store(%Locator{id: "fake"}, :temp)}
+    end
+
+    test "succeeds", %{result: result} do
+      assert {:ok, _} = result
+    end
+  end
+end
diff --git a/test/support/mock_storage.ex b/test/support/mock_storage.ex
@@ -5,7 +5,7 @@ defmodule Capsule.Storages.Mock do
 
   @impl Storage
   def put(_id, opts \\ []) do
-    {:ok, opts[:id]}
+    {:ok, Keyword.get(opts, :id, to_string(:erlang.ref_to_list(:erlang.make_ref())))}
   end
 
   @impl Storage
