Workspaces do Structurizr Divididos em Vários Arquivos Agora Podem Ser Importados no Archyl

Alguns workspaces do Structurizr guardam quase nada em workspace.dsl. Um cabeçalho, um bloco model e uma coluna de linhas !include, uma por sistema, com o modelo de verdade espalhado pelos arquivos para os quais elas apontam.

Até esta semana, o Archyl não conseguia importar isso. Nosso post de 4 de agosto sobre o encerramento do Structurizr Cloud dizia isso em uma linha: workspaces com vários arquivos precisavam ser achatados antes. Isso excluía os workspaces que mantêm cada sistema no seu próprio arquivo. O Structurizr Cloud encerra em 30 de setembro, daqui a duas semanas.

Agora você pode enviar o workspace como .zip, e o Archyl resolve cada !include a partir dos arquivos que estão dentro dele.

Por que um único arquivo nunca ia funcionar

Pegue um workspace organizado assim:

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

com um arquivo raiz que só junta as partes:

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

Envie ou cole esse arquivo raiz sozinho e o importador não tem a partir de que resolver os caminhos. Ele faz o parsing do que tem, pula cada include e avisa você:

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

Os avisos estão corretos, e também são o resultado inteiro: nada daqueles seis arquivos está nele. Um único arquivo .dsl autocontido continua sendo importado exatamente como antes. O zip é para todo o resto.

Compacte o diretório do workspace, não o repositório

Se o seu workspace usa !include, os arquivos separados existem como arquivos em algum lugar. A documentação de includes do Structurizr descreve um include de arquivo como "a single local file, specified by a relative path" — um único arquivo local, especificado por um caminho relativo. Então a cópia que importa está em um disco ou no Git, não na nuvem. Encontre o diretório que contém workspace.dsl e compacte esse.

De dentro do diretório:

zip -r workspace.zip workspace.dsl model systems

Ou, se o workspace fica em um repositório, direto de um commit:

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

A diferença importa porque o arquivo compactado é limitado a 500 entradas, e essa contagem é verificada antes de qualquer filtragem. Compacte um repositório inteiro com a pasta .git e você pode passar do limite antes que um único arquivo .dsl seja lido. Uma pasta envolvendo tudo no nível superior do zip não é problema, já que os includes são resolvidos em relação ao arquivo que faz o include.

O que acontece quando você envia

No modal de importação, o botão da aba Structurizr DSL agora diz Enviar .dsl ou .zip. Escolha um zip e o editor de código é substituído por um card com o nome e o tamanho dele. Clique em Validar e o card passa a mostrar também a quantidade de arquivos e o arquivo raiz escolhido.

Isso funciona tanto ao importar para um projeto existente quanto ao criar um novo. Um projeto novo recebe o nome a partir do cabeçalho do workspace, então workspace "Payments Platform" { ... } consegue criar um projeto e um workspace { ... } sem nome não consegue.

No servidor, o zip passa por quatro etapas:

1. Escolher a raiz. workspace.dsl se o zip tiver um; caso contrário, o arquivo .dsl menos profundo. Quando precisa escolher entre vários arquivos e nenhum se chama workspace.dsl, um aviso informa o arquivo usado.
2. Expandir os includes como texto, antes do parsing. O conteúdo do arquivo incluído substitui a linha !include, o mesmo inlining que o Structurizr faz. Os caminhos são relativos ao arquivo que faz o include, então systems/index.dsl incluindo shared/platform.dsl encontra systems/shared/platform.dsl.
3. Resolver includes de diretório. !include systems traz cada arquivo .dsl que está diretamente dentro de systems/, em ordem de nome. Subdiretórios não são percorridos.
4. Parar nas bordas. Um arquivo que acaba incluindo a si mesmo, diretamente ou por meio de outro arquivo, tem o ciclo quebrado e reportado. O aninhamento para em 10 níveis.

Depois, o workspace expandido passa pelo mesmo importador do Structurizr que um arquivo único, com a mesma fidelidade e a mesma lista de avisos para tudo o que for pulado.

Um include que não pode ser resolvido, como um arquivo ausente ou um caminho apontando para fora do zip, também vira um aviso. O restante do workspace é importado mesmo assim.

Includes remotos são recusados de propósito

O Structurizr também permite que !include aponte para uma URL HTTPS. O Archyl não segue essas URLs. Resolvê-las deixaria qualquer arquivo enviado fazer nossos servidores requisitarem um endereço escolhido por ele, o que é um vetor de server-side request forgery, não importa quem envie. A linha é pulada com um aviso:

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

Se o arquivo remoto contém elementos do modelo de que você precisa, baixe-o para dentro do zip e troque a linha por um caminho relativo.

Os limites

Entradas cujo caminho tenta escapar do zip, por meio de um caminho absoluto ou de segmentos .., são puladas com um aviso. Só arquivos de texto são mantidos: .dsl, .md, .json, .yaml, .yml e .txt. Imagens e todo o resto são descartados sem aviso, já que o importador de DSL não tem uso para eles.

O que ainda não faz

A sincronização com Git não resolve includes. A sincronização de repositórios lê archyl.yaml, não um workspace do Structurizr, então ainda não existe um caminho pelo qual o Archyl puxe um DSL com vários arquivos direto de um repositório. Se o seu DSL fica no Git, o comando git archive acima é o fluxo de trabalho por enquanto.

Nada mais mudou na fidelidade ao Structurizr. Layout, estilos e deployment views não eram importados antes e não são importados a partir de um zip. Também continua não existindo um caminho para workspace.json: o Archyl lê texto DSL. Se o que você mais valoriza no Structurizr é o layout ajustado à mão, as opções do post sobre o encerramento que mantêm você no tooling do próprio Structurizr continuam sendo a melhor escolha.

Antes de 30 de setembro

1. Garanta que você tem os arquivos-fonte. Um workspace dividido com !include foi escrito como arquivos, então encontre-os. Se algo existe só na cópia na nuvem, como um layout ajustado no navegador ou documentação escrita lá, o post de 4 de agosto explica como tirar isso de lá.
2. Compacte o diretório que contém workspace.dsl, não o repositório em volta dele.
3. Envie e valide. Abra Import Project, ou o modal de importação dentro de um projeto existente, escolha Structurizr DSL, envie o zip e clique em Validar. Confira o arquivo raiz escolhido e leia cada aviso antes de importar.
4. Faça commit do diretório em um repositório se ele ainda não estiver em um, para que a próxima pessoa não precise procurá-lo no seu notebook.

O comportamento completo do importador, incluindo as regras de nome para projetos novos, está na documentação de Architecture as Code. Para os outros formatos que o Archyl importa, veja importar projetos do Structurizr, LikeC4 e IcePanel.