Step 5: Transfer money
Alice sends 30 to Bob. Each account decides only with its own state (step 2), so no account can move money into another. A workflow coordinates the transfer: the application starts it with the transfer's ID, and it sends commands to the accounts one at a time. When the target account cannot take the money, the workflow gives it back to the sender.
The same feature in a CRUD application
A CRUD application moves money between two rows in one database transaction:
BEGIN;
UPDATE accounts SET balance = balance - 30 WHERE id = 'alice';
UPDATE accounts SET balance = balance + 30 WHERE id = 'bob';
COMMIT;
That works only while both rows live in one database. When the target account belongs to another service or another bank, the debit and the credit are separate operations, and something has to finish or undo the transfer when the second half fails, including after a restart. In FCQRS, every account is its own aggregate and stores its own events, so the same holds within one application. The workflow is the part that finishes or undoes the transfer, and it stores its progress so a restart does not lose a transfer halfway.
Add transfer commands and events
module Account
open FCQRS.Common
// What a caller, or a transfer, can ask an account to do.
type AccountCommand =
| Open of owner: string
| Deposit of amount: decimal
| Withdraw of amount: decimal
| SendTransfer of transferId: string * target: string * amount: decimal
| ReceiveTransfer of transferId: string * source: string * amount: decimal
| RefundTransfer of transferId: string * target: string * amount: decimal
// What the account replies. Rejected is a reply only: it is never stored.
type AccountEvent =
| Opened of owner: string
| Deposited of amount: decimal
| Withdrawn of amount: decimal
| TransferSent of transferId: string * target: string * amount: decimal
| TransferReceived of transferId: string * source: string * amount: decimal
| TransferRefunded of transferId: string * target: string * amount: decimal
| Rejected of reason: string
// What the account knows now. The sets hold the IDs of transfers it has
// handled, so a repeated transfer command moves no money twice.
type AccountState = {
Owner: string option
Balance: decimal
Sent: Set<string>
Received: Set<string>
Refunded: Set<string>
}
// The state before the account's first event.
let initial = {
Owner = None
Balance = 0m
Sent = Set.empty
Received = Set.empty
Refunded = Set.empty
}
Fcqrs_250-tutorial_005-transfer-money.md_page.AccountFCQRSFCQRS.CommonContains common types like Events and Commands Functionality for Write Side.
Fcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountCommandOpenowner: stringstringAn abbreviation for the CLI type . Basic Types
Depositamount: decimaldecimalAn abbreviation for the CLI type . Basic Types
WithdrawSendTransfertransferId: stringtarget: stringReceiveTransfersource: stringRefundTransferFcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountEventOpenedDepositedWithdrawnTransferSentTransferReceivedTransferRefundedRejectedreason: stringFcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountStateOwner: string optionoptionThe type of optional values. When used from other CLI languages the empty option is the null value. Use the constructors Some and None to create values of this type. Use the values in the Option module to manipulate values of this type, or pattern match against the values directly. 'None' values will appear as the value null to other CLI languages. Instance methods on this type will appear as static methods to other CLI languages due to the use of null as a value representation. Options
Balance: decimalSent: Set<string>Microsoft.FSharp.Collections.FSharpSet`1Immutable sets based on binary trees, where elements are ordered by F# generic comparison. By default comparison is the F# structural comparison function or uses implementations of the IComparable interface on element values. See the module for further operations on sets. All members of this class are thread-safe and may be used concurrently from multiple threads.
Received: Set<string>Refunded: Set<string>initial: AccountStateNoneThe representation of "No value"
Microsoft.FSharp.Collections.SetModuleContains operations for working with values of type .
empty: Set<'T>The empty set for the type 'T. Set.empty<int> Evaluates to set [ ]. This is an O(1) operation.
// What a caller, or a transfer, can ask an account to do.
public union AccountCommand(
Open, Deposit, Withdraw, SendTransfer, ReceiveTransfer, RefundTransfer);
public sealed record Open(string Owner);
public sealed record Deposit(decimal Amount);
public sealed record Withdraw(decimal Amount);
public sealed record SendTransfer(
string TransferId, string Target, decimal Amount);
public sealed record ReceiveTransfer(
string TransferId, string Source, decimal Amount);
public sealed record RefundTransfer(
string TransferId, string Target, decimal Amount);
// What the account replies. Rejected is a reply only: it is never stored.
public union AccountEvent(
Opened, Deposited, Withdrawn,
TransferSent, TransferReceived, TransferRefunded, Rejected);
public sealed record Opened(string Owner);
public sealed record Deposited(decimal Amount);
public sealed record Withdrawn(decimal Amount);
public sealed record TransferSent(
string TransferId, string Target, decimal Amount);
public sealed record TransferReceived(
string TransferId, string Source, decimal Amount);
public sealed record TransferRefunded(
string TransferId, string Target, decimal Amount);
public sealed record Rejected(string Reason);
// What the account knows now. The sets hold the IDs of transfers it has
// handled, so a repeated transfer command moves no money twice.
public sealed record AccountState(
string? Owner,
decimal Balance,
ImmutableHashSet<string> Sent,
ImmutableHashSet<string> Received,
ImmutableHashSet<string> Refunded);
A transfer has three messages, each named with a transfer ID that the caller chooses:
SendTransferasks the source account to send money. It storesTransferSentand debits itself.ReceiveTransferasks the target account to take the money. It storesTransferReceived.RefundTransferasks the source account to take back money the target did not accept. It storesTransferRefunded.
The state now remembers which transfer IDs each account has sent, received, and refunded.
Make each transfer command safe to repeat
// Chooses what to do with a command, based on the current state.
let decide (command: Command<AccountCommand>) (state: AccountState) =
match command.CommandDetails, state.Owner with
| Open _, Some _ -> DeferEvent(Rejected "The account is already open")
| Open owner, None -> PersistEvent(Opened owner)
| _, None -> DeferEvent(Rejected "The account is not open")
// A repeated send gets the first answer, checked before the balance,
// because the first send lowered it. No money moves twice.
| SendTransfer(id, target, amount), _ when state.Sent.Contains id ->
DeferEvent(TransferSent(id, target, amount))
| (Deposit amount | Withdraw amount | SendTransfer(_, _, amount)), _
when amount <= 0m -> DeferEvent(Rejected "The amount must be positive")
| Deposit amount, _ -> PersistEvent(Deposited amount)
| (Withdraw amount | SendTransfer(_, _, amount)), _
when amount > state.Balance ->
DeferEvent(Rejected $"Insufficient funds: {state.Balance} available")
| Withdraw amount, _ -> PersistEvent(Withdrawn amount)
| SendTransfer(id, target, amount), _ ->
PersistEvent(TransferSent(id, target, amount))
// A repeated delivery gets the first answer; no money moves.
| ReceiveTransfer(id, source, amount), _ when state.Received.Contains id ->
DeferEvent(TransferReceived(id, source, amount))
| ReceiveTransfer(id, source, amount), _ ->
PersistEvent(TransferReceived(id, source, amount))
| RefundTransfer(id, target, amount), _ when state.Refunded.Contains id ->
DeferEvent(TransferRefunded(id, target, amount))
| RefundTransfer(id, target, amount), _ ->
PersistEvent(TransferRefunded(id, target, amount))
// Applies one event. A rejection or a repeated reply changes nothing.
let fold (event: Event<AccountEvent>) (state: AccountState) =
match event.EventDetails with
| Opened owner -> { state with Owner = Some owner }
| Deposited amount -> { state with Balance = state.Balance + amount }
| Withdrawn amount -> { state with Balance = state.Balance - amount }
| TransferSent(id, _, _) when state.Sent.Contains id -> state
| TransferSent(id, _, amount) ->
{ state with
Balance = state.Balance - amount
Sent = state.Sent.Add id
}
// FCQRS folds a repeated reply too; a known ID changes nothing.
| TransferReceived(id, _, _) when state.Received.Contains id -> state
| TransferReceived(id, _, amount) ->
{ state with
Balance = state.Balance + amount
Received = state.Received.Add id
}
| TransferRefunded(id, _, _) when state.Refunded.Contains id -> state
| TransferRefunded(id, _, amount) ->
{ state with
Balance = state.Balance + amount
Refunded = state.Refunded.Add id
}
| Rejected _ -> state
decide: Command<AccountCommand> -> AccountState -> EventAction<AccountEvent>command: Command<AccountCommand>FCQRS.Common.Command`1Represents a command to be processed by an aggregate actor. <typeparam name="'CommandDetails">The specific type of the command payload.</typeparam>
Fcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountCommandstate: AccountStateFcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountStateCommandDetails: 'CommandDetailsThe specific details or payload of the command.
Owner: string optionOpenSomeThe representation of "Value of type 'T" The input value. An option representing the value.
DeferEventPublish and fold the event in the live actor without storing it or incrementing the persisted version. A deferred event does not start a saga; running sagas still receive it.
Rejectedowner: stringNoneThe representation of "No value"
PersistEventPersist the event to the journal. The actor's state will be updated using the event handler *after* persistence succeeds.
OpenedSendTransferid: stringtarget: stringamount: decimalContains: string -> boolA useful shortcut for Set.contains. See the Set module for further operations on sets. The value to check. True if the set contains value. let set = Set.empty.Add(2).Add(3) printfn $"Does the set contain 1? {set.Contains(1)}" The sample evaluates to the following output: Does the set contain 1? false This is an O(log n) operation, where n is the number of elements in the set.
Sent: Set<string>TransferSentDepositWithdraw(<=): 'T -> 'T -> boolStructural less-than-or-equal comparison The first parameter. The second parameter. The result of the comparison. 5 <= 1 // Evaluates to false 5 <= 5 // Evaluates to true [1; 5] <= [1; 6] // Evaluates to true
Deposited(>): 'T -> 'T -> boolStructural greater-than The first parameter. The second parameter. The result of the comparison. 5 > 1 // Evaluates to true 5 > 5 // Evaluates to false (1, "a") > (1, "z") // Evaluates to false
Balance: decimalWithdrawnReceiveTransfersource: stringReceived: Set<string>TransferReceivedRefundTransferRefunded: Set<string>TransferRefundedfold: Event<AccountEvent> -> AccountState -> AccountStateevent: Event<AccountEvent>FCQRS.Common.Event`1Represents an event generated by an aggregate actor as a result of processing a command. <typeparam name="'EventDetails">The specific type of the event payload.</typeparam>
Fcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountEventEventDetails: 'EventDetailsThe specific details or payload of the event.
(-): ^T1 -> ^T2 -> ^T3Overloaded subtraction operator The first parameter. The second parameter. The result of the operation. 10 - 2 // Evaluates to 8
Add: string -> Set<string>A useful shortcut for Set.add. Note this operation produces a new set and does not mutate the original set. The new set will share many storage nodes with the original. See the Set module for further operations on sets. The value to add to the set. The result set. let set = Set.empty.Add(1).Add(1).Add(2) printfn $"The new set is: {set}" The sample evaluates to the following output: The new set is: set [1; 2] This is an O(log n) operation, where n is the number of elements in the set.
(+): ^T1 -> ^T2 -> ^T3Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"
public sealed class Account
: Aggregate<AccountState, AccountCommand, AccountEvent>
{
// The name stored with every event of this aggregate.
public override string EntityName => "Account";
// The state before the account's first event.
public override AccountState InitialState => new(null, 0m, [], [], []);
// Chooses what to do with a command, based on the current state.
public override EventAction<AccountEvent> HandleCommand(
Command<AccountCommand> command, AccountState state) =>
(command.CommandDetails, state.Owner) switch
{
(Open, not null) => Reject("The account is already open"),
(Open open, null) => Store(new Opened(open.Owner)),
(_, null) => Reject("The account is not open"),
// A repeated send gets the first answer, checked before the
// balance, because the first send lowered it. No money moves twice.
(SendTransfer send, _) when state.Sent.Contains(send.TransferId) =>
Repeat(new TransferSent(
send.TransferId, send.Target, send.Amount)),
(Deposit { Amount: <= 0m } or Withdraw { Amount: <= 0m }
or SendTransfer { Amount: <= 0m }, _) =>
Reject("The amount must be positive"),
(Deposit deposit, _) => Store(new Deposited(deposit.Amount)),
(Withdraw withdraw, _) when withdraw.Amount > state.Balance =>
Reject($"Insufficient funds: {state.Balance} available"),
(SendTransfer send, _) when send.Amount > state.Balance =>
Reject($"Insufficient funds: {state.Balance} available"),
(Withdraw withdraw, _) => Store(new Withdrawn(withdraw.Amount)),
(SendTransfer send, _) => Store(
new TransferSent(send.TransferId, send.Target, send.Amount)),
// A repeated delivery gets the first answer; no money moves.
(ReceiveTransfer receive, _)
when state.Received.Contains(receive.TransferId) =>
Repeat(new TransferReceived(
receive.TransferId, receive.Source, receive.Amount)),
(ReceiveTransfer receive, _) =>
Store(new TransferReceived(
receive.TransferId, receive.Source, receive.Amount)),
(RefundTransfer refund, _)
when state.Refunded.Contains(refund.TransferId) =>
Repeat(new TransferRefunded(
refund.TransferId, refund.Target, refund.Amount)),
(RefundTransfer refund, _) =>
Store(new TransferRefunded(
refund.TransferId, refund.Target, refund.Amount))
};
// Applies one event. A rejection or a repeated reply changes nothing.
public override AccountState ApplyEvent(
Event<AccountEvent> stored, AccountState state) =>
stored.EventDetails switch
{
Opened opened => state with { Owner = opened.Owner },
Deposited deposited =>
state with { Balance = state.Balance + deposited.Amount },
Withdrawn withdrawn =>
state with { Balance = state.Balance - withdrawn.Amount },
TransferSent sent
when state.Sent.Contains(sent.TransferId) => state,
TransferSent sent => state with
{
Balance = state.Balance - sent.Amount,
Sent = state.Sent.Add(sent.TransferId)
},
// FCQRS folds a repeated reply too; a known ID changes nothing.
TransferReceived received
when state.Received.Contains(received.TransferId) => state,
TransferReceived received => state with
{
Balance = state.Balance + received.Amount,
Received = state.Received.Add(received.TransferId)
},
TransferRefunded refunded
when state.Refunded.Contains(refunded.TransferId) => state,
TransferRefunded refunded => state with
{
Balance = state.Balance + refunded.Amount,
Refunded = state.Refunded.Add(refunded.TransferId)
},
Rejected => state
};
// Stores the event and replies with it.
static EventAction<AccountEvent> Store(AccountEvent @event) =>
EventActions.Persist(@event);
// Replies without storing anything.
static EventAction<AccountEvent> Reject(string reason) =>
EventActions.Defer<AccountEvent>(new Rejected(reason));
// Replies with an earlier answer again, without storing it.
static EventAction<AccountEvent> Repeat(AccountEvent @event) =>
EventActions.Defer(@event);
}
Every transfer command gets the same treatment: a second command with a transfer ID the account has already handled gets the first answer again, as a reply that is not stored. The workflow in the next section sends each command again after a restart when it had not stored the reply, and the money must move only once.
The check for a repeated SendTransfer comes before the balance check. The first SendTransfer
lowered the balance, so a balance check on the repeat could refuse it, and the workflow would end a
transfer as refused after the money had left Alice's account.
FCQRS applies a repeated reply with fold too, as it does every deferred reply, so fold checks the
ID and leaves the state unchanged. An account that is not open rejects ReceiveTransfer; that
rejection is what sends a transfer back.
Write the transfer as a workflow
Shared setup
module Statement =
open System.Data.Common
open System.Threading.Tasks
open Akka.Persistence.Query
open Dapper
open FCQRS.Common
open Account
// The read model: one row per stored event, with the balance after it.
let createTable (connection: DbConnection) =
connection.Execute
"CREATE TABLE IF NOT EXISTS statement (
account TEXT NOT NULL,
version INTEGER NOT NULL,
entry TEXT NOT NULL,
amount NUMERIC NOT NULL,
balance NUMERIC NOT NULL,
PRIMARY KEY (account, version))"
|> ignore
// Adds a row whose balance continues from the account's previous row.
let private addRow =
"INSERT INTO statement (account, version, entry, amount, balance)
SELECT @Account, @Version, @Entry, @Amount,
COALESCE((SELECT balance FROM statement WHERE account = @Account
ORDER BY version DESC LIMIT 1), 0) + @Amount"
// FCQRS calls this for each stored event, inside a transaction it commits.
let handle (connection: DbConnection) (transaction: DbTransaction)
(envelope: EventEnvelope) =
task {
match envelope.Event with
// Only account events go on a statement; Sender is the account's ID.
| :? Event<AccountEvent> as stored ->
let add (entry: string) (amount: decimal) =
let row = {|
Account = string stored.Sender.Value
Version = envelope.SequenceNr
Entry = entry
Amount = amount
|}
connection.ExecuteAsync(addRow, row, transaction) :> Task
match stored.EventDetails with
| Opened owner -> do! add $"Opened for {owner}" 0m
| Deposited amount -> do! add "Deposit" amount
| Withdrawn amount -> do! add "Withdrawal" -amount
| TransferSent(id, target, amount) -> do! add $"Transfer {id} to {target}" -amount
| TransferReceived(id, source, amount) -> do! add $"Transfer {id} from {source}" amount
| TransferRefunded(id, _, amount) -> do! add $"Refund of transfer {id}" amount
// A rejection is a reply only; the journal never holds one.
| Rejected _ -> ()
| _ -> ()
}
:> Task
module Transfer =
open FCQRS.FSharp
open FCQRS.Workflows
open Account
Fcqrs_250-tutorial_005-transfer-money.md_page.StatementSystemDataCommonThreadingTasksAkkaPersistenceQueryDapperFCQRSFCQRS.CommonContains common types like Events and Commands Functionality for Write Side.
Fcqrs_250-tutorial_005-transfer-money.md_page.AccountcreateTable: DbConnection -> unitconnection: DbConnectionSystem.Data.Common.DbConnectionDefines the core behavior of database connections and provides a base class for database-specific connections.
Execute: string * obj * System.Data.IDbTransaction * System.Nullable<int> * System.Nullable<System.Data.CommandType> -> intExecute parameterized SQL. The connection to query on. The SQL to execute for this query. The parameters to use for this query. The transaction to use for this query. Number of seconds before command execution timeout. Is it a stored proc or a batch? The number of rows affected.
(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
ignore: 'T -> unitIgnore the passed value. This is often used to throw away results of a computation. The value to ignore. ignore 55555 // Evaluates to ()
addRow: stringhandle: DbConnection -> DbTransaction -> EventEnvelope -> Tasktransaction: DbTransactionSystem.Data.Common.DbTransactionDefines the core behavior of database transactions and provides a base class for database-specific transactions.
envelope: EventEnvelopeAkka.Persistence.Query.EventEnvelopeEvent wrapper adding meta data for the events in the result stream of query, or similar queries. The is the time the event was stored, in ticks. The value of this property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001 in the Gregorian calendar (same as `DateTime.Now.Ticks`).
task: TaskBuilderBuilds a task using computation expression syntax.
Event: objFCQRS.Common.Event`1Represents an event generated by an aggregate actor as a result of processing a command. <typeparam name="'EventDetails">The specific type of the event payload.</typeparam>
Fcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountEventstored: Event<AccountEvent>add: string -> decimal -> Taskentry: stringstringAn abbreviation for the CLI type . Basic Types
amount: decimaldecimalAn abbreviation for the CLI type . Basic Types
row: {| Account: string; Amount: decimal; Entry: string; Version: int64 |}Account: stringstring: 'T -> stringConverts the argument to a string using ToString. For standard integer and floating point values and any type that implements IFormattable, ToString conversion uses CultureInfo.InvariantCulture. The input value. The converted string. string 'A' // evaluates to "A" string 0xff // evaluates to "255" string -10 // evaluates to "-10"
Value: FCQRS.Model.Data.AggregateIdGet the value of a 'Some' option. A NullReferenceException is raised if the option is 'None'.
Sender: FCQRS.Model.Data.AggregateId optionAn optional identifier for the actor that generated the event.
Version: int64SequenceNr: int64Entry: stringAmount: decimalExecuteAsync: string * obj * System.Data.IDbTransaction * System.Nullable<int> * System.Nullable<System.Data.CommandType> -> Task<int>Execute a command asynchronously using Task. The connection to query on. The SQL to execute for this query. The parameters to use for this query. The transaction to use for this query. Number of seconds before command execution timeout. Is it a stored proc or a batch? The number of rows affected.
System.Threading.Tasks.TaskRepresents an asynchronous operation.
EventDetails: 'EventDetailsThe specific details or payload of the event.
Openedowner: stringDepositedWithdrawn(~-): ^T -> ^TOverloaded unary negation. The value to negate. The result of the operation.
TransferSentid: stringtarget: stringTransferReceivedsource: stringTransferRefundedRejectedFcqrs_250-tutorial_005-transfer-money.md_page.TransferFCQRS.FSharpIdiomatic-F# functional facade for FCQRS. Gives F# consumers the same one-call ergonomics the C# host-builder (HostExtensions.fs) gives C#, but with F# idioms: records-of-functions for the definitions, typed handles for the results, an explicit wiring pipeline, and plain helpers for saga side effects. It is a *pure addition* that wraps only the existing primitives (IActor.InitializeActor / SagaBuilder.initSimple / Projections.startTracked / InitializeSagaStarter / CreateCommandSubscription / Actor.api) and changes nothing in the C# interop layer or the core. open FCQRS.FSharp let api = Fcqrs.actor config loggerFactory (Some (Fcqrs.connect DBType.Sqlite conn)) "Cluster" let documents = Fcqrs.aggregate api { Name="Document"; Initial=...; Decide=...; Fold=... } let slugs = Fcqrs.aggregate api { Name="Slug"; Initial=...; Decide=...; Fold=... } let publication = Fcqrs.saga api (publicationDef documents.Factory slugs.Factory) Fcqrs.wireSagaStarters api [ publication ] let subs = Fcqrs.projection api (Projection.single 0 updateReadModel) // (Projection.multi when you must control which notifications publish) // send a command and await the matching aggregate reply: let! ev = documents.Send (Fcqrs.newCid()) (Fcqrs.aggregateId id) cmd (fun e -> ...)
Workflows// What the application asks for. The application starts the workflow with
// the transfer's ID as the workflow ID.
type TransferRequest = {
Id: string
Source: string
Target: string
Amount: decimal
}
// How a transfer ended.
type TransferOutcome =
// The target account took the money.
| Completed
// The target turned it down, and the source account got the money back.
| Refunded
// The source account turned it down, so no money moved.
| Refused of reason: string
Fcqrs_250-tutorial_005-transfer-money.md_page.Transfer.TransferRequestId: stringstringAn abbreviation for the CLI type . Basic Types
Source: stringTarget: stringAmount: decimaldecimalAn abbreviation for the CLI type . Basic Types
Fcqrs_250-tutorial_005-transfer-money.md_page.Transfer.TransferOutcomeCompletedRefundedRefusedreason: string// What the application asks for. The application starts the workflow with
// the transfer's ID as the workflow ID.
public sealed record TransferRequest(
string Id, string Source, string Target, decimal Amount);
// How a transfer ended.
public union TransferOutcome(Completed, Refunded, Refused);
// The target account took the money.
public sealed record Completed;
// The target turned it down, and the source account got the money back.
public sealed record Refunded;
// The source account turned it down, so no money moved.
public sealed record Refused(string Reason);
TransferRequest is the workflow's input: what the application asks for. TransferOutcome is its
result: how the transfer ended.
// Each send is a step: FCQRS stores its reply, and after a restart the
// workflow continues after the last stored step. A step that had not stored
// its reply sends its command again.
let transfer
(accounts: AggregateHandle<AccountCommand, AccountEvent>)
(request: TransferRequest)
=
let { Id = id; Source = source; Target = target; Amount = amount } = request
workflow {
// Take the money from the source account.
match! send accounts source (SendTransfer(id, target, amount)) with
| Rejected reason -> return Refused reason
| _ ->
// Deliver it to the target account.
let deliver = ReceiveTransfer(id, source, amount)
match! send accounts target deliver with
| TransferReceived _ -> return Completed
// The target's only other answer is Rejected: give the money back.
| _ ->
let refund = RefundTransfer(id, target, amount)
let! _ = send accounts source refund
return Refunded
}
// The name is stored with every instance and must not change.
let definition accounts = Workflow.define "Transfer" (transfer accounts)
transfer: AggregateHandle<AccountCommand,AccountEvent> -> TransferRequest -> Workflow<TransferOutcome>accounts: AggregateHandle<AccountCommand,AccountEvent>FCQRS.FSharp.AggregateHandle`2What you get back after registering an aggregate.
Fcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountCommandFcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountEventrequest: TransferRequestFcqrs_250-tutorial_005-transfer-money.md_page.Transfer.TransferRequestId: stringid: stringSource: stringsource: stringTarget: stringtarget: stringAmount: decimalamount: decimalworkflow: WorkflowBuilderBuilds a workflow: `workflow { let! x = activity ... }`.
send: AggregateHandle<'Command,'Event> -> string -> 'Command -> Workflow<'Event>`sendWith` under `Retry.command`: send again when no reply came in time, with backoff, for five minutes.
SendTransferRejectedreason: stringRefuseddeliver: AccountCommandReceiveTransferTransferReceivedCompletedrefund: AccountCommandRefundTransferRefundeddefinition: AggregateHandle<AccountCommand,AccountEvent> -> WorkflowDefinition<TransferRequest,TransferOutcome>FCQRS.Workflows.WorkflowDefines workflows.
define: string -> ('Input -> Workflow<'Result>) -> WorkflowDefinition<'Input,'Result>A workflow named `name` whose instances run `body` on their input.
// Each send is a step: FCQRS stores its reply, and after a restart the
// workflow continues after the last stored step. A step that had not stored
// its reply sends its command again.
// The name is stored with every instance and must not change.
public sealed class TransferWorkflow(IServiceProvider services)
: Workflow<TransferRequest, TransferOutcome>("Transfer")
{
// The accounts the workflow sends commands to.
private readonly AggregateFactory accounts =
services.AggregateFactory<Account>();
public override async WorkflowTask<TransferOutcome> Run(
WorkflowContext ctx, TransferRequest request)
{
var (id, source, target, amount) = request;
// Take the money from the source account.
var send = new SendTransfer(id, target, amount);
if (await Send(ctx, source, send) is Rejected rejected)
return new Refused(rejected.Reason);
// Deliver it to the target account.
var deliver = new ReceiveTransfer(id, source, amount);
if (await Send(ctx, target, deliver) is TransferReceived)
return new Completed();
// The target's only other answer is Rejected: give the money back.
var refund = new RefundTransfer(id, target, amount);
await Send(ctx, source, refund);
return new Refunded();
}
// Send takes any command. This helper takes an AccountCommand, so the
// compiler rejects anything else sent to an account.
Step<AccountEvent> Send(
WorkflowContext ctx, string account, AccountCommand command) =>
ctx.Send<AccountCommand, AccountEvent>(accounts, account, command);
}
The body reads top to bottom, in the order the transfer happens. send sends a command to an account
and waits for the reply: an event that this command caused. Each send is a step. FCQRS stores
the step's reply in the workflow's own journal before the body continues.
The stored steps are how the workflow survives a restart. When the process starts again, FCQRS runs the body from the beginning and gives each stored step its stored reply instead of sending the command again. The body continues at the first step that has no stored reply, and sends that step's command again, because the journal cannot show whether the command reached the account. This is why every transfer command must be safe to repeat.
The same replay is why the body must make the same decisions every time it runs. It uses only its input and the replies of its steps. A workflow that reads the clock or calls another system does it through steps of its own, which the workflow tutorial introduces.
Each send carries a command ID made from the workflow's ID and the step's position, and it sends
again, with the same ID, when no reply comes in time. Transfer is the workflow's stored name, like an
aggregate's EntityName, and must not change.
Register the workflow and start transfers
Shared setup
open System
open System.Data.Common
open System.IO
open Microsoft.Data.Sqlite
open Microsoft.Extensions.Configuration
open Microsoft.Extensions.Logging
open FCQRS.Actor
open FCQRS.Common
open FCQRS.FSharp
open FCQRS.Model.Data
open FCQRS.ProjectionStorage
open FCQRS.Projections
open FCQRS.Workflows
open Account
open Transfer
let database = Path.Combine(AppContext.BaseDirectory, "accounts.db")
let connectionString = $"Data Source={database}"
// Startup and the account registration are the same as in step 2.
let logging = LoggerFactory.Create(fun _ -> ())
let configuration = ConfigurationBuilder().Build()
let connection = Fcqrs.connect DBType.Sqlite connectionString
let api = Fcqrs.actor configuration logging (Some connection) "accounts"
let accounts =
Fcqrs.aggregate api
{ Name = "Account"
Initial = initial
Decide = decide
Fold = fold
Snapshots = Default
Passivation = PassivationPolicy.Default }
// Finish the aggregate startup. This program has no sagas.
Fcqrs.wireSagaStarters api []
SystemDataCommonIOMicrosoftSqliteExtensionsConfigurationLoggingFCQRSFCQRS.ActorFCQRS.CommonContains common types like Events and Commands Functionality for Write Side.
FCQRS.FSharpIdiomatic-F# functional facade for FCQRS. Gives F# consumers the same one-call ergonomics the C# host-builder (HostExtensions.fs) gives C#, but with F# idioms: records-of-functions for the definitions, typed handles for the results, an explicit wiring pipeline, and plain helpers for saga side effects. It is a *pure addition* that wraps only the existing primitives (IActor.InitializeActor / SagaBuilder.initSimple / Projections.startTracked / InitializeSagaStarter / CreateCommandSubscription / Actor.api) and changes nothing in the C# interop layer or the core. open FCQRS.FSharp let api = Fcqrs.actor config loggerFactory (Some (Fcqrs.connect DBType.Sqlite conn)) "Cluster" let documents = Fcqrs.aggregate api { Name="Document"; Initial=...; Decide=...; Fold=... } let slugs = Fcqrs.aggregate api { Name="Slug"; Initial=...; Decide=...; Fold=... } let publication = Fcqrs.saga api (publicationDef documents.Factory slugs.Factory) Fcqrs.wireSagaStarters api [ publication ] let subs = Fcqrs.projection api (Projection.single 0 updateReadModel) // (Projection.multi when you must control which notifications publish) // send a command and await the matching aggregate reply: let! ev = documents.Send (Fcqrs.newCid()) (Fcqrs.aggregateId id) cmd (fun e -> ...)
ModelFCQRS.Model.DataFCQRS.ProjectionStorageSQL storage for journal-wide, transactional projection catch-up.
FCQRS.ProjectionsTransactional projections with a journal-wide, durable catch-up boundary.
WorkflowsFcqrs_250-tutorial_005-transfer-money.md_page.AccountFcqrs_250-tutorial_005-transfer-money.md_page.Transferdatabase: stringSystem.IO.PathPerforms operations on instances that contain file or directory path information. These operations are performed in a cross-platform manner.
Combine: string * string -> stringCombines two strings into a path. The first path to combine. The second path to combine. .NET Framework and .NET Core versions older than 2.1: or contains one or more of the invalid characters defined in . or is . The combined paths. If one of the specified paths is a zero-length string, this method returns the other path. If contains an absolute path, this method returns .
System.AppContextProvides members for setting and retrieving data about an application's context.
BaseDirectory: stringGets the file path of the base directory that the assembly resolver uses to probe for assemblies. The file path of the base directory that the assembly resolver uses to probe for assemblies.
connectionString: stringlogging: ILoggerFactoryMicrosoft.Extensions.Logging.LoggerFactoryProduces instances of classes based on the given providers.
Create: Action<ILoggingBuilder> -> ILoggerFactoryCreates new instance of configured using provided delegate. A delegate to configure the . The that was created.
configuration: IConfigurationRoot``.ctor``: unit -> unitBuild: unit -> IConfigurationRootBuilds an with keys and values from the set of providers registered in . An with keys and values from the registered providers.
connection: ConnectionFCQRS.FSharp.Fcqrsconnect: DBType -> string -> ConnectionBuild a SQLite/etc. Connection from a raw connection string of any length.
FCQRS.Actor.DBTypeRepresents the type of database connection
SqliteSQLite using Microsoft.Data.Sqlite provider
api: IActoractor: IConfiguration -> ILoggerFactory -> Connection option -> string -> IActorCreate the actor system from plain values (cluster name as a string).
SomeThe representation of "Value of type 'T" The input value. An option representing the value.
accounts: AggregateHandle<AccountCommand,AccountEvent>aggregate: IActor -> Aggregate<'State,'Command,'Event> -> AggregateHandle<'Command,'Event>Register an aggregate and return its typed handle. Calling this IS the registration (it initializes the sharding region).
Name: stringInitial: 'Stateinitial: AccountStateDecide: Command<'Command> -> 'State -> EventAction<'Event>handleCommand (decide): command + current state -> what to do.
decide: Command<AccountCommand> -> AccountState -> EventAction<AccountEvent>Fold: Event<'Event> -> 'State -> 'StateapplyEvent (fold): event + current state -> next state (pure).
fold: Event<AccountEvent> -> AccountState -> AccountStateSnapshots: SnapshotPolicySnapshot cadence: Default (config / 30), NoSnapshots, or Every n.
DefaultUse the global config (config:akka:persistence:snapshot-version-count), or 30.
Passivation: PassivationPolicyIdle passivation: PassivationPolicy.Default (configuration, then Akka's 120s), After an idle period, or Never.
FCQRS.Common.PassivationPolicyIdle passivation for an aggregate type, set per entity at registration. Passivation stops an idle actor and releases its in-memory state; the next command recovers it from the journal. Only messages routed through cluster sharding count as activity. Sagas ignore this: their shard regions remember entities, which disables idle passivation in Akka.NET. A saga stops at StopSaga or abort instead.
DefaultUse configuration: `akka.cluster.sharding.<EntityName>.passivate-idle-entity-after`, then `akka.cluster.sharding.passivate-idle-entity-after`, then Akka.NET's 120s.
wireSagaStarters: IActor -> SagaHandle list -> unitWire every registered saga into one saga-starter (or the empty starter if none). Call after the aggregates + sagas are registered.
// Register the workflow with the accounts it sends commands to. Registering
// it also resumes the transfers that were running when the process stopped.
let transfers = Workflows.register api (Transfer.definition accounts)
transfers: WorkflowHandle<TransferRequest,TransferOutcome>FCQRS.Workflows.WorkflowsRegisters workflows with an actor system.
register: IActor -> WorkflowDefinition<'Input,'Result> -> WorkflowHandle<'Input,'Result>Registers the workflow and returns its handle. Instances that were running when the process last stopped resume as soon as this is called.
api: IActorFcqrs_250-tutorial_005-transfer-money.md_page.Transferdefinition: AggregateHandle<AccountCommand,AccountEvent> -> WorkflowDefinition<TransferRequest,TransferOutcome>accounts: AggregateHandle<AccountCommand,AccountEvent>// Register the workflow beside the account. The host registers it at startup,
// which also resumes the transfers that were running when the process stopped.
builder.Services.AddFcqrs(connectionString, "accounts")
.AddAggregate<Account>()
.AddTransactionalProjection(options, Statement.Handle);
builder.Services
.AddWorkflow<TransferWorkflow, TransferRequest, TransferOutcome>();
Shared setup
// The statement from step 4, with rows for transfers.
do
use connection = new SqliteConnection(connectionString)
Statement.createTable connection
let store =
SqlProjectionStore(
ProjectionSqlDialect.Sqlite,
Func<DbConnection>(fun () -> new SqliteConnection(connectionString)))
let options = TransactionalProjectionOptions("Statement", store)
let statement = Fcqrs.transactionalProjection api options Statement.handle
let describe event =
match event with
| Opened owner -> $"Opened for {owner}"
| Deposited amount -> $"Deposited {amount}"
| Withdrawn amount -> $"Withdrew {amount}"
| TransferSent(id, target, amount) -> $"Sent {amount} to {target} ({id})"
| TransferReceived(id, source, amount) -> $"Received {amount} from {source} ({id})"
| TransferRefunded(id, _, amount) -> $"Refunded {amount} ({id})"
| Rejected reason -> $"Rejected: {reason}"
let show (reply: Event<AccountEvent>) =
let stored = if reply.Journaled = Some true then "stored" else "not stored"
let description = describe reply.EventDetails
printfn $"{description} (version {reply.Version}, {stored})"
let alice = Fcqrs.aggregateId "alice"
let bob = Fcqrs.aggregateId "bob"
// Send a command and wait until the statement includes the event it stored.
let send account command =
Fcqrs.sendAwaiting statement accounts (Fcqrs.newCid ()) account command (fun _ -> true)
|> Async.RunSynchronously
|> show
connection: SqliteConnectionMicrosoft.Data.Sqlite.SqliteConnectionRepresents a connection to a SQLite database. Connection Strings Async Limitations
connectionString: stringFcqrs_250-tutorial_005-transfer-money.md_page.StatementcreateTable: DbConnection -> unitstore: SqlProjectionStore``.ctor``: ProjectionSqlDialect * Func<DbConnection> -> SqlProjectionStoreUses one database for both the journal and the transactional read model.
FCQRS.ProjectionStorage.ProjectionSqlDialectDatabase SQL syntax supported by the transactional projection store.
Sqlite: ProjectionSqlDialectSQLite with a provider such as Microsoft.Data.Sqlite.
System.Func`1Encapsulates a method that has no parameters and returns a value of the type specified by the parameter. The type of the return value of the method that this delegate encapsulates. The return value of the method that this delegate encapsulates.
System.Data.Common.DbConnectionDefines the core behavior of database connections and provides a base class for database-specific connections.
options: TransactionalProjectionOptions``.ctor``: string * SqlProjectionStore -> TransactionalProjectionOptionsstatement: IProjectionFCQRS.FSharp.FcqrstransactionalProjection: IActor -> TransactionalProjectionOptions -> (DbConnection -> DbTransaction -> Akka.Persistence.Query.EventEnvelope -> Threading.Tasks.Task) -> IProjectionStarts a transactional projection with journal-wide CatchUpAsync support. Write the read model through the supplied connection and transaction; FCQRS commits those updates and contiguous per-persistence-ID progress together. Retain unprocessed journal history. Each pass applies events in journal order: per persistence ID in sequence order, and across persistence IDs in write order on SQLite; on PostgreSQL, SQL Server, and Oracle an event that commits late is applied in a later pass. Set `options.Entities` to read only some entities' events. On SQLite the handler runs while the transaction holds the database's single writer lock, so it must not wait for a journal write such as a workflow start; use `projection` with `Named` progress for that. See TransactionalProjectionOptions.
api: IActorhandle: DbConnection -> DbTransaction -> Akka.Persistence.Query.EventEnvelope -> Threading.Tasks.Taskdescribe: AccountEvent -> stringevent: AccountEventOpenedowner: stringDepositedamount: decimalWithdrawnTransferSentid: stringtarget: stringTransferReceivedsource: stringTransferRefundedRejectedreason: stringshow: Event<AccountEvent> -> unitreply: Event<AccountEvent>FCQRS.Common.Event`1Represents an event generated by an aggregate actor as a result of processing a command. <typeparam name="'EventDetails">The specific type of the event payload.</typeparam>
Fcqrs_250-tutorial_005-transfer-money.md_page.Account.AccountEventstored: stringJournaled: bool optionWhether this envelope's event was journaled, read from the delivery stamp: Some true (a projection event will follow), Some false (a deferred/publish-only reply — nothing to await), or None (an envelope that never passed through aggregate delivery, e.g. read back from the journal, or produced by a pre-stamp FCQRS).
(=): 'T -> 'T -> boolStructural equality The first parameter. The second parameter. The result of the comparison. 5 = 5 // Evaluates to true 5 = 6 // Evaluates to false [1; 2] = [1; 2] // Evaluates to true (1, 5) = (1, 6) // Evaluates to false
SomeThe representation of "Value of type 'T" The input value. An option representing the value.
description: stringEventDetails: 'EventDetailsThe specific details or payload of the event.
printfn: Printf.TextWriterFormat<'T> -> 'TPrint to stdout using the given format, and add a newline. The formatter. The formatted result. See Printf.printfn (link: ) for examples.
alice: AggregateIdaggregateId: string -> AggregateIdAn aggregate id from a string (e.g. a document/user key). Any non-blank id works: the shard names entity actors Uri.EscapeDataString(entityId), so characters Akka actor names would reject directly (spaces, %) are escaped before they reach an actor path.
bob: AggregateIdsend: AggregateId -> AccountCommand -> unitaccount: AggregateIdcommand: AccountCommandsendAwaiting: FCQRS.Query.ISubscribe<IMessageWithCID> -> AggregateHandle<'Command,'Event> -> CID -> AggregateId -> 'Command -> ('Event -> bool) -> Async<Event<'Event>>Read-your-writes in one call: subscribe on the CID BEFORE sending, send, then await the projection ONLY if the delivered ack was journaled. A deferred (rejection-style) ack never reaches the journal, so a naive await would hang until timeout. The subscribe-before-send ordering is what makes the wait race-free; owning it here means callers cannot get it backwards. Awaits exactly ONE projected event: a batch persist (PersistAllEvents) caller should Subscribe with an explicit take instead. Envelopes without the delivery stamp (pre-stamp FCQRS) are treated as journaled. The projection wait is bounded by `akka.fcqrs.command-timeout` (default 30s, bare number = seconds): a projection that suppresses or filters out the matching notification raises TimeoutException instead of hanging the caller forever.
accounts: AggregateHandle<AccountCommand,AccountEvent>newCid: unit -> CIDA fresh correlation id (UUID v7).
(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
Microsoft.FSharp.Control.FSharpAsyncHolds static members for creating and manipulating asynchronous computations. See also F# Language Guide - Async Workflows. Async Programming
RunSynchronously: Async<'T> * int option * Threading.CancellationToken option -> 'TRuns the asynchronous computation and await its result. If an exception occurs in the asynchronous computation then an exception is re-raised by this function. If no cancellation token is provided then the default cancellation token is used. The computation is started on the current thread if is null, has of true, and no timeout is specified. Otherwise the computation is started by queueing a new work item in the thread pool, and the current thread is blocked awaiting the completion of the computation. The timeout parameter is given in milliseconds. A value of -1 is equivalent to . The computation to run. The amount of time in milliseconds to wait for the result of the computation before raising a . If no value is provided for timeout then a default of -1 is used to correspond to . The cancellation token to be associated with the computation. If one is not supplied, the default cancellation token is used. The result of the computation. Starting Async Computations printfn "A" let result = async { printfn "B" do! Async.Sleep(1000) printfn "C" 17 } |> Async.RunSynchronously printfn "D" Prints "A", "B" immediately, then "C", "D" in 1 second. result is set to 17.
let describeOutcome outcome =
match outcome with
| Completed -> "completed"
| Refunded -> "refunded"
| Refused reason -> $"refused: {reason}"
// Start a transfer from Alice and wait for it to end. A start with an ID that
// is already in the journal stores nothing, so a repeated request moves no
// money: the transfer's ID is the workflow's ID.
let transfer id target amount =
let request = {
Id = id
Source = "alice"
Target = target
Amount = amount
}
let start = transfers.Start id request |> Async.RunSynchronously
let repeated =
match start with
| StartResult.Started -> ""
| StartResult.AlreadyStarted _ -> " (already started)"
let ended =
transfers.Result id (TimeSpan.FromSeconds 30.)
|> Async.RunSynchronously
match ended with
| WorkflowOutcome.Finished outcome ->
printfn $"Transfer {id}: {describeOutcome outcome}{repeated}"
| other -> printfn $"Transfer {id} ended without a result: %A{other}"
transfer "t1" "bob" 30m
// Carol has no account, so this transfer comes back.
transfer "t2" "carol" 20m
describeOutcome: TransferOutcome -> stringoutcome: TransferOutcomeCompletedRefundedRefusedreason: stringtransfer: string -> string -> decimal -> unitid: stringtarget: stringamount: decimalrequest: TransferRequestId: stringSource: stringTarget: stringAmount: decimalstart: StartResulttransfers: WorkflowHandle<TransferRequest,TransferOutcome>Start: string -> 'Input -> Async<StartResult>Starts the workflow with this ID. Returns once the start is stored. A second start with the same ID stores nothing and reports the existing instance, also when it has ended.
(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
Microsoft.FSharp.Control.FSharpAsyncHolds static members for creating and manipulating asynchronous computations. See also F# Language Guide - Async Workflows. Async Programming
RunSynchronously: Async<'T> * int option * Threading.CancellationToken option -> 'TRuns the asynchronous computation and await its result. If an exception occurs in the asynchronous computation then an exception is re-raised by this function. If no cancellation token is provided then the default cancellation token is used. The computation is started on the current thread if is null, has of true, and no timeout is specified. Otherwise the computation is started by queueing a new work item in the thread pool, and the current thread is blocked awaiting the completion of the computation. The timeout parameter is given in milliseconds. A value of -1 is equivalent to . The computation to run. The amount of time in milliseconds to wait for the result of the computation before raising a . If no value is provided for timeout then a default of -1 is used to correspond to . The cancellation token to be associated with the computation. If one is not supplied, the default cancellation token is used. The result of the computation. Starting Async Computations printfn "A" let result = async { printfn "B" do! Async.Sleep(1000) printfn "C" 17 } |> Async.RunSynchronously printfn "D" Prints "A", "B" immediately, then "C", "D" in 1 second. result is set to 17.
repeated: stringFCQRS.Workflows.StartResultThe answer to a start request.
StartedThis request started the workflow, or a new run of it.
AlreadyStartedA workflow with this ID exists and the start's reuse policy keeps it. Nothing was stored.
ended: WorkflowOutcome<TransferOutcome>Result: string -> TimeSpan -> Async<WorkflowOutcome<'Result>>Waits up to the given time for the instance to end. The wait is in memory: the workflow continues when the caller stops waiting. Raises `TimeoutException` when the time passes, and `InvalidOperationException` when no workflow with this ID was started.
System.TimeSpanRepresents a time interval.
FromSeconds: float -> TimeSpanReturns a that represents a specified number of seconds, where the specification is accurate to the nearest millisecond. A number of seconds, accurate to the nearest millisecond. is less than TimeSpan.MinValue or greater than TimeSpan.MaxValue. -or- is . -or- is . is equal to . An object that represents .
FCQRS.Workflows.WorkflowOutcome`1How a workflow ended.
FinishedThe body returned this value.
printfn: Printf.TextWriterFormat<'T> -> 'TPrint to stdout using the given format, and add a newline. The formatter. The formatted result. See Printf.printfn (link: ) for examples.
other: WorkflowOutcome<TransferOutcome>static string DescribeOutcome(TransferOutcome outcome) => outcome switch
{
Completed => "completed",
Refunded => "refunded",
Refused refused => $"refused: {refused.Reason}"
};
// Start a transfer from Alice and wait for it to end. A start with an ID that
// is already in the journal stores nothing, so a repeated request moves no
// money: the transfer's ID is the workflow's ID.
async Task Transfer(string id, string target, decimal amount)
{
var request = new TransferRequest(id, "alice", target, amount);
var started = await transfers.StartAsync(id, request);
var repeated = started ? "" : " (already started)";
var outcome = await transfers.ResultAsync(id, TimeSpan.FromSeconds(30));
Console.WriteLine($"Transfer {id}: {DescribeOutcome(outcome)}{repeated}");
}
await Transfer("t1", "bob", 30m);
// Carol has no account, so this transfer comes back.
await Transfer("t2", "carol", 20m);
The application starts a transfer by its ID. Start returns once FCQRS has stored the start, so a
transfer that has started survives a crash right after. A second start with an ID that is already in
the journal stores nothing and reports the existing instance. A caller that retries a request, for
example after a timeout, cannot start the transfer twice, as long as it sends the same transfer ID.
Result waits for the workflow to end and gives its result. The wait is in memory: the transfer
continues when the caller stops waiting. A workflow that has already ended gives its stored result,
which the second run below shows.
The statement is a projection (step 4) and follows the journal on its own,
behind the workflow. CatchUpAsync waits until it has read every event the transfers stored, before
the program reads it.
Deliver a transfer twice
// After a restart, a workflow sends a command again when its reply was not
// stored. Do the same by hand:
send bob (ReceiveTransfer("t1", "alice", 30m))
send: AggregateId -> AccountCommand -> unitbob: AggregateIdReceiveTransfer// After a restart, a workflow sends a command again when its reply was not
// stored. Do the same by hand:
await Send(bob, new ReceiveTransfer("t1", "alice", 30m));
Run it
From samples/accounts:
dotnet run --project 5-transfer-money/fsharp
dotnet run --project 5-transfer-money/csharp
Both programs print:
Opened for Alice (version 1, stored)
Deposited 100 (version 2, stored)
Opened for Bob (version 1, stored)
Transfer t1: completed
Transfer t2: refunded
Received 30 from alice (t1) (version 2, not stored)
Statement for alice:
version entry amount balance
1 Opened for Alice 0 0
2 Deposit 100 100
3 Transfer t1 to bob -30 70
4 Transfer t2 to carol -20 50
5 Refund of transfer t2 20 70
Statement for bob:
version entry amount balance
1 Opened for Bob 0 0
2 Transfer t1 from alice 30 30
Transfer t1 moved 30 from Alice to Bob. Transfer t2 came back: Carol has no account, so her
account rejected ReceiveTransfer, and the workflow refunded Alice, which is row 5 of her statement.
The second delivery of t1 got the first answer again without storing anything, and Bob's statement
has one row for it.
Between rows 4 and 5, Alice's statement shows 20 that has left her account and reached no one. A workflow is not a transaction: a query during a transfer sees the money in flight.
Run it again
Rejected: The account is already open (version 5, not stored)
Deposited 100 (version 6, stored)
Rejected: The account is already open (version 2, not stored)
Transfer t1: completed (already started)
Transfer t2: refunded (already started)
Received 30 from alice (t1) (version 2, not stored)
The program sends the same requests again. Only the deposit is new: t1 and t2 are already in the
journal, so their starts store nothing and Result gives their stored results. The statements gain
one row, Alice's deposit.
When an account does not answer
send sends again with backoff for five minutes. When no reply comes in that time, the step fails
with the kind OutcomeUnknown: the command may have been applied, and the account may have taken the
money. The transfer does not treat that as a rejection, because a refund after Bob took the money
would create money. The failure ends the workflow as failed, and Status reports it:
// An operator, or a scheduled job, looks for a failed transfer and runs
// its failed step again. The step keeps its command ID, so an account
// that applied the command answers with its first verdict.
match transfers.Status "t1" |> Async.RunSynchronously with
| WorkflowStatus.Failed error when error.Kind = ErrorKind.OutcomeUnknown ->
transfers.Resume "t1" |> Async.RunSynchronously
| _ -> ()
transfers: WorkflowHandle<TransferRequest,TransferOutcome>Status: string -> Async<WorkflowStatus>Where the instance is.
(|>): 'T1 -> ('T1 -> 'U) -> 'UApply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6
Microsoft.FSharp.Control.FSharpAsyncHolds static members for creating and manipulating asynchronous computations. See also F# Language Guide - Async Workflows. Async Programming
RunSynchronously: Async<'T> * int option * Threading.CancellationToken option -> 'TRuns the asynchronous computation and await its result. If an exception occurs in the asynchronous computation then an exception is re-raised by this function. If no cancellation token is provided then the default cancellation token is used. The computation is started on the current thread if is null, has of true, and no timeout is specified. Otherwise the computation is started by queueing a new work item in the thread pool, and the current thread is blocked awaiting the completion of the computation. The timeout parameter is given in milliseconds. A value of -1 is equivalent to . The computation to run. The amount of time in milliseconds to wait for the result of the computation before raising a . If no value is provided for timeout then a default of -1 is used to correspond to . The cancellation token to be associated with the computation. If one is not supplied, the default cancellation token is used. The result of the computation. Starting Async Computations printfn "A" let result = async { printfn "B" do! Async.Sleep(1000) printfn "C" 17 } |> Async.RunSynchronously printfn "D" Prints "A", "B" immediately, then "C", "D" in 1 second. result is set to 17.
FCQRS.Workflows.WorkflowStatusWhere a workflow instance is.
FailedThe body threw an exception it did not handle.
error: StepErrorKind: ErrorKind(=): 'T -> 'T -> boolStructural equality The first parameter. The second parameter. The result of the comparison. 5 = 5 // Evaluates to true 5 = 6 // Evaluates to false [1; 2] = [1; 2] // Evaluates to true (1, 5) = (1, 6) // Evaluates to false
FCQRS.Workflows.ErrorKindWhy a step or a workflow ended without a value.
OutcomeUnknownA command's deadline passed with no reply. The command may have been applied.
Resume: string -> Async<unit>Resumes a faulted instance at the step whose failure faulted it: the body replays its stored steps and runs that step again, with the same idempotency key, and continues. Steps that completed before the failure do not run again. Returns once the resume is stored. Raises `InvalidOperationException` when the instance has not faulted, when the body threw its own exception, or when the body ran steps after the failure, such as compensation.
Resume keeps the stored steps and runs the failed one again. A transfer stays failed until something
resumes it; FCQRS does not restart a failed workflow by itself.
What remains the application's job
- A stable transfer ID. The workflow ID is the only thing that stops a repeated request from starting a second transfer. Take it from the request, not from a new GUID on each attempt.
- Repeatable commands. Every command a workflow sends can arrive more than once. Give it an ID the receiver remembers, and answer a repeat with the first verdict, checked before anything the first command changed.
- Failed transfers. A transfer whose outcome is unknown waits for
Resume. Watch for failed instances and decide who resumes them. - External systems. Stored steps do not make a call to another system happen exactly once. A call to a payment provider needs its own idempotency key, timeout, and a way to undo or escalate. Workflows covers recovery and failures in detail.
Earlier versions of FCQRS coordinated a transfer with a saga, a state machine started by the account's
TransferSent event. Sagas remain supported for applications that use them;
Write a saga shows this transfer as one.
Next
Step 6: Add a memo adds a memo to transfers. TransferSent events are already
stored without one, so the step shows how to change an event that the journal already holds. The
workflow tutorial continues with what a workflow can do besides
sending commands: retries, timers, signals from people, and parallel steps.