Journal Écrire des diagrammes de séquences

Posté par goeb le 13 septembre 2016 à 20:51. Licence CC By‑SA.

Étiquettes :

sept.

2016

Ce journal a été promu en dépêche : Écrire des diagrammes de séquences.

Les diagrammes de séquences sont très utiles pour représenter le déroulement d'événements au fil du temps. Ils sont par exemple très utilisés pour décrire des protocoles de communication, où les paquets d'information se croisent, se perdent, passent du temps dans les tuyaux.

Ces diagrammes comportent :

des acteurs, avec leur ligne de vie (un acteur peut représenter une personne, une machine, un process, un thread, …). La spécification UML utilise le terme de "participant".
des messages échangés entre acteurs

On fait ces dessins au tableau, puis on les efface, mais parfois on voudrait les inclure dans une page d'un document, ou les envoyer par email.

Logiciels existants

Des outils logiciels existent, pour générer de tels diagrammes :

éditeur de texte (ascii art)
Mscgen (http://www.mcternan.me.uk/mscgen)
éditeurs dits UML
éditeurs SDL (Specification and Description Language)
éditeurs de diagrammes : Dia, Libreoffice, Microsoft Visio, …

Mais pour le moment je ne suis pas satisfait de ceux que j'ai utilisés. Je voudrais les possibilités suivantes :

créer un acteur ou le détruire au cours du temps
croiser les échanges de messages
perdre un message
indiquer l'expiration d'un temps imparti (timeout)
faire une mise en page du dessin sans dessiner (j'entends par là que je ne veux pas passer trop de temps à déplacer à la souris les éléments pour les aligner ou les relier, et puis tout décaler un par un parce que j'ai inséré un nouvel acteur en plein milieu, …)
avoir un logiciel gratuit et open-source

Si quelqu'un connaît un tel logiciel, je suis preneur.

Et alors ?

En attendant j'ai fait un prototype d'un tel logiciel que j'appelle pour le moment "meseq" sur le principe de mscgen :

on écrit un fichier texte décrivant le scénario
meseq génère une image PNG à partir de ce fichier

L'avantage de cette approche est la simplicité et la rapidité de développement de l'outil, mais l'inconvénient est que c'est moins ergonomique qu'un éditeur avec rendu WYSIWYG.

J'ai mis au point une syntaxe rudimentaire pour le fichier d'entrée. Je sais déjà que je vais la modifier pour la rendre plus évolutive.
Voici un exemple pour illustrer cette syntaxe (fichier .msq) :

[init]
actors w3client proxy "" w3server

[scenario]

w3client   ->   proxy   CONNECT
w3client   <-   proxy   OK
w3client   ->   proxy   bytes
proxy      ->   w3server bytes
:
w3client  <->   w3server "TLS Handshake\nwhat follows is ciphered"
:
:
w3client   ->    proxy   "GET /index.html"
proxy      ->   w3server "GET /index.html"
proxy      <-   w3server "200, index.html"
w3client   <-    proxy   "200, index.html"

Et voici l'image générée par meseq (plus complète que l'exemple ci-dessus) :

example_web.msq.png

Autre exemple, avec flèches qui se croisent, etc. :

example_piggyback.msq.png

Show me the prototype

Ce prototype est là pour étudier la faisabilité, présenter mes idées, et expérimenter.
Bon, il est codé vite et mal : non documenté, buggué, mal structuré,… Bref, un vrai code de goret.

Ce prototype et les exemples sont sur Github : https://github.com/goeb/meseq

On utilise les bibliothèques Cairo et Pango pour dessiner, écrire le texte, puis générer l'image. Elles sont relativement simples à utiliser.

