finish cleaning up Cache.Hash

Author: boydm

CHANGELOG.md

@@ -13,7 +13,7 @@
 * Add Graph.modify/3 with a finder function
 * Rename Cache.request_notification/1 -> Cache.subscribe/1
 * Rename Cache.stop_notification/1 -> Cache.unsubscribe/1
-
+* General cleanup of Scenic.Cache.Hash. Some functions removed. Some function signatures changed.
 
 ## 0.8.0
 

lib/scenic/cache/hash.ex

@@ -5,13 +5,33 @@
 
 defmodule Scenic.Cache.Hash do
   @moduledoc """
-  Ssimple functions to load a file, following the hashing rules
+  Helper functions to work with hash signatures.
+
+  Both the [`Cache.File`](Scenic.Cache.File.html) and [`Cache.Term`](Scenic.Cache.Term.html)
+  modules use cryptographic hash signatures to verify that files are valid before using
+  the data they contain.
+
+  This modules provides a collection of helper functions that make it easy to use, generate
+  and validate these hashes.
+
+  Any time one of these functions asks for a type of hash, the supported types are:
+  `:sha`, `:sha224`, `:sha256`, `:sha384`, `:sha512`, and `:ripemd160`
   """
-  #  import IEx
 
   @hash_types [:sha, :sha224, :sha256, :sha384, :sha512, :ripemd160]
   @default_hash :sha
 
+  @type hash_type ::
+          :sha
+          | :sha224
+          | :sha256
+          | :sha384
+          | :sha512
+          | :ripemd160
+
+  @type type_error :: {:error, :invalid_hash_type}
+  @type hash_error :: {:error, :hash_failure}
+
   # ===========================================================================
   defmodule Error do
     @moduledoc false
@@ -20,40 +40,56 @@ defmodule Scenic.Cache.Hash do
   end
 
   # --------------------------------------------------------
+  @doc false
+  @deprecated "Cache.valid_hash_types/0 will be removed in 0.10.0"
   @spec valid_hash_types() :: [:ripemd160 | :sha | :sha224 | :sha256 | :sha384 | :sha512, ...]
   def valid_hash_types(), do: @hash_types
+
   # --------------------------------------------------------
-  @spec valid_hash_type?(any()) :: boolean()
-  def valid_hash_type?(hash_type), do: Enum.member?(@hash_types, hash_type)
+  @spec valid_hash_type?(type :: hash_type) :: boolean()
+  defp valid_hash_type?(type), do: Enum.member?(@hash_types, type)
+
   # --------------------------------------------------------
-  @spec valid_hash_type!(any()) :: any() | no_return
-  def valid_hash_type!(hash_type) do
-    case Enum.member?(@hash_types, hash_type) do
+  @spec valid_hash_type!(type :: hash_type) :: hash_type | no_return
+  defp valid_hash_type!(type) do
+    case Enum.member?(@hash_types, type) do
       true ->
-        hash_type
+        type
 
       false ->
-        msg = "Invalid hash type: #{hash_type}\r\n" <> "Must be one of: #{inspect(@hash_types)}"
+        msg = "Invalid hash type: #{type}\r\n" <> "Must be one of: #{inspect(@hash_types)}"
         raise Error, message: msg
     end
   end
 
   # --------------------------------------------------------
-  @spec binary(any(), any()) :: {:error, :invalid_hash_type} | {:ok, binary()}
-  def binary(data, hash_type) do
-    case valid_hash_type?(hash_type) do
-      true -> {:ok, hash_type |> :crypto.hash(data) |> Base.url_encode64(padding: false)}
+  @doc """
+  Calculate the hash of binary data
+
+  Returns the hash wrapped in a `{:ok, hash}` tuple.
+  """
+  @spec binary(data :: binary, type :: hash_type) :: {:ok, bitstring()} | type_error
+  def binary(data, type) do
+    case valid_hash_type?(type) do
+      true -> {:ok, type |> :crypto.hash(data) |> Base.url_encode64(padding: false)}
       false -> {:error, :invalid_hash_type}
     end
   end
 
-  def binary!(data, hash_type) do
-    valid_hash_type!(hash_type)
+  @doc """
+  Calculate the hash of binary data
+
+  Returns the hash directly.
+  """
+  @spec binary!(data :: binary, type :: hash_type) :: bitstring()
+  def binary!(data, type) do
+    valid_hash_type!(type)
     |> :crypto.hash(data)
     |> Base.url_encode64(padding: false)
   end
 
   # --------------------------------------------------------
+  @spec file(path :: bitstring, type :: hash_type) :: {:ok, bitstring()} | type_error
   def file(path, hash_type) do
     do_compute_file(
       path,
@@ -62,6 +98,7 @@ defmodule Scenic.Cache.Hash do
     )
   end
 
