Defines a Commanded application.

The application expects at least an :otp_app option to be specified. It should point to an OTP application that has the application configuration.

For example, the application:

defmodule MyApp.Application do
  use Commanded.Application, otp_app: :my_app

  router(MyApp.Router)
end

Could be configured with:

# config/config.exs
config :my_app, MyApp.Application
  event_store: [
    adapter: Commanded.EventStore.Adapters.EventStore,
    event_store: MyApp.EventStore
  ],
  pubsub: :local,
  registry: :local

Alternatively, you can include the configuration when defining the application:

defmodule MyApp.Application do
  use Commanded.Application,
    otp_app: :my_app,
    event_store: [
      adapter: Commanded.EventStore.Adapters.EventStore,
      event_store: MyApp.EventStore
    ],
    pubsub: :local,
    registry: :local

  router(MyApp.Router)
end

A Commanded application must be started before it can be used:

{:ok, _pid} = MyApp.Application.start_link()

Instead of starting the application manually, you should use a Supervisor.

Supervision

Use a supervisor to start your Commanded application:

Supervisor.start_link([
  MyApp.Application
], strategy: :one_for_one)

Command routing

Commanded applications are also composite routers allowing you to include one or more routers within an application.

Example

defmodule MyApp.Application do
  use Commanded.Application, otp_app: :my_app

  router(MyApp.Accounts.Router)
  router(MyApp.Billing.Router)
  router(MyApp.Notifications.Router)
end

See Commanded.Commands.CompositeRouter for details.

Command dispatch

Once a router has been configured you can dispatch a command via the application:

:ok = MyApp.dispatch(command, opts)

See dispatch/1 and dispatch/2 for details.

Dynamic named applications

An application can be provided with a name as an option to start_link/1. This can be used to start the same application multiple times, each using its own separately configured and isolated event store. Each application must be started with a unique name.

Multipe instances of the same event handler or process manager can be started by refering to a started application by its name. The event store operations can also be scoped to an application by referring to its name.

Example

Start an application process for each tenant in a multi-tenanted app, guaranteeing that the data and processing remains isolated between tenants.

for tenant <- [:tenant1, :tenant2, :tenant3] do
  {:ok, _app} = MyApp.Application.start_link(name: tenant)
end

Typically you would start the applications using a supervisor:

children =
  for tenant <- [:tenant1, :tenant2, :tenant3] do
    {MyApp.Application, name: tenant}
  end

Supervisor.start_link(children, strategy: :one_for_one)

To dispatch a command you must provide the application name:

:ok = MyApp.Application.dispatch(command, application: :tenant1)

Default dispatch options

An application can be configured with default command dispatch options such as :consistency, :timeout, and :returning. Any defaults will be used unless overridden by options provided to the dispatch function.

defmodule MyApp.Application do
  use Commanded.Application,
    otp_app: :my_app,
    default_dispatch_opts: [
      consistency: :eventual,
      returning: :aggregate_version
    ]
end

See the Commanded.Commands.Router module for more details about the supported options.

Telemetry

• [:commanded, :application, :dispatch, :start]

  • Description: Emitted when an application starts dispatching a command
  • Measurements: %{system_time: integer()}
  • Metadata: %{application: Commanded.Application.t(), execution_context: Commanded.Aggregates.ExecutionContext.t()}

• [:commanded, :application, :dispatch, :stop]

  • Description: Emitted when an application stops dispatching a command
  • Measurements: %{duration: non_neg_integer()}
  • Metadata: %{application: Commanded.Application.t(), execution_context: Commanded.Aggregates.ExecutionContext.t(), error: nil | any()}