Haytni v0.0.1 Haytni.ConfirmablePlugin View Source

This plugin ensure that email addresses given by users are valid by sending them an email containing an unique token that they have to return back in order to really be able to use (unlock) their account.

On an email address change, it also warns the user by sending an email to the previous address and requests a confirmation, same as registering, to active in order to validate the change.

Fields:

  • confirmed_at (datetime@utc, nullable, default: NULL): when the account was confirmed else NULL
  • confirmation_sent_at (datetime@utc): when the confirmation was sent
  • confirmation_token (string, nullable, unique, default: NULL): the token to be confirmed if any pending confirmation (else NULL)
  • unconfirmed_email (string, nullable, default: NULL): on email change the new email is stored here until its confirmation

Configuration:

  • reconfirmable (default: true): any email changes have to be confirmed to be applied. Until confirmed, new email is stored in unconfirmed_email column, and copied to email column on successful confirmation
  • confirmation_keys (default: ~W[email]a): the key(s) to be matched before sending a new confirmation
  • confirm_within (default: {3, :day}): delay after which confirmation token is considered as expired (ie the user has to ask for a new one)

Routes:

  • confirmation_path (actions: show, new/create)

Link to this section Summary

Functions

Confirms an account from its (confirmation) token

Has the given user been confirmed?

Extract (early) the user from the HTTP request (http authentification, cookies/session, …)

Invoked when an authentification failed (wrong password). It receives the concerned account and a Keyword to return after updating it if any change have to be done to this user

This callback is invoked when a user (manually) log out. Its purpose is mainly to do some cleanup like removing a cookie

Invoked when an authentification is successful. Like on_failed_authentification/2, it receives the current user and a Keyword to return after updating it if you want to bring any change to this user to the database

Resend confirmation instructions to an email address (requested by its owner)

Same as validate_create_registration but registration’s edition as logic between the two may be completely different

Link to this section Functions

Link to this function confirm(token) View Source
confirm(token :: String.t()) :: struct() | {:error, String.t()} | no_return()

Confirms an account from its (confirmation) token.

Returns {:error, reason} if token is expired or invalid else the (updated) user.

Raises if the user could not be updated.

Link to this function confirm_within(default \\ {3, :day}) View Source
Link to this function confirmation_keys(default \\ ~W"email"a) View Source
Link to this function confirmation_token_length(default \\ 32) View Source
Link to this function confirmed?(struct) View Source
confirmed?(user :: struct()) :: boolean()

Has the given user been confirmed?

Extract (early) the user from the HTTP request (http authentification, cookies/session, …).

Returns a tuple of the form {conn, user} with user being nil if no user could be found at this early stage.

Callback implementation for Haytni.Plugin.find_user/1.

Link to this function on_failed_authentification(user, keywords) View Source

Invoked when an authentification failed (wrong password). It receives the concerned account and a Keyword to return after updating it if any change have to be done to this user.

For example, you can use it as follows to count the number of failed attempts to login:

def on_failed_authentification(user = %_{}, keyword) do
  Keyword.put(keyword, :failed_attempts, user.failed_attempts + 1)
end

Note: we choose to use and pass keyword as an accumulator to let the possibility to plugins to deal themselves on a conflict (several different plugins which want to alter a same field). Even if Keyword allows a same key to be defined several times, you’ll probably don’t want it to happen as the last defined value for a given key will (silently) override the others.

Callback implementation for Haytni.Plugin.on_failed_authentification/2.

This callback is invoked when a user (manually) log out. Its purpose is mainly to do some cleanup like removing a cookie.

Callback implementation for Haytni.Plugin.on_logout/1.

Link to this function on_successful_authentification(conn, user, keywords) View Source

Invoked when an authentification is successful. Like on_failed_authentification/2, it receives the current user and a Keyword to return after updating it if you want to bring any change to this user to the database.

To continue our example with a failed attempts counter, on a successful authentification it may be a good idea to reset it in this scenario:

def on_successful_authentification(conn = %Plug.Conn{}, user = %_{}, keywords) do
  {conn, user, Keyword.put(keywords, :failed_attempts, 0)}
end

Callback implementation for Haytni.Plugin.on_successful_authentification/3.

Link to this function reconfirmable(default \\ true) View Source
Link to this function resend_confirmation_instructions(confirmation) View Source
resend_confirmation_instructions(confirmation :: Haytni.Confirmation.t()) ::
  {:ok, struct()} | {:error, :no_match | :already_confirmed} | no_return()

Resend confirmation instructions to an email address (requested by its owner).

Returns:

  • {:error, :no_match} if there is no account matching confirmation_keys
  • {:error, :already_confirmed} if the account is not pending confirmation
  • {:ok, user} if successful

Raises if user couldn’t be updated.

Link to this function validate_update_registration(changeset) View Source

Same as validate_create_registration but registration’s edition as logic between the two may be completely different.

Callback implementation for Haytni.Plugin.validate_update_registration/1.