Les workspaces Structurizr répartis sur plusieurs fichiers s'importent désormais dans Archyl

Certains workspaces Structurizr ne mettent presque rien dans workspace.dsl. Un en-tête, un bloc model et une colonne de lignes !include, une par système, le vrai modèle étant réparti dans les fichiers vers lesquels elles pointent.

Jusqu'à cette semaine, Archyl ne savait pas importer ça. Notre article du 4 août sur la fermeture de Structurizr Cloud le disait en une ligne : les workspaces multi-fichiers devaient d'abord être aplatis. Cela excluait les workspaces qui placent chaque système dans son propre fichier. Structurizr Cloud ferme le 30 septembre, dans deux semaines.

Vous pouvez maintenant importer le workspace sous forme de .zip, et Archyl résout chaque !include à partir des fichiers qu'il contient.

Pourquoi un seul fichier ne pouvait pas suffire

Prenez un workspace organisé ainsi :

workspace.dsl
model/
  people.dsl
  relationships.dsl
systems/
  ledger.dsl
  notifications.dsl
  payments.dsl

avec un fichier racine qui ne fait qu'assembler les morceaux :

workspace "Payments Platform" "Card payments and settlement" {
    model {
        !include model/people.dsl
        !include systems
        !include model/relationships.dsl
    }
}

Importez ou collez ce fichier racine seul, et l'importeur n'a rien à partir de quoi résoudre les chemins. Il parse ce qu'il a, ignore chaque include et vous l'indique :

line 3: directive '!include' is not supported and was skipped
line 4: directive '!include' is not supported and was skipped
line 5: directive '!include' is not supported and was skipped

Les avertissements sont exacts, et ils constituent aussi tout le résultat : rien de ces six fichiers n'y figure. Un fichier .dsl unique et autonome s'importe toujours exactement comme avant. Le zip, c'est pour tout le reste.

Zippez le répertoire du workspace, pas le dépôt

Si votre workspace utilise !include, les fichiers découpés existent quelque part en tant que fichiers. La documentation des includes de Structurizr décrit un include de fichier comme "a single local file, specified by a relative path" — un fichier local unique, désigné par un chemin relatif. La copie qui compte est donc sur un disque ou dans Git, pas dans le cloud. Trouvez le répertoire qui contient workspace.dsl et zippez celui-là.

Depuis l'intérieur du répertoire :

zip -r workspace.zip workspace.dsl model systems

Ou, si le workspace vit dans un dépôt, directement depuis un commit :

git archive --format=zip -o workspace.zip HEAD:docs/architecture

La distinction compte parce que l'archive est plafonnée à 500 entrées, et ce décompte est vérifié avant tout filtrage. Zippez un dépôt entier avec son dossier .git et vous pouvez dépasser le plafond avant même qu'un seul fichier .dsl soit lu. Un dossier englobant au premier niveau de l'archive ne pose pas de problème, puisque les includes sont résolus relativement au fichier qui fait l'include.

Ce qui se passe à l'import

Dans la fenêtre d'import, le bouton de l'onglet Structurizr DSL indique désormais Importer un .dsl ou .zip. Choisissez une archive et l'éditeur de code est remplacé par une carte affichant son nom et sa taille. Cliquez sur Valider et la carte ajoute le nombre de fichiers et le fichier racine retenu.

Cela fonctionne pour un import dans un projet existant comme pour la création d'un nouveau projet. Un nouveau projet prend son nom dans l'en-tête du workspace : workspace "Payments Platform" { ... } peut créer un projet, un workspace { ... } sans nom ne le peut pas.

Côté serveur, l'archive passe par quatre étapes :

