better authorization interface

Author: pezra

lib/exhal/authorizer.ex

@@ -9,11 +9,27 @@ defprotocol ExHal.Authorizer do
   """
   @type url :: String.t()
 
+  @typedoc """
+  An object that implements the ExHal.Authorizer protocol.
+  """
+  @type authorizer :: any()
+
+  @typedoc """
+  Name of a HTTP header field.
+  """
+  @type header_field_name :: String.t
+
   @doc """
-  Returns `{:ok, credentials}` if the authorizer
-  knows the resource and has credentials for it. Otherwise, returns
-  `:no_auth`.
+
+  Called before each request to calculate any header fields needed to
+  authorize the request. A common return would be
+
+      %{"Authorization" => "Bearer <sometoken>"}
+
+  If the URL is unrecognized or no header fields are appropriate or
+  needed this function should return and empty map.
+
   """
-  @spec authorization(any, url()) :: {:ok, credentials()} | :no_auth
+  @spec authorization(authorizer, url()) :: %{optional(header_field_name()) => String.t()}
   def authorization(authorizer, url)
 end

lib/exhal/client.ex

@@ -146,7 +146,7 @@ defmodule ExHal.Client do
     headers =
       client.headers
       |> merge_headers(normalize_headers(local_headers))
-      |> merge_headers(auth_headers(client, url))
+      |> merge_headers(Authorizer.authorization(client.authorizer, url))
 
     poison_opts = merge_poison_opts(client.opts, local_opts)
 
@@ -191,11 +191,4 @@ defmodule ExHal.Client do
   defp normalize_headers(headers) do
     Enum.into(headers, %{}, fn {k, v} -> {to_string(k), v} end)
   end
-
-  defp auth_headers(client, url) do
-    case Authorizer.authorization(client.authorizer, url) do
-      :no_auth -> %{}
-      {:ok, auth} -> %{"Authorization" => auth}
-    end
-  end
 end

lib/exhal/null_authorizer.ex

@@ -10,5 +10,5 @@ defmodule ExHal.NullAuthorizer do
 end
 
 defimpl ExHal.Authorizer, for: ExHal.NullAuthorizer do
-  def authorization(_authorizer, _url), do: :no_auth
+  def authorization(_authorizer, _url), do: %{}
 end

lib/exhal/simple_authorizer.ex

@@ -18,9 +18,9 @@ defimpl ExHal.Authorizer, for: ExHal.SimpleAuthorizer do
     url
     |> String.starts_with?(authorizer.url_prefix)
     |> if do
-      {:ok, authorizer.authorization}
+      %{"Authorization" =>  authorizer.authorization}
     else
-      :no_auth
+      %{}
     end
   end
 end

test/exhal/null_authorizer_test.exs

@@ -7,7 +7,7 @@ defmodule ExHal.NullAuthorizerTest do
   end
 
   test ".authorization/2" do
-    assert :no_auth = Authorizer.authorization(null_authorizer_factory(), "http://example.com")
+    assert %{} == Authorizer.authorization(null_authorizer_factory(), "http://example.com")
   end
 
   defp null_authorizer_factory() do

test/exhal/simple_authorizer_test.exs

@@ -8,17 +8,17 @@ defmodule ExHal.SimpleAuthorizerTest do
 
   describe ".authorization/2" do
     test "alien resource" do
-      assert :no_auth =
-               Authorizer.authorization(simple_authorizer_factory(), "http://malware.com")
+      assert %{} ==
+        Authorizer.authorization(simple_authorizer_factory(), "http://malware.com")
     end
 
     test "subtly alien resource" do
-      assert :no_auth =
-               Authorizer.authorization(simple_authorizer_factory(), "http://mallory.example.com")
+      assert %{} ==
+        Authorizer.authorization(simple_authorizer_factory(), "http://mallory.example.com")
     end
 
     test "recognized resource" do
-      assert {:ok, "Bearer hello-beautiful"} =
+      assert %{"Authorization" => "Bearer hello-beautiful"} ==
                Authorizer.authorization(
                  simple_authorizer_factory("Bearer hello-beautiful"),
                  "http://example.com/foo"