Journal Écrire des diagrammes de séquences

Posté par . Licence CC by-sa
51
13
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 (page perso) . É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 (page perso) . É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 . É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 . É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 . É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 (page perso) . É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 . É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 . É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 (page perso) . É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 . É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 . É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 (page perso) . É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 :

    Diagramme de séquence simple

    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 (page perso) . É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 (page perso) . É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 . Évalué à 1.

      Ok, je rajouterai le SVG. C'est facile.

  • # en parlant de décrire des protocoles

    Posté par . É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 . É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 . É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 (page perso) . É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:

    Frise projet

    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 . É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 . É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 ;)

  • # Markdeep

    Posté par . Évalué à 4.

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

    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

  • # Graphviz

    Posté par . É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…

Suivre le flux des commentaires

Note : les commentaires appartiennent à ceux qui les ont postés. Nous n'en sommes pas responsables.