Run a free-monad program as a workflow
A free-monad program lists the operations it needs as an instruction type, and an interpreter
decides what each instruction does. Free.toWorkflow is an interpreter that carries out each
instruction as a workflow step, so the program's progress is stored and survives a restart. Use it
for logic that also runs outside a workflow, with another interpreter. A workflow that runs
nowhere else is shorter with the workflow builder, which Write a workflow
explains.
Free programs explains instructions, builders, and
interpreters. The free monad is in FCQRS.Model.FreeMonad, and Free.toWorkflow in
FCQRS.Workflows. This page is F# only: the free monad has no C# API.
Write the program
An order reserves stock, waits five minutes, and charges the customer. Each operation is a case of
OrderInstruction, and Eff.perform makes a program of one instruction whose result is the
interpreter's answer:
Shared setup
open System
open System.Threading.Tasks
open FCQRS.Model.FreeMonad
open FCQRS.Workflows
SystemThreadingTasksFCQRSModelFCQRS.Model.FreeMonadWorkflowstype OrderInstruction =
| Reserve of order: string
| Wait of TimeSpan
| Charge of amount: decimal
let reserve order : Free<OrderInstruction, Result<string, string>> =
Eff.perform (Reserve order)
let wait duration : Free<OrderInstruction, Result<unit, string>> =
Eff.performR (Wait duration)
let charge amount : Free<OrderInstruction, Result<string, string>> =
Eff.performR (Charge amount)
let order (id: string) =
freeResult {
let! shelf = reserve id
do! wait (TimeSpan.FromMinutes 5.0)
let! receipt = charge 30m
return $"{shelf} {receipt}"
}
Fcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.OrderInstructionReserveorder: stringstringAn abbreviation for the CLI type . Basic Types
WaitSystem.TimeSpanRepresents a time interval.
Chargeamount: decimaldecimalAn abbreviation for the CLI type . Basic Types
reserve: string -> Free<OrderInstruction,Result<string,string>>FCQRS.Model.FreeMonad.Free`2Microsoft.FSharp.Core.FSharpResult`2Helper type for error handling without exceptions. Choices and Results
FCQRS.Model.FreeMonad.Effperform: 'I -> Free<'I,'X>wait: TimeSpan -> Free<OrderInstruction,Result<unit,string>>duration: TimeSpanunitThe type 'unit', which has only one value "()". This value is special and always uses the representation 'null'. Basic Types
performR: 'I -> Free<'I,Result<'X,'E>>charge: decimal -> Free<OrderInstruction,Result<string,string>>order: string -> Free<OrderInstruction,Result<string,string>>id: stringfreeResult: FreeResultBuildershelf: stringFromMinutes: float -> TimeSpanReturns a that represents a specified number of minutes, where the specification is accurate to the nearest millisecond. A number of minutes, 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 .
receipt: stringfreeResult ends the program at the first Error. Reserve answers with a Result, so an order
that is out of stock ends there. Eff.performR wraps an answer that is not a Result in Ok.
The program calls no service and reads no clock. It only names instructions, so it has no dependency on workflows.
Give each instruction a step
step maps an instruction to the workflow step that carries it out. Free.answer boxes the step's
result, because the cases give results of different types:
type IWarehouse =
abstract Reserve:
key: string * order: string -> Task<Result<string, string>>
type IPayments =
abstract Charge: key: string * amount: decimal -> Task<string>
let policy = Retry.times 3 (TimeSpan.FromSeconds 30.0)
let step (warehouse: IWarehouse) (payments: IPayments) instruction =
match instruction with
| Reserve order ->
activity "reserve" policy (fun attempt ->
warehouse.Reserve(attempt.IdempotencyKey, order))
|> Free.answer
| Wait duration -> sleep duration |> Free.answer
| Charge amount ->
activity "charge" policy (fun attempt ->
payments.Charge(attempt.IdempotencyKey, amount))
|> Free.answer
let orders warehouse payments =
Workflow.define "order" (fun (id: string) ->
Free.toWorkflow (step warehouse payments) (order id))
Fcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.IWarehouseReserve: IWarehouse -> string * string -> Task<Result<string,string>>keystringAn abbreviation for the CLI type . Basic Types
orderSystem.Threading.Tasks.Task`1Represents an asynchronous operation that can return a value. The type of the result produced by this .
Microsoft.FSharp.Core.FSharpResult`2Helper type for error handling without exceptions. Choices and Results
Fcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.IPaymentsCharge: IPayments -> string * decimal -> Task<string>amountdecimalAn abbreviation for the CLI type . Basic Types
policy: RetryPolicyFCQRS.Workflows.RetryCommon retry policies.
times: int -> TimeSpan -> RetryPolicyAt most `attempts` attempts, with backoff from one second to one minute. Each attempt fails when it has not finished within `attemptTimeout`.
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 .
step: IWarehouse -> IPayments -> OrderInstruction -> Workflow<objnull>warehouse: IWarehousepayments: IPaymentsinstruction: OrderInstructionReserveorder: stringactivity: string -> RetryPolicy -> (AttemptContext -> Task<'T>) -> Workflow<'T>Calls an external system. The call runs at least once: a crash after the call and before its result is stored repeats it, so pass `IdempotencyKey` to the external system. `name` is stored and must not change while instances are running. The policy needs an `AttemptTimeout` or a `Deadline`: an attempt with neither would wait as long as its call, also for a call that ignores its cancellation token.
attempt: AttemptContextReserve: string * string -> Task<Result<string,string>>IdempotencyKey: stringThe same for every attempt of this step, across restarts: workflow name, workflow ID, and step path. Pass it to the external system so a repeated call is recognised.
(|>): '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
FCQRS.Workflows.FreeRuns a program written with `FCQRS.Model.FreeMonad` as a workflow. With both namespaces open, `Free.bind` and `Free.toWorkflow` both resolve.
answer: Workflow<'T> -> Workflow<objnull>A step's result, boxed: the answer that an instruction's continuation takes.
Waitduration: TimeSpansleep: TimeSpan -> Workflow<unit>Waits for `duration`. The due time is stored when the step is first reached, so a restart does not postpone it.
Chargeamount: decimalCharge: string * decimal -> Task<string>orders: IWarehouse -> IPayments -> WorkflowDefinition<string,Result<string,string>>FCQRS.Workflows.WorkflowDefines workflows.
define: string -> ('Input -> Workflow<'Result>) -> WorkflowDefinition<'Input,'Result>A workflow named `name` whose instances run `body` on their input.
id: stringtoWorkflow: ('Instruction -> Workflow<objnull>) -> Free<'Instruction,'Result> -> Workflow<'Result>The workflow that runs `program`: `step` gives the workflow step that carries out each instruction, such as `Free.answer (activity "charge" policy run)`, and its result is the instruction's answer. Each step stores its result as any workflow step does, so a restart replays the stored answers through the program and continues at the instruction it had reached. The program's own code runs again on every replay and must be deterministic, like a workflow body. The step names that `step` gives are persistent contracts, and so is the order in which the program performs its instructions: an instance whose journal holds another name or order is parked. A step whose result has another type than the program expects faults the instance.
order: string -> Free<OrderInstruction,Result<string,string>>orders is an ordinary workflow definition. Register it with Workflows.register and start it by
ID like any other. The services arrive as arguments of step; the program never sees them.
Each instruction stores its answer as its step's result. After a restart the workflow replays the
stored answers through the program and continues at the instruction it had reached: a stored
reserve does not run again. An instruction that was running when the process stopped runs again,
so the warehouse and the payment service must honour the idempotency key.
Test it
WorkflowTest runs the workflow in memory, and the test gives each step's outcome:
let finishes (warehouse: IWarehouse) (payments: IPayments) =
let flow = WorkflowTest.Start(orders warehouse payments, "A-1")
flow.Complete("reserve", (Ok "shelf-4": Result<string, string>))
flow.Advance(TimeSpan.FromMinutes 5.0)
flow.Complete("charge", "receipt-9")
// A restart after any stored record must store the same journal.
flow.CheckReplay()
flow.Result = Ok "shelf-4 receipt-9"
finishes: IWarehouse -> IPayments -> boolwarehouse: IWarehouseFcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.IWarehousepayments: IPaymentsFcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.IPaymentsflow: WorkflowTest<string,Result<string,string>>FCQRS.Workflows.WorkflowTestRuns workflows in memory, for tests. See `WorkflowTest<'Input, 'Result>`.
Start: WorkflowDefinition<'Input,'Result> * 'Input -> WorkflowTest<'Input,'Result>Starts the workflow with `input` at `WorkflowTest.DefaultStart`.
orders: IWarehouse -> IPayments -> WorkflowDefinition<string,Result<string,string>>Complete: string * 'T -> unitCompletes the waiting activity, command, or child step named `step` with `value`, which is stored and read back as the actor does. A value the step cannot read back fails the step as `NotRetryable`. Raises `InvalidOperationException` when no such step waits, and `ArgumentException` when `value` cannot be stored as the step's result.
OkRepresents an OK or a Successful result. The code succeeded with a value of 'T.
Microsoft.FSharp.Core.FSharpResult`2Helper type for error handling without exceptions. Choices and Results
stringAn abbreviation for the CLI type . Basic Types
Advance: TimeSpan -> unitMoves the time forward, and fires the timers and signal timeouts that are due by then.
System.TimeSpanRepresents a time interval.
FromMinutes: float -> TimeSpanReturns a that represents a specified number of minutes, where the specification is accurate to the nearest millisecond. A number of minutes, 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 .
CheckReplay: unit -> unitRestarts the instance after every stored record the test produced, gives it the same outcomes, and checks that each restart stores the same journal. Raises `WorkflowReplayException` for the first restart that stores a different record or parks the instance: a body whose steps, stored values, or result change on replay. A pass does not show that the body is deterministic: an activity's arguments are not stored, so a GUID or a time read outside a step that reaches only an activity's call is not seen.
Result: Result<string,string>The body's result. Raises `WorkflowFaultedException` or `WorkflowCancelledException` when the instance ended otherwise, and `InvalidOperationException` while it has not ended.
(=): '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
Test a workflow describes the harness. The program can also be tested
without a workflow: Free.run, in FCQRS.Model 6.2.0 and later, runs it with a function that
answers each instruction, as Free programs
shows.
Run instructions together
A program performs one instruction at a time. To ask two carriers for a shipping price at once, an
instruction carries the programs to run as its parameters, and the step that carries it out runs
them with all or race:
type ShippingInstruction =
| Quote of carrier: string
| All of Free<ShippingInstruction, objnull> list
| First of Free<ShippingInstruction, objnull> list
let quote carrier : Free<ShippingInstruction, decimal> =
Eff.perform (Quote carrier)
let allOf (programs: Free<ShippingInstruction, 'T> list) =
Eff.perform<_, objnull list> (All(List.map (Free.map box) programs))
|> Free.map (List.map unbox<'T>)
let firstOf (programs: Free<ShippingInstruction, 'T> list) =
Eff.perform<_, 'T> (First(List.map (Free.map box) programs))
let priced carrier =
quote carrier |> Free.map (fun price -> carrier, price)
let cheapest carriers =
free {
let! prices = allOf (List.map priced carriers)
return List.minBy snd prices
}
let fastest carriers = firstOf (List.map priced carriers)
Fcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.ShippingInstructionQuotecarrier: stringstringAn abbreviation for the CLI type . Basic Types
AllFCQRS.Model.FreeMonad.Free`2objnullAn abbreviation for the CLI type or null. With the 'nullable reference types' feature, this is an alias to 'obj | null'. Basic Types
listThe type of immutable singly-linked lists. See the module for further operations related to lists. Use the constructors [] and :: (infix) to create values of this type, or the notation [1; 2; 3]. Use the values in the List module to manipulate values of this type, or pattern match against the values directly. See also F# Language Guide - Lists.
Firstquote: string -> Free<ShippingInstruction,decimal>decimalAn abbreviation for the CLI type . Basic Types
FCQRS.Model.FreeMonad.Effperform: 'I -> Free<'I,'X>allOf: Free<ShippingInstruction,'T> list -> Free<ShippingInstruction,'T list>programs: Free<ShippingInstruction,'T> listTMicrosoft.FSharp.Collections.ListModuleContains operations for working with values of type . Operations for collections such as lists, arrays, sets, maps and sequences. See also F# Collection Types in the F# Language Guide.
map: ('T -> 'U) -> 'T list -> 'U listBuilds a new collection whose elements are the results of applying the given function to each of the elements of the collection. The function to transform elements from the input list. The input list. The list of transformed elements. let inputs = [ "a"; "bbb"; "cc" ] inputs |> List.map (fun x -> x.Length) Evaluates to [ 1; 3; 2 ] This is an O(n) operation, where n is the length of the list.
FCQRS.Model.FreeMonad.Freemap: ('a -> 'b) -> Free<'c,'a> -> Free<'c,'b>box: 'T -> objnullBoxes a strongly typed value. The value to box. The boxed object. let x: int = 123 let obj1 = box x // obj1 is a generic object type unbox<int> obj1 // Evaluates to 123 (int) unbox<double> obj1 // Throws System.InvalidCastException
(|>): '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
unbox: objnull -> 'TUnbox a strongly typed value. The boxed value. The unboxed result. let x: int = 123 let obj1 = box x // obj1 is a generic object type unbox<int> obj1 // Evaluates to 123 (int) unbox<double> obj1 // Throws System.InvalidCastException
firstOf: Free<ShippingInstruction,'T> list -> Free<ShippingInstruction,'T>priced: string -> Free<ShippingInstruction,(string * decimal)>price: decimalcheapest: string list -> Free<ShippingInstruction,(string * decimal)>carriers: string listfree: FreeBuilderprices: (string * decimal) listminBy: ('T -> 'U) -> 'T list -> 'TReturns the lowest of all elements of the list, compared via Operators.min on the function result Raises if list is empty. This is an O(n) operation, where n is the length of the list. The function to transform list elements into the type to be compared. The input list. Thrown when the list is empty. The minimum value. let inputs = ["aaa"; "b"; "cccc"] inputs |> List.minBy (fun s -> s.Length) Evaluates to "b" let inputs = [] inputs |> List.minBy (fun (s: string) -> s.Length) Throws System.ArgumentException.
snd: 'T1 * 'T2 -> 'T2Return the second element of a tuple, snd (a,b) = b. The input tuple. The second value. snd ("first", 2) // Evaluates to 2
fastest: string list -> Free<ShippingInstruction,(string * decimal)>allOf gives every program's result, in the order of the list. firstOf gives the result of the
program that finishes first. One instruction holds programs with one result type, so the helpers
box each program's result and unbox the answer; cheapest and fastest see typed values.
The step for All and First turns each program into a workflow with Free.toWorkflow, so the
instructions inside a program become steps of their own:
type ICarriers =
abstract Quote: key: string * carrier: string -> Task<decimal>
let rec shippingStep (carriers: ICarriers) instruction =
let branches programs =
programs |> List.map (Free.toWorkflow (shippingStep carriers))
match instruction with
| Quote carrier ->
activity $"quote {carrier}" policy (fun attempt ->
carriers.Quote(attempt.IdempotencyKey, carrier))
|> Free.answer
| All programs -> branches programs |> all |> Free.answer
| First programs -> branches programs |> race |> Free.answer
let shipping carriers =
Workflow.define "shipping" (fun (names: string list) ->
Free.toWorkflow (shippingStep carriers) (cheapest names))
Fcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.ICarriersQuote: ICarriers -> string * string -> Task<decimal>keystringAn abbreviation for the CLI type . Basic Types
carrierSystem.Threading.Tasks.Task`1Represents an asynchronous operation that can return a value. The type of the result produced by this .
decimalAn abbreviation for the CLI type . Basic Types
shippingStep: ICarriers -> ShippingInstruction -> Workflow<objnull>carriers: ICarriersinstruction: ShippingInstructionbranches: Free<ShippingInstruction,'a> list -> Workflow<'a> listprograms: Free<ShippingInstruction,'a> list(|>): '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.Collections.ListModuleContains operations for working with values of type . Operations for collections such as lists, arrays, sets, maps and sequences. See also F# Collection Types in the F# Language Guide.
map: ('T -> 'U) -> 'T list -> 'U listBuilds a new collection whose elements are the results of applying the given function to each of the elements of the collection. The function to transform elements from the input list. The input list. The list of transformed elements. let inputs = [ "a"; "bbb"; "cc" ] inputs |> List.map (fun x -> x.Length) Evaluates to [ 1; 3; 2 ] This is an O(n) operation, where n is the length of the list.
FCQRS.Workflows.FreeRuns a program written with `FCQRS.Model.FreeMonad` as a workflow. With both namespaces open, `Free.bind` and `Free.toWorkflow` both resolve.
toWorkflow: ('Instruction -> Workflow<objnull>) -> Free<'Instruction,'Result> -> Workflow<'Result>The workflow that runs `program`: `step` gives the workflow step that carries out each instruction, such as `Free.answer (activity "charge" policy run)`, and its result is the instruction's answer. Each step stores its result as any workflow step does, so a restart replays the stored answers through the program and continues at the instruction it had reached. The program's own code runs again on every replay and must be deterministic, like a workflow body. The step names that `step` gives are persistent contracts, and so is the order in which the program performs its instructions: an instance whose journal holds another name or order is parked. A step whose result has another type than the program expects faults the instance.
Quotecarrier: stringactivity: string -> RetryPolicy -> (AttemptContext -> Task<'T>) -> Workflow<'T>Calls an external system. The call runs at least once: a crash after the call and before its result is stored repeats it, so pass `IdempotencyKey` to the external system. `name` is stored and must not change while instances are running. The policy needs an `AttemptTimeout` or a `Deadline`: an attempt with neither would wait as long as its call, also for a call that ignores its cancellation token.
policy: RetryPolicyattempt: AttemptContextQuote: string * string -> Task<decimal>IdempotencyKey: stringThe same for every attempt of this step, across restarts: workflow name, workflow ID, and step path. Pass it to the external system so a repeated call is recognised.
answer: Workflow<'T> -> Workflow<objnull>A step's result, boxed: the answer that an instruction's continuation takes.
Allprograms: Free<ShippingInstruction,objnull> listall: Workflow<'T> list -> Workflow<'T list>Runs the branches together and gives every result, in branch order. If a branch fails, the others are abandoned and the failure is raised here. Every branch result is stored in this workflow's journal, so use a child workflow per item for a fan-out over thousands of items.
Firstrace: Workflow<'T> list -> Workflow<'T>Runs the branches together. The first to finish decides the result, with its value or its exception, and the others are abandoned. The winner is stored, so replay selects the same branch.
shipping: ICarriers -> WorkflowDefinition<string list,(string * decimal)>FCQRS.Workflows.WorkflowDefines workflows.
define: string -> ('Input -> Workflow<'Result>) -> WorkflowDefinition<'Input,'Result>A workflow named `name` whose instances run `body` on their input.
names: string listlistThe type of immutable singly-linked lists. See the module for further operations related to lists. Use the constructors [] and :: (infix) to create values of this type, or the notation [1; 2; 3]. Use the values in the List module to manipulate values of this type, or pattern match against the values directly. See also F# Language Guide - Lists.
cheapest: string list -> Free<ShippingInstruction,(string * decimal)>Both quotes are scheduled before either completes, and the order in which they complete does not matter. Each step's name holds the carrier, so a test can answer them in any order:
let cheapestWins (carriers: ICarriers) =
let flow = WorkflowTest.Start(shipping carriers, [ "north"; "south" ])
flow.Complete("quote south", 9m)
flow.Complete("quote north", 12m)
flow.CheckReplay()
flow.Result = ("south", 9m)
cheapestWins: ICarriers -> boolcarriers: ICarriersFcqrs_550-how-to_016-run-a-free-program-as-a-workflow.md_page.ICarriersflow: WorkflowTest<string list,(string * decimal)>FCQRS.Workflows.WorkflowTestRuns workflows in memory, for tests. See `WorkflowTest<'Input, 'Result>`.
Start: WorkflowDefinition<'Input,'Result> * 'Input -> WorkflowTest<'Input,'Result>Starts the workflow with `input` at `WorkflowTest.DefaultStart`.
shipping: ICarriers -> WorkflowDefinition<string list,(string * decimal)>Complete: string * 'T -> unitCompletes the waiting activity, command, or child step named `step` with `value`, which is stored and read back as the actor does. A value the step cannot read back fails the step as `NotRetryable`. Raises `InvalidOperationException` when no such step waits, and `ArgumentException` when `value` cannot be stored as the step's result.
CheckReplay: unit -> unitRestarts the instance after every stored record the test produced, gives it the same outcomes, and checks that each restart stores the same journal. Raises `WorkflowReplayException` for the first restart that stores a different record or parks the instance: a body whose steps, stored values, or result change on replay. A pass does not show that the body is deterministic: an activity's arguments are not stored, so a GUID or a time read outside a step that reaches only an activity's call is not seen.
Result: string * decimalThe body's result. Raises `WorkflowFaultedException` or `WorkflowCancelledException` when the instance ended otherwise, and `InvalidOperationException` while it has not ended.
(=): '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
With fastest, race stores the first quote that completes and cancels the other step. Another
interpreter decides what All and First mean for it. A function that Free.run calls can run the
programs of All one after another and answer First with its first program's result. An
interpreter for Free.runTask receives no cancellation token, so it cannot stop the programs that
lose a race.
What the program must keep
- The program's code must be deterministic. It runs again on every replay, like a workflow body. It reads time and random values through instructions, never directly.
- Step names are persistent contracts. The name each instruction's step has, such as
"reserve", is stored. Renaming it, or changing the order in which a program performs its instructions, parks the instances that are running. Change a program that has running instances as Change a workflow while instances are running describes; aversionstep can be one more instruction. - Answer types are checked when the program runs. A step whose result has another type than
the instruction's caller expects faults the instance with an exception that names both types.
Pair each instruction with a typed function, as
reserveandchargedo, so the type is written once. - A program performs one instruction at a time. Steps run together only inside one
instruction, as Run instructions together shows. The position of
each program in
AllorFirstis part of its steps' stored paths, so reordering the programs parks running instances, as reordering instructions does.
Next: Test your domain checks decisions, replay, and retries.