Il existe d'autres bibliothèques pour dessiner, que je n'ai pas étudiées (et je ne suis pas sûr qu'il existe un moyen simple de les utiliser en Python) :

libgd, utilisée par mscgen
les bibliothèques sous-jacentes de Graphviz (dont le rendu est agréable)

Pour la suite

Les améliorations à faire sont :

améliorer le rendu (diagramme plus compact verticalement, réduire les conflits de textes qui se superposent,…)
ajouter des visuels (bloc de commentaire, couleurs, …)
augmenter la qualité de code
choisir une licence open-source

Par la suite je porterai peut-être ce programme en C ou C++, afin qu'il soit plus facile d'accès pour les personnes ne disposant pas de Python sur leur poste (je pense aux personnes lambda sur OS Windows).

Afin d'orienter les choix qui restent à faire, je serais intéressé par les avis éclairés des lecteurs de LinuxFR :

utilisez-vous les diagrammes de séquences ?
quels éléments visuels trouvez-vous indispensables, et pour représenter quoi ?
faut-il rester en Python ou passer en C ou C++ ?

# Reste en python

Posté par Colin Pitrat (site web personnel) le 13 septembre 2016 à 21:27. Évalué à 10.

Par la suite je porterai peut-être ce programme en C ou C++, afin qu'il soit plus facile d'accès pour les personnes ne disposant pas de Python sur leur poste (je pense aux personnes lambda sur OS Windows).

Alors reste en python et regarde du côté de py2exe …

http://stackoverflow.com/questions/2933/how-can-i-create-a-directly-executable-cross-platform-gui-app-using-python
- [^] # Re: Reste en python
  
  Posté par Colin Pitrat (site web personnel) le 13 septembre 2016 à 21:29. Évalué à 7.
  
  Et sinon super projet, chaque fois que j'ai eu besoin de faire un petit diagramme comme ça j'ai sois fini par m'en passer, soit passé 15mn pour aligner 4 flèches dans une GUI.
- [^] # Re: Reste en python
  
  Posté par goeb le 14 septembre 2016 à 20:30. Évalué à 2.
  
  Intéressant.
  Mais py2exe semble ne pas avoir de mise à jour depuis 2008. Est-ce encore d'actualité ?
  - [^] # Re: Reste en python
    
    Posté par Yakulu le 15 septembre 2016 à 07:05. Évalué à 2.
    
    Tu as aussi cx_freeze, mais qui n’est pas des plus actifs lui non plus.
    Il semble cependant que le projet du genre le plus dynamique soit PyInstaller.
- [^] # Re: Reste en python
  
  Posté par barmic le 16 septembre 2016 à 16:24. Évalué à 3.
  
  Sinon à changer de langage pour ça, j'imaginerais plus go qui a pas mal plus aux développeurs python et qui a 2 grands avantages : il se crosscompile très facilement et il génère de base des binaires statiquement liés. C'est parfait pour les déploiements simplifiés (→ sans aucune dépendance).
  
  Tous les contenus que j'écris ici sont sous licence CC0 (j'abandonne autant que possible mes droits d'auteur sur mes écrits)
# sdedit

Posté par X@v (site web personnel) le 13 septembre 2016 à 21:53. Évalué à 3.

Il y a quelque temps de ça, j'utilisais sdedit qui me permettais de créer des diagrammes de séquences équivalents.
# PlantUML

Posté par woffer 🐧 le 13 septembre 2016 à 22:17. Évalué à 10.

Personnellement, moi j'utilise PlantUML depuis des années pour tous mes diagrammes UML. Je peux facilement mettre mes doc UML avec mon code en gestion de conf.
- [^] # Re: PlantUML
  
  Posté par Benoît Bailleux (Mastodon) le 14 septembre 2016 à 08:58. Évalué à 2.
  
  Yeah, PlantUML roxor des ours. Il permet de générer des dessins (pas seulement des diagrammes de séquences) en bitmap (PNG), SVG et ASCII art.
  
  Par contre, il colle à UML, et du coup, je ne pense pas qu'il permettent certaines des choses que tu recherches (flèches qui se croisent ou grosse flèche double du « TLS Handshake »…)
  
  Mais peut-être peux-tu contribuer (je sais bien que c'est bien plus facile à dire qu'à faire) avec tes supers idées ?
  - [^] # Re: PlantUML
    
    Posté par PlantUML (site web personnel) le 14 septembre 2016 à 14:29. Évalué à 6.
    
    Bonjour,
    C'est vrai que nous collons à l'UML (d'où le nom), mais quand c'est possible nous nous écartons de cette ligne.
    (Par exemple, nous avons rajouté des fonctionnalités SDL, ainsi que le support des diagrammes Archimate).
    
    Ainsi, pour la double flèche, la syntaxe suivante est déjà possible:
    w3client<-> w3server : TLS Hanshake\nthat follows is ciphered
    
    Une autre possiblité est d'utiliser:
    == TLS Hanshake\nhat follows is ciphered ==
    
    Résultat:
    http://www.plantuml.com/plantuml/uml/ixLL2F49Ll18p2lEICnEZSdBI2nHIClFoSalBrR8B5P8pYp8I2rAJL6mjUKgDqxEoKpDAx7HjLCeDovEBIfBBLAm8au_0000
    
    Ce n'est pas exactement le dessin voulu, mais ça peut dépanner.
- [^] # Re: PlantUML
  
  Posté par Hobgoblins Master (Mastodon) le 14 septembre 2016 à 13:58. Évalué à 5.
  
  Super intéressant ça, en tout cas, ça devrait m’aider par rapport à ce que je fais aujourd’hui sous Dia, d’ailleurs, connaissez vous un soft équivalent qui pourrait me remplacer Dia pour faire des schémas réseaux / système…
  - [^] # Re: PlantUML
    
    Posté par tetraf le 16 septembre 2016 à 16:20. Évalué à 2.
    
    Je connais l'extension VRT Network Equipment pour LibreOffice Draw, qui permet d'obtenir des schémas un peu différents de ceux de Dia.
    Mais je suis aussi intéressé s'il existe une alternative basée sur du texte simple et qui sorte des schémas « montrables » de systèmes, réseaux, armoires…
- [^] # Re: PlantUML
  
  Posté par Gart Algar le 19 septembre 2016 à 10:47. Évalué à 1.
  
  En plus y'a un plugin sous intellij, eclipse, etc.
  Il y a aussi des macros confluences pour intégrer directement dans le wiki le texte et avoir l'image générée
  Bref plantUML c'est trop bien
# Des sites existent

Posté par Flyounet (site web personnel) le 13 septembre 2016 à 22:27. Évalué à 10.
Il y a longtemps j'utilisais WebSequence Diagram. C'était bien.

Mais pas assez ouvert, alors en cherchant un peu, j'ai trouvé : PlantUML. Et comme ils le disent : Open-source tool that uses simple textual descriptions to draw UML diagrams.

Un exemple simple :
- Voici le texte utilisé : @startuml Actor User as u box "Client Workstation" #aqua participant "Client Browser" as b participant "Client JavaWebStart" as c endbox box "Servers Infrastructure" #darksalmon participant ReverseProxy as r participant ApplicationServer as s endbox u -> b : I want to go to application https://test.com == Authentication == b -> r : User wants to go to application https://test.com r --> b : OK, but first Authenticate b --> u : Give your creds u -> b : user=test, pass=**** b -> r : OK, here are the credentials r -> r : Checking authentication r --> b : OK you're granted. Take the cookie(s) b --> u : You're accepted. Going to the app == Request a Page to have the JavaWebStart file == b -> r : Going to https://test.com see my cookie(s) r -> r : Checking cookie(s) : OK granted. r -> s : Please have a look on this request note over s The authentication mechanism of the application is not represented in this schema. But it also adds cookie like JSESSIONID. endnote s --> r : The answer (with the link to JavaWebStart) r --> b : The answer (with the link to JavaWebStart) + cookie updated b --> u : The answer u -> b : Click on the JWS b -> s : I want this (including the check on the ReverseProxy for security) s --> b : Here is the file (including the update of cookie on the RP). b --> u : Do you want to execute the JWS ? == Executing JWS == u --> c : Execute c -> r : I want something on https://test.com (i have no cookie) r --> c : **You shall not pass !** note over c,r : That's why the Java Web Start needs to know the cookies @enduml
- Et l'image générée :
PlantUML en action avec l'exemple ci-dessus.

Bien sûr, je pourrais télécharger le jar et le faire tourner en local, mais j'ai juste pas envie. D'autant plus qu'il y a pléthore de license disponible.
# msc-generator

Posté par pulkomandy (site web personnel, Mastodon) le 14 septembre 2016 à 07:35. Évalué à 5.

Il y a msc-generator, qui est plus ou moins basé sur mscgen avec plein de fonctions en plus: https://sites.google.com/site/mscgen2393/

C'est un bon point de départ. Il manque quelques trucs dans les possibilités de "styles" mais on s'en sort avec quelques outils autour (un makefile et quelques astuces à base de cat pour concaténer des fichiers).

Il y a une interface graphique pour Windows, avec un apperçu du rendu et un éditeur (pas terrible). Il y a bien sur un outil en ligne de commande pour générer le graphe. Il y a une intégration dans Microsoft Office sous forme d'objets OLE, mais c'est un peu gadget.

Il manque un export en format vectoriel de qualité, même l'export en SVG a certaines parties du diagramme rendues en bitmap, et du coup ça pixellise quand on veut intégrer les SDL à un document imprimé.

En tout cas, il serait appréciable de garder une syntaxe proche de mscgen et/ou msc-generator (qui a quelques variantes). ça permettra aux gens de migrer vers ton outil.

Enfin, Python est facile à installer sous Windows. Alors qu'une chaîne de compilation pour du C/C++, c'est moins facile.
# En SVG

Posté par ComputingFroggy (site web personnel) le 14 septembre 2016 à 08:26. Évalué à 7.

Tu devrais générer un fichier SVG : c'est plus scallable et surtout plus facilement modifiable (même si ce n'est pas vraiment le but, on ne sait jamais).
- [^] # Re: En SVG
  
  Posté par goeb le 15 septembre 2016 à 12:11. Évalué à 1.
  
  Ok, je rajouterai le SVG. C'est facile.
# en parlant de décrire des protocoles

Posté par c^3 le 14 septembre 2016 à 09:51. Évalué à 2.

Il y a des outils ± formels pour ça, ça peut aider à trouver les failles (faire son propre protocole, c'est dangereux et compliqué, surtout avec la crypto, cf les failles découvertes récemment dans TLS ou les passeports français). En général, c'est pas facile à utiliser, mais il y a un nouvel arrivant assez intéressant par l'un des auteurs de Raft (le protocole de consensus). Il décrit l'outil dans un blog post. Le focus est mis sur la simulation (on écrit un petit programme pour représenter le protocole, on écrit des invariants, et on peut lancer des simulations randomisées pour tester — en gros, du model checking) ET sur la visualisation (avec d3.js) pour débugguer le protocole en même temps qu'on le formalise. Perso j'aime bien l'exemple des ascenseurs ^{^}

The cake is a lie.
# seqdiag

Posté par barmic le 14 septembre 2016 à 09:55. Évalué à 6.

J'ai eu le même besoin récemment et je suis passé par seqdiag.

Je n'avais pas de besoin aussi sophistiqués que toi, mais il était nécessaire pour moi de travailler avec du texte. En effet je génère mes diagrammes à partir de CSV que je sors de wireshark (et j'ai une moulinette awk qui génère la source du diagramme).

Ton outil a l'air très sympa :)

C'est agréable d'avoir une sortie PNG, mais pour moins t'embêter à ta place j'aurais plutôt généré du SVG ou du postscript (qui ne nécessitent pas de bibliothèque en plus pour leur génération).

Tous les contenus que j'écris ici sont sous licence CC0 (j'abandonne autant que possible mes droits d'auteur sur mes écrits)
- [^] # Re: seqdiag
  
  Posté par barmic le 14 septembre 2016 à 10:01. Évalué à 5.
  
  Ça me fait penser qu'on peut détourner des logiciels de visualisation de traces pour ça (comme ViTE).
  
  Tous les contenus que j'écris ici sont sous licence CC0 (j'abandonne autant que possible mes droits d'auteur sur mes écrits)
# En Metapost

Posté par Michaël (site web personnel) le 14 septembre 2016 à 10:24. Évalué à 4.
Je programme en METAPOST – c'est si on veut l'ancêtre, toujours bien vivant, d'asymptote et de tikz – pour produire diverses sorte de diagrammes. Voir Blueprint. C'est un langage plutôt déclaratif (pour les équations linéaires) et basé sur des remplacements de macros, donc une chose assez bizarre à programmer. Mais lorsqu'on s'y met on peut produire des interfaces déclaratives pour les diagrammes, qui sont assez sympa à utiliser, voir par exemple:

Un morceau de code source est
```
beginfig(0)

  beginroadmap;

  % Important time points
  time "WEEK 1",  7.0;
  time "WEEK 2", 14.0;
  time "WEEK 3", 21.0;
  time "WEEK 4", 28.0;
  time "WEEK 5", 35.0;


  phase "Initial\\Contact";

  % Initial Meeeting
  milestone 0, 1.0,  1;
  annotation "Initial Meeting",         12h, overline2;
  annotation "Initial Meeting",          6h, underline2;


  phase "Planning";

  % Assessment
  milestone 1, 2.0,  2;
  annotation "Needs\\Assessment",       11h, overline1;
  annotation "Needs Assessment\\Feedback",   6h, underline1 + u*right;
…
```
- [^] # Re: En Metapost
  
  Posté par barmic le 14 septembre 2016 à 10:36. Évalué à 4.
  
  Je ne connais pas METAPOST, mais j'ai déjà fais du tikz. Il y a un système de positionnement qui n'est pas nécessaire pour un digramme de séquence. Mais c'est sympa et assez facile finalement :)
  
  Tous les contenus que j'écris ici sont sous licence CC0 (j'abandonne autant que possible mes droits d'auteur sur mes écrits)
# Mermaid

Posté par Larry Cow le 14 septembre 2016 à 10:31. Évalué à 5.

Sinon, il y a ça, qui a un but assez similaire : http://knsv.github.io/mermaid/

Ils gérent plusieurs sortes de diags, notamment le diagramme de séquence. C'est assez pratique (tout comme meseq) de pouvoir stocker ses gra-graphes sous forme de texte, ça se git mieux ;)
- [^] # Re: Mermaid
  
  Posté par SauronDeMordor (site web personnel) le 14 septembre 2016 à 12:34. Évalué à 3.
  
  oui j utilise aussi mermaid, et ca s interface super bien dans un wiki gollum en plus.
  - [^] # Re: Mermaid
    
    Posté par Larry Cow le 14 septembre 2016 à 14:02. Évalué à 3.
    
    Ah, tu m'intéresses. Il y a un truc particulier à faire dans Gollum, pour ça? J'avais naïvement fait confiance à la liste de http://knsv.github.io/mermaid/#downstream-projects qui ne le mentionne pas…
# Markdeep

Posté par pepp le 14 septembre 2016 à 15:07. Évalué à 4. Dernière modification le 24 août 2019 à 15:01.

Un autre outil qui génère peut servir pour générer des diagrammes (et plein d'autre choses) : Markdeep. (NdM: lien corrigé)

Comme c'est du markdown on peut soit le créer / l'éditer à la main, soit faire un outil qui génére le markdown à partir d'un langage comme le tiens.

Pour ton exemple ça donnerait ça: http://soupeaucaillou.com/test.md.html
- [^] # Re: Markdeep
  
  Posté par lolop (site web personnel) le 14 septembre 2016 à 18:33. Évalué à 5.
  
  Bug dans le lien Markdeep: voir http://casual-effects.com/markdeep/
  
  Python 3 - Apprendre à programmer dans l'écosystème Python → https://www.dunod.com/EAN/9782100809141
# Graphviz

Posté par jepostesurlatribune le 20 septembre 2016 à 13:54. Évalué à 1.

Pour pas mal de graphes, j'utilise Graphviz.
http://www.graphviz.org/Gallery.php
couplé à du gslgen, cela couvre plein de besoins à travers le même outils.

Je modélise en XML, puis je génère le script du graphe ou d'autres choses, méthodes de classes, ….

gslgen : syntax xml éditable en texte.
graphviz : rendu du graph selon le besoin, ortho, courbe, horizontal, vertical, .

licence
graphviz: Eclipse Public License - v 1.0
gslgen : GNU GENERAL PUBLIC LICENSE - Version 3

et ça marche pour des diagrammes, de process, du planning, de ressources, d'étapes …
le graphe est paramétrable et a toujours un beau rendu.

On gère l'info pas le rendu…