+  @spec file!(path :: bitstring, type :: hash_type) :: bitstring()
   def file!(path, hash_type) do
     # start the hash context
     hash_context =
@@ -103,6 +140,13 @@ defmodule Scenic.Cache.Hash do
   end
 
   # --------------------------------------------------------
+  @doc """
+  Verify that the given data conforms to the given hash.
+
+  If the verification passes, returns `{:ok, data}`
+  If it fails, returns `{:error, :hash_failure}`
+  """
+  @spec verify(data :: binary, hash :: bitstring, type :: hash_type) :: {:ok, binary} | hash_error
   def verify(data, hash, hash_type) do
     case binary(data, hash_type) do
       {:ok, ^hash} -> {:ok, data}
@@ -111,6 +155,13 @@ defmodule Scenic.Cache.Hash do
   end
 
   # --------------------------------------------------------
+  @doc """
+  Verify that the given data conforms to the given hash.
+
+  If the verification passes, returns the data unchanged.
+  If it fails, raises an error
+  """
+  @spec verify!(data :: binary, hash :: bitstring, type :: hash_type) :: binary | no_return
   def verify!(data, hash, hash_type) do
     case binary!(data, hash_type) == hash do
       true -> data
@@ -119,9 +170,13 @@ defmodule Scenic.Cache.Hash do
   end
 
   # --------------------------------------------------------
-  def verify_file(path_data), do: path_params(path_data) |> do_verify_file()
+  @doc """
+  Verify that the data in a file conforms to the given hash.
 
-  defp do_verify_file({path, hash, hash_type}) do
+  If the verification passes, returns `{:ok, hash}`
+  If it fails, returns `{:error, :hash_failure}`
+  """
+  def verify_file(path, hash, hash_type) do
     case file(path, hash_type) do
       {:ok, computed_hash} ->
         case computed_hash == hash do
@@ -135,42 +190,46 @@ defmodule Scenic.Cache.Hash do
   end
 
   # --------------------------------------------------------
-  def verify_file!(path_data), do: path_params(path_data) |> do_verify_file!()
+  @doc """
+  Verify that the data in a file conforms to the given hash.
 
-  defp do_verify_file!({path, hash, hash_type}) do
+  If the verification passes, returns the hash unchanged.
+  If it fails, raises an error
+  """
+  def verify_file!(path, hash, hash_type) do
     case file!(path, hash_type) == hash do
       true -> hash
       false -> raise Error
     end
   end
 
-  # --------------------------------------------------------
-  def from_path(path) do
-    path
-    |> String.split(".")
-    |> List.last()
-  end
+  # # --------------------------------------------------------
+  # defp from_path(path) do
+  #   path
+  #   |> String.split(".")
+  #   |> List.last()
+  # end
 
-  # --------------------------------------------------------
-  def path_params(path)
+  # # --------------------------------------------------------
+  # defp path_params(path)
 
-  def path_params(path) when is_bitstring(path) do
-    hash = from_path(path)
-    path_params({path, hash, @default_hash})
-  end
+  # defp path_params(path) when is_bitstring(path) do
+  #   hash = from_path(path)
+  #   path_params({path, hash, @default_hash})
+  # end
 
-  def path_params({path, hash_type}) when is_atom(hash_type) do
-    hash = from_path(path)
-    path_params({path, hash, hash_type})
-  end
+  # defp path_params({path, hash_type}) when is_atom(hash_type) do
+  #   hash = from_path(path)
+  #   path_params({path, hash, hash_type})
+  # end
 
-  def path_params({path_or_data, hash}), do: path_params({path_or_data, hash, @default_hash})
+  # defp path_params({path_or_data, hash}), do: path_params({path_or_data, hash, @default_hash})
 
-  def path_params({path_or_data, hash, hash_type})
-      when is_binary(path_or_data) and is_bitstring(hash) and is_atom(hash_type) do
-    {path_or_data, hash, valid_hash_type!(hash_type)}
-  end
+  # defp path_params({path_or_data, hash, hash_type})
+  #     when is_binary(path_or_data) and is_bitstring(hash) and is_atom(hash_type) do
+  #   {path_or_data, hash, valid_hash_type!(hash_type)}
+  # end
 
-  def path_params(path_or_data, hash_or_type), do: path_params({path_or_data, hash_or_type})
-  def path_params(path_or_data, hash, hash_type), do: path_params({path_or_data, hash, hash_type})
+  # defp path_params(path_or_data, hash_or_type), do: path_params({path_or_data, hash_or_type})
+  # defp path_params(path_or_data, hash, hash_type), do: path_params({path_or_data, hash, hash_type})
 end