Los workspaces de Structurizr repartidos en varios archivos ya se importan en Archyl

Algunos workspaces de Structurizr no guardan casi nada en workspace.dsl. Una cabecera, un bloque model y una columna de líneas !include, una por sistema, con el modelo real repartido entre los archivos a los que apuntan.

Hasta esta semana, Archyl no podía importar eso. Nuestro artículo del 4 de agosto sobre el cierre de Structurizr Cloud lo decía en una línea: los workspaces de varios archivos había que aplanarlos primero. Eso descartaba los workspaces que tienen cada sistema en su propio archivo. Structurizr Cloud cierra el 30 de septiembre, dentro de dos semanas.

Ahora puedes subir el workspace como .zip, y Archyl resuelve cada !include contra los archivos que contiene.

Por qué un solo archivo nunca iba a funcionar

Toma un workspace organizado así:

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

con un archivo raíz que solo une las piezas:

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

Sube o pega ese archivo raíz por sí solo y el importador no tiene contra qué resolver las rutas. Parsea lo que tiene, se salta cada include y te avisa:

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

Los avisos son correctos, y también son todo el resultado: no hay nada de esos seis archivos. Un único archivo .dsl autocontenido se sigue importando exactamente igual que antes. El zip es para todo lo demás.

Comprime el directorio del workspace, no el repositorio

Si tu workspace usa !include, los archivos divididos existen como archivos en algún sitio. La documentación de includes de Structurizr describe un include de archivo como "a single local file, specified by a relative path" — un único archivo local, indicado mediante una ruta relativa. Así que la copia que importa está en un disco o en Git, no en la nube. Busca el directorio que contiene workspace.dsl y comprime ese.

Desde dentro del directorio:

zip -r workspace.zip workspace.dsl model systems

O, si el workspace vive en un repositorio, directamente desde un commit:

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

La diferencia importa porque el zip está limitado a 500 entradas, y ese recuento se comprueba antes de filtrar nada. Comprime un repositorio entero con su carpeta .git y puedes superar el límite antes de que se lea un solo archivo .dsl. Una carpeta envolvente en el nivel superior del zip no es problema, ya que los includes se resuelven de forma relativa al archivo que hace el include.

Qué pasa cuando lo subes

En el modal de importación, el botón de la pestaña Structurizr DSL ahora dice Subir .dsl o .zip. Elige un zip y el editor de código se sustituye por una tarjeta con su nombre y tamaño. Haz clic en Validar y la tarjeta añade el número de archivos y el archivo raíz que eligió.

Esto funciona tanto al importar en un proyecto existente como al crear uno nuevo. Un proyecto nuevo toma su nombre de la cabecera del workspace, así que workspace "Payments Platform" { ... } puede crear un proyecto y un workspace { ... } sin nombre no puede.

En el servidor, el zip pasa por cuatro pasos:

  1. Elegir la raíz. workspace.dsl si el zip lo tiene; si no, el archivo .dsl menos profundo. Cuando tiene que elegir entre varios archivos y ninguno se llama workspace.dsl, un aviso indica el archivo que usó.
  2. Expandir los includes como texto, antes de parsear. El contenido del archivo incluido sustituye la línea !include, el mismo inlining que hace Structurizr. Las rutas son relativas al archivo que incluye, así que systems/index.dsl incluyendo shared/platform.dsl encuentra systems/shared/platform.dsl.
  3. Resolver los includes de directorio. !include systems incorpora cada archivo .dsl que esté directamente dentro de systems/, por orden de nombre. Los subdirectorios no se recorren.
  4. Detenerse en los bordes. Si un archivo acaba incluyéndose a sí mismo, directamente o a través de otro archivo, el ciclo se rompe y se informa. El anidamiento se detiene en 10 niveles.

Después, el workspace expandido pasa por el mismo importador de Structurizr que un archivo único, con la misma fidelidad y la misma lista de avisos para todo lo que se salte.

Un include que no se puede resolver, como un archivo que falta o una ruta que apunta fuera del zip, también se convierte en un aviso. El resto del workspace se importa igualmente.

Los includes remotos se rechazan a propósito

Structurizr también permite que !include apunte a una URL HTTPS. Archyl no las sigue. Resolverlas permitiría que cualquier archivo subido hiciera que nuestros servidores pidieran la dirección que ese archivo eligiera, lo que es un vector de server-side request forgery sin importar quién lo suba. La línea se salta con un aviso:

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

Si el archivo remoto contiene elementos del modelo que necesitas, descárgalo dentro del zip y cambia la línea a una ruta relativa.

Los límites

Límite Valor Si se supera
Tamaño del zip 10 MiB Subida rechazada
Entradas en el zip 500 Subida rechazada
Tamaño total una vez expandido 50 MiB Subida rechazada
Cualquier archivo individual 5 MiB Archivo omitido, con un aviso
Anidamiento de includes 10 niveles Include más profundo omitido, con un aviso

Las entradas cuya ruta intenta escapar del zip, mediante una ruta absoluta o segmentos .., se omiten con un aviso. Solo se conservan los archivos de texto: .dsl, .md, .json, .yaml, .yml y .txt. Las imágenes y todo lo demás se descartan sin aviso, ya que al importador DSL no le sirven de nada.

Lo que todavía no hace

La sincronización con Git no resuelve includes. La sincronización de repositorios lee archyl.yaml, no un workspace de Structurizr, así que todavía no hay ninguna vía por la que Archyl traiga un DSL de varios archivos directamente desde un repositorio. Si tu DSL vive en Git, el comando git archive de arriba es, por ahora, el flujo de trabajo.

Nada más ha cambiado en la fidelidad con Structurizr. El layout, los estilos y las deployment views no se importaban antes y tampoco se importan desde un zip. Tampoco hay todavía una vía para workspace.json: Archyl lee texto DSL. Si lo que más valoras de Structurizr es el layout ajustado a mano, las opciones del artículo sobre el cierre que te mantienen en las herramientas propias de Structurizr siguen encajando mejor.

Antes del 30 de septiembre

  1. Asegúrate de tener los archivos fuente. Un workspace dividido con !include se escribió como archivos, así que búscalos. Si algo solo existe en la copia en la nube, como un layout retocado en el navegador o documentación escrita allí, el artículo del 4 de agosto explica cómo sacarlo.
  2. Comprime el directorio que contiene workspace.dsl, no el repositorio que lo rodea.
  3. Sube y valida. Abre Import Project, o el modal de importación dentro de un proyecto existente, elige Structurizr DSL, sube el zip y haz clic en Validar. Revisa el archivo raíz que eligió y lee cada aviso antes de importar.
  4. Haz commit del directorio en un repositorio si todavía no está en uno, para que la siguiente persona no tenga que buscarlo en tu portátil.

El comportamiento completo del importador, incluidas las reglas de nombre para proyectos nuevos, está en la documentación de Architecture as Code. Para los demás formatos que importa Archyl, consulta importar proyectos de Structurizr, LikeC4 e IcePanel.