calcinator

v5.0.0

calcinator v5.0.0 Calcinator View Source

Converts actions from a controller or RPC server using JSONAPI formatted params to calls on a Calcinator.Resources module.

Link to this section Summary

Types

association()
insertable_params()

Nested params format used by Ecto.Changeset.t

parameter()

The name of the parameter that was used for the query and was not found

params()

The raw request params that need to be validated as a JSONAPI document and converted to an Alembic.Document.t

rendered()

A rendered JSONAPI document as a map

t()
  • asociation_by_include - maps JSONAPI nested includes (`%{String.t => String.tmap}` to the nested associations
    (`atomKeyword.t) that are understood byresources_module`.
    • authorization_module - The module that implements the Calcinator.Authorization behaviour. Defaults to Calcinator.Authorization.Subjectless.
    • resources_module - The module that implements the Calcinator.Resources behaviour.
    • subject - the subject that is trying to do the action and needs to be authorized by authorization_module
    • view_module - The module that implements the Calcinator.View behaviour

Functions

allow_sandbox_access(state, params)
authorized(calcinator, resource_or_related)
can(calcinator, action, target)
changeset(calcinator, updatable, updatable_params)
create(state, params)

Creates resource from params

delete(state, params)

Deletes resource with "id" in params

get(calcinator, params, id_key, query_options)
get_related_resource(state, params, options)

[Gets a resource related through a relationship] (http://jsonapi.org/format/#document-resource-object-related-resource-links)

index(state, params, map)

Gets index of a resource with (optional) pagination depending on whether the state resources_module supports pagination

show(state, params)

Shows resource with the "id" in params

show_relationship(state, params, options)

Shows a relationship

update(state, params)

Updates a resource with the "id" in params

update_changeset(state, changeset, params)

Link to this section Types

Link to this type association() View Source 
association() :: atom | list | map
Link to this type insertable_params() View Source 
insertable_params() :: %{optional(String.t) => term}

Nested params format used by Ecto.Changeset.t.

Link to this type parameter() View Source 
parameter() :: String.t

The name of the parameter that was used for the query and was not found.

Link to this type params() View Source 
params() :: %{optional(String.t) => term}

The raw request params that need to be validated as a JSONAPI document and converted to an Alembic.Document.t

Link to this type rendered() View Source 
rendered() :: map

A rendered JSONAPI document as a map

Link to this type t() View Source 
t() :: %Calcinator{associations_by_include: map, authorization_module: module, ecto_schema_module: module, params: term, resources_module: module, subject: Calcinator.Authorization.subject, view_module: module}
  • asociation_by_include - maps JSONAPI nested includes (`%{String.t => String.tmap}` to the nested associations
    (`atomKeyword.t) that are understood byresources_module`.
  • authorization_module - The module that implements the Calcinator.Authorization behaviour. Defaults to Calcinator.Authorization.Subjectless.
  • resources_module - The module that implements the Calcinator.Resources behaviour.
  • subject - the subject that is trying to do the action and needs to be authorized by authorization_module
  • view_module - The module that implements the Calcinator.View behaviour.

Link to this section Functions

Link to this function allow_sandbox_access(state, params) View Source 
allow_sandbox_access(t, params) ::
  :ok |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing}
Link to this function authorized(calcinator, resource_or_related) View Source 
authorized(t, related :: nil) :: nil
authorized(t, unfiltered :: struct) :: struct
authorized(t, unfiltered :: [struct]) :: [struct]
Link to this function can(calcinator, action, target) View Source 
can(t, Calcinator.Authorization.action, Authorizaton.target) ::
  :ok |
  {:error, :unauthorized}
Link to this function changeset(calcinator, updatable, updatable_params) View Source 
changeset(t, Ecto.Schema.t, insertable_params) ::
  {:ok, Ecto.Changeset.t} |
  {:error, Ecto.Changeset.t} |
  {:error, :ownership}
Link to this function create(state, params) View Source 
create(t, params) ::
  {:ok, rendered} |
  {:error, :ownership} |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing} |
  {:error, :timeout} |
  {:error, :unauthorized} |
  {:error, Alembic.Document.t} |
  {:error, Ecto.Changeset.t}

Creates resource from params.

Steps

  1. state authorization_module can?(subject, :create, ecto_schema_module)
  2. Check params are a valid JSONAPI document
  3. state authorization_module can?(subject, :create, Ecto.Changeset.t)
  4. allow_sandbox_access/2
  5. state authorization_module filter_associations_can(created, subject, :show)
  6. state view_module show(authorized, ...)

Returns

  • {:ok, rendereded} - rendered view of created resource
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :sandbox_access_disallowed} - Sandbox token was required and present, but did not have the correct information to grant access.
  • {:error, :sandbox_token_missing} - Sandbox token was required (because state resources_module Calcinator.Resources.sandboxed?/0 returned true), but params["meta"]["beam"] was not present.
  • {:error, :timeout} - if the backing store for state resources_module times out when calling Calcinator.Resources.insert/2.
  • {:error, :unauthorized} - if state authorization_module can?(subject, :create, ecto_schema_module) or can?(subject, :create, %Ecto.Changeset{}) returns false
  • {:error, Alembic.Document.t} - if params is not a valid JSONAPI document
  • {:error, Ecto.Changeset.t} - if validations errors inserting Ecto.Changeset.t
Link to this function delete(state, params) View Source 
delete(t, params) ::
  :ok |
  {:error, {:not_found, parameter}} |
  {:error, :ownership} |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing} |
  {:error, :timeout} |
  {:error, :unauthorized} |
  {:error, Alembic.Document.t} |
  {:error, Ecto.Changeset.t} |
  {:error, reason :: term}

Deletes resource with "id" in params.

Steps

  1. allow_sandbox_access/2
  2. state resources_module get(id, ...)
  3. state authorization_module can?(subject, :delete, struct)
  4. state resources_module delete(struct)

Returns

  • :ok - resource was successfully deleted
  • {:error, {:not_found, "id"}} - The “id” did not correspond to resource in the backing store
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :sandbox_access_disallowed} - Sandbox token was required and present, but did not have the correct information to grant access.
  • {:error, :sandbox_token_missing} - Sandbox token was required (because state resources_module Calcinator.Resources.sandboxed?/0 returned true), but params["meta"]["beam"] was not present.
  • {:error, :timeout} - if the backing store for state resources_module times out when calling Calcinator.Resources.get/2 or Calcinator.Resources.delete/1.
  • {:error, :unauthorized} - The state subject is not authorized to delete the resource
  • {:error, Alembic.Document.t} - JSONAPI error document with params errors
  • {:error, Ecto.Changeset.t} - the deletion failed with the errors in Ecto.Changeset.t
  • {:error, reason} - a backing store-specific error
