Starts the comparison itself, once both sides are ready, and queues its
opening message for the pump.
Either side may call this, and only while getVerificationStage
reads 'ready'. Two sides calling it at the same moment is safe: the
protocol settles which comparison survives.
The same side calling twice is refused, and that is deliberate. A
double tap on a button, or a retry after an unrelated failure, would
otherwise build a second comparison under the same identifier and destroy
the flow while reporting success.
Three different rejections, because three different things have to
happen next. The layer underneath reports one error for all of them;
this function reads getVerificationStage to tell them apart,
because a screen that shows a person one sentence for all three is
showing the wrong one most of the time:
'comparison_already_started' -- the other side started it first.
Nothing is wrong, but there is something left for you to do:
call acceptVerification again. Their start is a question, and
until you answer it they are waiting and the flow does not move. This
used to say "wait for 'keys-exchanged'", which was wrong: waiting
alone never produced one. Then read
getVerificationMaterial as usual.
A flow that went to a scanned code arrives at this same kind, and
wants none of that done about it. This kind is derived from
getVerificationStage reading 'started', and a code flow reads
'started' too, so the kind cannot tell the two apart. On a code flow
acceptVerification answers 'wrong_stage' and so does
getVerificationMaterial, because there is no comparison and
there will be no string: carry on with getVerificationCode and
confirmScan, or with submitScannedCode. What tells
the two apart is your own state, not anything this library reports: a
build that never called offerScannableCodes can only be in the
first case, and one that asked this flow for a code knows it is in the
second.
'verification_ended' -- the flow is over, whether it finished or was
refused. There is nothing to carry on with; ask again with
requestVerification if you still want to.
'wrong_stage' -- anything else, which means either that the flow has
not been agreed by both sides yet, or that it became a code rather
than a comparison. Read getVerificationStage: 'requested' is
the first, and it wants a wait or an acceptVerification if the
invitation was yours to answer; 'code-scanned' is the second, and it
wants confirmScan. 'ready' is neither, and it is the one
answer here that says nothing is wrong with the flow: the stage moved
between this call and the stage read that followed it, so try again.
A code flow reaches two of these bullets, and which one is the code's
own state. Before anybody has scanned it the stage is 'started' and
this call answers 'comparison_already_started', whose advice is written
for a comparison and is the loop described in that bullet; once somebody
has scanned it the stage is 'code-scanned' and the rejection stays
'wrong_stage'. Two assertions in facade.test.ts hold the pair apart:
reports comparison_already_started for a flow that went to a scanned code and leaves the rejection as wrong_stage for a flow that became a code somebody scanned.
Starts the comparison itself, once both sides are ready, and queues its opening message for the pump.
Either side may call this, and only while getVerificationStage reads
'ready'. Two sides calling it at the same moment is safe: the protocol settles which comparison survives.The same side calling twice is refused, and that is deliberate. A double tap on a button, or a retry after an unrelated failure, would otherwise build a second comparison under the same identifier and destroy the flow while reporting success.
Three different rejections, because three different things have to happen next. The layer underneath reports one error for all of them; this function reads getVerificationStage to tell them apart, because a screen that shows a person one sentence for all three is showing the wrong one most of the time:
'comparison_already_started'-- the other side started it first. Nothing is wrong, but there is something left for you to do: call acceptVerification again. Their start is a question, and until you answer it they are waiting and the flow does not move. This used to say "wait for'keys-exchanged'", which was wrong: waiting alone never produced one. Then read getVerificationMaterial as usual.A flow that went to a scanned code arrives at this same kind, and wants none of that done about it. This kind is derived from getVerificationStage reading
'started', and a code flow reads'started'too, so the kind cannot tell the two apart. On a code flow acceptVerification answers'wrong_stage'and so does getVerificationMaterial, because there is no comparison and there will be no string: carry on with getVerificationCode and confirmScan, or with submitScannedCode. What tells the two apart is your own state, not anything this library reports: a build that never called offerScannableCodes can only be in the first case, and one that asked this flow for a code knows it is in the second.'verification_ended'-- the flow is over, whether it finished or was refused. There is nothing to carry on with; ask again with requestVerification if you still want to.'wrong_stage'-- anything else, which means either that the flow has not been agreed by both sides yet, or that it became a code rather than a comparison. Read getVerificationStage:'requested'is the first, and it wants a wait or an acceptVerification if the invitation was yours to answer;'code-scanned'is the second, and it wants confirmScan.'ready'is neither, and it is the one answer here that says nothing is wrong with the flow: the stage moved between this call and the stage read that followed it, so try again.A code flow reaches two of these bullets, and which one is the code's own state. Before anybody has scanned it the stage is
'started'and this call answers'comparison_already_started', whose advice is written for a comparison and is the loop described in that bullet; once somebody has scanned it the stage is'code-scanned'and the rejection stays'wrong_stage'. Two assertions infacade.test.tshold the pair apart:reports comparison_already_started for a flow that went to a scanned codeandleaves the rejection as wrong_stage for a flow that became a code somebody scanned.