State Diagrams! (#283)

* docs(diagrams): add generated state diagrams

Uses FSM UML generator to build state diagram visualizations for market modules (client & provider
for storage & retrieval)

* build(diagrams): automate diagram build and check

* fix(tests): fix tests & makefile

update fsm & makefile to resolve issues in build

* fix(deps): mod tidy

* fix(deps): update fsm uml generator

* docs(diagrams): make ordering static

* ci(deps): install puppeteer deps

* docs(diagrams): make pngs update only on change

* docs(diagrams): fix final FSM gen

* fix(lint): fix errors

* fix(Makefile): add node_modules build

* docs(diagrams): add pngs

* fix(deps): update go-statemachine

rebase and update go-statemachine

.circleci/config.yml

@@ -2,11 +2,12 @@ version: 2.1
 orbs:
   go: gotest/[email protected]
   codecov: codecov/[email protected]
+  node: circleci/[email protected]
 
 executors:
   golang:
     docker:
-      - image: circleci/golang:1.13
+      - image: circleci/golang:1.13-node
     resource_class: large
 
 commands:
@@ -51,6 +52,27 @@ jobs:
       - run: go generate ./...
       - run: git --no-pager diff
       - run: git --no-pager diff --quiet
+
+
+  docs-check:
+    executor: golang
+    steps:
+      - install-deps
+      - prepare
+      - run: 
+          name: Install Headless Chrome Dependencies
+          command: |
+            sudo apt-get install -yq \
+            gconf-service libasound2 libatk1.0-0 libatk-bridge2.0-0 libc6 libcairo2 libcups2 libdbus-1-3 \
+            libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \
+            libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 \
+            libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates \
+            fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget
+      - node/install-packages
+      - run: make diagrams
+      - run: git --no-pager diff
+      - run: git --no-pager diff --quiet
+
   build-all:
     executor: golang
     steps:
@@ -172,4 +194,5 @@ workflows:
       - test
       - mod-tidy-check
       - cbor-gen-check
+      - docs-check
       - build-all

.gitignore

@@ -17,3 +17,6 @@ filestore/_test/
 
 .filecoin-build
 .update-modules
+
+# NPM
+node_modules/

Makefile

@@ -35,4 +35,27 @@ test: build
 clean:
 	rm -f .filecoin-build
 	rm -f .update-modules
-	rm -f coverage.txt
+	rm -f coverage.txt
+
+DOTs=$(shell find docs -name '*.dot')
+MMDs=$(shell find docs -name '*.mmd')
+SVGs=$(DOTs:%=%.svg) $(MMDs:%=%.svg)
+PNGs=$(DOTs:%=%.png) $(MMDs:%=%.png)
+
+node_modules: package.json
+	npm install
+
+diagrams: ${MMDs} ${SVGs} ${PNGs}
+
+%.mmd.svg: %.mmd
+	node_modules/.bin/mmdc -i $< -o $@
+
+%.mmd.png: %.mmd
+	node_modules/.bin/mmdc -i $< -o $@
+
+FORCE:
+
+docsgen: FORCE .update-modules .filecoin-build
+	go run ./docsgen
+
+$(MMDs): docsgen node_modules

docs/retrievalclient.mmd

@@ -0,0 +1,74 @@
+stateDiagram-v2
+	state "DealStatusNew" as 0
+	state "DealStatusPaymentChannelCreating" as 1
+	state "DealStatusPaymentChannelAddingFunds" as 2
+	state "DealStatusPaymentChannelReady" as 4
+	state "DealStatusAccepted" as 6
+	state "DealStatusFailed" as 7
+	state "DealStatusRejected" as 8
+	state "DealStatusFundsNeeded" as 9
+	state "DealStatusOngoing" as 10
+	state "DealStatusFundsNeededLastPayment" as 11
+	state "DealStatusCompleted" as 12
+	state "DealStatusDealNotFound" as 13
+	state "DealStatusErrored" as 15
+	state "DealStatusBlocksComplete" as 16
+	state "DealStatusFinalizing" as 17
+	0 : On entry runs ProposeDeal
+	1 : On entry runs WaitForPaymentChannelCreate
+	2 : On entry runs WaitForPaymentChannelAddFunds
+	4 : On entry runs ProcessNextResponse
+	6 : On entry runs SetupPaymentChannelStart
+	9 : On entry runs ProcessPaymentRequested
+	10 : On entry runs ProcessNextResponse
+	11 : On entry runs ProcessPaymentRequested
+	16 : On entry runs ProcessNextResponse
+	17 : On entry runs Finalize
+	[*] --> 0
+	note right of 0
+		The following events are not shown cause they can trigger from any state.
+
+		ClientEventWriteDealProposalErrored - transitions state to DealStatusErrored
+		ClientEventReadDealResponseErrored - transitions state to DealStatusErrored
+		ClientEventUnknownResponseReceived - transitions state to DealStatusFailed
+		ClientEventWriteDealPaymentErrored - transitions state to DealStatusErrored
+	end note
+	0 --> 0 : ClientEventOpen
+	1 --> 7 : ClientEventPaymentChannelErrored
+	6 --> 7 : ClientEventPaymentChannelErrored
+	6 --> 1 : ClientEventPaymentChannelCreateInitiated
+	6 --> 2 : ClientEventPaymentChannelAddingFunds
+	1 --> 4 : ClientEventPaymentChannelReady
+	2 --> 4 : ClientEventPaymentChannelReady
+	1 --> 7 : ClientEventAllocateLaneErrored
+	2 --> 7 : ClientEventAllocateLaneErrored
+	2 --> 7 : ClientEventPaymentChannelAddFundsErrored
+	0 --> 8 : ClientEventDealRejected
+	0 --> 13 : ClientEventDealNotFound
+	0 --> 6 : ClientEventDealAccepted
+	9 --> 7 : ClientEventFundsExpended
+	11 --> 7 : ClientEventFundsExpended
+	9 --> 7 : ClientEventBadPaymentRequested
+	11 --> 7 : ClientEventBadPaymentRequested
+	9 --> 7 : ClientEventCreateVoucherFailed
+	11 --> 7 : ClientEventCreateVoucherFailed
+	9 --> 10 : ClientEventPaymentSent
+	11 --> 17 : ClientEventPaymentSent
+	4 --> 7 : ClientEventConsumeBlockFailed
+	10 --> 7 : ClientEventConsumeBlockFailed
+	4 --> 11 : ClientEventLastPaymentRequested
+	10 --> 11 : ClientEventLastPaymentRequested
+	16 --> 11 : ClientEventLastPaymentRequested
+	4 --> 16 : ClientEventAllBlocksReceived
+	10 --> 16 : ClientEventAllBlocksReceived
+	16 --> 16 : ClientEventAllBlocksReceived
+	4 --> 12 : ClientEventComplete
+	10 --> 12 : ClientEventComplete
+	16 --> 12 : ClientEventComplete
+	17 --> 12 : ClientEventComplete
+	4 --> 7 : ClientEventEarlyTermination
+	10 --> 7 : ClientEventEarlyTermination
+	4 --> 9 : ClientEventPaymentRequested
+	10 --> 9 : ClientEventPaymentRequested
+	4 --> 10 : ClientEventBlocksReceived
+	10 --> 10 : ClientEventBlocksReceived

docs/retrievalprovider.mmd

@@ -0,0 +1,53 @@
+stateDiagram-v2
+	state "DealStatusNew" as 0
+	state "DealStatusAwaitingAcceptance" as 5
+	state "DealStatusAccepted" as 6
+	state "DealStatusFailed" as 7
+	state "DealStatusRejected" as 8
+	state "DealStatusFundsNeeded" as 9
+	state "DealStatusOngoing" as 10
+	state "DealStatusFundsNeededLastPayment" as 11
+	state "DealStatusCompleted" as 12
+	state "DealStatusDealNotFound" as 13
+	state "DealStatusErrored" as 15
+	state "DealStatusBlocksComplete" as 16
+	state "DealStatusFinalizing" as 17
+	0 : On entry runs ReceiveDeal
+	5 : On entry runs DecideOnDeal
+	6 : On entry runs SendBlocks
+	7 : On entry runs SendFailResponse
+	8 : On entry runs SendFailResponse
+	9 : On entry runs ProcessPayment
+	10 : On entry runs SendBlocks
+	11 : On entry runs ProcessPayment
+	13 : On entry runs SendFailResponse
+	17 : On entry runs Finalize
+	[*] --> 0
+	note right of 0
+		The following events are not shown cause they can trigger from any state.
+
+		ProviderEventWriteResponseFailed - transitions state to DealStatusErrored
+		ProviderEventReadPaymentFailed - transitions state to DealStatusErrored
+	end note
+	0 --> 0 : ProviderEventOpen
+	0 --> 5 : ProviderEventDealReceived
+	5 --> 15 : ProviderEventDecisioningError
+	0 --> 7 : ProviderEventGetPieceSizeErrored
+	0 --> 13 : ProviderEventDealNotFound
+	0 --> 8 : ProviderEventDealRejected
+	5 --> 8 : ProviderEventDealRejected
+	5 --> 6 : ProviderEventDealAccepted
+	6 --> 7 : ProviderEventBlockErrored
+	10 --> 7 : ProviderEventBlockErrored
+	6 --> 16 : ProviderEventBlocksCompleted
+	10 --> 16 : ProviderEventBlocksCompleted
+	6 --> 9 : ProviderEventPaymentRequested
+	10 --> 9 : ProviderEventPaymentRequested
+	16 --> 11 : ProviderEventPaymentRequested
+	9 --> 7 : ProviderEventSaveVoucherFailed
+	11 --> 7 : ProviderEventSaveVoucherFailed
+	9 --> 9 : ProviderEventPartialPaymentReceived
+	11 --> 11 : ProviderEventPartialPaymentReceived
+	9 --> 10 : ProviderEventPaymentReceived
+	11 --> 17 : ProviderEventPaymentReceived
+	17 --> 12 : ProviderEventComplete

docs/storageclient.mmd

@@ -0,0 +1,63 @@
+stateDiagram-v2
+	state "StorageDealUnknown" as 0
+	state "StorageDealProposalAccepted" as 3
+	state "StorageDealSealing" as 5
+	state "StorageDealActive" as 6
+	state "StorageDealExpired" as 7
+	state "StorageDealSlashed" as 8
+	state "StorageDealFailing" as 9
+	state "StorageDealFundsEnsured" as 11
+	state "StorageDealWaitingForDataRequest" as 12
+	state "StorageDealValidating" as 13
+	state "StorageDealTransferring" as 15
+	state "StorageDealEnsureClientFunds" as 19
+	state "StorageDealClientFunding" as 21
+	state "StorageDealError" as 24
+	3 : On entry runs ValidateDealPublished
+	5 : On entry runs VerifyDealActivated
+	6 : On entry runs WaitForDealCompletion
+	9 : On entry runs FailDeal
+	11 : On entry runs ProposeDeal
+	12 : On entry runs WaitingForDataRequest
+	13 : On entry runs VerifyDealResponse
+	19 : On entry runs EnsureClientFunds
+	21 : On entry runs WaitForFunding
+	[*] --> 0
+	note right of 0
+		The following events are not shown cause they can trigger from any state.
+
+		ClientEventStreamCloseError - transitions state to StorageDealError
+		ClientEventRestart - does not transition state
+	end note
+	0 --> 19 : ClientEventOpen
+	19 --> 21 : ClientEventFundingInitiated
+	19 --> 9 : ClientEventEnsureFundsFailed
+	21 --> 9 : ClientEventEnsureFundsFailed
+	19 --> 11 : ClientEventFundsEnsured
+	21 --> 11 : ClientEventFundsEnsured
+	11 --> 24 : ClientEventWriteProposalFailed
+	11 --> 12 : ClientEventDealProposed
+	12 --> 24 : ClientEventReadResponseFailed
+	13 --> 24 : ClientEventReadResponseFailed
+	12 --> 9 : ClientEventResponseVerificationFailed
+	13 --> 9 : ClientEventResponseVerificationFailed
+	12 --> 9 : ClientEventUnexpectedDealState
+	12 --> 9 : ClientEventDataTransferFailed
+	15 --> 9 : ClientEventDataTransferFailed
+	12 --> 15 : ClientEventDataTransferInitiated
+	12 --> 13 : ClientEventDataTransferComplete
+	15 --> 13 : ClientEventDataTransferComplete
+	13 --> 9 : ClientEventResponseDealDidNotMatch
+	13 --> 9 : ClientEventDealRejected
+	13 --> 3 : ClientEventDealAccepted
+	3 --> 24 : ClientEventDealPublishFailed
+	3 --> 5 : ClientEventDealPublished
+	5 --> 24 : ClientEventDealActivationFailed
+	5 --> 6 : ClientEventDealActivated
+	6 --> 8 : ClientEventDealSlashed
+	6 --> 7 : ClientEventDealExpired
+	6 --> 24 : ClientEventDealCompletionFailed
+	9 --> 24 : ClientEventFailed
+	8 --> [*]
+	7 --> [*]
+	24 --> [*]