Link to this function get(calcinator, params, id_key, query_options) View Source 
get(t, params, id_key :: String.t, Resources.query_options) ::
  {:ok, Ecto.Schema.t} |
  {:error, {:not_found, parameter}} |
  {:error, :ownership} |
  {:error, :timeout} |
  {:error, reason :: term}
Link to this function index(state, params, map) View Source 
index(t, params, %{base_uri: URI.t}) ::
  {:ok, rendered} |
  {:error, :ownership} |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing} |
  {:error, :timeout} |
  {:error, :unauthorized} |
  {:error, Alembic.Document.t}

Gets index of a resource with (optional) pagination depending on whether the state resources_module supports pagination.

Steps

  1. state authorization_module can?(subject, :index, ecto_schema_module)
  2. allow_sandbox_access/2
  3. state resources_module list/1
  4. state authorization_module filter_can(listed, subject, :show)
  5. state authorization_module filter_associations_can(filtered_listed, subject, :show)
  6. state view_module index(association_filtered, ...)

Returns

  • {:ok, rendered} - the rendered resources with (optional) pagination in the "meta".
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :sandbox_access_disallowed} - Sandbox token was required and present, but did not have the correct information to grant access.
  • {:error, :sandbox_token_missing} - Sandbox token was required (because state resources_module Calcinator.Resources.sandboxed?/0 returned true), but params["meta"]["beam"] was not present.
  • {:error, :timeout} - if the backing store for state resources_module times out when calling list/1.
  • {:error, :unauthorized} - if state authorization_module can?(subject, :index, ecto_schema_module) returns false
  • {:error, Alembic.Document.t} - if params are not valid JSONAPI.
Link to this function show(state, params) View Source 
show(t, params) ::
  {:ok, rendered} |
  {:error, {:not_found, parameter}} |
  {:error, :ownership} |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing} |
  {:error, :timeout} |
  {:error, :unauthorized} |
  {:error, Alembic.Document.t} |
  {:error, reason :: term}

Shows resource with the "id" in params.

Steps

  1. allow_sandbox_acces/2
  2. state resources_module get(id, ...)
  3. state authorization_module can?(subject, :show, got)
  4. state authorization_module filter_associations_can(got, subject, :show)
  5. state view_module show(authorized, ...)