1. Choisir la racine. workspace.dsl si l'archive en contient un, sinon le fichier .dsl le moins profond. Quand il faut choisir entre plusieurs fichiers et qu'aucun ne s'appelle workspace.dsl, un avertissement indique le fichier utilisé.
2. Développer les includes en texte, avant le parsing. Le contenu du fichier inclus remplace la ligne !include, le même inlining que fait Structurizr. Les chemins sont relatifs au fichier qui inclut, donc systems/index.dsl qui inclut shared/platform.dsl trouve systems/shared/platform.dsl.
3. Résoudre les includes de répertoire. !include systems intègre chaque fichier .dsl situé directement dans systems/, dans l'ordre des noms. Les sous-répertoires ne sont pas parcourus.
4. S'arrêter aux bords. Quand un fichier finit par s'inclure lui-même, directement ou via un autre fichier, le cycle est rompu et signalé. L'imbrication s'arrête à 10 niveaux.

Le workspace développé passe ensuite par le même importeur Structurizr qu'un fichier unique, avec la même fidélité et la même liste d'avertissements pour tout ce qu'il ignore.

Un include impossible à résoudre, comme un fichier manquant ou un chemin qui pointe hors de l'archive, devient lui aussi un avertissement. Le reste du workspace est quand même importé.

Les includes distants sont refusés exprès

Structurizr permet aussi à !include de pointer vers une URL HTTPS. Archyl ne les suit pas. Les résoudre permettrait à n'importe quel fichier importé de faire interroger par nos serveurs l'adresse de son choix, ce qui est un vecteur de server-side request forgery, peu importe qui l'importe. La ligne est ignorée avec un avertissement :

!include: remote target "https://example.com/shared/identity.dsl" is not supported and was skipped

Si le fichier distant contient des éléments de modèle dont vous avez besoin, téléchargez-le dans l'archive et remplacez la ligne par un chemin relatif.

Les limites

Les entrées dont le chemin tente de sortir de l'archive, via un chemin absolu ou des segments .., sont ignorées avec un avertissement. Seuls les fichiers texte sont conservés : .dsl, .md, .json, .yaml, .yml et .txt. Les images et tout le reste sont écartés sans avertissement, puisque l'importeur DSL n'en a aucun usage.

Ce qu'il ne fait toujours pas

La synchronisation Git ne résout pas les includes. La synchronisation de dépôt lit archyl.yaml, pas un workspace Structurizr : il n'existe donc pas encore de chemin par lequel Archyl récupère un DSL multi-fichiers directement depuis un dépôt. Si votre DSL vit dans Git, la commande git archive ci-dessus est le workflow pour l'instant.

Rien d'autre n'a changé côté fidélité à Structurizr. Le layout, les styles et les deployment views n'étaient pas importés avant et ne le sont pas davantage depuis un zip. Il n'y a toujours pas de chemin workspace.json non plus : Archyl lit du texte DSL. Si c'est le layout ajusté à la main que vous appréciez le plus dans Structurizr, les options de l'article sur la fermeture qui vous gardent sur l'outillage propre à Structurizr restent le meilleur choix.

Avant le 30 septembre

1. Assurez-vous d'avoir les fichiers sources. Un workspace découpé avec !include a été écrit sous forme de fichiers, alors retrouvez-les. Si quelque chose n'existe que dans la copie cloud, comme un layout retouché dans le navigateur ou de la documentation rédigée là-bas, l'article du 4 août explique comment le récupérer.
2. Zippez le répertoire qui contient workspace.dsl, pas le dépôt qui l'entoure.
3. Importez et validez. Ouvrez Import Project, ou la fenêtre d'import dans un projet existant, choisissez Structurizr DSL, importez le zip et cliquez sur Valider. Vérifiez le fichier racine retenu et lisez chaque avertissement avant d'importer.
4. Commitez le répertoire dans un dépôt s'il n'y est pas déjà, pour que la personne suivante n'ait pas à le chercher sur votre portable.

Le comportement complet de l'importeur, y compris les règles de nommage des nouveaux projets, est décrit dans la documentation Architecture as Code. Pour les autres formats qu'Archyl importe, voir importer des projets Structurizr, LikeC4 et IcePanel.