Skip to content

Commit 17e882b

Browse files
stephencdalystephencdaly
committed
Update file upload sequence diagram
1 parent e6e1d71 commit 17e882b

1 file changed

Lines changed: 132 additions & 76 deletions

File tree

‎diagrams/sequence-diagrams/file-upload.md‎

Lines changed: 132 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ graph LR
3838
3939
sqs --subscribe to topic--> sns
4040
41-
forms --store/get/delete completed form<br/>update delivery status--> rds
41+
forms --store/get/delete submission<br/>update delivery status--> rds
4242
4343
ses --delivery<br />notification--> sns
4444
@@ -62,36 +62,33 @@ graph LR
6262

6363
## Uploading a file when completing a form
6464

65+
### User completes a file upload question
66+
6567
```mermaid
6668
6769
---
68-
title: GOV.UK Forms File Upload
70+
title: User completes a file upload question
6971
---
7072
7173
sequenceDiagram
7274
7375
autonumber
7476
75-
actor user
77+
actor user as User
7678
77-
participant browser
79+
participant browser as Browser
7880
79-
participant runner as forms-runner
81+
participant runner as Forms Runner
8082
participant s3 as Amazon S3
8183
participant guard as Amazon GuardDuty
82-
participant ses as Amazon SES
83-
participant inbox as email inbox
84-
85-
actor processor
8684
8785
user->>browser: navigate to file upload page
8886
browser->>runner: GET file upload page
8987
runner->>runner: render file upload page
90-
note over runner: can use "accept"<br />HTML attribute to<br />limit file type(s)
91-
runner->>browser: HTTP response
88+
runner->>browser: HTTP 200 response
9289
browser->>user: display file upload page
9390
94-
note over user: users sees "File upload" component<br/>from GOV.UK Design System
91+
note over user: User sees "File upload" component<br/>from GOV.UK Design System
9592
9693
user->>browser: select "Choose file"
9794
browser->>user: display file dialog
@@ -100,12 +97,13 @@ browser->>user: display filename of selected file
10097
user->>browser: select "Continue"
10198
10299
browser->>runner: POST file
103-
note over runner: Need to check memory requirements if holding files in memory
104100
105-
runner->>runner: check filesize
106-
note over runner: is check done during upload or after upload?
101+
runner->>runner: validate file size and type
107102
108-
note over runner: how to handle file size too big?
103+
opt Invalid file
104+
runner->>browser: HTTP 422 response
105+
browser->>user: display file upload page with error message
106+
end
109107
110108
runner->>s3: write file
111109
runner->>runner: associate file with user session
@@ -114,97 +112,155 @@ s3->>guard: new object event
114112
note over guard: GuardDuty<br />Malware Protection<br />for S3
115113
guard->>s3: scan
116114
117-
runner->>s3: GetObjectTagging
118-
s3->>runner: return TagSet
119-
120-
note over runner: poll until tags returned
121-
122115
alt No malware detected
123-
guard->>s3: tag object NO_THREATS_FOUND
116+
guard->>s3: tag object NO_THREATS_FOUND
124117
else otherwise
125-
guard->>s3: tag object
118+
guard->>s3: tag object
126119
end
127120
128-
runner->>s3: GetObjectTagging
129-
s3->>runner: return TagSet
121+
loop poll until GuardDuty tag is returned
122+
runner->>s3: GetObjectTagging
123+
s3->>runner: return TagSet
124+
end
130125
131-
note over user,guard: will user wait until file upload and checks have completed?
126+
note over runner,guard: We may want to change how we get the GuardDuty status if making<br/>the user wait while we poll causes issues
132127
133-
opt file not OK
134-
runner->>browser: redirect to error
135-
browser->>runner: GET file upload page with error (following redirect)
136-
runner->>browser: HTTP response
137-
browser->>user: display error message
138-
note over user: now what?<br />allow user to try again?
128+
opt GuardDuty status is not NO_THREATS_FOUND
129+
runner->>browser: HTTP 422 response
130+
browser->>user: display file upload page with error message
139131
end
140132
141-
runner->>browser: redirect to next page
142-
browser->>runner: GET next page (following redirect)
143-
runner->>browser: HTTP reponse
133+
runner->>browser: HTTP 302 redirect response
134+
browser->>runner: GET review file page
135+
browser->>user: display review file page with uploaded filename
136+
note over user,browser: User can choose to remove their file. If they<br/>do they are shown a confirmation page, and taken<br/>back to the file upload page if they confirm.
137+
138+
user->>browser: select "Continue"
139+
140+
runner->>browser: HTTP 302 redirect response
141+
142+
note over user,runner: User completes the rest of the questions
143+
```
144+
145+
### User submits their form
146+
```mermaid
147+
148+
---
149+
title: User submits their form
150+
---
151+
152+
sequenceDiagram
153+
154+
autonumber
155+
156+
actor user as User
157+
158+
participant browser as Browser
144159
145-
note over user,runner: complete rest of questions
160+
participant runner as Forms Runner
161+
participant runner-db as Forms Runner database
162+
participant solidqueue-db as Solid Queue database
146163
147164
browser->>runner: GET check your answers
148-
runner->>browser: HTTP response
165+
runner->>browser: HTTP 200 response
149166
browser->>user: display check your answers page
150167
151-
user->>browser: submit form
168+
user->>browser: select "Submit"
152169
browser->>runner: POST submit form
170+
runner->>runner-db: save Submission
171+
runner->>solidqueue-db: enqueue send submission job
153172
154-
note over runner: Also considering asynchronous email sending via queue
155-
156-
runner->>s3: get file(s)
157-
158-
note over runner: Need to check memory requirements if holding files in memory
159-
160-
runner->>ses: send email
161-
alt success:
162-
ses->>inbox: send email
163-
runner->>browser: redirect to confirmation
164-
browser->>runner: GET confirmation page
165-
runner->>browser: HTTP reponse
166-
browser->>user: display confirmation page
167-
processor->>inbox: get form from inbox
168-
processor->>processor: process form
169-
else failure:
170-
runner->>browser: redirect to error
171-
browser->>runner: GET error page
172-
runner->>browser: HTTP reponse
173-
browser->>user: display error page
174-
note over user: now what?<br />allow user to try again?
175-
end
176-
```
173+
runner->>browser: HTTP 302 response
174+
browser->>runner: GET confirmation page
175+
runner->>browser: HTTP 200 response
176+
browser->>user: Display confirmation page
177177
178-
## Asynchronous form sending
178+
```
179179

180-
> [!NOTE]
181-
> Asynchronous form sending has not yet been implemented, these are ideas / proposals:
180+
### Sending the submission email asynchronously
182181

183182
```mermaid
184183
185184
---
186-
title: GOV.UK Forms Asynchronous form sending
185+
title: Sending the submission email asynchronously
187186
---
188187
189188
sequenceDiagram
190189
191190
autonumber
192191
193-
participant runner as forms-runner
192+
participant worker as Forms runner worker
193+
participant solidqueue-db as Solid Queue database
194+
participant runner-db as Forms Runner database
194195
participant s3 as Amazon S3
195196
participant ses as Amazon SES
196-
participant inbox as email inbox
197+
participant sns as Amazon SNS
198+
participant inbox as Email inbox
199+
participant sentry as Sentry
197200
198201
actor processor
199202
200-
runner->>runner: enqueue email sending job
201-
note over runner: some time later...
202-
runner->>runner: dequeue email sending job
203-
runner->>s3: get file(s)
204-
runner->>ses: send email
205-
note over runner,ses: how are errors handled?
206-
ses->>inbox: send email
207-
processor->>inbox: get form from inbox
208-
processor->>processor: process form
203+
worker->>solidqueue-db: dequeue send submission job
204+
worker->>runner-db: get Submission
205+
worker->>s3: get file(s)
206+
worker->>ses: send email
207+
208+
break error
209+
alt AWS SDK error and max retries not reached
210+
worker->>solidqueue-db: schedule retry
211+
else
212+
worker->>sentry: send error
213+
end
214+
end
215+
216+
ses->>worker: return message_id
217+
worker->>runner-db: set mail_message_id on Submission
218+
worker->>runner-db: update mail_status of Submission to "pending"
219+
220+
ses-)inbox: send email
221+
note over ses,inbox: happens some time later
209222
223+
alt email sent successfully
224+
processor->>inbox: get form from inbox
225+
processor->>processor: process form
226+
else email bounces
227+
ses->>sns: send bounce notification
228+
note over ses,sns: We have an SQS queue subscribed to the<br/> SNS topic and a recurring task to poll<br/>the SQS queue.
229+
end
210230
```
231+
232+
### Handling email bounces/complaints
233+
```mermaid
234+
235+
---
236+
title: Handling email bounces/complaints
237+
---
238+
239+
sequenceDiagram
240+
241+
autonumber
242+
243+
participant worker as Solid Queue worker
244+
participant solidqueue-db as Solid Queue database
245+
participant runner-db as Forms Runner database
246+
participant sqs as Amazon SQS
247+
participant inbox as Email inbox
248+
participant sentry as Sentry
249+
250+
actor support as Forms team tech support
251+
252+
worker->>solidqueue-db: enqueue recurring receive bounces job
253+
worker->>solidqueue-db: dequeue receive bounces job
254+
worker->>sqs: get messages from bounces and complaints queue
255+
alt there is a bounce SQS message
256+
worker->>runner-db: get Submission by the message_id in the SQS message
257+
worker->>runner-db: update mail_status of Submission to "bounced"
258+
worker->>sentry: send error event
259+
else there is a complaint SQS message
260+
worker->>worker: Log that there was a complaint
261+
end
262+
263+
support->>sentry: Alert via Slack
264+
support->>support: Identify why the email bounced
265+
support->>support: Run rake task to retry submission
266+
```

0 commit comments

Comments
 (0)