Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions config/test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,7 @@ default_app_config = [
config :commanded, Commanded.Commands.ConsistencyApp, default_app_config
config :commanded, Commanded.DefaultApp, []
config :commanded, Commanded.DistributedApp, []
config :commanded, Commanded.Event.Upcast.ProcessManager.Application, default_app_config
config :commanded, Commanded.Middleware.TenantApp, default_app_config
config :commanded, Commanded.ProcessManagers.ErrorApp, default_app_config
config :commanded, Commanded.ProcessManagers.ExampleApp, default_app_config
config :commanded, Commanded.ProcessManagers.ResumeApp, default_app_config
config :commanded, Commanded.ProcessManagers.TodoApp, default_app_config
config :commanded, Commanded.TestApplication, default_app_config

config :commanded, event_stores: [TestEventStore]
Expand Down
12 changes: 5 additions & 7 deletions guides/explanations/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -243,15 +243,15 @@ In Commanded, the available options during command dispatch are:
:ok = BankApp.dispatch(command, consistency: :eventual)
```

- `:strong` - block command dispatch until all strongly consistent event handlers and process managers have successfully processed all events created by the command.
- `:strong` - block command dispatch until all strongly consistent event handlers have successfully processed all events created by the command.

```elixir
:ok = BankApp.dispatch(command, consistency: :strong)
```

Dispatching a command using `:strong` consistency but without any strongly consistent event handlers configured will have no effect.

- Provide an explicit list of event handler and process manager modules (or their configured names), containing only those handlers you'd like to wait for. No other handlers will be awaited on, regardless of their own configured consistency setting.
- Provide an explicit list of event handler modules (or their configured names), containing only those handlers you'd like to wait for. No other handlers will be awaited on, regardless of their own configured consistency setting.

```elixir
:ok = BankApp.dispatch(command, consistency: [ExampleHandler, AnotherHandler])
Expand All @@ -262,11 +262,11 @@ In Commanded, the available options during command dispatch are:

#### Which consistency guarantee should I use?

When dispatching a command using `consistency: :strong` the dispatch will block until all of the strongly consistent event handlers and process managers have handled all events created by the command. This guarantees that when you receive the `:ok` response from dispatch, your strongly consistent read models will have been updated and can safely be queried.
When dispatching a command using `consistency: :strong` the dispatch will block until all of the strongly consistent event handlers have handled all events created by the command. This guarantees that when you receive the `:ok` response from dispatch, your strongly consistent read models will have been updated and can safely be queried.

Strong consistency helps to alleviate problems and workarounds you would otherwise encounter when dealing with eventual consistency in your own application. Use `:strong` consistency when you want to query a read model immediately after dispatching a command. You **must** also configure the event handler to use `:strong` consistency.

Using `:eventual` consistency, or omitting the `consistency` option, will cause the command dispatch to immediately return without waiting for any event handlers or process managers. The handlers run independently, and asynchronously, in the background, therefore you will need to deal with potentially stale read model data.
Using `:eventual` consistency, or omitting the `consistency` option, will cause the command dispatch to immediately return without waiting for any event handlers. The handlers run independently, and asynchronously, in the background, therefore you will need to deal with potentially stale read model data.

#### Configure default consistency

Expand All @@ -276,7 +276,7 @@ You may override the default consistency (`:eventual`) by setting `default_consi
config :commanded, default_consistency: :strong
```

This will effect command dispatch, event handlers, and process managers where a consistency is not explicitly defined.
This will effect command dispatch and event handlers where a consistency is not explicitly defined.

#### Consistency failures

Expand Down Expand Up @@ -411,8 +411,6 @@ defmodule ExampleHandler do
end
```

Commands dispatched by a process manager will be automatically assigned the appropriate causation and correlation ids from the source domain event.

You can use [Commanded audit middleware](https://hex.pm/packages/commanded_audit_middleware) to record every dispatched command. This allows you to follow the chain of commands and events by using the causation id. The correlation id can be used to find all related commands and events.

#### Configuring UUID provider
Expand Down
2 changes: 1 addition & 1 deletion guides/explanations/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,7 +227,7 @@ An event handler is a `GenServer` process that subscribes to the configured even

Commanded supports upcasting of events at runtime using the `Commanded.Event.Upcaster` protocol.

By implementing the upcaster protocol you can transform an event before it is used by a consumer. This might be an aggregate, an event handler, or a process manager. Because the upcaster changes the event at runtime, handlers only need to support the latest version. You can also use upcasting to change the type of event.
By implementing the upcaster protocol you can transform an event before it is used by a consumer. This might be an aggregate or an event handler. Because the upcaster changes the event at runtime, handlers only need to support the latest version. You can also use upcasting to change the type of event.

### Examples

Expand Down
226 changes: 0 additions & 226 deletions guides/explanations/process-managers.md

This file was deleted.

2 changes: 1 addition & 1 deletion guides/explanations/serialization.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Default JSON serializer

JSON serialization can be used for event data & metadata, and aggregate and process manager snapshots.
JSON serialization can be used for event data & metadata, and aggregate snapshots.

To enable JSON serialization with the included `Commanded.Serialization.JsonSerializer` module add the `jason` library to your deps:

Expand Down
5 changes: 1 addition & 4 deletions guides/explanations/supervision.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Supervision

Use an OTP supervisor to host your Commanded application, process managers, event handlers, and read model projectors.
Use an OTP supervisor to host your Commanded application, event handlers, and read model projectors.

```elixir
defmodule Bank.Supervisor do
Expand All @@ -19,9 +19,6 @@ defmodule Bank.Supervisor do
# Event handler
AccountBalanceHandler,

# Process manager
TransferMoneyProcessManager,

# Read model projector
AccountsProjector,

Expand Down
2 changes: 1 addition & 1 deletion guides/explanations/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ use Mix.Config
config :my_app, consistency: :strong
```

Then read the setting when defining your event handlers and process managers:
Then read the setting when defining your event handlers:

```elixir
defmodule ExampleEventHandler do
Expand Down
13 changes: 2 additions & 11 deletions guides/howtos/migrating-from-v1-to-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Overview

Commanded v2.0 introduces breaking changes to improve type safety and API clarity. The primary change is that metadata passed to event handlers and process managers has been changed from a plain map to the `Commanded.EventStore.EnrichedMetadata` struct.
Commanded v2.0 introduces breaking changes to improve type safety and API clarity. The primary change is that metadata passed to event handlers has been changed from a plain map to the `Commanded.EventStore.EnrichedMetadata` struct.

The issues come when you need to propagate the used-provided metadata, and you need to drop some keys, example:

Expand Down Expand Up @@ -80,16 +80,7 @@ end
end
```

2. **Update your process manager callbacks:**

- `interested?/2`
- `handle/3`
- `apply/3`
- `after_command/3`

All now receive `%EnrichedMetadata{}` instead of a plain map.

3. **Update pattern matching:**
2. **Update pattern matching:**

```elixir
# Before
Expand Down
1 change: 0 additions & 1 deletion guides/howtos/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ A separate guide is provided for each of the components you can build:
- [Aggregates](https://hexdocs.pm/commanded/aggregates.html)
- [Commands, registration and dispatch](https://hexdocs.pm/commanded/commands.html)
- [Events and handlers](https://hexdocs.pm/commanded/events.html)
- [Process managers](https://hexdocs.pm/commanded/process-managers.html)

Commanded uses strong consistency for command dispatch (write model) and eventual consistency, by default, for the read model. Receiving an `:ok` reply from dispatch indicates the command was successfully handled and any created domain events fully persisted to your chosen event store. You may opt into strong consistency for individual event handlers and command dispatch as required.

Expand Down
Loading