Bodyguard v2.1.1 Bodyguard.Action
Execute authorized actions in a composable way.
An Action can be built up over the course of a request, providing a means to specify authorization parameters in the steps leading up to actually executing the job.
When authorization fails, there is an opportunity to handle it using a fallback function before returning the final result.
Authorization is performed by deferring to a Bodyguard.Policy
.
Fields
context
– Context for the actionpolicy
– Implementation ofBodyguard.Policy
behaviour; defaults to thecontext
user
– The user to authorizename
– The name of the authorized actionauth_run?
– If an authorization check has been performedauth_result
– Result of the authorization checkauthorized?
– If authorization has succeeded (defaultfalse
)job
– Function to execute if authorization passes; signaturejob(action)
fallback
– Function to execute if authorization fails; signaturefallback(action)
assigns
– Generic parameters along for the ride
Controller Example
defmodule MyApp.Web.PostController do
use MyApp.Web, :controller
import Bodyguard.Action
alias MyApp.Blog
action_fallback MyApp.FallbackController
plug Bodyguard.Plug.BuildAction, context: Blog, user: &get_current_user/1
def index(conn, _) do
run conn.assigns.action, fn(action) ->
posts = Blog.list_posts(action.user)
render(conn, "index.html", posts: posts)
end
end
defp get_current_user(conn) do
# ...
end
end
Verbose Example
import Bodyguard.Action
alias MyApp.Blog
act(Blog)
|> put_user(get_current_user())
|> put_policy(Blog.SomeSpecialPolicy)
|> assign(:drafts, true)
|> authorize(:list_posts)
|> put_job(fn action ->
Blog.list_posts(action.user, drafts_only: action.assigns.drafts)
end)
|> put_fallback(fn _action -> {:error, :not_found} end)
|> run()
Summary
Functions
Initialize an Action
Put a new assign
Mark the Action as authorized, regardless of previous authorization
Mark the Action as unauthorized, regardless of previous authorization
Use the policy to perform authorization
Same as authorize/3
but raises on failure
Replace the assigns
Change the context
Change the fallback handler
Change the job to execute
Change the policy
Change the user to authorize
Execute the Action’s job
Execute the given job
Execute the given job and fallback
Execute the job, raising on failure
Execute the given job, raising on failure
Types
t() :: %Bodyguard.Action{assigns: assigns, auth_result: Bodyguard.Policy.auth_result | nil, auth_run?: boolean, authorized?: boolean, context: module | nil, fallback: fallback | nil, job: job | nil, name: atom | nil, policy: module | nil, user: any}
Functions
Initialize an Action.
The context
is assumed to implement Bodyguard.Policy
callbacks. To
specify a unique policy, use put_policy/2
.
The Action is considered unauthorized by default, until authorization is run.
Mark the Action as authorized, regardless of previous authorization.
Mark the Action as unauthorized, regardless of previous authorization.
Use the policy to perform authorization.
The opts
are merged in to the Action’s assigns
and passed as the
params
.
See Bodyguard.permit/3
for details.
Change the fallback handler.
Execute the Action’s job.
The job
must have been previously assigned using put_job/2
.
If authorized, the job is run and its value is returned.
If unauthorized, and a fallback has been provided, the fallback is run and its value returned.
Otherwise, the result of the authorization is returned (something like
{:error, reason}
).
Execute the given job.
If authorized, the job is run and its value is returned.
If unauthorized, and a fallback has been provided, the fallback is run and its value returned.
Otherwise, the result of the authorization is returned (something like
{:error, reason}
).
Execute the given job and fallback.
If authorized, the job is run and its value is returned.
If unauthorized, the fallback is run and its value returned.
Execute the job, raising on failure.
The job
must have been previously assigned using put_job/2
.