@callback authorization_module() :: Permit.Types.authorization_module()

Configures the controller with the application's authorization configuration.

example

Example

@impl Permit.Phoenix.Controller
def authorization_module, do: MyApp.Authorization

# Requires defining an authorization configuration module
defmodule MyApp.Authorization, do:
  use Permit, permissions_module: MyApp.Permissions

@callback except() :: [Permit.Types.action_group()]

Allows opting out of using Permit for given controller actions.

Defaults to [], thus by default all actions are guarded with Permit.

@callback fallback_path(Permit.Types.action_group(), Permit.Phoenix.Types.conn()) ::
  binary()

If handle_unauthorized/2 is not defined, sets the fallback path to which the user is redirected on authorization failure.

Defaults to /.

@callback fetch_subject(Permit.Phoenix.Types.conn()) :: Permit.Types.subject()

Retrieves the current user from conn as the authorization subject. Defaults to conn.assigns[:current_user].

example

Example

@impl true
def fetch_subject(%{assigns: assigns}) do
  assigns[:user]
end

@callback handle_unauthorized(Permit.Types.action_group(), Permit.Phoenix.Types.conn()) ::
  Permit.Phoenix.Types.conn()

Called when authorization on an action or a loaded record is not granted. Must halt conn after rendering or redirecting.

example

Example

defmodule MyApp.CommentController do
  use Permit.Phoenix.Controller,
    authorization_module: MyApp.Authorization
    resource_module: MyApp.Blog.Comment

  @impl true
  def handle_unauthorized(action, conn) do
    case get_format(conn) do
      "json" ->
        # render a 4xx JSON response

      "html" ->
        # handle HTML response, e.g. redirect
    end
  end
end

@callback id_param_name(Permit.Types.action_group(), Permit.Phoenix.Types.conn()) ::
  binary()

Sets the name of the ID param that will be used for preloading a record for authorization.

Defaults to "id". If the route contains a different name of the record ID param, it should be changed accordingly.

@callback id_struct_field_name(Permit.Types.action_group(), Permit.Phoenix.Types.conn()) ::
  atom()

Sets the name of the field that contains the resource's ID which should be looked for.

Defaults to :id. If the record's ID (usually a primary key) is in a different field, then it should be changed accordingly.

@callback loader(Permit.Types.resolution_context()) :: Permit.Types.object() | nil

If Permit.Ecto is not used, it allows defining a loader function that loads a record or a list of records, depending on action type (singular or plural).

example

Example

@impl true
def loader(%{action: :index, params: %{page: page}}),
  do: ItemContext.load_all(page: page)

def loader(%{action: :show}, params: %{id: id}),
  do: ItemContext.load(id)

@callback preload_actions() :: [Permit.Types.action_group()]

Declares which actions in the controller are to use Permit's automatic preloading and authorization in addition to defaults: [:show, :edit, :update, :delete, :index].

Defaults to [], which means that [:show, :edit, :update, :delete, :index] and no other actions will use preloading.

@callback resource_module() :: Permit.Types.resource_module()

Declares the controller's resource module. For instance, when Phoenix and Ecto is used, typically for an ArticleController the resource will be an Article Ecto schema.

This resource module, along with the controller action name, will be used for authorization checks before each action.

If Permit.Ecto is used, this setting selects the Ecto schema which will be used for automatic preloading a record for authorization.

example

Example

defmodule MyApp.ArticleController do
  use Permit.Phoenix.Controller

  def authorization_module, do: MyApp.Authorization

  def resource_module, do: MyApp.Article

  # Alternatively, you can do the following:

  use Permit.Phoenix.Controller,
    authorization_module: MyApp.Authorization,
    resource_module: MyApp.Blog.Article
end