ash-project/ash
1
0
Fork 0
mirror of https://github.com/ash-project/ash.git synced 2024-09-20 13:33:20 +12:00
Code Issues Projects Releases Packages Wiki Activity

chore: remove DSLs, no need to commit generated content

Browse source
This commit is contained in:
Zach Daniel 2023-09-14 16:48:49 -04:00
parent e7f59862ab
commit bef7058613
8 changed files with 0 additions and 4544 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

153
documentation/dsls/DSL:-Ash.Api.cheatmd
View file

@ -1,153 +0,0 @@
# DSL: Ash.Api.Dsl
Apis are the entrypoints for working with your resources.
Apis may optionally include a list of resources, in which case they can be
used as an `Ash.Registry` in various places. This is for backwards compatibility,
but if at all possible you should define an `Ash.Registry` if you are using an extension
that requires a list of resources. For example, most extensions look for two application
environment variables called `:ash_apis` and `:ash_registries` to find any potential registries
## api
General Api configuration
---
### Examples
```
api do
description """
Resources related to the flux capacitor.
"""
end
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `description` | `String.t` | A description for the api. |
## resources
List the resources present in this API
---
* [resource](#resources-resource)
### Examples
```
resources do
resource MyApp.Tweet
resource MyApp.Comment
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `allow` | `mfa` | | Support a dynamic resource list by providing a callback that checks whether or not the resource should be allowed. |
| `allow_unregistered?` | `boolean` | false | Whether the Api will support only registered entries or not. |
| `registry` | `module` | | Configure a registry that contains the resources. This option is generally not necessary anymore, and remains for backwards compatibility. Instead, configure resources in this block directly. |
## resources.resource
```elixir
resource resource
```
---
Introspection Target: `Ash.Api.Dsl.ResourceReference`
A resource present in the API
---
### Examples
```
resource Foo
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `resource` - required-arg 1 | `module` | |
## execution
Options for how requests are executed using this Api
---
### Examples
```
execution do
timeout :timer.seconds(30)
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `timeout` | `timeout` | 30000 | The default timeout to use for requests using this API. See the [timeouts guide](/documentation/topics/timeouts.md) for more. |
| `trace_name` | `String.t` | | The name to use in traces. Defaults to the last part of the module. See the [monitoring guide](/documentation/topics/monitoring.md) for more |
## authorization
Options for how requests are authorized using this Api. See the [security guide](/documentation/topics/security.md) for more.
---
### Examples
```
authorization do
authorize :by_default
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `require_actor?` | `boolean` | false | Requires that an actor has been supplied. |
| `authorize` | `:always \| :by_default \| :when_requested` | :when_requested | When to run authorization for a given request. |

37
documentation/dsls/DSL:-Ash.DataLayer.Ets.cheatmd
View file

@ -1,37 +0,0 @@
# DSL: Ash.DataLayer.Ets
An ETS (Erlang Term Storage) backed Ash Datalayer, for testing and lightweight usage.
Remember, this does not have support for transactions! This is not recommended for production
use, especially in multi-user applications. It can, however, be great for prototyping.
## ets
A section for configuring the ets data layer
---
### Examples
```
ets do
# Used in testing
private? true
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `private?` | `boolean` | false | Sets the ets table protection to private, and scopes it to only this process. The table name will not be used directly if this is true, to allow multiple processes to use this resource separately. |
| `table` | `atom` | | The name of the table. Defaults to the resource name. |

40
documentation/dsls/DSL:-Ash.DataLayer.Mnesia.cheatmd
View file

