PlantUML est un outil open-source qui permet de dessiner rapidement tout un tas de diagrammes. Voyons un exemple avec le diagramme séquence.

Le code est explicite et facile à prendre en main :

@startuml img/resume-upload-s3.svg

' Agrandissement x4
scale 4.0

' Le titre optionnel du diagramme
header Resume a S3 upload

Client -[#green]> S3: Ask for uploaded chunks using a given multipart upload ID
note right: API: ListParts\nACL: s3:ListMultipartUploadParts
Client <[#green]-- S3: Uploaded chunks
Client --[#red]x S3: No such multipart upload ID or  **no enough ACL**:\nstop now and start a new S3 upload

loop missing chunks count
Client -[#blue]> S3: Upload chunk N
note right: API: UploadPart\nACL: s3:PutObject
Client <[#blue]-- S3: Chunk N uploaded
end

Client -[#orange]> S3: Complete the multipart upload
note right: API: CompleteMultipartUpload\nACL: s3:PutObject
Client <[#orange]-- S3: Response OK

Client -> Nuxeo: Attach the blob to the document
Client <-- Nuxeo: Response OK

@enduml

Dans cet exemple, le code commence par @startuml img/resume-upload-s3.svg, ce qui permet de spécifier le fichier de sortie lors de la génération de celui-ci. Ici, on veut du SVG, mais PNG ou texte (ASCII art) sont possibles aussi.
Le chemin du fichier n'est pas obligatoire et seul @startuml est requis.

Pour générer le fichier de sortie :

$ plantuml -tsvg uploads.txt

Voici le résultat :

resume-upload-s3.png

Petite astuce si le diagramme est destiné à faire parti d'une page de documentation écrite en markdown : le code de génération peut-être incrusté dans un commentaire.

# Upload Process

Find here sequencial diagrams of how chunked uploads are managed.

## Using the Amazon S3 Upload Handler

### Resume a S3 Upload

Required ACLs:

- [s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html)
- [s3:ListMultipartUploadParts](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuAndPermissions.html)

Used APIs:

- [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)
- [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html)
- [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html)

Depending of current ACLs given to the AIM of the bucket, one may not be able to resume a transfer if the `s3:ListMultipartUploadParts` is not granted.
On the following diagram, you can see that there will be a **new upload** initiated if that is the case:

![resume-upload-s3.svg](img/resume-upload-s3.svg)

<!--
@startuml img/resume-upload-s3.svg
scale 4.0
header Resume a S3 upload

Client -[#green]> S3: Ask for uploaded chunks using a given multipart upload ID
note right: API: ListParts\nACL: s3:ListMultipartUploadParts
Client <[#green]-- S3: Uploaded chunks
Client --[#red]x S3: No such multipart upload ID or  **no enough ACL**:\nstop now and start a new S3 upload

loop missing chunks count
Client -[#blue]> S3: Upload chunk N
note right: API: UploadPart\nACL: s3:PutObject
Client <[#blue]-- S3: Chunk N uploaded
end

Client -[#orange]> S3: Complete the multipart upload
note right: API: CompleteMultipartUpload\nACL: s3:PutObject
Client <[#orange]-- S3: Response OK

Client -> Nuxeo: Attach the blob to the document
Client <-- Nuxeo: Response OK

@enduml
-->

Et pour générer le fichier de sortie :

$ plantuml -tsvg uploads.md

Si le fichier markdown contient plusieurs diagrammes, ils seront tous générés (exemple). Bien pratique !