From 6cdd9f96b8f0dc16bdc45947a97311c8e421c804 Mon Sep 17 00:00:00 2001 From: Dominic Fox <40790090+r3domfox@users.noreply.github.com> Date: Tue, 5 Feb 2019 14:19:08 +0000 Subject: [PATCH] CORDA-2423 document draining requirements in flow state machines (#4707) * CORDA-2423 document draining requirements in flow state machines * Expand and move to warning block * Add warning to hello-world-flow.rst --- docs/source/flow-state-machines.rst | 11 +++++++++++ docs/source/hello-world-flow.rst | 9 +++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/source/flow-state-machines.rst b/docs/source/flow-state-machines.rst index a36b69f44c..8c8c217153 100644 --- a/docs/source/flow-state-machines.rst +++ b/docs/source/flow-state-machines.rst @@ -400,6 +400,17 @@ minutes, hours or even days in the case of a flow that needs human interaction! special token that's recognised by the platform, and wired up to the right instance when the continuation is loaded off disk again. +.. warning:: If a node has flows still in a suspended state, with flow continuations written to disk, it will not be + possible to upgrade that node to a new version of Corda or your app, because flows must be completely "drained" + before an upgrade can be performed, and must reach a finished state for draining to complete (see + :ref:`draining_the_node` for details). While there are mechanisms for "evolving" serialised data held + in the vault, there are no equivalent mechanisms for updating serialised checkpoint data. For this + reason it is not a good idea to design flows with the intention that they should remain in a suspended + state for a long period of time, as this will obstruct necessary upgrades to Corda itself. Any + long-running business process should therefore be structured as a series of discrete transactions, + written to the vault, rather than a single flow persisted over time through the flow checkpointing + mechanism. + ``receive`` and ``sendAndReceive`` return a simple wrapper class, ``UntrustworthyData``, which is just a marker class that reminds us that the data came from a potentially malicious external source and may have been tampered with or be unexpected in other ways. It doesn't add any functionality, but acts as a reminder to "scrub" diff --git a/docs/source/hello-world-flow.rst b/docs/source/hello-world-flow.rst index 51f5210076..ad72155142 100644 --- a/docs/source/hello-world-flow.rst +++ b/docs/source/hello-world-flow.rst @@ -27,6 +27,15 @@ We also need the borrower to receive the transaction and record it for itself. A to approve and sign IOU issuance transactions. We will be able to impose this requirement when we look at contracts in the next tutorial. +.. warning:: The execution of a flow is distributed in space and time, as the flow crosses node boundaries and each + participant may have to wait for other participants to respond before it can complete its part of the + overall work. While a node is waiting, the state of its flow may be persistently recorded to disk as a + restorable checkpoint, enabling it to carry on where it left off when a counterparty responds. However, + before a node can be upgraded to a newer version of Corda, or of your Cordapp, all flows must have + completed, as there is no mechanism to upgrade a persisted flow checkpoint. It is therefore undesirable + to model a long-running business process as a single flow: it should rather be broken up into a series + of transactions, with flows used only to orchestrate the completion of each transaction. + Subflows ^^^^^^^^ Tasks like recording a transaction or sending a transaction to a counterparty are very common in Corda. Instead of