Added readme, added deny_all_test, add behaviour for hooks

Author: zmoshansky

README.md

@@ -1,40 +1,49 @@
-[Aeacus - The holder of keys](https://en.wikipedia.org/wiki/Aeacus)
+[Echo - ECHO Echo echo...](https://en.wikipedia.org/wiki/Echo_(mythology))
 ======
 
-A simple, secure, and highly configurable Elixir identity [username | email | id | etc.]/password authentication module to use with Ecto.
+A simple & highly extendable, meta-notification system; Echo checks notification preferences & dispatch notifications to different adapters (ex. email, logger, analytics, sms, etc.).
 
-[![Build Status](https://travis-ci.org/zmoshansky/aeacus.svg)](https://travis-ci.org/zmoshansky/aeacus) [![Hex.pm](http://img.shields.io/hexpm/v/aeacus.svg)](https://hex.pm/packages/aeacus) [![Hex.pm](http://img.shields.io/hexpm/dt/aeacus.svg)](https://hex.pm/packages/aeacus) [![Github Issues](http://githubbadges.herokuapp.com/zmoshansky/aeacus/issues.svg)](https://github.com/zmoshansky/aeacus/issues) [![Pending Pull-Requests](http://githubbadges.herokuapp.com/zmoshansky/aeacus/pulls.svg)](https://github.com/zmoshansky/aeacus/pulls)
+[![Build Status](https://travis-ci.org/zmoshansky/echo.svg)](https://travis-ci.org/zmoshansky/echo) [![Hex.pm](http://img.shields.io/hexpm/v/echo.svg)](https://hex.pm/packages/echo) [![Hex.pm](http://img.shields.io/hexpm/dt/echo.svg)](https://hex.pm/packages/echo) [![Github Issues](http://githubbadges.herokuapp.com/zmoshansky/echo/issues.svg)](https://github.com/zmoshansky/echo/issues) [![Pending Pull-Requests](http://githubbadges.herokuapp.com/zmoshansky/echo/pulls.svg)](https://github.com/zmoshansky/echo/pulls)
 
 #### Description ####
-Aeacus only performs authentication, making it well suited for integration with session storage, or a token system; like [Guardian](https://github.com/hassox/guardian). Alternatively, this could be used directly over a secure (HTTPS) connection with [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication); But, it is highly discouraged as there is a greater security risk, due to repeatedly sending your authentication information to the server, only relying on TLS for security.
-
-#### Requirements ####
-Aeacus requires that you have an Ecto model that has UNIQUE(identity_field) and password_field. These fields can be configured to easily match your schema, whether it be `username`, `email`, or `pass`, `password`, `hash`, `hashed_password`, etc. Of course, the passwords must be stored using the same crypto system as Aeacus; The password should be salted and hashed, plaintext is heavily discouraged. See the tests for examples.
+Echo is designed to be highly adaptable to your notification needs through different adapters and per adapter hooks. A notification is dispatched with `Echo.notify/2` which then calls on each registered adapter, requesting that it delivers the notification. Each adapter is passed an `event_type`, of your designation, and `data` that it may use to deliver the notification.
 
 #### Config ####
-You must set the `:repo` and `:model` for Aeacus. The other options have sane defaults.
+Echo is easible configured, a possible sample configuration is given below. Custom Preferences & Adapters are easy to build, look at `lib/echo/adapters/email` & `test/support/test_preferences.ex` for examples. Hooks allow you to specify the module which implements `@behaviour Echo.Hooks`, which generates the adapter specific data needed to deliver a notification (see `test/support/email_hook` for an example); this might include: selecting the correct template, parsing data, or even nothing at all. Doing nothing allows unknown event types to be skipped by adapters.
 
 ```
-config :aeacus, Aeacus,
-  repo: MyApp.Repo,
-  model: MyApp.User,
-  # Optional, The following are the default options
-  crypto: Comeonin.Pbkdf2,
-  identity_field: :email,
-  password_field: :hashed_password,
-  error_message: "Invalid identity or password."
+config :echo, Echo,
+  preferences: Echo.Preferences.AllowAll,
+  adapters: [Echo.Adapters.Logger, Echo.Adapters.Email, YourApp.CustomAdapter],
+  hooks: %{
+    email: YourApp.EmailHook
+  }
 ```
 
-#### Example Session Controller ####
-`Aeacus.Authenticator.authenticate` expects a `Map` with keys `:identity`, and `:password`. Alternatively, `Aeacus.Authenticator.authenticate_resource` can be used if a resource is already loaded.
+#### Architecture ####
+Echo is somewhat like a pub-sub system; events are published, and adapters that are capable of handling them dispatch the notification accordingly. The intended flow is:
+
+- `preferences` module provides an ACL to check whether an event should be delivered on a particular adapter according to a user's preferences (ex. deny newsletters, but allow billing emails).
+- `hooks` provide a way to prepare arguments to an adapter based on the `event_type` & `data`. A hook can prevent it's adapter from delivering the notification if no data is returned. This means notifications are only sent for adapters that are configured to handle them, otherwise, they are harmlessly disregarded by that adapter.
 
+ex.) In the code below, an email is sent for `:user_register`, but not `:log_analytics`; `Adapter.Email` will harmlessly skip it as an `:unknown_event`.
+```
+Echo.notify(:log_analytics, data)
+...
+Echo.notify(:user_register, data)
 ```
-defmodule MyApp.SessionController do
-  def create(conn, params) do
-    case Aeacus.Authenticator.authenticate %{identity: params[:email], password: params[:pass]} do
-      {:ok, user} -> CreateTokenOrCookie
-      {:error, message} -> DisplayAuthenticationScreenAgain
+```
+defmodule App.EmailHook
+@behaviour Echo.Hooks
+
+  def message(event_type, data) do
+    ...
+    template = case event_type do
+      :user_register -> "emails/register.html.eex"
+      :user_forgot_password -> "emails/forgot_password.html.eex"
+      _ -> nil
     end
+    ...
   end
 end
-```
+```

config/config.exs

@@ -13,10 +13,9 @@ config :logger, :console,
   format: "$date $time [$level] $metadata$message\n",
   metadata: [:user_id]
 
-# It is also possible to import configuration files, relative to this
-# directory. For example, you can emulate configuration per environment
-# by uncommenting the line below and defining dev.exs, test.exs and such.
-# Configuration from the imported file will override the ones defined
-# here (which is why it is important to import them last).
-#
-import_config "#{Mix.env}.exs"
+config :echo, Echo,
+  preferences: Echo.Preferences.Test,
+  adapters: [Echo.Adapters.Logger, Echo.Adapters.Email],
+  hooks: %{
+    email: Echo.Test.EmailHook
+  }

config/dev.exs

@@ -11,13 +11,14 @@ defmodule Echo do
   @doc """
   Merges the application config with the default configuration options specified by Echo.
   """
-  @spec config() :: List.t
+  @spec config() :: Map.t
   def config do
-    default_config Application.get_env(:echo, Echo)
+    Map.merge @default_config, Enum.into(Application.get_env(:echo, Echo), %{})
   end
 
   @doc """
-  Notify calls dispatch/2 on each adapter, which checks preferences then sends notification.
+  Notify calls dispatch/2 on each registered adapter, which checks preferences then sends notification.
+
   A List of tuples is returned of the form {:ok, __MODULE__} or {:error, __MODULE__, term | String.t}
   indicating the status of each call.
   """
@@ -27,13 +28,4 @@ defmodule Echo do
       Enum.map Echo.config[:adapters], fn(adapter) -> adapter.dispatch(event_type, data) end
     end
   end
-
-
-  @spec default_config(Map.t) :: Map.t
-  defp default_config(configuration) do
-    case Enum.empty?(configuration) do
-      true -> @default_config
-      false -> Map.merge @default_config, Enum.into(configuration, %{})
-    end
-  end
-end
+end

config/test.exs

@@ -1,11 +1,13 @@
 defmodule Echo.Adapters.Behaviour do
   use Behaviour
 
-  defcallback notify(term | String.t | nil, Map.t | nil) :: {:ok, term, any} | {:error, term, term | String.t}
+  defcallback notify(term | String.t | nil, any) :: {:ok, term, any} | {:error, term, term | String.t}
 
   @doc false
   defmacro __using__(_opts) do
     quote do
+      @behaviour Echo.Adapters.Behaviour
+
       @spec dispatch(term | String.t | nil, Map.t | nil) :: Tuple.t
       def dispatch(event_type, data) do
         if Echo.config[:preferences].notification_allowed?(__MODULE__, event_type, data) do

lib/echo.ex

@@ -6,13 +6,14 @@ defmodule Echo.Adapters.Email do
   See Adapter Project page for up-to-date details.
 
   ex.)
+  ```
     {:echo, "~> x.x.x"}
     {:mailman, "~> x.x.x"},
     {:eiconv, github: "zotonic/eiconv"}
+  ```
   """
   use Echo.Adapters.Behaviour
 
-
   def notify(event_type, data) do
     config = Echo.config.hooks[:email].config(event_type, data)
     message = Echo.config.hooks[:email].message(event_type, data)

lib/echo/adapters/behaviour.ex

@@ -0,0 +1,8 @@
+defmodule Echo.Hooks do
+  @moduledoc """
+  message/2 must be implemented, returning the data for an adapter to deliver a notification.
+  """
+  use Behaviour
+
+  defcallback message(term | String.t | nil, any) :: any
+end

lib/echo/adapters/email.ex

@@ -4,7 +4,7 @@ defmodule Echo.Mixfile do
   def project do
     [
       app: :echo,
-      version: "0.0.1",
+      version: "0.1.0",
       elixir: "~> 1.0",
       elixirc_paths: elixirc_paths(Mix.env),
       description: description,
@@ -36,9 +36,10 @@ defmodule Echo.Mixfile do
 
   defp deps do
     [
-      {:ex_doc, ">=0.1.0", only: [:test]},
+      {:ex_doc, ">=0.1.0", only: [:dev, :test]},
+        {:earmark, ">= 0.0.0", only: [:dev, :test]},
       {:mailman, "~> 0.2.0", only: [:test]},
-        {:eiconv, github: "zotonic/eiconv", only: [:test]},
+        {:eiconv, github: "zotonic/eiconv", only: [:test]}
     ]
   end
 
@@ -53,7 +54,9 @@ defmodule Echo.Mixfile do
 
   defp description do
     """
-      A basic notification dispatch system, composed from many adapters. Useful for email, sms, analytics, logs, etc.
+      A simple & highly extendable, meta-notification system; Echo checks
+      notification preferences & dispatch notifications to different adapters
+      (ex. email, logger, analytics, sms, etc.)
     """
   end
 

lib/echo/hooks.ex

@@ -0,0 +1,13 @@
+defmodule Echo.Preferences.DenyAllTest do
+  use ExUnit.Case
+
+  test "notification_allowed?/2 always returns true" do
+    refute Echo.Preferences.DenyAll.notification_allowed? :foo, %{}
+    refute Echo.Preferences.DenyAll.notification_allowed? nil, nil
+  end
+
+  test "notification_allowed?/3 always returns true" do
+    refute Echo.Preferences.DenyAll.notification_allowed? :foo, :bar, %{}
+    refute Echo.Preferences.DenyAll.notification_allowed? :nil, nil, nil
+  end
+end

mix.exs

@@ -1,4 +1,5 @@
 defmodule Echo.Test.EmailHook do
+  @behaviour Echo.Hooks
 
   # TODO - Remove pending deletion in Mailman
   def config(_event_type, _data) do