Returns

  • {:ok, rendered} - rendered resource
  • {:error, {:not_found, "id"}} - The “id” did not correspond to resource in the backing store
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :sandbox_access_disallowed} - Sandbox token was required and present, but did not have the correct information to grant access.
  • {:error, :sandbox_token_missing} - Sandbox token was required (because state resources_module Calcinator.Resources.sandboxed?/0 returned true), but params["meta"]["beam"] was not present.
  • {:error, :timeout} - if the backing store for state resources_module times out when calling Calcinator.Resources.get/2.
  • {:error, :unauthorized} - state authorization_module can?(subject, :show, got) returns false
  • {:error, Alembic.Document.t} - params is not valid JSONAPI
  • {:error, reason} - a backing store-specific error
Link to this function show_relationship(state, params, options) View Source 
show_relationship(t, params, map) ::
  {:ok, rendered} |
  {:error, {:not_found, parameter}} |
  {:error, :ownership} |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing} |
  {:error, :timeout} |
  {:error, :unauthorized} |
  {:error, Alembic.Document.t} |
  {:error, reason :: term}

Shows a relationship.

Steps

  1. Gets source
  2. state authorization_module can?(subject, :show, source)
  3. Get related
  4. state authorization_module can?(subject, :show, [related, source])
  5. state authorization_module filter_associations_can(related, subject, :show)
  6. state view_module show_relationship(authorized, ...)

Returns

  • {:ok, rendered} - rendered view of relationship
  • {:error, {:not_found, id_key}} - The value of the id_key key in params did not correspond to a resource in the backing store.
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :sandbox_access_disallowed} - Sandbox token was required and present, but did not have the correct information to grant access.
  • {:error, :sandbox_token_missing} - Sandbox token was required (because state resources_module Calcinator.Resources.sandboxed?/0 returned true), but params["meta"]["beam"] was not present.
  • {:error, :timeout} - if the backing store for state resources_module times out when calling Calcinator.Resources.get/2.
  • {:error, :unauthorized} - if the either the source or related resource cannot be shown
  • {:error, Alembic.Document.t} - JSONAPI error document with params errors
  • {:error, reason} - a backing store-specific error
Link to this function update(state, params) View Source 
update(t, params) ::
  {:ok, rendered} |
  {:error, :bad_gateway} |
  {:error, {:not_found, parameter}} |
  {:error, :ownership} |
  {:error, :sandbox_access_disallowed} |
  {:error, :sandbox_token_missing} |
  {:error, :unauthorized} |
  {:error, Alembic.Document.t} |
  {:error, Ecto.Changeset.t} |
  {:error, reason :: term}

Updates a resource with the "id" in params

Steps

  1. allow_sandbox_access/2
  2. state resources_module get(id, ...)
  3. Check params are a valid JSONAPI document
  4. state authorization_module can?(subject, :update, Ecto.Changeset.t)
  5. state resources_module update(Ecto.Changeset.t, ...)
  6. state authorization_module filter_associations_can(updated, subject, :show)
  7. state view_module show(authorized, ...)

Returns

  • {:ok, rendered} - the rendered updated resource
  • {:error, :bad_gateway} - backing store as internal error that can’t be represented in any other format. Try again later or call support.
  • {:error, {:not_found, "id"}} - get failed or update failed because the resource was deleted between the get and update.
  • {:error, :ownership} - connection to backing store was not owned by the calling process
  • {:error, :sandbox_access_disallowed} - Sandbox token was required and present, but did not have the correct information to grant access.
  • {:error, :sandbox_token_missing} - Sandbox token was required (because state resources_module Calcinator.Resources.sandboxed?/0 returned true), but params["meta"]["beam"] was not present.
  • {:error, :timeout} - if the backing store for state resources_module times out when calling Calcinator.Resources.get/2 or Calcinator.Resources.update/2.
  • {:error, :unauthorized} - the resource either can’t be shown or can’t be updated
  • {:error, Alembic.Document.t} - the params are not valid JSONAPI
  • {:error, Ecto.Changeset.t} - validations error when updating
  • {:error, reason} - a backing store-specific error
Link to this function update_changeset(state, changeset, params) View Source 
update_changeset(t, Ecto.Changeset.t, params) ::
  {:ok, Ecto.Schema.t} |
  {:error, Alembic.Document.t} |
  {:error, Ecto.Changeset.t} |
  {:error, :bad_gateway} |
  {:error, :not_found}