@ -1,40 +0,0 @@
# DSL: Ash.DataLayer.Mnesia
An Mnesia backed Ash Datalayer.
In your application initialization, you will need to call `Mnesia.create_schema([node()])`.
Additionally, you will want to create your mnesia tables there.
This data layer is *unoptimized*, fetching all records from a table and filtering them
in memory. For that reason, it is not recommended to use it with large amounts of data. It can be
great for prototyping or light usage, though.
## mnesia
A section for configuring the mnesia data layer
---
### Examples
```
mnesia do
table :custom_table
end
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `table` | `atom` | The table name to use, defaults to the name of the resource |

633
documentation/dsls/DSL:-Ash.Flow.cheatmd
View file

@ -1,633 +0,0 @@
# DSL: Ash.Flow.Dsl
The built in flow DSL.
## Halting
Steps can be halted, which will stop the flow from continuing and return a halted flow. To attach a specific reason, use a `halt_reason`.
If you need more complex halting logic, then you'd want to use a custom step, and return `{:error, Ash.Error.Flow.Halted.exception(...)}`
## flow
Details about the flow itself, like description and the successful return type.
---
* [argument](#flow-argument)
### Examples
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `api` | `module` | An api to use by default when calling actions |
| `description` | `String.t` | A description of the flow |
| `trace_name` | `String.t` | The name to use when creating traces. Defaults to the short name. |
| `short_name` | `atom` | A short name to use for the flow. Defaults to the last to parts of the module name, underscored. |
| `returns` | ``any`` | The step or step that should constitute the return value. |
## flow.argument
```elixir
argument name, type
```
---
Introspection Target: `Ash.Flow.Argument`
An argument to be passed into the flow
---
### Examples
```
argument :params, :map do
default %{}
end
```
```
argument :retries, :integer do
allow_nil? false
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name to use for the argument |
| `type` - required-arg 2 | `module` | | The type of the argument. See `Ash.Type` for more. |
| `default` | `(-> any) \| mfa \| any()` | | A default value to use for the argument if not provided |
| `allow_nil?` | `boolean` | true | Whether or not the argument value may be nil |
| `constraints` | `Keyword.t` | [] | Constraints to provide to the type when casting the value. See the type's documentation for more information. |
## steps
---
* [map](#steps-map)
* [branch](#steps-branch)
* [transaction](#steps-transaction)
* [create](#steps-create)
* [debug](#steps-debug)
* [update](#steps-update)
* [destroy](#steps-destroy)
* [validate](#steps-validate)
* [read](#steps-read)
* [run_flow](#steps-run_flow)
* [custom](#steps-custom)
### Examples
```
steps do
# invokes a create action
create :create_post, MyApp.Post, :create
end
```
## steps.map
```elixir
map name, over
```
---
Introspection Target: `Ash.Flow.Step.Map`
Runs a set of steps for each item in a provided list.
---
### Examples
```
map :create_users, range(1, arg(:count)) do
output :create_user
create :create_user, Org, :create do
input %{
first_name: {Faker.Person, :first_name, []},
last_name: {Faker.Person, :last_name, []}
}
end
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `over` - arg 2 | ``any`` | | The value to be iterated over. Will be available inside the `map` step as `element(:map_step_name)` |
| `output` | `atom` | | Which step to use when constructing the output list. Defaults to the last step. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
## steps.branch
```elixir
branch name, condition
```
---
Introspection Target: `Ash.Flow.Step.Branch`
Runs a set of steps based on a given value.
---
### Examples
```
branch :create_users, result(:create_users?) do
output :create_user
create :create_user, Org, :create do
input %{
first_name: {Faker.Person, :first_name, []},
last_name: {Faker.Person, :last_name, []}
}
end
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `condition` - arg 2 | ``any`` | | A template that must evaluate to `true` for the branch to be executed. |
| `output` | `atom` | | Which step to use as the output. Defaults to the last step. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
## steps.transaction
```elixir
transaction name, resource
```
---
Introspection Target: `Ash.Flow.Step.Transaction`
Runs a set of steps in a transaction.
---
### Examples
```
transaction :create_users do
create :create_user, User, :create do
input %{
first_name: {Faker.Person, :first_name, []},
last_name: {Faker.Person, :last_name, []}
}
end
create :create_user, Org, :create do
input %{
first_name: {Faker.Person, :first_name, []},
last_name: {Faker.Person, :last_name, []}
}
end
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `resource` - arg 2 | `module \| list(module)` | | The Ash resource to use for the transaction. |
| `output` | ``any`` | | Which step or steps to use when constructing the output. Defaults to the last step. |
| `timeout` | `timeout` | | A timeout to apply to the transaction. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
## steps.create
```elixir
create name, resource, action
```
---
Introspection Target: `Ash.Flow.Step.Create`
Declares a step that will call a create action on a resource.
---
### Examples
```
create :create_post, MyApp.Post, :create
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `resource` - required-arg 2 | ``any`` | | The resource to call the action on. |
| `action` - required-arg 3 | ``any`` | | The action to call on the resource. |
| `upsert?` | `boolean` | false | Wether or not this action is always an upsert. |
| `upsert_identity` | `atom` | | The identity to use for the upsert. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
| `api` | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. |
| `tenant` | ``any`` | | A tenant to use for the operation. May be a template or a literal value. |
| `input` | ``any`` | | A template for the input. |
## steps.debug
```elixir
debug name
```
---
Introspection Target: `Ash.Flow.Step.Debug`
Declares a step that will inspect its input and provide
additional debug information.
---
### Examples
```
debug :show_some_information do
input %{post: result(:create_post)}
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `input` | ``any`` | | A template for the input. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
## steps.update
```elixir
update name, resource, action
```
---
Introspection Target: `Ash.Flow.Step.Update`
Declares a step that will call a update action on a resource.
---
### Examples
```
update :update_post, MyApp.Post, :update do
record result(:get_post)
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `resource` - required-arg 2 | ``any`` | | The resource to call the action on. |
| `action` - required-arg 3 | ``any`` | | The action to call on the resource. |
| `record` - required | ``any`` | | The record to be updated, can use template helpers, e.g `result(:step_name)`. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
| `api` | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. |
| `tenant` | ``any`` | | A tenant to use for the operation. May be a template or a literal value. |
| `input` | ``any`` | | A template for the input. |
## steps.destroy
```elixir
destroy name, resource, action
```
---
Introspection Target: `Ash.Flow.Step.Destroy`
Declares a step that will call a destroy action on a resource.
---
### Examples
```
destroy :destroy_post, MyApp.Post, :destroy
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `resource` - required-arg 2 | ``any`` | | The resource to call the action on. |
| `action` - required-arg 3 | ``any`` | | The action to call on the resource. |
| `record` - required | ``any`` | | The record to be updated, can use template helpers, e.g `result(:step_name)`. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
| `api` | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. |
| `tenant` | ``any`` | | A tenant to use for the operation. May be a template or a literal value. |
| `input` | ``any`` | | A template for the input. |
## steps.validate
```elixir
validate name, resource, action
```
---
Introspection Target: `Ash.Flow.Step.Update`
Validates some input against an action.
---
### Examples
```
validate :update_post, MyApp.Post, :update do
record result(:get_post)
only_keys [:name]
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `resource` - required-arg 2 | ``any`` | | The resource to call the action on. |
| `action` - required-arg 3 | ``any`` | | The action to call on the resource. |
| `record` | ``any`` | | The record to be created/updated/destroyed. If the value is `nil` and would be required by the action type, the step is skipped and `nil` is the result of the step. |
| `only_keys` | `list(atom \| list(atom))` | | A list of keys or paths to keys that should be validated. Others will be ignored, and errors generated for other fields will be ignored. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
| `api` | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. |
| `tenant` | ``any`` | | A tenant to use for the operation. May be a template or a literal value. |
| `input` | ``any`` | | A template for the input. |
## steps.read
```elixir
read name, resource, action
```
---
Introspection Target: `Ash.Flow.Step.Read`
Declares a step that will call a read action on a resource.
---
### Examples
```
read :destroy_post, MyApp.Post, :destroy
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `resource` - required-arg 2 | ``any`` | | The resource to call the action on. |
| `action` - required-arg 3 | ``any`` | | The action to call on the resource. |
| `get?` | `boolean` | false | Whether or not read action is expected to return a single result or `nil`. Set to `true` automatically if `get? true`. |
| `not_found_error?` | `boolean` | true | Whether or not finding no record should result in a not found error |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
| `api` | ``any`` | | The api to use when calling the action. Defaults to the api set in the `flow` section. |
| `tenant` | ``any`` | | A tenant to use for the operation. May be a template or a literal value. |
| `input` | ``any`` | | A template for the input. |
## steps.run_flow
```elixir
run_flow name, flow
```
---
Introspection Target: `Ash.Flow.Step.RunFlow`
Runs another flow as part of the current flow.
The return value of the step is the return value of the flow.
---
### Examples
```
run_flow :get_org, GetOrgByName do
input %{
name: arg(:org_name)
}
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `flow` - required-arg 2 | `atom` | | The flow to run. |
| `input` | ``any`` | | A template for the input. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |
## steps.custom
```elixir
custom name, custom
```
---
Introspection Target: `Ash.Flow.Step.Custom`
Runs a custom step module.
See `Ash.Flow.Step` for the necessary callbacks and more information.
---
### Examples
```
custom :do_custom_thing, MyApp.DoCustomThing do
input %{...}
end
```
```
custom :do_custom_thing, {MyApp.DoCustomThing, opt1: :foo, opt2: :bar} do
input %{...}
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `name` - required-arg 1 | `atom` | | The name of the step. Will be used when expressing dependencies, and step inputs. |
| `custom` - arg 2 | `(any, any -> any) \| module` | | The module that implements the step behaviour. Also accepts a 2 argument function that takes the input and the context. |
| `input` | ``any`` | | A template for the input. |
| `async?` | `boolean` | false | Whether or not this step can be run outside of the current process. |
| `short_name` | `String.t` | | Set a short name for the step. Will be used when building things like mermaid charts. |
| `wait_for` | ``any`` | | Ensures that the step happens after the configured step or steps. This is a template who's results are not used, only awaited. |
| `touches_resources` | `list(atom)` | | A list of resources touched by any custom logic in this step. This is used in the case that this step is run in a transaction. This is primarily only needed for `custom` steps. |
| `halt_if` | ``any`` | | Halts the step by emitting an error (with an `Ash.Error.Flow.Halted`). Can use template variables. See the section on Halting for more. |
| `halt_reason` | ``any`` | :halted | Configures the reason for the `halt_if` clause. |
| `description` | `String.t` | | A description for the step. |

124
documentation/dsls/DSL:-Ash.Notifier.PubSub.cheatmd
View file

@ -1,124 +0,0 @@
# DSL: Ash.Notifier.PubSub
A pubsub notifier extension.
## pub_sub
A section for configuring how resource actions are published over pubsub
See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guide for more.
---
* [publish](#pub_sub-publish)
* [publish_all](#pub_sub-publish_all)
### Examples
```
pub_sub do
module MyEndpoint
prefix "post"
broadcast_type :phoenix_broadcast
publish :destroy, ["foo", :id]
publish :update, ["bar", :name] event: "name_change"
publish_all :create, "created"
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `module` - required | `atom` | | The module to call `broadcast/3` on e.g module.broadcast(topic, event, message). |
| `prefix` | `String.t` | | A prefix for all pubsub messages, e.g `users`. A message with `created` would be published as `users:created` |
| `broadcast_type` | `:notification \| :phoenix_broadcast \| :broadcast` | :notification | What shape the event payloads will be in. See |
| `name` | `atom` | | A named pub sub to pass as the first argument to broadcast. |
## pub_sub.publish
```elixir
publish action, topic
```
---
Introspection Target: `Ash.Notifier.PubSub.Publication`
Configure a given action to publish its results over a given topic.
See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guides for more.
---
### Examples
```
publish :create, "created"
```
```
publish :assign, "assigned"
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `action` - required-arg 1 | `atom` | The name of the action that should be published |
| `topic` - required-arg 2 | ``any`` | The topic to publish |
| `event` | `String.t` | The name of the event to publish. Defaults to the action name |
| `dispatcher` | `atom` | The module to use as a dispatcher. If none is set, the pubsub module provided is used. |
## pub_sub.publish_all
```elixir
publish_all type, topic
```
---
Introspection Target: `Ash.Notifier.PubSub.Publication`
Works just like `publish`, except that it takes a type
and publishes all actions of that type
See the [PubSub](/documentation/topics/pub_sub.md) and [Notifiers](/documentation/topics/notifiers.md) guides for more.
---
### Examples
```
publish_all :create, "created"
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `type` - arg 1 | `:create \| :update \| :destroy` | Publish on all actions of a given type |
| `topic` - required-arg 2 | ``any`` | The topic to publish |
| `action` | `atom` | The name of the action that should be published |
| `event` | `String.t` | The name of the event to publish. Defaults to the action name |
| `dispatcher` | `atom` | The module to use as a dispatcher. If none is set, the pubsub module provided is used. |

865
documentation/dsls/DSL:-Ash.Policy.Authorizer.cheatmd
View file

@ -1,865 +0,0 @@
# DSL: Ash.Policy.Authorizer
An authorization extension for ash resources.
To add this extension to a resource, add it to the list of `authorizers` like so:
```elixir
use Ash.Resource,
...,
authorizers: [
Ash.Policy.Authorizer
]
```
A resource can be given a set of policies, which are enforced on each call to a resource action.
For reads, policies can be configured to filter out data that the actor shouldn't see, as opposed to
resulting in a forbidden error.
See the [policies guide](/documentation/topics/policies.md) for practical examples.
Policies are solved/managed via a boolean satisfiability solver. To read more about boolean satisfiability,
see this page: https://en.wikipedia.org/wiki/Boolean_satisfiability_problem. At the end of
the day, however, it is not necessary to understand exactly how Ash takes your
authorization requirements and determines if a request is allowed. The
important thing to understand is that Ash may or may not run any/all of your
authorization rules as they may be deemed unnecessary. As such, authorization
checks should have no side effects. Ideally, the checks built-in to ash should
cover the bulk of your needs.
## policies
A section for declaring authorization policies.
Each policy that applies must pass independently in order for the
request to be authorized.
See the [policies guide](/documentation/topics/policies.md) for more.
---
* [policy](#policies-policy)
* authorize_if
* forbid_if
* authorize_unless
* forbid_unless
* [bypass](#policies-bypass)
* authorize_if
* forbid_if
* authorize_unless
* forbid_unless
### Examples
```
policies do
# Anything you can use in a condition, you can use in a check, and vice-versa
# This policy applies if the actor is a super_user
# Additionally, this policy is declared as a `bypass`. That means that this check is allowed to fail without
# failing the whole request, and that if this check *passes*, the entire request passes.
bypass actor_attribute_equals(:super_user, true) do
authorize_if always()
end
# This will likely be a common occurrence. Specifically, policies that apply to all read actions
policy action_type(:read) do
# unless the actor is an active user, forbid their request
forbid_unless actor_attribute_equals(:active, true)
# if the record is marked as public, authorize the request
authorize_if attribute(:public, true)
# if the actor is related to the data via that data's `owner` relationship, authorize the request
authorize_if relates_to_actor_via(:owner)
end
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `default_access_type` | `:strict \| :filter \| :runtime` | :filter | The default access type of policies for this resource. |
## policies.policy
```elixir
policy condition
```
---
Introspection Target: `Ash.Policy.Policy`
A policy has a name, a condition, and a list of checks.
Checks apply logically in the order they are specified, from top to bottom.
If no check explicitly authorizes the request, then the request is forbidden.
This means that, if you want to "blacklist" instead of "whitelist", you likely
want to add an `authorize_if always()` at the bottom of your policy, like so:
```elixir
policy action_type(:read) do
forbid_if not_logged_in()
forbid_if user_is_denylisted()
forbid_if user_is_in_denylisted_group()
authorize_if always()
end
```
If the policy should always run, use the `always()` check, like so:
```elixir
policy always() do
...
end
```
See the [policies guide](/documentation/topics/policies.md) for more.
---
* [authorize_if](#policies-policy-authorize_if)
* [forbid_if](#policies-policy-forbid_if)
* [authorize_unless](#policies-policy-authorize_unless)
* [forbid_unless](#policies-policy-forbid_unless)
### Examples
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `condition` - arg 1 | ``any`` | A check or list of checks that must be true in order for this policy to apply. |
| `description` | `String.t` | A description for the policy, used when explaining authorization results |
| `access_type` | `:strict \| :filter \| :runtime` | What portion of the checks inside the policy are allowed to run. See the guide for more. |
## policies.policy.authorize_if
```elixir
authorize_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_if logged_in()
```
```
authorize_if actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.policy.forbid_if
```elixir
forbid_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_if not_logged_in()
```
```
forbid_if actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.policy.authorize_unless
```elixir
authorize_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is false, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_unless not_logged_in()
```
```
authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.policy.forbid_unless
```elixir
forbid_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_unless logged_in()
```
```
forbid_unless actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.bypass
```elixir
bypass condition
```
---
Introspection Target: `Ash.Policy.Policy`
A policy that, if passed, will skip all following policies. If failed, authorization moves on to the next policy
---
* [authorize_if](#policies-bypass-authorize_if)
* [forbid_if](#policies-bypass-forbid_if)
* [authorize_unless](#policies-bypass-authorize_unless)
* [forbid_unless](#policies-bypass-forbid_unless)
### Examples
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `condition` - arg 1 | ``any`` | A check or list of checks that must be true in order for this policy to apply. |
| `description` | `String.t` | A description for the policy, used when explaining authorization results |
| `access_type` | `:strict \| :filter \| :runtime` | What portion of the checks inside the policy are allowed to run. See the guide for more. |
## policies.bypass.authorize_if
```elixir
authorize_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_if logged_in()
```
```
authorize_if actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.bypass.forbid_if
```elixir
forbid_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_if not_logged_in()
```
```
forbid_if actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.bypass.authorize_unless
```elixir
authorize_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is false, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_unless not_logged_in()
```
```
authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## policies.bypass.forbid_unless
```elixir
forbid_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_unless logged_in()
```
```
forbid_unless actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies
---
* [field_policy_bypass](#field_policies-field_policy_bypass)
* authorize_if
* forbid_if
* authorize_unless
* forbid_unless
* [field_policy](#field_policies-field_policy)
* authorize_if
* forbid_if
* authorize_unless
* forbid_unless
### Examples
```
field_policies do
field_policy :admin_only_field do
authorize_if actor_attribute_equals(:admin, true)
end
end
```
```
# Example of denylist style
field_policies do
field_policy [:sensitive, :fields] do
authorize_if actor_attribute_equals(:admin, true)
end
field_policy :* do
authorize_if always()
end
end
```
## field_policies.field_policy_bypass
```elixir
field_policy_bypass fields, condition \ {Ash.Policy.Check.Static, [result: true]}
```
---
Introspection Target: `Ash.Policy.FieldPolicy`
A field policy that, if passed, will skip all following field policies for that field or fields. If failed, field authorization moves on to the next policy
---
* [authorize_if](#field_policies-field_policy_bypass-authorize_if)
* [forbid_if](#field_policies-field_policy_bypass-forbid_if)
* [authorize_unless](#field_policies-field_policy_bypass-authorize_unless)
* [forbid_unless](#field_policies-field_policy_bypass-forbid_unless)
### Examples
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `fields` - arg 1 | `list(atom) \| atom` | The field or fields that the policy applies to. |
| `condition` - arg 2 | ``any`` | A check or list of checks that must be true in order for this field policy to apply. If not specified, it always applies. |
| `description` | `String.t` | A description for the policy, used when explaining authorization results |
## field_policies.field_policy_bypass.authorize_if
```elixir
authorize_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_if logged_in()
```
```
authorize_if actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy_bypass.forbid_if
```elixir
forbid_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_if not_logged_in()
```
```
forbid_if actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy_bypass.authorize_unless
```elixir
authorize_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is false, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_unless not_logged_in()
```
```
authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy_bypass.forbid_unless
```elixir
forbid_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_unless logged_in()
```
```
forbid_unless actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy
```elixir
field_policy fields, condition \ {Ash.Policy.Check.Static, [result: true]}
```
---
Introspection Target: `Ash.Policy.FieldPolicy`
Field policies behave similarly to policies. See `d:Ash.Policy.Authorizer.field_policies`
for more.
---
* [authorize_if](#field_policies-field_policy-authorize_if)
* [forbid_if](#field_policies-field_policy-forbid_if)
* [authorize_unless](#field_policies-field_policy-authorize_unless)
* [forbid_unless](#field_policies-field_policy-forbid_unless)
### Examples
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `fields` - arg 1 | `list(atom) \| atom` | The field or fields that the policy applies to. |
| `condition` - arg 2 | ``any`` | A check or list of checks that must be true in order for this field policy to apply. If not specified, it always applies. |
| `description` | `String.t` | A description for the policy, used when explaining authorization results |
## field_policies.field_policy.authorize_if
```elixir
authorize_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_if logged_in()
```
```
authorize_if actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy.forbid_if
```elixir
forbid_if check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_if not_logged_in()
```
```
forbid_if actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy.authorize_unless
```elixir
authorize_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is false, the request is authorized, otherwise run remaining checks.
---
### Examples
```
authorize_unless not_logged_in()
```
```
authorize_unless actor_attribute_matches_record(:group, :blacklisted_groups)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |
## field_policies.field_policy.forbid_unless
```elixir
forbid_unless check
```
---
Introspection Target: `Ash.Policy.Check`
If the check is true, the request is forbidden, otherwise run remaining checks.
---
### Examples
```
forbid_unless logged_in()
```
```
forbid_unless actor_attribute_matches_record(:group, :group)
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `check` - required-arg 1 | ``any`` | The check to run. See `Ash.Policy.Check` for more. |
| `name` | `String.t` | A short name or description for the check, used when explaining authorization results |

65
documentation/dsls/DSL:-Ash.Registry.cheatmd
View file

@ -1,65 +0,0 @@
# DSL: Ash.Registry.Dsl
A small DSL for declaring an `Ash.Registry`. Not generally necessary any longer.
`Ash.Registry` can be used generically, but the main way it is used in Ash is to provide a compile-time registry for an Ash Api.
## entries
List the entries present in this registry
---
* [entry](#entries-entry)
### Examples
```
entries do
entry MyApp.User
entry MyApp.Post
entry MyApp.Comment
end
```
### Reference
| Name | Type | Default | Docs |
| --- | --- | --- | --- |
| `warn_on_empty?` | `boolean` | true | Set to `false` to ignore warnings about an empty registry |
## entries.entry
```elixir
entry entry
```
---
Introspection Target: `Ash.Registry.Entry`
A reference to an ash module (typically a resource)
---
### Examples
```
entry MyApp.User
```
### Reference
| Name | Type | Docs |
| --- | --- | --- |
| `entry` - required-arg 1 | `atom` | The referenced module |

2627
documentation/dsls/DSL:-Ash.Resource.cheatmd
View file

File diff suppressed because it is too large Load diff