View Source Rolex.DSL (Rolex v0.5.0)

Implements a small domain-specific language ("DSL") for scoping permissions.

The DSL is defined by a handful of keyword options:

  • :role - a plain atom naming the role
  • :to - specifies the subject scope; i.e. "who holds the role?"
  • :on - specifics the object scope; i.e. "on which resources does the role apply?

When revoking permissions, from is used in place of to, because it reads more naturally.

Subject and object scopes are specified using any of these values:

  • :all - a special atom for granting or denying ALL of something
  • any Ecto schema module; e.g. MyApp.Users.User
  • any Ecto schema record; e.g. %MyApp.Users.User{id: 123}

Summary

Functions

Returns a changeset for DSL options used to perform action.

Returns a changeset for options used when filtering permissions.

Returns a changeset for DSL options used when granting or denying permissions.

Returns a changeset for options used when revoking permissions.

Returns a new Rolex.DSL initialized from input on success, or {:error, reason} otherwise.

Converts input from external DSL options to internal Rolex.Permission schema params.

Types

@type action() :: :grant | :deny | :revoke | :filter
@type any_from_opt() :: {:from, any_scope()}
@type any_on_opt() :: {:on, any_scope()}
@type any_role() :: :any | role()
@type any_role_opt() :: {:role, any_role()}
@type any_scope() :: :any | {:any, schema()} | scope()
@type any_to_opt() :: {:to, any_scope()}
@type changeset() :: Ecto.Changeset.t(t())
@type filter_option() ::
  {:role, :any | role()} | {:to, :any | scope()} | {:on, :any | scope()}
@type from_opt() :: {:from, scope()}
@type on_opt() :: {:on, scope()}
@type record() :: Ecto.Schema.t()
@type revoke_option() ::
  {:role, :any | role()} | {:from, :any | scope()} | {:on, :any | scope()}
@type role() :: atom()
@type role_opt() :: {:role, role()}
@type schema() :: module()
@type scope() :: :all | schema() | record()
@type t() :: %Rolex.DSL{from: scope(), on: scope(), role: role(), to: scope()}
@type to_opt() :: {:to, scope()}

Functions

@spec changeset(
  action(),
  keyword()
) :: changeset()

Returns a changeset for DSL options used to perform action.

Action may be any of :grant, :deny, :revoke, :filter.

Link to this function

changeset_for_filter(opts)

View Source
@spec changeset_for_filter([any_role_opt() | any_to_opt() | any_on_opt()]) ::
  changeset()

Returns a changeset for options used when filtering permissions.

Options:

  • :role - a plain atom naming a role, or:
    • :any - will match any permission role
  • :to - :all, schema, record, or:
    • :any - will match any permission subject
    • {:any, <schema>} - will match any permission subject of the named schema
  • :on - :all, schema, record, or:
    • :any - will match any permission object
    • {:any, <schema>} - will match any permission object of the named schema
Link to this function

changeset_for_grant_or_deny(opts)

View Source
@spec changeset_for_grant_or_deny([role_opt() | to_opt() | on_opt()]) :: changeset()

Returns a changeset for DSL options used when granting or denying permissions.

Options:

  • :role - a plain atom naming a role
  • :to - :all, schema, or record
  • :on - :all, schema, or record
Link to this function

changeset_for_revoke(opts)

View Source
@spec changeset_for_revoke([any_role_opt() | any_from_opt() | any_on_opt()]) ::
  changeset()

Returns a changeset for options used when revoking permissions.

Options:

  • :role - a plain atom naming a role, or:
    • :any - will match any permission role
  • :from - :all, schema, record, or:
    • :any - will match any permission subject
    • {:any, <schema>} - will match any permission subject of the named schema
  • :on - :all, schema, record, or:
    • :any - will match any permission object
    • {:any, <schema>} - will match any permission object of the named schema

Returns a new Rolex.DSL initialized from input on success, or {:error, reason} otherwise.

Link to this function

to_permission_params(input)

View Source
@spec to_permission_params(t() | Enumerable.t()) :: map() | {:error, term()}

Converts input from external DSL options to internal Rolex.Permission schema params.

Returns an atom-keyed map on success, or an {:error, reason} tuple otherwise.